XcodeMCP

🚀 XcodeMCP

XcodeMCP 是一个模型上下文协议（MCP）服务器，它可以通过 JavaScript for Automation（JXA）直接控制 Xcode。它既可以作为 MCP 服务器使用，也可以作为独立的命令行工具（CLI）使用。

🚀 快速开始

要求

• 安装了 Xcode 的 macOS 系统
• Node.js 18 及以上版本
• 建议安装 XCLogParser：brew install xclogparser

安装

XcodeMCP 有两种使用方式：

1. MCP 服务器：可与 Claude Desktop、VS Code 或其他 MCP 客户端集成。
2. 命令行工具：可在终端中直接运行 xcodecontrol 命令。

快速安装

建议安装 XCLogParser，但不是必需的：

brew install xclogparser

从 npm 安装

直接使用 npx 运行：

npx -y xcodemcp@latest

或者全局安装：

npm install -g xcodemcp

MCP 配置

添加到你的 MCP 配置中：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Claude Code CLI 设置

要使用命令行将 XcodeMCP 添加到 Claude Code 中：

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "LOG_LEVEL": "INFO"
  }
}'

开发设置

对于本地开发：

git clone https://github.com/lapfelix/XcodeMCP.git
cd XcodeMCP
npm install

# 在开发模式下运行（TypeScript）
npm run dev:ts

# 或者构建并运行编译后的版本
npm run build
npm start

✨ 主要特性

• 通过 JavaScript for Automation 直接控制 Xcode（而非 xcodebuild CLI）。
• 可以在 Xcode 中打开项目、进行构建、运行、测试和调试。
• 使用 XCLogParser 解析构建日志，能精确定位错误位置。
• 提供全面的环境验证和健康检查。
• 当可选依赖项缺失时，支持优雅降级。
• 新增：包含一个功能齐全的命令行工具（CLI），其功能与 MCP 服务器完全一致。

📦 安装指南

命令行工具安装

要使用命令行工具，需全局安装：

npm install -g xcodemcp

💻 使用示例

命令行工具基本使用

# 显示帮助信息和可用工具
xcodecontrol --help

# 使用标志运行工具
xcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# 获取特定工具的帮助信息
xcodecontrol build --help

# 使用 JSON 输入代替标志
xcodecontrol build --json-input '{"xcodeproj": "/path/to/Project.xcodeproj", "scheme": "MyScheme"}'

# 以 JSON 格式输出结果
xcodecontrol --json health-check

路径解析

命令行工具支持绝对路径和相对路径，使用更方便：

# 绝对路径（传统方式）
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# 相对路径（v2.0.0 新增）
xcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyApp
xcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp

# 也适用于文件路径
xcodecontrol open-file --filePath src/ViewController.swift --lineNumber 42

相对路径会从当前工作目录解析，在项目目录中使用命令行工具时更加便捷。

日志详细程度控制

使用详细程度标志控制日志输出：

# 详细模式（显示 INFO 和 DEBUG 日志）
xcodecontrol -v build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# 安静模式（仅显示错误）
xcodecontrol -q test --xcodeproj /path/to/Project.xcodeproj

# 默认模式（仅显示警告和错误）
xcodecontrol run --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

快速示例

# 检查系统健康状况
xcodecontrol health-check

# 构建项目
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# 运行应用
xcodecontrol run --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# 运行测试
xcodecontrol test --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

# 清理构建目录
xcodecontrol clean --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

# 浏览 XCResult 文件
xcodecontrol xcresult-browse --xcresult-path /path/to/result.xcresult

# 从测试失败中获取 UI 层次结构
xcodecontrol xcresult-get-ui-hierarchy --xcresult-path /path/to/result.xcresult --test-id "MyTest/testMethod()" --timestamp 30.5

工具名称映射

命令行工具的命令使用短横线分隔（kebab-case），而非下划线：

• xcode_build → build
• xcode_test → test
• xcode_run → run
• xcode_health_check → health-check
• xcresult_browse → xcresult-browse
• find_xcresults → find-xcresults

📚 详细文档

可用工具

项目管理

• xcode_open_project - 打开项目和工作区
• xcode_get_workspace_info - 获取工作区状态和详细信息
• xcode_get_projects - 列出工作区中的项目
• xcode_open_file - 打开文件，可指定行号

构建操作

• xcode_build - 进行构建，并详细解析错误
• xcode_clean - 清理构建产物
• xcode_test - 运行测试，可传递可选参数
• xcode_run - 运行活动方案
• xcode_debug - 启动调试会话
• xcode_stop - 停止当前操作

配置

• xcode_get_schemes - 列出可用方案
• xcode_set_active_scheme - 切换活动方案
• xcode_get_run_destinations - 列出模拟器和设备

XCResult 分析

• xcresult_browse - 浏览测试结果，分析失败情况
• xcresult_browser_get_console - 获取特定测试的控制台输出
• xcresult_summary - 快速查看测试结果概述
• xcresult_get_screenshot - 从测试失败中提取截图
• xcresult_get_ui_hierarchy - 获取 UI 层次结构，以 AI 可读的 JSON 格式输出，可选择时间戳
• xcresult_get_ui_element - 通过索引获取特定 UI 元素的详细属性
• xcresult_list_attachments - 列出测试的所有附件
• xcresult_export_attachment - 从测试结果中导出特定附件

诊断

