Xcode MCP服务器
MCP（模型上下文协议）服务器为AI助手提供全面的Xcode集成。该服务器使AI代理能够与Xcode项目交互，管理iOS模拟器，并通过增强的错误处理和对多种项目类型的支持执行各种与Xcode相关的任务。
特性
项目管理
- 设置活动项目并获取详细的项目信息
- 从模板（iOS、macOS、watchOS、tvOS）创建新的Xcode项目
- 使用目标和组规范将文件添加到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或纱线
- Swift 5.5+for 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相关功能）
- 安装依赖项：
npm install- 构建项目：
npm run build- 创建配置文件：
# 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 - 添加以下配置（根据需要调整路径）：
{
"mcpServers": {
"xcode": {
"command": "node",
"args": ["/path/to/xcode-mcp-server/dist/index.js"]
}
}
}安装故障排除
常见设置问题：
- 构建错误:
- 确保你有正确的Node.js版本（v16+） - 尝试删除 node_modules 跑步 npm install 再次 - 检查TypeScript错误 npx tsc --noEmit - 确保代码中的所有导入都已正确解析
- 缺少的依赖:
- 如果您看到有关缺少模块的错误，请运行 npm install 再次 - 对于本机依赖项，您可能需要Xcode命令行工具： xcode-select --install
- 权限问题:
- 确保您对安装目录具有写入权限 - 对于CocoaPods安装，您可能需要使用 sudo gem install cocoapods
- 配置问题:
- 验证您的 .env 文件具有正确的格式和有效的路径 - 确保 PROJECTS_BASE_DIR 指向现有目录 - 检查路径是否不包含需要转义的特殊字符
- Claude桌面集成:
- 确保Claude配置中的路径指向正确的位置 index.js - 更改配置后重新启动Claude Desktop - 在尝试与Claude一起使用之前，请检查服务器是否正在运行
用法
启动服务器
npm start对于自动重启的开发模式：
npm run dev配置选项
您可以通过两种方式配置服务器：
- 环境变量
.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服务器使用模型上下文协议为AI模型与Xcode项目交互提供标准化接口。服务器架构设计有几个关键组件：
核心组件
- 服务器实现：处理工具注册和请求处理的主MCP服务器。
- 路径管理：通过根据允许的目录验证所有路径来确保安全的文件访问。
- 项目管理：检测、加载和管理不同类型的Xcode项目：
- 标准Xcode项目（.xcodeproj） - Xcode工作区（.xcworkspace） - Swift包管理器项目（Package.Swift）
- 目录状态：维护活动目录上下文以进行相对路径解析。
- 工具注册表：将工具组织到不同Xcode操作的逻辑类别中。
请求流
- AI助手向MCP服务器发送工具执行请求。
- 服务器验证请求参数和权限。
- 使用经过验证的参数调用相应的工具处理程序。
- 该工具执行请求的操作，通常使用本机Xcode命令。
- 结果被格式化并返回给AI助手。
- 全面的错误处理为故障排除提供了有意义的反馈。
安全功能
- 路径验证：所有文件操作都限制在允许的目录中。
- 错误处理：详细的错误消息有助于诊断问题。
- 参数验证：使用Zod模式验证输入参数。
- 流程管理：外部进程通过适当的错误处理安全执行。
项目类型支持
服务器智能地处理不同的项目类型：
- 标准项目：直接操纵xcodeproj
- 工作区：在工作区内管理多个项目
- SPM项目：处理Swift包管理器的特定操作
这种架构允许AI助手与任何类型的Xcode项目无缝协作，同时保持安全性并提供详细的反馈。
贡献
欢迎投稿！请随时提交拉取请求。
- 分叉存储库
- 创建功能分支(
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许可证获得许可-有关详细信息，请参阅许可证文件。
致谢
- 感谢MCP SDK的模型上下文协议团队
- 使用TypeScript和Node.js构建
- 使用Xcode命令行工具和Swift包管理器
- 特别感谢所有帮助改进服务器功能和健壮性的贡献者