XC-MCP: XCode CLI wrapper

Instructions

Implementation Reference

• src/tools/xcodebuild/version.ts:47-112 (handler)

  Core handler function that executes the xcodebuild -version command, handles optional sdk and outputFormat parameters, parses JSON or text output, and returns structured MCP content.

  export async function xcodebuildVersionTool(args: any) {
    const { sdk, outputFormat = 'json' } = args as VersionToolArgs;
  
    try {
      // Build command
      let command = 'xcodebuild -version';
  
      if (sdk) {
        command += ` -sdk ${sdk}`;
      }
  
      if (outputFormat === 'json') {
        command += ' -json';
      }
  
      // Execute command
      const result = await executeCommand(command);
  
      if (result.code !== 0) {
        throw new McpError(
          ErrorCode.InternalError,
          `Failed to get version information: ${result.stderr}`
        );
      }
  
      let responseText: string;
  
      if (outputFormat === 'json') {
        try {
          // Parse and format JSON response
          const versionInfo = JSON.parse(result.stdout);
          responseText = JSON.stringify(versionInfo, null, 2);
        } catch {
          // If JSON parsing fails, the output might be plain text
          // This can happen with older Xcode versions
          responseText = JSON.stringify(
            {
              version: result.stdout,
              format: 'text',
            },
            null,
            2
          );
        }
      } else {
        responseText = result.stdout;
      }
  
      return {
        content: [
          {
            type: 'text' as const,
            text: responseText,
          },
        ],
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `xcodebuild-version failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/registry/xcodebuild.ts:44-66 (registration)

  MCP server tool registration for 'xcodebuild-version', including Zod inputSchema validation, description from docs, defer loading config, and wrapper handler that validates Xcode installation before calling the core handler.

  server.registerTool(
    'xcodebuild-version',
    {
      description: getDescription(XCODEBUILD_VERSION_DOCS, XCODEBUILD_VERSION_DOCS_MINI),
      inputSchema: {
        sdk: z.string().optional(),
        outputFormat: z.enum(['json', 'text']).default('json'),
      },
      ...DEFER_LOADING_CONFIG,
    },
    async args => {
      try {
        await validateXcodeInstallation();
        return await xcodebuildVersionTool(args);
      } catch (error) {
        if (error instanceof McpError) throw error;
        throw new McpError(
          ErrorCode.InternalError,
          `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
        );
      }
    }
  );

• src/registry/xcodebuild.ts:48-51 (schema)

  Zod input schema defining optional 'sdk' string parameter and 'outputFormat' enum with default 'json'.

  inputSchema: {
    sdk: z.string().optional(),
    outputFormat: z.enum(['json', 'text']).default('json'),
  },

• src/tools/xcodebuild/version.ts:114-159 (helper)

  Full and mini documentation strings for the tool, used in registration description and rtfm tool.

  export const XCODEBUILD_VERSION_DOCS = `
  # xcodebuild-version
  
  ⚡ **Get Xcode and SDK version information** with structured output
  
  ## What it does
  
  Retrieves comprehensive version information about your Xcode installation and available SDKs. Returns structured JSON data that's easy to parse and validate, eliminating the need to parse raw command-line output. Validates Xcode installation before execution to provide clear error messages if Xcode is not properly configured.
  
  ## Why you'd use it
  
  - Validate environment before running builds or tests (CI/CD validation)
  - Check SDK availability for specific platform versions
  - Ensure consistent Xcode versions across team or build environments
  - Get structured version data for automated tooling and scripts
  
  ## Parameters
  
  ### Optional
  - **sdk** (string): Query specific SDK version (e.g., "iphoneos", "iphonesimulator")
  - **outputFormat** (string, default: 'json'): "json" or "text" output format
  
  ## Returns
  
  Structured JSON response containing Xcode version, build number, and SDK information. Falls back gracefully to text format for older Xcode versions that don't support JSON output.
  
  ## Examples
  
  ### Get Xcode version as JSON
  \`\`\`typescript
  const result = await xcodebuildVersionTool({ outputFormat: "json" });
  \`\`\`
  
  ### Query specific SDK
  \`\`\`typescript
  const sdkInfo = await xcodebuildVersionTool({ sdk: "iphoneos" });
  \`\`\`
  
  ## Related Tools
  
  - xcodebuild-showsdks: Show all available SDKs
  - xcodebuild-list: List project information
  `;
  
  export const XCODEBUILD_VERSION_DOCS_MINI =
    'Get Xcode and SDK version info. Use rtfm({ toolName: "xcodebuild-version" }) for docs.';