Xcode MCP Server

Instructions

Implementation Reference

• src/index.ts:91-171 (handler)

  MCP CallToolRequestSchema handler that processes tool calls. For 'xcode_*' tools like 'xcode_list_simulators_json', strips 'xcode_' prefix and calls CommandExecutor.executeCommand with the remaining command name and arguments.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    try {
      // Handle web monitor tools
      if (name === 'start_web_monitor') {
        const result = await this.webMonitorManager.start();
        return {
          content: [
            {
              type: 'text',
              text: `${result.message}\n\nWeb interface available at: ${result.url}`
            }
          ]
        };
      }
      
      if (name === 'stop_web_monitor') {
        const result = this.webMonitorManager.stop();
        return {
          content: [
            {
              type: 'text',
              text: result.message
            }
          ]
        };
      }
      
      if (name === 'web_monitor_status') {
        const status = this.webMonitorManager.getStatus();
        let text = status.running 
          ? `Web monitor is running at ${status.url} (port ${status.port})`
          : 'Web monitor is not running';
        return {
          content: [
            {
              type: 'text',
              text: text
            }
          ]
        };
      }
      
      // 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,
          },
        ],
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${errorMessage}`,
          },
        ],
      };
    }
  });

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

  Core execution handler for individual commands (e.g., 'list_simulators_json'). Builds shell command from template, validates params, executes via child_process.exec, returns output/error.

  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
      };
    }
  }

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

  Generates input schema and tool metadata for MCP registration. Creates tool names like 'xcode_list_simulators_json' from loaded command definitions with corresponding input schemas.

  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:87-89 (registration)

  Registers all dynamically generated Xcode tools (including 'xcode_list_simulators_json') with MCP ListToolsRequestSchema handler.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [...tools, ...webMonitorTools],
  }));

• src/command-executor.ts:85-122 (helper)

  Helper that constructs the actual shell command string by replacing placeholders {param} in command templates with argument values, handling optionals, booleans, and cleanup.

  buildCommand(command: XcodeCommand, args: Record<string, any>): string {
    let builtCommand = command.command;
  
    // Replace required parameters
    if (command.parameters) {
      for (const [paramName, paramDef] of Object.entries(command.parameters)) {
        const value = args[paramName] !== undefined ? args[paramName] : paramDef.default;
        
        if (paramDef.type === 'boolean') {
          // Handle boolean parameters
          if (value === true) {
            // Replace placeholder with the template if true
            builtCommand = builtCommand.replace(`{${paramName}}`, paramDef.template || '');
          } else {
            // Remove placeholder if false
            builtCommand = builtCommand.replace(`{${paramName}}`, '');
          }
        } else if (value !== undefined && value !== null && value !== '') {
          if (paramDef.template) {
            // Use custom template for parameter
            const paramValue = paramDef.template.replace(`{${paramName}}`, value);
            builtCommand = builtCommand.replace(`{${paramName}}`, paramValue);
          } else {
            // Direct replacement
            builtCommand = builtCommand.replace(`{${paramName}}`, value);
          }
        } else {
          // Remove optional parameter placeholders
          builtCommand = builtCommand.replace(new RegExp(`\\s*\\{${paramName}\\}`, 'g'), '');
        }
      }
    }
  
    // Clean up any remaining placeholder patterns
    builtCommand = builtCommand.replace(/\s+/g, ' ').trim();
    
    return builtCommand;
  }