STARWARCLOUD STARWAR.AI
返回市场
XcodeMCP服务器

XcodeMCP服务器

作者：lapfelix44 星标更新：2025-10-21
安装使用来源：spider==github.com

项目介绍

XcodeMCP

npm 版本 测试状态

Model Context Protocol (MCP) 服务器，通过 JavaScript for Automation (JXA) 直接控制 Xcode。可用作 MCP 服务器或独立的命令行工具。

功能

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

系统要求

  • 安装了 Xcode 的 macOS
  • Node.js 18+
  • XCLogParser（推荐）：brew install xclogparser

使用方法

XcodeMCP 可以通过两种方式使用：

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

快速安装

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=安装服务器&color=0098FF" alt="在 VS Code 中安装"> <img alt="在 VS Code Insiders 中安装" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=安装服务器&color=24bfa5"> <img src="https://cursor.com/deeplink/mcp-install-dark.svg" height=20 alt="安装 MCP 服务器">

推荐但可选地安装 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": {
      }
    }
  }
}

Claude Code CLI 设置

要通过命令行将 XcodeMCP 添加到 Claude Code：

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

不使用清理构建文件夹工具

要通过命令行将 XcodeMCP 添加到 Claude Code：

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

使用单个项目工作流的首选值

对于仅处理一个 xcodeproj 和方案的项目，可以配置首选值使工具参数变为可选：

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "XCODE_MCP_PREFERRED_SCHEME": "MyApp",
    "XCODE_MCP_PREFERRED_XCODEPROJ": "MyApp.xcodeproj"
  }
}'

配置首选值后：

  • 工具参数变为可选而非必填
  • 工具描述显示默认值（例如，默认为 MyApp.xcodeproj）
  • 仍可通过提供显式参数覆盖默认值
  • 减少在单一项目上工作的重复操作

故障排除

如果 Claude Code 中的 /mcp 表明 MCP 失败，请尝试手动从项目文件夹运行以查看输出：npx -y xcodemcp@latest

开发设置

本地开发：

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

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

# 或编译并运行已编译版本
npm run build
npm start

命令行工具使用方法

XcodeMCP 包含一个强大的命令行工具，提供了与 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

工具名称映射

命令行命令使用短横线命名法而不是下划线：

  • xcode_build → build
  • xcode_test → test
  • xcode_build_and_run → build-and-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_build_and_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 - 获取 AI 可读的 JSON 格式的 UI 层次结构，并选择时间戳
  • xcresult_get_ui_element - 通过索引获取特定 UI 元素的详细属性
  • xcresult_list_attachments - 列出所有测试的附件
  • xcresult_export_attachment - 导出特定测试结果的附件

诊断：

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

XCResult 分析特性

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

测试结果分析

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

视觉调试

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

UI 层次结构分析

  • AI 可读格式：提取 UI 层次结构为压缩的 JSON，具有单字母属性（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：可选的日志文件路径

    • 日志写入指定文件以及标准错误输出
    • 自动创建父目录
    • 示例：/tmp/xcodemcp.log 或 ~/Library/Logs/xcodemcp.log

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

    • 设置为 false 以禁用标准错误日志输出（仅使用文件日志时有用）

示例

调试日志并输出到文件：

{
  "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"
      }
    }
  }
}

所有日志都正确格式化，带有时间戳和日志级别，标准错误输出保持与 MCP 协议兼容。

故障排除

XCLogParser 未找到

即使已安装，但看到 XCLogParser 未找到的警告：

  1. 验证安装：

    which xclogparser
xclogparser version

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

    • PATH 问题：如果 which xclogparser 返回空，请将安装目录添加到 PATH：

      # 对于 Intel Mac 上的 Homebrew
export PATH="/usr/local/bin:$PATH"

# 对于 Apple Silicon 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 的情况下运行，但构建错误解析将受到限制。

输出示例

构建有错误：

❌ 构建失败 (2 个错误)

错误：
  • /path/HandsDownApp.swift:7:18: 期望在实例方法声明中使用 'func' 关键字
  • /path/MenuBarManager.swift:98:13: 'toggleItem' 的无效重新声明

健康检查：

✅ 所有系统正常运行

✅ 操作系统：检测到 macOS 环境
✅ XCODE：在 /Applications/Xcode.app 找到 Xcode（版本 16.4）
✅ XCLOGPARSER：找到 XCLogParser（XCLogParser 0.2.41）
✅ OSASCRIPT：JavaScript for Automation (JXA) 可用
✅ 权限：Xcode 自动化权限正常