Xcode MCP Server

Instructions

Implementation Reference

• src/index.ts:96-106 (handler)

  MCP CallToolRequestSchema handler block that executes the 'start_web_monitor' tool by invoking WebMonitorManager.start() and formatting the response with the URL.

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

• src/index.ts:58-66 (schema)

  Tool schema definition for 'start_web_monitor' including name, description, and empty input schema (no parameters required).

  {
    name: 'start_web_monitor',
    description: 'Start the web interface for visual command execution and monitoring',
    inputSchema: {
      type: 'object',
      properties: {},
      required: []
    }
  },

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

  Defines the webMonitorTools array (including start_web_monitor) and registers them by including in the ListToolsRequestSchema response.

  // 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/web-monitor-manager.ts:44-113 (helper)

  WebMonitorManager.start() method: core logic for starting the web monitor - finds available port, spawns web-server process, waits for startup, handles errors and cleanup.

  async start(): Promise<{ url: string; port: number; message: string }> {
    if (this.isRunning && this.webServerProcess) {
      return {
        url: `http://localhost:${this.port}`,
        port: this.port,
        message: 'Web monitor is already running'
      };
    }
  
    try {
      // Find an available port
      this.port = await this.findAvailablePort();
      
      // Spawn the web server process
      const webServerPath = join(__dirname, 'web-server.js');
      
      console.error(`[WebMonitor] Starting web server at ${webServerPath} on port ${this.port}`);
      
      this.webServerProcess = spawn('node', [webServerPath], {
        env: { ...process.env, PORT: this.port.toString() },
        stdio: ['ignore', 'pipe', 'pipe'],
        detached: false
      });
  
      // Wait for the "running at" message
      await new Promise<void>((resolve, reject) => {
        const timeout = setTimeout(() => {
          reject(new Error('Web server failed to start within timeout'));
        }, 5000);
  
        if (this.webServerProcess!.stdout) {
          this.webServerProcess!.stdout.on('data', (data) => {
            const output = data.toString();
            if (output.includes('running at')) {
              clearTimeout(timeout);
              resolve();
            }
          });
        }
  
        this.webServerProcess!.on('error', (err) => {
          clearTimeout(timeout);
          reject(err);
        });
  
        this.webServerProcess!.on('exit', (code) => {
          clearTimeout(timeout);
          reject(new Error(`Web server exited with code ${code}`));
        });
      });
  
      this.isRunning = true;
  
      // Handle process cleanup
      this.webServerProcess.on('exit', () => {
        this.isRunning = false;
        this.webServerProcess = null;
      });
  
      const url = `http://localhost:${this.port}`;
      return {
        url,
        port: this.port,
        message: `Web monitor started successfully at ${url}`
      };
    } catch (error) {
      this.stop();
      throw error;
    }
  }