MCP Playground Server

Instructions

Implementation Reference

• src/index.ts:138-151 (handler)

  MCP tool handler that extracts the command argument, calls the suggester's validateCommand method, and formats the result as MCP content response.

  private async handleCommandValidate(args: any) {
    const { command } = args;
    
    const validation = await this.suggester.validateCommand(command);
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(validation, null, 2),
        },
      ],
    };
  }

• src/suggester.ts:159-247 (helper)

  Core implementation of command validation: parses command parts, validates against command structure from parser, checks for unknown commands/options, required options, provides suggestions and errors.

  async validateCommand(command: string): Promise<ValidationResult> {
    const result: ValidationResult = {
      valid: true,
      errors: [],
      warnings: [],
      suggestions: []
    };
  
    const parts = command.trim().split(' ').filter(p => p.length > 0);
    
    if (parts.length === 0) {
      result.valid = false;
      result.errors.push('Empty command');
      return result;
    }
  
    // Check if starts with 'playground'
    if (parts[0] !== 'playground') {
      result.valid = false;
      result.errors.push('Command must start with "playground"');
      return result;
    }
  
    const commandParts = parts.slice(1).filter(part => !part.startsWith('--'));
    const optionParts = parts.slice(1).filter(part => part.startsWith('--'));
  
    // Validate command path
    if (commandParts.length === 0) {
      result.valid = false;
      result.errors.push('No command specified');
      return result;
    }
  
    const foundCommand = this.parser.findCommand(commandParts);
    if (!foundCommand) {
      result.valid = false;
      result.errors.push(`Unknown command: ${commandParts.join(' ')}`);
      
      // Suggest similar commands
      const suggestions = await this.getSuggestions(commandParts.join(' '));
      result.suggestions = suggestions.slice(0, 3).map(s => s.completion);
      
      return result;
    }
  
    // Validate options
    const providedOptions = new Set<string>();
    for (let i = 0; i < optionParts.length; i++) {
      const optionPart = optionParts[i];
      const optionName = optionPart.replace(/^--?/, '');
      
      const option = foundCommand.options?.find(opt => opt.name === optionName);
      if (!option) {
        result.valid = false;
        result.errors.push(`Unknown option: ${optionPart}`);
        continue;
      }
  
      if (providedOptions.has(optionName) && !option.repeatable) {
        result.warnings.push(`Option --${optionName} specified multiple times but is not repeatable`);
      }
      
      providedOptions.add(optionName);
    }
  
    // Check required options
    foundCommand.options?.forEach(option => {
      if (option.required && !providedOptions.has(option.name)) {
        result.valid = false;
        result.errors.push(`Missing required option: --${option.name}`);
      }
    });
  
    // Check if command needs subcommands
    if (foundCommand.subcommands && foundCommand.subcommands.length > 0) {
      // Check if this is a terminal command or needs subcommands
      const hasSubcommand = commandParts.length > 1;
      if (!hasSubcommand) {
        result.warnings.push('This command has subcommands available');
        result.suggestions.push(
          ...foundCommand.subcommands.slice(0, 3).map(sub => 
            `playground ${commandParts.join(' ')} ${sub.name}`
          )
        );
      }
    }
  
    return result;
  }

• src/index.ts:59-72 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema.

  {
    name: "playground_command_validate",
    description: "Validate a complete playground command and suggest corrections",
    inputSchema: {
      type: "object",
      properties: {
        command: {
          type: "string",
          description: "Complete playground command to validate",
        },
      },
      required: ["command"],
    },
  },

• src/index.ts:62-71 (schema)

  Input schema definition for the playground_command_validate tool.

  inputSchema: {
    type: "object",
    properties: {
      command: {
        type: "string",
        description: "Complete playground command to validate",
      },
    },
    required: ["command"],
  },