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。

📄 许可证

[在此添加您的许可证信息]