Xcode MCP

🚀 Xcode MCP 服務器

Xcode MCP 服務器是一款全面的模型上下文協議（MCP）服務器，專為 Xcode 開發自動化量身打造。它提供了 115 種以上的工具，涵蓋項目管理、構建、測試、模擬器控制、崩潰報告、資源管理、本地化以及由人工智能驅動的工作流程等多個方面，極大地提升了 Xcode 開發的效率和便捷性。

🚀 快速開始

前提條件

• macOS（用於 Xcode 工具）
• Python 3.11 或更高版本
• Conda（推薦）或 pip
• Xcode 命令行工具

安裝

# 克隆倉庫
git clone <repository-url>
cd xcode-mcp

# 創建 conda 環境
conda env create -f environment.yml
conda activate xcode-mcp

# 或者使用 pip
pip install -r requirements.txt

Cursor 配置

將以下內容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "/path/to/miniconda3/envs/xcode-mcp/bin/python",
      "args": [
        "/path/to/xcode-mcp/run_unified_mcp.py"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "your-api-key-here"
      }
    }
  }
}

重啟 Cursor 以加載 MCP 服務器。

✨ 主要特性

• 112 個直接 Xcode 工具：針對常見任務提供快速、單步操作。
• 3 個 LangGraph 子代理工具：具備推理和狀態管理功能的多步工作流。
• 21 個新工具：包括崩潰報告、資源管理、本地化和模擬器增強功能。
• 統一服務器：單個 MCP 服務器整合所有功能。
• 令牌優化：通過緩存和壓縮減少 30 - 40% 的令牌使用量。
• 超特定模式：包含示例和驗證的全面 JSON 模式。
• 角色系統：可配置的代理角色，適用於不同用例。

📦 安裝指南

方法一：自動化設置腳本

./setup.sh

此腳本將完成以下操作：

• 創建 conda 環境
• 安裝依賴項
• 驗證安裝
• 測試服務器

方法二：手動安裝

# 創建 conda 環境
conda env create -f environment.yml
conda activate xcode-mcp

# 驗證安裝
python -c "from src.unified_mcp_server import UnifiedMCPServer; print('✅ 安裝成功')"

依賴項

核心依賴項：

• fastapi - HTTP 服務器（可選）
• pydantic - 數據驗證
• langgraph - 子代理工作流（可選）
• langchain - 大語言模型集成（可選）

完整列表請參考 environment.yml。

⚙️ 配置

環境變量

# 大語言模型提供商 API 密鑰
export DEEPSEEK_API_KEY="your-deepseek-key"
export OPENAI_API_KEY="your-openai-key"  # 可選

# 模型選擇
export DEFAULT_MODEL="ollama:qwen3-coder:30b"  # 或 "deepseek:deepseek-coder"

MCP 配置

服務器通過 ~/.cursor/mcp.json 進行配置。為確保可靠性，請使用絕對路徑：

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "/Users/username/miniconda3/envs/xcode-mcp/bin/python",
      "args": ["/Users/username/Projects/xcode-mcp/run_unified_mcp.py"],
      "env": {
        "DEEPSEEK_API_KEY": "your-key"
      }
    }
  }
}

💻 使用示例

基礎用法

直接工具

用於簡單的單步操作：

使用 list_projects 工具
使用 build_project 工具並指定方案 "MyApp"
使用 run_tests 工具

LangGraph 子代理工具

用於複雜的多步工作流：

使用 langgraph_agent 並輸入提示 "設置我的開發環境"
使用 langgraph_workflow 並指定工作流 "構建、測試並生成報告"

使用角色

應用角色以實現特定行為：

{
  "name": "langgraph_agent",
  "arguments": {
    "prompt": "幫助我優化構建",
    "persona": {
      "id": "build-optimizer",
      "role": "optimizer"
    }
  }
}

🛠️ 工具參考

直接工具（112 個工具）

v2.1.0 新增工具

• 崩潰報告（4 個工具）：symbolicate_crash_log、analyze_crash_log、get_crash_reports、export_crash_log
• 資源管理（5 個工具）：optimize_images、generate_app_icons、validate_asset_catalog、check_asset_sizes、manage_color_assets
• 模擬器增強（5 個工具）：set_simulator_location、get_simulator_logs、list_simulator_apps、simulate_network_conditions、clone_simulator
• 本地化（4 個工具）：extract_strings、validate_localizations、check_localization_coverage、list_localizations
• 構建增強（3 個工具）：set_build_number、set_version、analyze_build_time

原有工具（94 個工具）

項目管理

• list_projects - 列出所有 Xcode 項目
• create_project - 創建新的 Xcode 項目
• open_project - 在 Xcode 中打開項目
• list_schemes - 列出可用的構建方案
• switch_scheme - 更改活動方案

