使用说明

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包管理器
特别感谢所有帮助改进服务器功能和健壮性的贡献者