Xcode MCP 服务器
MCP（模型上下文协议）服务器，为 AI 助手提供全面的 Xcode 集成。该服务器使 AI 代理能够与 Xcode 项目交互、管理 iOS 模拟器，并执行各种与 Xcode 相关的任务，同时增强错误处理功能并支持多种项目类型。
特征
项目管理
- 设置活跃项目并获取详细项目信息
- 从模板创建新的 Xcode 项目（iOS、macOS、watchOS、tvOS）
- 使用目标和组规范将文件添加到 Xcode 项目
- 解析工作区文档以查找相关项目
- 列出项目和工作区中可用的方案
文件操作
- 支持不同编码的读/写文件
- 使用 base64 编码/解码处理二进制文件
- 使用模式和正则表达式搜索文件中的文本内容
- 检查文件存在并获取文件元数据
- 自动创建目录结构
构建和测试
- 使用可自定义的选项构建项目
- 运行测试并报告详细的故障
- 分析代码以查找潜在问题
- 清理构建目录
- 存档项目以供分发
CocoaPods 集成
- 在项目中初始化 CocoaPods
- 安装和更新 Pod
- 添加和删除 pod 依赖项
- 执行任意 pod 命令
Swift 包管理器
- 初始化新的 Swift 包
- 添加和删除具有各种版本要求的软件包依赖项
- 更新软件包并解决依赖关系
- 使用 DocC 为 Swift 软件包生成文档
- 运行测试并构建 Swift 包
iOS模拟器工具
- 列出可用的模拟器及其详细信息
- 启动和关闭模拟器
- 在模拟器上安装和启动应用程序
- 截取屏幕截图并录制视频
- 管理模拟器设置和状态
Xcode 实用程序
- 通过 xcrun 执行 Xcode 命令
- 编译资产目录
- 从源图像生成应用程序图标集
- 跟踪应用程序性能
- 导出并验证存档以供 App Store 提交
- 在不同的 Xcode 版本之间切换
安装
先决条件
- 安装了 Xcode 14.0 或更高版本的 macOS
- Node.js 16 或更高版本
- npm 或 yarn
- Swift 5.5+ 的 Swift 包管理器功能
- CocoaPods（可选，用于 CocoaPods 集成）
设置
选项 1：自动设置（推荐）
使用附带的安装脚本自动执行安装和配置过程：
# Make the script executable
chmod +x setup.sh
# Run the setup script
./setup.sh
安装脚本的作用：
- 环境验证：
- 检查您是否在 macOS 上运行
- 验证 Xcode 是否已安装并可访问
- 确认 Node.js (v16+) 和 npm 可用
- 检查 Ruby 安装
- 验证 CocoaPods 安装（如果缺失则提供安装）
- 依赖项安装：
- 运行
npm install来安装所有必需的 Node.js 包 - 执行
npm run build来编译 TypeScript 代码
- 配置设置：
- 如果不存在则创建一个
.env文件 - 提示输入项目基目录
- 询问您是否要启用调试日志记录
- 保存您的配置偏好
- Claude 桌面集成（可选）：
- 提供为 Claude Desktop 配置服务器
- 创建或更新 Claude Desktop 配置文件
- 设置适当的命令和参数来启动服务器
何时使用安装脚本：
- 首次安装以确保满足所有先决条件
- 当您需要使用交互式提示进行引导配置时
- 如果你想快速设置 Claude Desktop 集成
- 验证您的环境是否具有所有必需的组件
该脚本将通过清晰的提示和有用的反馈指导您完成配置过程。
选项 2：手动设置
何时使用手动设置：
- 您更喜欢明确控制每个安装步骤
- 您有一个自定义环境或非标准配置
- 您正在设置 CI/CD 管道或自动化环境
- 您想要自定义安装过程的特定方面
- 您是一位熟悉 Node.js 项目的经验丰富的开发人员
请按照以下步骤进行手动安装：
- 克隆存储库：
git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server
- 验证先决条件（必须安装这些）：
- Xcode 和 Xcode 命令行工具
- Node.js v16 或更高版本
- npm
- Ruby（用于 CocoaPods 支持）
- CocoaPods（可选，用于与 pod 相关的功能）
- 安装依赖项：
- 构建项目：
- 创建配置文件：
# 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文件以设置您的首选配置。 - 对于 Claude Desktop 集成（可选）：
- 编辑或创建
~/Library/Application Support/Claude/claude_desktop_config.json - 添加以下配置（根据需要调整路径）：GXP6
设置故障排除
常见设置问题：
- 构建错误：
- 确保您拥有正确的 Node.js 版本（v16+）
- 尝试删除
node_modules并再次运行npm install - 使用
npx tsc --noEmit检查 TypeScript 错误 - 确保代码中的所有导入都得到正确解析
- 缺少依赖项：
- 如果您看到有关缺少模块的错误，请再次运行
npm install - 对于本机依赖项，您可能需要 Xcode 命令行工具：
xcode-select --install
- 权限问题：
- 确保您对安装目录具有写入权限
- 对于 CocoaPods 安装，您可能需要使用
sudo gem install cocoapods
- 配置问题：
- 验证您的
.env文件具有正确的格式和有效的路径 - 确保
PROJECTS_BASE_DIR指向现有目录 - 检查路径不包含需要转义的特殊字符
- Claude 桌面集成：
- 确保 Claude 配置中的路径指向
index.js的正确位置 - 更改配置后重新启动 Claude Desktop
- 在尝试使用 Claude 之前，请检查服务器是否正在运行
用法
启动服务器
对于自动重启的开发模式：
配置选项
您可以通过两种方式配置服务器：
.env文件中的环境变量：PROJECTS_BASE_DIR=/path/to/your/projects
DEBUG=true
ALLOWED_PATHS=/path/to/additional/allowed/directory
PORT=8080
- 命令行参数：
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助手
该服务器实现了模型上下文协议 (MCP)，使其能够与支持此协议的各种 AI 助手兼容。连接方法如下：
- 启动 Xcode MCP 服务器
- 配置你的AI助手使用服务器URL（通常为
http://localhost:3000 ） - 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 服务器使用模型上下文协议 (MCP) 为 AI 模型与 Xcode 项目交互提供标准化接口。该服务器架构由以下几个关键组件设计而成：
核心组件
- 服务器实现：处理工具注册和请求处理的主要 MCP 服务器。
- 路径管理：通过验证所有路径是否与允许的目录一致，确保文件访问的安全。
- 项目管理：检测、加载和管理不同类型的 Xcode 项目：
- 标准 Xcode 项目（.xcodeproj）
- Xcode 工作区（.xcworkspace）
- Swift 包管理器项目（Package.swift）
- 目录状态：维护相对路径解析的活动目录上下文。
- 工具注册表：将工具组织成逻辑类别，以用于不同的 Xcode 操作。
请求流程
- AI助手向MCP服务器发送工具执行请求。
- 服务器验证请求参数和权限。
- 使用经过验证的参数调用适当的工具处理程序。
- 该工具执行请求的操作，通常使用本机 Xcode 命令。
- 结果被格式化并返回给AI助手。
- 全面的错误处理为故障排除提供了有意义的反馈。
安全功能
- 路径验证：所有文件操作都限制在允许的目录中。
- 错误处理：详细的错误消息有助于诊断问题。
- 参数验证：使用 Zod 模式验证输入参数。
- 流程管理：通过适当的错误处理，外部流程可以安全执行。
项目类型支持
服务器智能地处理不同的项目类型：
- 标准项目：直接 .xcodeproj 操作
- 工作区：管理工作区内的多个项目
- SPM 项目：处理 Swift 包管理器特定的操作
这种架构允许 AI 助手无缝地与任何类型的 Xcode 项目协作，同时保持安全性并提供详细的反馈。
贡献
欢迎贡献代码！欢迎提交 Pull 请求。
- 分叉存储库
- 创建你的功能分支（
git checkout -b feature/amazing-feature ） - 提交您的更改（
git commit -m 'Add some amazing feature' ） - 推送到分支（
git push origin feature/amazing-feature ） - 打开拉取请求
开发指南
- 遵循现有的代码风格和组织
- 添加带有特定错误消息的全面错误处理
- 为新功能编写测试
- 更新文档以反映您的更改
- 确保与不同项目类型（标准、工作区、SPM）的兼容性
添加新工具
要向服务器添加新工具：
- 在
src/tools/目录中确定适当的类别 - 使用 Zod 模式验证的现有模式来实现该工具
- 在类别的
index.ts文件中注册该工具 - 添加带有特定错误消息的错误处理
- 在适当的文档文件中记录该工具
故障排除
常见问题
- 路径访问错误：确保您尝试访问的路径在允许的目录内
- 构建失败：检查 Xcode 命令行工具是否已安装且为最新版本
- 未找到工具：验证工具名称是否正确且已正确注册
- 参数验证错误：检查工具文档中的参数类型和要求
调试
- 启动启用调试日志记录的服务器：
npm start -- --debug - 检查控制台输出以获取详细的错误消息
- 检查服务器日志以获取请求和响应详细信息
- 对于特定于工具的问题，请尝试直接在终端中运行等效的 Xcode 命令
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。
致谢
- 感谢模型上下文协议团队提供的 MCP SDK
- 使用 TypeScript 和 Node.js 构建
- 使用 Xcode 命令行工具和 Swift 包管理器
- 特别感谢所有帮助改善服务器功能和稳健性的贡献者