構建

• build_project - 構建項目
• build_workspace - 構建工作區
• clean_build - 清理構建產物
• archive_project - 創建歸檔文件
• analyze_build - 分析構建性能

測試

• run_tests - 運行單元測試
• run_ui_tests - 運行 UI 測試
• generate_test_report - 生成測試報告
• code_coverage_report - 獲取覆蓋率報告

模擬器和設備

• list_devices - 列出可用的模擬器
• boot_simulator - 啟動模擬器
• install_app - 在設備上安裝應用
• launch_app - 啟動應用

大語言模型集成

• get_llm_status - 檢查大語言模型服務狀態
• configure_llm - 配置大語言模型提供商

完整列表請參考 schemas/xcode-mcp-tools.json。

LangGraph 工具（3 個工具）

langgraph_agent

用於複雜工作流的子代理，具備推理和狀態管理功能。

參數：

• prompt（必需） - 自然語言任務描述
• model（可選） - 模型覆蓋（例如，"ollama:qwen3-coder:30b"）
• persona（可選） - 角色配置

示例：

使用 langgraph_agent 並輸入提示 "驗證我的開發環境並列出所有項目"

langgraph_workflow

執行多步工作流，自動編排工具。

參數：

• workflow（必需） - 工作流描述
• context（可選） - 額外上下文
• persona（可選） - 角色配置

示例：

使用 langgraph_workflow 並指定工作流 "1. 清理構建 2. 構建項目 3. 運行測試 4. 生成報告"

langgraph_status

獲取 LangGraph 代理的狀態和可用功能。

🏗️ 架構

統一服務器

項目使用統一的 MCP 服務器（src/unified_mcp_server.py），整合了以下內容：

• 直接工具：來自 src/xcode_tools/ 的 94 個工具
• LangGraph 工具：3 個使用 LangGraph 的子代理工具
• 優化層：緩存、壓縮和模式優化

項目結構

xcode-mcp/
├── src/
│   ├── unified_mcp_server.py    # 主統一服務器
│   ├── tool_registry.py          # 工具註冊系統
│   ├── langgraph_agent.py        # LangGraph 代理實現
│   ├── llm_service.py            # 大語言模型提供商抽象
│   └── xcode_tools/              # 工具實現
│       ├── project.py            # 項目管理
│       ├── build.py              # 構建操作
│       ├── testing.py            # 測試工具
│       ├── simulator.py          # 模擬器控制
│       └── ...
├── schemas/
│   ├── xcode-mcp-tools.json      # 工具模式定義
│   ├── persona_schemas.json      # 角色模式
│   └── persona_examples.json     # 預配置角色
├── tests/
│   └── test_unified_server.py    # 全面測試套件
├── docs/                         # 額外文檔
├── examples/                     # 使用示例
├── run_unified_mcp.py            # 服務器入口點
└── environment.yml               # Conda 依賴項

工具註冊

工具通過以下方式自動註冊：

1. JSON 模式（schemas/xcode-mcp-tools.json）
2. Python 實現（src/xcode_tools/）
3. 動態發現和映射

LangGraph 集成

LangGraph 工具內部使用直接工具：

• 代理接收自然語言提示
• 分解為步驟
• 調用適當的直接工具
• 跨步驟維護狀態
• 返回全面結果

👤 角色

角色為不同用例提供特定的代理行為。

可用角色

senior-ios-architect

• 角色：架構師
• 專長：Swift、Xcode、架構、iOS、性能
• 風格：專業、詳細、專家級
• 適用場景：架構決策、最佳實踐、設計模式

swift-mentor

• 角色：導師
• 專長：Swift、Xcode、iOS、SwiftUI
• 風格：友好、全面、中級水平
• 適用場景：學習、教育、逐步指導

build-optimizer

• 角色：優化師
• 專長：Xcode、性能、CI/CD
• 風格：簡潔、適中、高級水平
• 適用場景：構建性能優化、CI/CD

test-specialist

• 角色：測試專家
• 專長：測試、Xcode、Swift、CI/CD
• 風格：專業、詳細、高級水平
• 適用場景：測試策略、覆蓋率、質量

使用角色

{
  "persona": {
    "id": "build-optimizer",
    "role": "optimizer",
    "expertise": ["xcode", "performance"],
    "communication_style": {
      "tone": "concise",
      "verbosity": "moderate",
      "technical_level": "advanced"
    }
  }
}

完整示例請參考 schemas/persona_examples.json。

🔧 技術細節

故障排除

MCP 服務器顯示紅色

1. 驗證配置

   python3 -m json.tool ~/.cursor/mcp.json
   

2. 手動測試服務器

   python test_mcp_connection.py
   

3. 終止陳舊進程

   pkill -f "run_unified_mcp.py"
   

