MCP Playground Server

Instructions

Implementation Reference

• src/index.ts:120-136 (handler)

  MCP tool handler function that processes the tool call, invokes the suggester for suggestions, retrieves command structure from parser, and returns formatted JSON response.

  private async handleCommandSuggest(args: any) {
    const { partial_command, context } = args;
    
    const suggestions = await this.suggester.getSuggestions(partial_command, context);
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            suggestions,
            command_structure: this.parser.getCommandStructure(partial_command),
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:44-57 (schema)

  Input schema definition for the playground_command_suggest tool, specifying parameters partial_command (required) and optional context.

  inputSchema: {
    type: "object",
    properties: {
      partial_command: {
        type: "string",
        description: "Partial playground command to complete",
      },
      context: {
        type: "string",
        description: "Additional context about what you're trying to do",
      },
    },
    required: ["partial_command"],
  },

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

  Tool registration in ListTools response, defining name, description, and input schema.

  {
    name: "playground_command_suggest",
    description: "Get command suggestions and completions for the Kafka Docker Playground CLI",
    inputSchema: {
      type: "object",
      properties: {
        partial_command: {
          type: "string",
          description: "Partial playground command to complete",
        },
        context: {
          type: "string",
          description: "Additional context about what you're trying to do",
        },
      },
      required: ["partial_command"],
    },
  },
  {

• src/suggester.ts:24-56 (helper)

  Core helper function implementing the suggestion logic: parses partial command, handles top-level, command, and option suggestions by delegating to specialized methods.

  async getSuggestions(partialCommand: string, context?: string): Promise<CommandSuggestion[]> {
    const suggestions: CommandSuggestion[] = [];
    const parts = partialCommand.trim().split(' ').filter(p => p.length > 0);
    
    // Remove 'playground' if it's the first part
    if (parts.length > 0 && parts[0] === 'playground') {
      parts.shift();
    }
  
    if (parts.length === 0) {
      // Suggest top-level commands
      const commands = this.parser.getCommands();
      commands.forEach(cmd => {
        suggestions.push({
          completion: `playground ${cmd.name}`,
          description: cmd.description || '',
          type: 'command',
          score: 1.0
        });
      });
      return suggestions;
    }
  
    // Check if the last part is incomplete (doesn't start with --)
    const lastPart = parts[parts.length - 1];
    const isOption = lastPart.startsWith('--');
    
    if (isOption) {
      return this.getOptionSuggestions(parts);
    } else {
      return this.getCommandSuggestions(parts, context);
    }
  }

• src/suggester.ts:99-136 (helper)

  Helper method for suggesting option completions and values based on partial option name and command context.

  private getOptionSuggestions(parts: string[]): CommandSuggestion[] {
    const suggestions: CommandSuggestion[] = [];
    const lastPart = parts[parts.length - 1];
    const optionName = lastPart.replace(/^--?/, '');
    
    // Find the command these options belong to
    const commandParts = parts.filter(part => !part.startsWith('--'));
    const command = this.parser.findCommand(commandParts);
    
    if (!command?.options) {
      return suggestions;
    }
  
    // Suggest matching options
    command.options.forEach(option => {
      if (option.name.startsWith(optionName)) {
        const fullCommand = commandParts.join(' ');
        const completion = `playground ${fullCommand} --${option.name}`;
        
        suggestions.push({
          completion,
          description: option.description || '',
          type: 'option',
          score: this.calculateScore(option.name, optionName)
        });
  
        // If option has predefined values, suggest them too
        if (option.values) {
          option.values.forEach(value => {
            suggestions.push({
              completion: `${completion} ${value}`,
              description: `${option.description} (value: ${value})`,
              type: 'value',
              score: 0.9
            });
          });
        }
      }