• xcode_health_check - 进行环境验证和故障排除

XCResult 分析功能

XcodeMCP 提供了全面的工具来分析 Xcode 测试结果（.xcresult 文件），便于调试测试失败情况并提取有价值的信息：

测试结果分析

• 浏览结果：浏览测试层次结构，查看通过/失败状态，检查详细的测试信息。
• 控制台日志：提取控制台输出和测试活动，带有精确的时间戳，便于调试。
• 快速摘要：获取概述统计信息，包括通过率、失败次数和持续时间。

可视化调试

• 截图提取：使用 ffmpeg 从视频附件中提取帧，从测试失败中提取 PNG 截图。
• 时间戳精度：指定精确的时间戳，捕获测试执行过程中特定时刻的 UI 状态。

UI 层次结构分析

• AI 可读格式：以压缩的 JSON 格式提取 UI 层次结构，使用单字母属性（t=类型，l=标签，f=框架，c=子元素，j=索引）。
• 时间戳选择：自动找到最接近指定时间戳的 UI 层次结构捕获。
• 元素深入分析：使用索引引用获取任何 UI 元素的完整详细信息，包括可访问性属性和框架信息。
• 大小优化：与完整的层次结构数据相比，大小减少 75% 以上，同时保留所有必要信息。

附件管理

• 完整清单：列出任何测试的所有附件（截图、视频、调试描述、UI 层次结构）。
• 选择性导出：按索引或类型导出特定附件。
• 智能检测：自动识别和分类不同的附件类型。

使用示例

# 浏览测试结果
xcresult_browse "/path/to/TestResults.xcresult"

# 获取控制台输出以查找失败时间戳
xcresult_browser_get_console "/path/to/TestResults.xcresult" "MyTest/testMethod()"

# 获取特定时间戳的 UI 层次结构（AI 可读精简版本）
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25

# 获取完整的 UI 层次结构（有大小警告）
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25 true

# 获取特定 UI 元素的详细属性
xcresult_get_ui_element "/path/to/ui_hierarchy_full.json" 15

# 在失败点提取截图
xcresult_get_screenshot "/path/to/TestResults.xcresult" "MyTest/testMethod()" 30.71

配置

日志配置

XcodeMCP 支持可配置的日志记录，有助于调试和监控：

环境变量

• LOG_LEVEL：控制日志详细程度（默认：INFO）

  • SILENT：无日志输出
  • ERROR：仅输出错误消息
  • WARN：输出警告和错误
  • INFO：输出一般操作信息（推荐）
  • DEBUG：输出详细的诊断信息

• XCODEMCP_LOG_FILE：可选的日志文件路径

  • 日志除了输出到 stderr 外，还会写入指定的文件。
  • 父目录会自动创建。
  • 示例：/tmp/xcodemcp.log 或 ~/Library/Logs/xcodemcp.log

• XCODEMCP_CONSOLE_LOGGING：启用/禁用控制台输出（默认：true）

  • 设置为 false 可禁用 stderr 日志记录（仅使用文件日志时有用）

示例

调试日志记录并输出到文件：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "XCODEMCP_LOG_FILE": "~/Library/Logs/xcodemcp.log"
      }
    }
  }
}

静默模式（无日志记录）：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx", 
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "SILENT"
      }
    }
  }
}

仅记录到文件：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"], 
      "env": {
        "LOG_LEVEL": "INFO",
        "XCODEMCP_LOG_FILE": "/tmp/xcodemcp.log",
        "XCODEMCP_CONSOLE_LOGGING": "false"
      }
    }
  }
}

所有日志都带有时间戳和日志级别，格式规范，stderr 输出与 MCP 协议保持兼容。

故障排除

未找到 XCLogParser

如果你看到未找到 XCLogParser 的警告，即使它已经安装：

1. 验证安装：

   which xclogparser
   xclogparser version
   

2. 常见问题及解决方案：

   • PATH 问题：如果 which xclogparser 没有返回结果，将安装目录添加到你的 PATH 中：

     # 英特尔 Mac 上的 Homebrew
     export PATH="/usr/local/bin:$PATH"
     
     # 苹果硅芯片 Mac 上的 Homebrew
     export PATH="/opt/homebrew/bin:$PATH"
     

   • 错误命令：旧文档可能引用 xclogparser --version，但正确的命令是 xclogparser version（无短横线）。

   • 权限问题：确保 xclogparser 可执行：

     chmod +x $(which xclogparser)
     

3. 环境验证：运行健康检查以获取详细诊断信息：

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "xcode_health_check", "arguments": {}}}' | npx xcodemcp
   

注意：XcodeMCP 可以在没有 XCLogParser 的情况下运行，但构建错误解析功能将受到限制。

示例输出

构建出错

❌ BUILD FAILED (2 errors)

ERRORS:
  • /path/HandsDownApp.swift:7:18: Expected 'func' keyword in instance method declaration
  • /path/MenuBarManager.swift:98:13: Invalid redeclaration of 'toggleItem'

健康检查

✅ All systems operational

✅ OS: macOS environment detected
✅ XCODE: Xcode found at /Applications/Xcode.app (version 16.4)
✅ XCLOGPARSER: XCLogParser found (XCLogParser 0.2.41)
✅ OSASCRIPT: JavaScript for Automation (JXA) is available
✅ PERMISSIONS: Xcode automation permissions are working