shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

xcode-mcp

Xcode MCP服务器是一个全面的开发自动化工具，提供115+个工具用于项目管理、构建、测试、模拟器控制、崩溃报告、资源管理和本地化，支持AI驱动的工作流和可配置的代理角色系统。

article

README

🚀 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。

📄 许可证

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

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client