XcodeMCP

XcodeMCP

开发 TypeScript

🚀 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
默认排序 时间排序

0 个评论

« 上一篇
Heimdall
下一篇 »
Terminal Mcp Server
  • 0 关注
  • 0 收藏，23 浏览
  • system 提出于 2025-09-25 10:39

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »