ludus-mcp/src/tools/index.ts

MCP server for managing Ludus cybersecurity training environments through natural language commands

// ============================================================================
// LUDUS MCP TOOLS - STATIC TOOL EXPORTS
// ============================================================================
// This file exports ALL Ludus MCP tools as static objects (matching older server.ts)

import { Tool } from '@modelcontextprotocol/sdk/types.js';

// ============================================================================
// STATIC TOOL EXPORTS - Range Planning & Research
// ============================================================================

export const ludusRangePlannerTool: Tool = {
  name: 'ludus_range_planner',
  description: '**PRIMARY RANGE ORCHESTRATOR** - Use this FIRST for any range creation! Analyzes requirements, researches roles/templates, designs VM architecture, generates structured instructions using existing MCP tools, and estimates resource requirements.',
  inputSchema: {
    type: 'object',
    properties: {
      user_intent: {
        type: 'string',
        description: 'User requirements for the range (e.g., "I need AD with SCCM and elastic monitoring")'
      },
      workstation_count: {
        type: 'number',
        description: 'Number of workstations needed (default: 2)',
        default: 2
      },
      complexity_level: {
        type: 'string',
        enum: ['simple', 'advanced', 'enterprise'],
        description: 'Complexity level (default: simple)',
        default: 'simple'
      },
      environment_type: {
        type: 'string',
        description: 'Environment type (default: active_directory)',
        default: 'active_directory'
      },
      special_requirements: {
        type: 'array',
        items: { type: 'string' },
        description: 'Special requirements or constraints'
      },
      user_context: {
        type: 'string',
        description: 'Context for file organization/naming'
      },
      output_file: {
        type: 'string',
        description: 'Optional: where to save the generated config'
      },
      preview_mode: {
        type: 'boolean',
        description: 'Just show plan, don\'t create files (default: false)'
      },
      include_testing: {
        type: 'boolean',
        description: 'Add testing/validation VMs (default: false)'
      }
    },
    required: ['user_intent']
  }
};

export const ludusRangeConfigCheckAgainstPlanTool: Tool = {
  name: 'ludus_range_config_check_against_plan',
  description: 'QA checklist tool to verify range configuration against original user requirements and plan. Used during validation phase to ensure all requirements are met.',
  inputSchema: {
    type: 'object',
    properties: {
      user_requirements: {
        type: 'string',
        description: 'Original user requirements/intent for the range'
      },
      config_content: {
        type: 'string',
        description: 'The YAML range configuration content to check'
      },
      roles_used: {
        type: 'array',
        items: { type: 'string' },
        description: 'List of Ludus roles used in the configuration'
      },
      expected_vms: {
        type: 'number',
        description: 'Expected number of VMs based on plan'
      },
      plan_id: {
        type: 'string',
        description: 'Plan ID from ludus_range_planner output'
      }
    },
    required: ['user_requirements', 'config_content', 'roles_used']
  }
};

// Import the existing static schema tool
export { ludusReadRoleCollectionSchemaTool } from './ludusReadRoleCollectionSchema.js';

// NEW: List YAML role/collection schema files
export const ludusListRoleCollectionSchemasTool: Tool = {
  name: 'ludus_list_role_collection_schemas',
  description: 'List all available role and collection schema files (.yaml/.yml) in ~/.ludus-mcp/schemas/. Shows inventory of roles, collections, and templates with file metadata.',
  inputSchema: {
    type: 'object',
    properties: {
      help: {
        type: 'boolean',
        description: 'Show detailed help information about this tool',
        default: false
      }
    }
  }
};

// ============================================================================
// STATIC TOOL EXPORTS - Core Range Management
// ============================================================================

