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