Xcode MCP Server

Instructions

Implementation Reference

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

  Main handler implementing the run_tests tool logic: runs xcodebuild tests with filtering options, captures and processes output, generates logs, test reports, and code coverage.

  private async runTests(
      projectPath: string,
      scheme: string,
      configuration: string = "Debug",
      testIdentifier?: string,
      skipTests?: string[],
      destination: string = "platform=iOS Simulator,name=iPhone 15 Pro"
  ): Promise<{ success: boolean; output: string; logPath: string }> {
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
      const logPath = path.join(this.buildLogsDir, `test-${timestamp}.log`);
      const projectDir = path.dirname(projectPath);
      const reportsPath = path.join(projectDir, 'TestReports', `Reports-${timestamp}`);
      const xcresultPath = `${reportsPath}.xcresult`;
  
      try {
          await mkdir(path.join(projectDir, 'TestReports'), { recursive: true });
      } catch (error) {
          console.error(`Failed to prepare test reports directory: ${error}`);
      }
  
      let testFlags = 'test';
      if (testIdentifier) {
          testFlags += ` -only-testing:${testIdentifier}`;
      }
      if (skipTests?.length) {
          testFlags += ` ${skipTests.map(test => `-skip-testing:${test}`).join(' ')}`;
      }
  
      const command = `which xcodebuild && xcodebuild -project "${projectPath}" \
          -scheme "${scheme}" \
          -configuration "${configuration}" \
          -destination '${destination}' \
          -resultBundlePath "${xcresultPath}" \
          -enableCodeCoverage YES \
          -UseModernBuildSystem=YES \
          -json \
          clean ${testFlags} 2>&1 | tee ${logPath}`;
  
      try {
          const { stdout, stderr } = await execAsync(command, { maxBuffer: 100 * 1024 * 1024 });
  
          try {
              const jsonOutput = stdout.split('\n')
                  .filter(line => line.trim())
                  .map(line => {
                      try { return JSON.parse(line); }
                      catch (e) { return line; }
                  });
              await writeFile(logPath + '.json', JSON.stringify(jsonOutput, null, 2));
          } catch (parseError) {
              console.error('Failed to parse JSON output:', parseError);
          }
  
          // Process test results using xcresulttool
          if (fs.existsSync(xcresultPath)) {
              try {
                  // Get test summary
                  const summaryCmd = `xcrun xcresulttool get --format json --path "${xcresultPath}"`;
                  const { stdout: summaryOutput } = await execAsync(summaryCmd);
                  await writeFile(path.join(this.buildLogsDir, `test-summary-${timestamp}.json`), summaryOutput);
  
                  // Get code coverage if available
                  const coverageOutput = await execAsync(`xcrun xccov view --report "${xcresultPath}"`);
                  await writeFile(path.join(this.buildLogsDir, `coverage-${timestamp}.txt`), coverageOutput.stdout);
              } catch (resultsError) {
                  console.error('Failed to process test results:', resultsError);
              }
          }
  
          const success = !stdout.includes('** TEST FAILED **') && !stdout.includes('** BUILD FAILED **');
          return { success, output: stdout + stderr, logPath };
      } catch (error) {
          console.error('Test error:', error);
          if (error instanceof Error) {
              const execError = error as { stderr?: string };
              const errorOutput = error.message + (execError.stderr ? `\n${execError.stderr}` : '');
              await writeFile(logPath, errorOutput);
              return { success: false, output: errorOutput, logPath };
          }
          throw error;
      }
  }

• src/index.ts:295-325 (registration)

  Registers the "run_tests" tool in the MCP ListToolsRequestSchema handler, defining its name, description, and JSON input schema.

      name: "run_tests",
      description: "Run Xcode project tests with optional filtering",
      inputSchema: {
          type: "object",
          properties: {
              projectPath: {
                  type: "string",
                  description: "Path to the .xcodeproj or .xcworkspace"
              },
              scheme: {
                  type: "string",
                  description: "Test scheme name"
              },
              testIdentifier: {
                  type: "string",
                  description: "Optional specific test to run (e.g., 'MyTests/testExample')"
              },
              skipTests: {
                  type: "array",
                  items: { type: "string" },
                  description: "Optional array of test identifiers to skip"
              },
              configuration: {
                  type: "string",
                  description: "Build configuration (e.g., Debug, Release)",
                  default: "Debug"
              }
          },
          required: ["projectPath", "scheme"]
      }
  }]

• src/index.ts:32-73 (schema)

  TypeScript interface and type guard for validating run_tests tool input arguments.

  interface TestArguments {
      projectPath: string;
      scheme: string;
      testIdentifier?: string;
      skipTests?: string[];
      configuration?: string;
      destination?: string;
  }
  
  interface BuildOptions extends BuildArguments {
      includeWarnings?: boolean;
  }
  
  interface TestOptions extends TestArguments {
      includeWarnings?: boolean;
  }
  
  // Add these type guard functions
  function isBuildOptions(args: unknown): args is BuildOptions {
      if (!isBuildArguments(args)) return false;
      const a = args as Partial<BuildOptions>;
      return a.includeWarnings === undefined || typeof a.includeWarnings === 'boolean';
  }
  
  function isTestOptions(args: unknown): args is TestOptions {
      if (!isTestArguments(args)) return false;
      const a = args as Partial<TestOptions>;
      return a.includeWarnings === undefined || typeof a.includeWarnings === 'boolean';
  }
  
  function isTestArguments(args: unknown): args is TestArguments {
      if (typeof args !== 'object' || args === null) return false;
      const a = args as Partial<TestArguments>;
      return (
          typeof a.projectPath === 'string' &&
          typeof a.scheme === 'string' &&
          (a.testIdentifier === undefined || typeof a.testIdentifier === 'string') &&
          (a.skipTests === undefined || (Array.isArray(a.skipTests) && a.skipTests.every(t => typeof t === 'string'))) &&
          (a.configuration === undefined || typeof a.configuration === 'string') &&
          (a.destination === undefined || typeof a.destination === 'string')
      );
  }

• src/index.ts:346-366 (handler)

  MCP CallToolRequestSchema dispatch case for "run_tests": validates arguments and invokes the runTests handler.

  case "run_tests": {
      if (!isTestArguments(request.params.arguments)) {
          throw new McpError(ErrorCode.InvalidParams, "Invalid test arguments provided");
      }
      const result = await this.runTests(
          request.params.arguments.projectPath,
          request.params.arguments.scheme,
          request.params.arguments.configuration,
          request.params.arguments.testIdentifier,
          request.params.arguments.skipTests,
          request.params.arguments.destination
      );
      this.latestBuildLog = result.logPath;
      return {
          content: [{
              type: "text",
              text: result.output
          }],
          isError: !result.success
      };
  }