export const deployRangeTool: Tool = {
  name: 'deploy_range',
  description: 'Deploy a Ludus range from a configuration file. Creates virtualized training environment. CREDENTIAL SECURITY: Ensure configs use placeholders {{LudusCredName-<user>-<name>}}. DESTRUCTIVE: Always verify before deployment.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      configPath: { type: 'string', description: 'Path to range configuration file' },
      force: { type: 'boolean', description: 'Force deployment without prompts' },
      tags: { type: 'string', description: 'Comma-separated deployment tags' },
      limit: { type: 'string', description: 'Limit deployment to specific pattern' },
      onlyRoles: { type: 'string', description: 'Deploy only specific roles' },
      verboseAnsible: { type: 'boolean', description: 'Enable verbose Ansible output' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const getRangeStatusTool: Tool = {
  name: 'get_range_status',
  description: 'Get current status of a deployed range including deployment progress and VM states.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const listUserRangesTool: Tool = {
  name: 'list_user_ranges',
  description: 'List all deployed ranges for a user, showing current status and basic information.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const getConnectionInfoTool: Tool = {
  name: 'get_connection_info',
  description: 'Download connection files (RDP, WireGuard, etc.) for accessing deployed range VMs.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      downloadLocation: { type: 'string', description: 'Custom download directory path' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const destroyRangeTool: Tool = {
  name: 'destroy_range',
  description: 'DESTRUCTIVE: Permanently destroy/stop a range, deleting all VMs and data. This action is irreversible.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      force: { type: 'boolean', description: 'Force destruction without prompts' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const rangeAbortTool: Tool = {
  name: 'range_abort',
  description: 'Abort an in-progress range deployment, stopping all deployment tasks.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const ludusPowerTool: Tool = {
  name: 'ludus_power',
  description: 'Power management for range VMs (start/stop). Power off operations require confirmation as they may interrupt running processes.',
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['on', 'off'], description: 'Power action to perform' },
      user: { type: 'string', description: 'Target user (admin only)' },
      vmNames: { type: 'string', description: 'VM name(s) to power on/off. Defaults to "all"' },
      confirmDestructiveAction: { type: 'boolean', description: 'Required confirmation for power off operations. Must be true to power off VMs.' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['action']
  }
};

export const getTagsTool: Tool = {
  name: 'get_tags',
  description: 'Get available deployment tags for selective range deployment.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

// ============================================================================
// STATIC TOOL EXPORTS - Configuration Management
// ============================================================================

export const readRangeConfigTool: Tool = {
  name: 'read_range_config',
  description: 'Read and display range configuration from file or URL. Supports local files and remote URLs.',
  inputSchema: {
    type: 'object',
    properties: {
      source: { type: 'string', description: 'File path or URL to configuration' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['source']
  }
};

export const writeRangeConfigTool: Tool = {
  name: 'write_range_config',
  description: 'Write range configuration to file with automatic validation. Creates directories as needed.',
  inputSchema: {
    type: 'object',
    properties: {
      filePath: { type: 'string', description: 'Destination file path' },
      content: { type: 'string', description: 'YAML configuration content' },
      user: { type: 'string', description: 'User directory to organize configs (creates subfolder under range-config-templates)' },
      overwrite: { type: 'boolean', description: 'Overwrite existing file' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['filePath', 'content']
  }
};

export const validateRangeConfigTool: Tool = {
  name: 'validate_range_config',
  description: 'Validate range configuration against schema and best practices. Essential before deployment.',
  inputSchema: {
    type: 'object',
    properties: {
      source: { type: 'string', description: 'File path or URL to validate' },
      content: { type: 'string', description: 'YAML content to validate directly' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const listRangeConfigsTool: Tool = {
  name: 'list_range_configs',
  description: 'List and analyze range configurations in directory. Provides validation status and metadata.',
  inputSchema: {
    type: 'object',
    properties: {
      directory: { type: 'string', description: 'Directory to search (optional, uses smart search if omitted)' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const getRangeConfigTool: Tool = {
  name: 'get_range_config',
  description: 'Get current range configuration from Ludus server or retrieve example configuration.',
  inputSchema: {
    type: 'object',
    properties: {
      user: { type: 'string', description: 'Target user (admin only)' },
      example: { type: 'boolean', description: 'Get example configuration instead' },
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

export const setRangeConfigTool: Tool = {
  name: 'set_range_config',
  description: 'Apply range configuration to Ludus server. Sets active configuration for deployment.\n\n**WORKING DIRECTORY**: All file paths are relative to ~/.ludus-mcp/range-config-templates/\n\n**PATH USAGE**: Use relative paths only (e.g., "base-configs/acme.yml", "user1/config.yaml")',
  inputSchema: {
    type: 'object',
    properties: {
      file: { type: 'string', description: 'Relative file path (e.g., "base-configs/acme.yml") of the configuration file within ~/.ludus-mcp/range-config-templates/' },
      user: { type: 'string', description: 'Target user (admin only)' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['file']
  }
};

// ============================================================================
// STATIC TOOL EXPORTS - Credential & Security
// ============================================================================

export const getCredentialFromUserTool: Tool = {
  name: 'get_credential_from_user',
  description: 'Prompt user to securely enter credentials via popup dialog. Stores in OS keyring. Names must follow LudusCredName-<TargetUser>-<CredName> format.',
  inputSchema: {
    type: 'object',
    properties: {
      credName: { type: 'string', description: 'Credential name (format: LudusCredName-<TargetUser>-<CredName>)' },
      help: { type: 'boolean', description: 'Show credential naming help and examples' }
    },
    required: ['credName']
  }
};

export const insertCredsRangeConfigTool: Tool = {
  name: 'insert_creds_range_config',
  description: 'Replace credential placeholders in range config with actual values from keyring and save the file. Handles {{LudusCredName-<User>-<CredName>}} placeholders securely.\n\n**BEHAVIOR:** Always injects credentials and saves the result. No validation-only mode.\n\n**USAGE WORKFLOW:**\n1. Use list_range_configs to verify configPath exists\n2. Identify placeholders in config (e.g., {{LudusCredName-MP-TailscaleKey}})\n3. Map each placeholder to its credential name in credentialMappings\n4. Credentials must exist in keyring (use get_credential_from_user first if needed)\n5. File is automatically saved with injected credentials\n\n**EXAMPLE:**\n```\ncredentialMappings: {\n  "{{LudusCredName-MP-TailscaleKey}}": "LudusCredName-MP-TailscaleKey",\n  "{{LudusCredName-MP-AdminPass}}": "LudusCredName-MP-AdminPass"\n}\n```\n\n**FILE HANDLING:**\n- No outputPath: Overwrites original file with injected credentials\n- With outputPath: Saves injected version to new file, leaves original unchanged',
  inputSchema: {
    type: 'object',
    properties: {
      configPath: { type: 'string', description: 'Path to range configuration file (use list_range_configs to verify path)' },
      credentialMappings: { 
        type: 'object', 
        description: 'REQUIRED: Mapping of placeholder strings to credential names. Key = placeholder in config, Value = credential name in keyring',
        additionalProperties: { type: 'string' }
      },
      outputPath: { type: 'string', description: 'Output path (optional, if omitted overwrites original file)' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: []
  }
};

// ============================================================================
// STATIC TOOL EXPORTS - Documentation & Search
// ============================================================================

export const ludusDocsSearchTool: Tool = {
  name: 'ludus_docs_search',
  description: 'Search Ludus documentation for configuration help, troubleshooting, and best practices.',
  inputSchema: {
    type: 'object',
    properties: {
      action: { 
        type: 'string', 
        enum: ['search', 'list_categories', 'get_category'],
        description: 'Search action to perform'
      },
      search_query: { type: 'string', description: 'Search terms for documentation' },
      category: { type: 'string', description: 'Specific category to search or retrieve' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['action']
  }
};

export const ludusRolesSearchTool: Tool = {
  name: 'ludus_roles_search',
  description: 'Search Ludus roles documentation for specific roles, variables, and usage examples.',
  inputSchema: {
    type: 'object',
    properties: {
      action: { 
        type: 'string', 
        enum: ['search', 'list_all', 'get_role_details'],
        description: 'Search action to perform'
      },
      search_query: { type: 'string', description: 'Role name or search terms' },
      role_name: { type: 'string', description: 'Specific role name for detailed info' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['action']
  }
};

export const ludusEnvironmentGuidesSearchTool: Tool = {
  name: 'ludus_environment_guides_search',
  description: 'Search environment-specific guides and tutorials for different types of cyber ranges.',
  inputSchema: {
    type: 'object',
    properties: {
      action: { 
        type: 'string', 
        enum: ['search', 'list_guides', 'get_guide'],
        description: 'Search action to perform'
      },
      search_query: { type: 'string', description: 'Environment type or search terms' },
      guide_name: { type: 'string', description: 'Specific guide name' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['action']
  }
};

export const ludusNetworkingSearchTool: Tool = {
  name: 'ludus_networking_search',
  description: 'Search networking documentation for VPN, network topology, and connectivity guidance.',
  inputSchema: {
    type: 'object',
    properties: {
      action: { 
        type: 'string', 
        enum: ['search', 'list_topics', 'get_topic'],
        description: 'Search action to perform'
      },
      search_query: { type: 'string', description: 'Networking topic or search terms' },
      topic_name: { type: 'string', description: 'Specific networking topic' },
      help: { type: 'boolean', description: 'Show help information' }
    },
    required: ['action']
  }
};

export const ludusReadRangeConfigSchemaTool: Tool = {
  name: 'ludus_read_range_config_schema',
  description: 'Direct access to official Ludus range configuration JSON schema. Provides complete structure, validation rules, and property definitions.',
  inputSchema: {
    type: 'object',
    properties: {
      search_terms: {
        type: 'array',
        items: { type: 'string' },
        description: 'Optional array of terms to search for within the schema'
      },
      include_full_schema: {
        type: 'boolean',
        description: 'If true, returns the complete schema',
        default: false
      },
      section_filter: {
        type: 'array',
        items: { 
          type: 'string',
          enum: ['properties', 'definitions', 'required', 'examples', 'enum']
        },
        description: 'Filter to specific schema sections'
      }
    }
  }
};

// ============================================================================
// STATIC TOOL EXPORTS - Utility & Admin
// ============================================================================

export const ludusCliExecuteTool: Tool = {
  name: 'ludus_cli_execute',
  description: 'CRITICAL: Do NOT include "ludus" prefix in command - tool adds it automatically! Execute arbitrary Ludus CLI commands. Provides raw CLI access for advanced operations.',
  inputSchema: {
    type: 'object',
    properties: {
      command: { 
        type: 'string', 
        description: 'The Ludus CLI command to execute (e.g., "--help", "range", "templates", "user"). Do not include "ludus" prefix.'
      },
      args: { 
        type: 'array', 
        items: { type: 'string' },
        description: 'Command arguments as array (e.g., ["logs", "-f"] for "range logs -f"). Optional if arguments are included in command string.'
      },
      user: { type: 'string', description: 'User ID to execute command for (admin only). If omitted, executes for current user.' }
    },
    required: ['command']
  }
};

export const ludusHelpTool: Tool = {
  name: 'ludus_help',
  description: 'Get help information for Ludus CLI commands and subcommands.',
  inputSchema: {
    type: 'object',
    properties: {
      command: { type: 'string', description: 'Command to get help for' },
      subcommand: { type: 'string', description: 'Subcommand to get help for' },
      user: { type: 'string', description: 'User context for help' }
    }
  }
};

export const listAllUsersTool: Tool = {
  name: 'list_all_users',
  description: 'List all users in the Ludus system. Requires admin privileges.',
  inputSchema: {
    type: 'object',
    properties: {
      help: { type: 'boolean', description: 'Show help information' }
    }
  }
};

// ============================================================================
// HANDLER EXPORTS (for server.ts)
// ============================================================================

export { handleLudusRangePlanner } from './ludusRangePlanner.js';
export { handleLudusRangeConfigCheckAgainstPlan } from './ludusRangeConfigCheckAgainstPlan.js';
export { handleLudusReadRoleCollectionSchema } from './ludusReadRoleCollectionSchema.js';
export { handleLudusListRoleCollectionSchemas } from './ludusListRoleCollectionSchemas.js';
export { handleReadRangeConfig, handleWriteRangeConfig, handleValidateRangeConfig, handleListRangeConfigs, handleGetRangeConfig } from './rangeConfig.js';
export { handleSetRangeConfig } from './setRangeConfig.js';
export { handleGetConnectionInfo } from './getConnectionInfo.js';
export { handleDestroyRange } from './destroyRange.js';
export { handleLudusPower } from './ludusPower.js';
export { handleGetCredentialFromUser } from './getCredentialFromUser.js';
export { handleInsertCredsRangeConfig } from './insertCredsRangeConfig.js';
export { handleLudusDocsSearch } from './ludusDocsSearch.js';
export { handleLudusRolesDocsRead } from './ludusRolesSearch.js';
export { handleLudusEnvironmentGuidesSearch } from './ludusEnvironmentGuidesSearch.js';
export { handleLudusNetworkingDocsRead } from './ludusNetworkingSearch.js';
export { handleLudusReadRangeConfigSchema } from './ludusReadRangeConfigSchema.js';
export { handleListAllUsers } from './listAllUsers.js';