Xcode MCP Server

Xcode MCP 服务

一个 MCP（Model Context Protocol）服务，为 AI 助手提供全面的 Xcode 集成。该服务支持 AI Agent 与 Xcode 项目交互、管理 iOS 模拟器，并执行各种 Xcode 相关任务，同时增强错误处理能力并支持多种项目类型。

功能

项目管理

• 设置活动项目并获取详细的项目信息
• 根据模板创建新的 Xcode 项目（iOS、macOS、watchOS、tvOS）
• 向 Xcode 项目添加文件，并指定目标和组
• 解析工作区文档以查找关联的项目
• 列出项目和工作区中可用的方案

文件操作

• 读取/写入文件，并支持不同编码
• 使用 base64 编码/解码处理二进制文件
• 使用模式和正则表达式搜索文件中的文本内容
• 检查文件是否存在并获取文件元数据
• 自动创建目录结构

构建与测试

• 使用可自定义选项构建项目
• 运行测试并详细报告失败情况
• 分析代码以发现潜在问题
• 清理构建目录
• 为分发归档项目

CocoaPods 集成

• 在项目中初始化 CocoaPods
• 安装和更新 Pods
• 添加和移除 Pods 依赖项
• 执行任意 Pod 命令

Swift Package Manager

• 初始化新的 Swift 包
• 根据各种版本要求添加和移除包依赖项
• 更新包并解析依赖项
• 使用 DocC 为 Swift 包生成文档
• 运行测试并构建 Swift 包

iOS 模拟器工具

• 列出可用模拟器及其详细信息
• 启动和关闭模拟器
• 在模拟器上安装和启动应用
• 截取屏幕截图并录制视频
• 管理模拟器设置和状态

Xcode 实用工具

• 通过 xcrun 执行 Xcode 命令
• 编译资源目录
• 根据源图像生成应用图标集
• 跟踪应用性能
• 导出并验证用于提交至 App Store 的归档
• 在不同 Xcode 版本之间切换

安装

先决条件

• 安装了 Xcode 14.0 或更高版本的 macOS
• Node.js 16 或更高版本
• npm 或 yarn
• 使用 Swift Package Manager 功能需要 Swift 5.5+
• CocoaPods（可选，用于 CocoaPods 集成）

设置

选项 1：自动设置（推荐）

使用随附的设置脚本自动完成安装和配置流程：

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

设置脚本的功能：

1. 环境验证：

   • 检查当前是否运行在 macOS 上
   • 验证 Xcode 已安装且可访问
   • 确认 Node.js（v16+）和 npm 可用
   • 检查是否已安装 Ruby
   • 验证 CocoaPods 是否已安装（如缺失则提供安装选项）

2. 依赖项安装：

   • 运行 npm install 安装所有必需的 Node.js 包
   • 执行 npm run build 编译 TypeScript 代码

3. 配置设置：

   • 如果 .env 文件不存在，则创建该文件
   • 提示输入项目的基础目录
   • 询问是否启用调试日志
   • 保存配置偏好设置

4. Claude Desktop 集成（可选）：

   • 提供为 Claude Desktop 配置服务的选项
   • 创建或更新 Claude Desktop 配置文件
   • 设置启动服务所需的命令和参数

何时使用设置脚本：

• 首次安装时，确保满足所有先决条件
• 需要通过交互式提示引导完成配置时
• 希望快速设置 Claude Desktop 集成时
• 验证环境是否包含所有必需组件时

脚本将通过清晰的提示和实用的反馈，引导你完成配置流程。

选项 2：手动设置

适合手动设置的情况：

• 你希望明确控制每个安装步骤
• 你使用自定义环境或非标准配置
• 你正在 CI/CD 流水线或自动化环境中进行设置
• 你想自定义安装流程的特定方面
• 你是熟悉 Node.js 项目的资深开发者

按照以下步骤手动安装：

1. 克隆仓库：

   git clone https://github.com/r-huijts/xcode-mcp-server.git
   cd xcode-mcp-server
   