4. 重啟 Cursor
   • 完全退出（Cmd + Q）
   • 等待 5 秒
   • 重新打開 Cursor
5. 使用絕對 Python 路徑 更新 ~/.cursor/mcp.json 以使用絕對路徑：

   "command": "/path/to/miniconda3/envs/xcode-mcp/bin/python"
   

沒有顯示工具

1. 檢查 Cursor 中服務器是否顯示綠色
2. 驗證工具列表：

   python -c "from src.unified_mcp_server import UnifiedMCPServer; s = UnifiedMCPServer(); print(len(s.registry.tools))"
   

3. 重啟 Cursor

LangGraph 無法工作

1. 驗證安裝：

   conda activate xcode-mcp
   python -c "import langgraph; print('✅ LangGraph 已安裝')"
   

2. 如果缺失則安裝：

   pip install langgraph langchain langchain-core langchain-openai langchain-ollama
   

工具執行錯誤

1. 檢查 Xcode 命令行工具：

   xcodebuild -version
   

2. 驗證 Xcode 操作的權限
3. 檢查 schemas/xcode-mcp-tools.json 中工具特定的要求

測試

運行測試套件

# 全面測試
python tests/test_unified_server.py

# 連接測試
python test_mcp_connection.py

預期結果

• ✅ 8/8 個測試通過
• ✅ 97 個工具可用
• ✅ 所有協議正常工作
• ✅ 服務器響應正確

開發

添加新工具

1. 添加到模式（schemas/xcode-mcp-tools.json）：

   {
     "name": "my_new_tool",
     "description": "工具描述",
     "parameters": [...]
   }
   

2. 實現函數（src/xcode_tools/）：

   def my_new_tool(param1: str, param2: int) -> dict:
       # 實現代碼
       return {"result": "..."}
   

3. 測試：

   python -c "from src.tool_registry import get_registry; r = get_registry(); print(r.execute_tool('my_new_tool', param1='test', param2=1))"
   

項目組織

• 核心服務器：src/unified_mcp_server.py
• 工具註冊表：src/tool_registry.py
• 工具實現：src/xcode_tools/
• 模式：schemas/
• 測試：tests/
• 文檔：docs/

性能優化

• 模式緩存：5 分鐘 TTL
• 響應緩存：緩存成功的響應
• 緊湊 JSON：減少令牌使用量
• 懶加載：僅在需要時加載 LangGraph

性能指標

• 令牌減少：通過優化減少 30 - 40%
• 內存使用：統一服務器減少 50%
• 響應時間：緩存響應加快 50%
• 模式加載：緩存加快 80%

📚 詳細文檔

附加資源

• 工具模式：schemas/xcode-mcp-tools.json
• 角色模式：schemas/persona_schemas.json
• 角色示例：schemas/persona_examples.json
• 示例：examples/

貢獻

1. 遵循現有代碼結構
2. 為新功能添加測試
3. 更新模式和文檔
4. 在提交前運行測試套件

網絡訪問

要將 MCP 服務器暴露給網絡上的其他設備：

# 啟動網絡服務器（默認端口 8000）
python run_network_server.py

# 使用自定義設置
MCP_HOST=0.0.0.0 MCP_PORT=8000 python run_network_server.py

# 使用身份驗證
MCP_API_KEY=your-secret-key MCP_REQUIRE_AUTH=true python run_network_server.py

端點：

• HTTP：http://YOUR_IP:8000/mcp
• WebSocket：ws://YOUR_IP:8000/ws
• 工具列表：http://YOUR_IP:8000/tools
• 健康檢查：http://YOUR_IP:8000/health

完整的網絡設置指南請參考 docs/NETWORK_SETUP.md，包括：

• 配置選項
• 身份驗證設置
• 客戶端示例（Python、JavaScript、curl）
• 安全考慮
• 生產部署

致謝

• 模型上下文協議規範
• LangGraph 用於子代理工作流
• Xcode 命令行工具

版本信息

• 版本：2.1.0
• 最後更新：2025-01-XX
• 維護者：Eddikson Peña

v2.1.0 新增內容

新增 21 個工具

• 崩潰報告：符號化和分析崩潰日誌、自動提取崩潰信息、導出崩潰報告
• 資源管理：自動優化圖像、生成應用圖標集、驗證資源目錄、檢查資源大小
• 模擬器增強：設置 GPS 位置、獲取模擬器日誌、列出已安裝應用、克隆模擬器
• 本地化：提取可本地化字符串、驗證翻譯、檢查覆蓋率百分比、列出支持的語言環境
• 構建增強：設置特定的構建/版本號、分析構建時間、增強版本管理

完整詳細信息請參考 DEPLOYMENT_SUMMARY.md。

📄 許可證

[在此添加您的許可證信息]