Ludus MCP uses YAML schema files to define available Ansible roles and collections and map variables to roles. These schemas provide the LLM with detailed information about role variables, dependencies, and usage patterns for accurate range configuration.

All role and collection schemas are stored in:

~/.ludus-mcp/schemas/

This directory contains:

• Individual YAML files for each role or collection
• Sample-schema.yaml - Template for creating new schemas
• Project schemas downloaded from GitHub
• Custom schemas created by users

Schemas serve multiple functions:

1. Variable Definitions - Specify required and optional variables for each role
2. Type Validation - Define variable types (string, boolean, integer, array)
3. Default Values - Provide sensible defaults for role variables
4. Documentation - Explain what each variable does and how to use it
5. Dependencies - List other roles or collections required

Each schema file contains:

• Role or collection metadata (name, version, author)
• Variable definitions with types and descriptions
• Usage examples and dependency information
• Installation and configuration notes

The LLM uses ludus_list_role_collection_schemas to:

• See all available schema files
• Get file metadata (size, last modified)
• Categorize roles vs collections vs templates
• Plan which schemas to read based on requirements

The LLM uses ludus_read_role_collection_schema to:

• Read all schemas for comprehensive research
• Filter specific schemas using file_names parameter
• Get aggregated variable data for configuration building
• Understand role relationships and dependencies

• No Filter - Reads all YAML files in schemas directory
• Targeted Reading - Specify exact file names: ["ludus_ad.yaml", "sccm_collection.yaml"]
• Strategic Research - Choose filtering based on complexity and confidence

Project schemas are downloaded from the Ludus repository when the MCP server starts:

• Downloads from main branch of LudusMCP project repository
• Updates existing Project schemas
• Preserves custom schemas during updates
• Creates directory structure if missing

Project schemas include:

• Core Ludus Roles - Built-in functionality (AD, domain join, users)
• Security Tools - EDR agents, SIEM components, monitoring
• Infrastructure - Database servers, web servers, networking
• Collections - Multi-role deployments (SCCM, Exchange, ADFS)

Project schemas follow consistent naming:

• ludus_ad.yaml - Core Ludus roles
• badsectorlabs.ludus_elastic_agent.yaml - Community roles
• aleemladha.ludus_exchange.yaml - Author-prefixed roles
• bagelByt3s.ludus_adfs.yaml - Collection schemas

Copy and modify the sample template:

cp ~/.ludus-mcp/schemas/Sample-schema.yaml ~/.ludus-mcp/schemas/your_custom_role.yaml

If the role is public, please feel free to submit PR adding the schema to the project repo.

The Sample-schema.yaml template includes:

• Complete schema format with examples
• All possible field types and options
• Commented sections for roles vs collections
• Variable type examples (string, boolean, integer, array)
• Metadata fields and documentation patterns

1. Copy Template - Start with Sample-schema.yaml
2. Define Metadata - Set name, type, version, description, author
3. List Dependencies - Specify required roles or collections
4. Define Variables - Add all role variables with types and descriptions
5. Add Examples - Include usage examples and default values
6. Document Usage - Add installation notes and warnings if needed

Use descriptive names that match the role structure:

• company.custom_role.yaml - Organization-specific roles
• project.specialized_tool.yaml - Project-specific implementations
• team.modified_elastic.yaml - Modified versions of existing roles

• Project schemas are refreshed on server startup
• Existing project schemas are overwritten with latest versions
• No backup of old project schemas is maintained
• Updates happen automatically during mcp server start.

• Custom schemas are never overwritten during updates
• User-created schemas persist through server restarts
• Custom schemas remain during official schema downloads
• Manual deletion required to remove custom schemas

name: role_or_collection_name
type: role  # or "collection"
version: "1.0.0"
description: "What this role does"
repository: "https://github.com/author/repo"
author: "Author Name (@handle)"
dependencies: []
variables:
  variable_name:
    type: "string"
    required: true
    default: "default_value"
    description: "What this variable controls"

Supported variable types:

• string - Text values, paths, hostnames
• boolean - True/false values
• integer - Numeric values, ports, counts
• array - Lists of items
• object - Complex nested structures

Optional schema fields:

• valid_options - Enumerated valid values
• example - Usage examples
• warning - Important warnings about the role
• installation_method - How to install the role
• usage_notes - Special deployment considerations

1. Discovery - Lists available schemas to understand options
2. Selection - Chooses relevant schemas based on requirements
3. Analysis - Reads schema content to understand variables
4. Validation - Cross-references configuration against schemas

1. Variable Extraction - Gets all required and optional variables
2. Type Checking - Ensures variable types match schema definitions
3. Default Application - Uses schema defaults where appropriate
4. Dependency Resolution - Includes required roles and collections

1. Schema Validation - Verifies configuration matches schema requirements
2. Completeness Check - Ensures all required variables are defined
3. Type Verification - Confirms variable types are correct
4. Dependency Verification - Validates role dependencies are satisfied

Validate custom schemas by:

• Following the Sample-schema.yaml format exactly
• Verifying the LLM can read and parse the schema
• Checking variable definitions are complete

Update existing schemas by:

• Modifying the YAML file directly
• Testing with the LLM to verify changes work

Remember these schemas are primarily for the LLM. You can use these to prompt or provide additional context for a role variable. For instance, if a role should use a variable in only certain situations, describe that clearly in the schema.

Don't wordcel with the schema. Give clear simple definitions or instructions to LLM.

• Verify file exists in ~/.ludus-mcp/schemas/ directory
• Check file has .yaml or .yml extension
• Use ludus_list_role_collection_schemas to verify detection

• Validate YAML syntax (indentation, colons, quotes)
• Check required fields are present (name, type, variables)
• Verify variable definitions follow correct format
• Review Sample-schema.yaml for proper structure

• Use descriptive file names matching role names
• Include complete variable definitions with descriptions
• Add usage examples and dependency information
• Remove broken or incomplete schema files

• Ensure all variables have type definitions
• Include descriptions for complex variables
• Provide default values where appropriate
• Document required vs optional variables clearly