2. 验证前置条件（必须安装以下项目）：

   • Xcode 和 Xcode Command Line Tools
   • Node.js v16 或更高版本
   • npm
   • Ruby（用于支持 CocoaPods）
   • CocoaPods（可选，用于 pod 相关功能）

3. 安装依赖项：

   npm install
   

4. 构建项目：

   npm run build
   

5. 创建配置文件：

   # Option A: Start with the example configuration
   cp .env.example .env
   
   # Option B: Create a minimal configuration
   echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
   echo "DEBUG=false" >> .env
   

   编辑 .env 文件以设置你偏好的配置。

6. 集成 Claude Desktop（可选）：

   • 编辑或创建 ~/Library/Application Support/Claude/claude_desktop_config.json
   • 添加以下配置（根据需要调整路径）：

   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/path/to/xcode-mcp-server/dist/index.js"]
       }
     }
   }
   

设置故障排查

常见设置问题：

1. 构建错误：

   • 确保使用正确的 Node.js 版本（v16+）
   • 尝试删除 node_modules 并再次运行 npm install
   • 使用 npx tsc --noEmit 检查 TypeScript 错误
   • 确保代码中的所有导入都已正确解析

2. 缺少依赖项：

   • 如果看到有关缺少模块的错误，请再次运行 npm install
   • 对于原生依赖项，你可能需要 Xcode Command Line Tools：xcode-select --install

3. 权限问题：

   • 确保你对安装目录具有写入权限
   • 安装 CocoaPods 时，你可能需要使用 sudo gem install cocoapods

4. 配置问题：

   • 确认 .env 文件格式正确且路径有效
   • 确保 PROJECTS_BASE_DIR 指向现有目录
   • 检查路径中是否包含需要转义的特殊字符

5. Claude Desktop 集成：

   • 确保 Claude 配置中的路径指向 index.js 的正确位置
   • 更改配置后重启 Claude Desktop
   • 尝试通过 Claude 使用服务前，检查服务是否正在运行

使用

启动服务

npm start

以开发模式运行并自动重启：

npm run dev

配置选项

你可以通过以下两种方式配置服务：

1. .env 文件中的环境变量：

   PROJECTS_BASE_DIR=/path/to/your/projects
   DEBUG=true
   ALLOWED_PATHS=/path/to/additional/allowed/directory
   PORT=8080
   

2. 命令行参数：

   npm start -- --projects-dir=/path/to/your/projects --port=8080
   

关键配置参数

• PROJECTS_BASE_DIR / --projects-dir：项目的基础目录（必需）
• ALLOWED_PATHS / --allowed-paths：允许访问的其他目录（以逗号分隔）
• PORT / --port：服务运行的端口（默认值：3000）
• DEBUG / --debug：启用调试日志记录（默认值：false）
• LOG_LEVEL / --log-level：设置日志级别（默认值：info）

连接 AI 助手

该服务实现了 Model Context Protocol（MCP），因此兼容支持此协议的各种 AI 助手。连接步骤如下：

1. 启动 Xcode MCP 服务
2. 将 AI 助手配置为使用服务 URL（通常为 http://localhost:3000）
3. AI 助手现在即可访问该服务提供的所有 Xcode 工具

工具文档

如需全面了解所有可用工具及其用法，请参阅工具概览。

如需详细的用法示例和最佳实践，请参阅用户指南。

常见工作流

设置新项目

// Create a new iOS app project
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// Add a Swift Package dependency
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

处理文件

// Read a file with specific encoding
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

// Write to a file
await tools.write_file({
  path: "MyAwesomeApp/NewFile.swift",
  content: "import Foundation\n\nclass NewClass {}\n",
  createIfMissing: true
});

// Search for text in files
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

构建和测试

// Build the project
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// Run tests
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

项目结构

