Xcode MCP Server

Instructions

Implementation Reference

• src/index.ts:134-154 (handler)

  Core handler logic for executing 'xcode_clean_project': strips 'xcode_' prefix to get 'clean_project', executes via CommandExecutor, formats output/errors into MCP response.

  // Handle Xcode commands
  // Remove 'xcode_' prefix if present
  const commandName = name.startsWith('xcode_') ? name.slice(6) : name;
  const result = await this.commandExecutor.executeCommand(commandName, args);
  
  let responseText = result.output;
  if (result.error) {
    responseText += `\n\nWarnings/Errors:\n${result.error}`;
  }
  if (!result.success) {
    responseText = `Command failed: ${result.error}\n\nCommand executed: ${result.command}`;
  }
  
  return {
    content: [
      {
        type: 'text',
        text: responseText,
      },
    ],

• src/command-executor.ts:281-306 (schema)

  Generates input schema and metadata (name: 'xcode_clean_project', description, inputSchema with parameters from 'clean_project' command definition loaded from commands.json).

  generateMCPToolDefinitions(): Array<{
    name: string;
    description: string;
    inputSchema: any;
  }> {
    return Object.entries(this.commands).map(([name, command]) => ({
      name: `xcode_${name}`,
      description: command.description,
      inputSchema: {
        type: 'object',
        properties: command.parameters ? Object.fromEntries(
          Object.entries(command.parameters).map(([paramName, paramDef]) => [
            paramName,
            {
              type: paramDef.type,
              description: paramDef.description,
              ...(paramDef.default !== undefined && { default: paramDef.default })
            }
          ])
        ) : {},
        required: command.parameters ? Object.entries(command.parameters)
          .filter(([_, paramDef]) => paramDef.required)
          .map(([paramName]) => paramName) : []
      }
    }));
  }

• src/index.ts:52-89 (registration)

  Loads commands from commands.json, generates MCP tool list including 'xcode_clean_project', registers with MCP server via ListToolsRequestSchema handler.

  // Load commands and dynamically create tool list
  await this.commandExecutor.loadCommands();
  const tools = this.commandExecutor.generateMCPToolDefinitions();
  
  // Add web monitor management tools
  const webMonitorTools = [
    {
      name: 'start_web_monitor',
      description: 'Start the web interface for visual command execution and monitoring',
      inputSchema: {
        type: 'object',
        properties: {},
        required: []
      }
    },
    {
      name: 'stop_web_monitor',
      description: 'Stop the web interface if it is running',
      inputSchema: {
        type: 'object',
        properties: {},
        required: []
      }
    },
    {
      name: 'web_monitor_status',
      description: 'Get the current status of the web monitor',
      inputSchema: {
        type: 'object',
        properties: {},
        required: []
      }
    }
  ];
  
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [...tools, ...webMonitorTools],
  }));

• src/command-executor.ts:124-162 (handler)

  Executes the underlying 'clean_project' command: validates params, builds shell command from template, runs via execAsync or internal handler, returns result.

  async executeCommand(name: string, args: Record<string, any> = {}): Promise<{
    success: boolean;
    output: string;
    error?: string;
    command: string;
  }> {
    const command = this.getCommand(name);
    if (!command) {
      throw new Error(`Command '${name}' not found`);
    }
  
    this.validateParameters(command, args);
  
    // Handle internal commands
    if (command.command.startsWith('internal:')) {
      return await this.executeInternalCommand(command, args);
    }
  
    // Handle external commands
    const builtCommand = this.buildCommand(command, args);
  
    try {
      const { stdout, stderr } = await execAsync(builtCommand);
      
      return {
        success: true,
        output: stdout,
        error: stderr || undefined,
        command: builtCommand
      };
    } catch (error) {
      return {
        success: false,
        output: '',
        error: error instanceof Error ? error.message : String(error),
        command: builtCommand
      };
    }
  }