xcode-mcp-server/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server implementation
│   ├── types/                   # Type definitions
│   │   └── index.ts             # Core type definitions
│   ├── utils/                   # Utility functions
│   │   ├── errors.js            # Error handling classes
│   │   ├── pathManager.ts       # Path validation and management
│   │   ├── project.js           # Project utilities
│   │   └── simulator.js         # Simulator utilities
│   └── tools/                   # Tool implementations
│       ├── project/             # Project management tools
│       │   └── index.ts         # Project creation, detection, file adding
│       ├── file/                # File operation tools
│       │   └── index.ts         # File reading, writing, searching
│       ├── build/               # Build and testing tools
│       │   └── index.ts         # Building, testing, analyzing
│       ├── cocoapods/           # CocoaPods integration
│       │   └── index.ts         # Pod installation and management
│       ├── spm/                 # Swift Package Manager tools
│       │   └── index.ts         # Package management and documentation
│       ├── simulator/           # iOS simulator tools
│       │   └── index.ts         # Simulator control and interaction
│       └── xcode/               # Xcode utilities
│           └── index.ts         # Xcode version management, asset tools
├── docs/                        # Documentation
│   ├── tools-overview.md        # Comprehensive tool documentation
│   └── user-guide.md            # Usage examples and best practices
├── tests/                       # Tests
└── dist/                        # Compiled code (generated)

工作原理

Xcode MCP 服务使用 Model Context Protocol 为 AI 模型与 Xcode 项目交互提供标准化接口。服务架构由几个关键组件构成：

核心组件

1. 服务端实现：负责工具注册和请求处理的主要 MCP 服务。

2. 路径管理：通过验证所有路径是否位于允许的目录中，确保文件访问安全。

3. 项目管理：检测、加载和管理不同类型的 Xcode 项目：

   • 标准 Xcode 项目（.xcodeproj）
   • Xcode 工作区（.xcworkspace）
   • Swift Package Manager 项目（Package.swift）

4. 目录状态：维护当前目录上下文，以解析相对路径。

5. 工具注册表：将工具按逻辑类别组织，以执行不同的 Xcode 操作。

请求流程

1. AI 助手向 MCP 服务发送工具执行请求。

2. 服务端验证请求参数和权限。

3. 使用经过验证的参数调用相应的工具处理程序。

4. 工具执行请求的操作，通常会使用原生 Xcode 命令。

5. 将结果格式化后返回给 AI 助手。

6. 全面的错误处理可为故障排查提供有用的反馈。

安全功能

• 路径验证：所有文件操作都限制在允许的目录中。
• 错误处理：详细的错误消息有助于诊断问题。
• 参数验证：使用 Zod schema 验证输入参数。
• 进程管理：安全地执行外部进程，并妥善处理错误。

项目类型支持

服务端可以智能地处理不同类型的项目：

• 标准项目：直接操作 .xcodeproj
• 工作区：管理工作区中的多个项目
• SPM 项目：处理 Swift Package Manager 特定操作

此架构让 AI 助手能够无缝处理任何类型的 Xcode 项目，同时确保安全并提供详细反馈。

参与贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开发指南

• 遵循现有的代码风格和组织方式
• 添加全面的错误处理，并提供具体的错误消息
• 为新功能编写测试
• 更新文档以反映所做的更改
• 确保兼容不同的项目类型（标准项目、工作区、SPM）

添加新工具

要向服务端添加新工具：

1. 在 src/tools/ 目录中找到合适的类别
2. 使用现有模式实现工具，并通过 Zod schema 验证
3. 在该类别的 index.ts 文件中注册工具
4. 添加错误处理，并提供具体的错误消息
5. 在相应的文档文件中记录该工具

故障排查

常见问题

• 路径访问错误：确保尝试访问的路径位于允许的目录中
• 构建失败：检查是否已安装最新版本的 Xcode 命令行工具
• 找不到工具：确认工具名称正确且已正确注册
• 参数验证错误：检查工具文档中的参数类型和要求

调试

1. 启用调试日志并启动服务端：npm start -- --debug
2. 检查控制台输出中的详细错误消息
3. 查看服务端日志中的请求和响应详情
4. 如果遇到特定工具的问题，尝试直接在终端中运行对应的 Xcode 命令

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 Model Context Protocol 团队提供 MCP SDK
• 使用 TypeScript 和 Node.js 构建
• 使用 Xcode 命令行工具和 Swift Package Manager
• 特别感谢所有帮助提升服务端功能和健壮性的贡献者