Xcode MCP 服务器

一个提供全面Xcode集成的MCP（模型上下文协议）服务器，专为AI助手设计。该服务器使AI代理能够与Xcode项目交互、管理iOS模拟器，并执行各种Xcode相关任务，同时具备增强的错误处理能力并支持多种项目类型。

功能特性

项目管理

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

文件操作

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

构建与测试

使用可定制选项构建项目
运行测试并提供详细的失败报告
分析代码以发现潜在问题
清理构建目录
归档项目以供分发

CocoaPods集成

在项目中初始化CocoaPods
安装和更新pods
添加和移除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：自动化安装（推荐）

使用包含的安装脚本自动完成安装和配置过程：

# 使脚本可执行
chmod +x setup.sh

# 运行安装脚本
./setup.sh

安装脚本的功能：

环境验证：
- 检查是否在macOS上运行
- 验证Xcode已安装并可访问
- 确认Node.js（v16+）和npm可用
- 检查Ruby安装情况
- 验证CocoaPods安装（如果缺失则提供安装选项）
依赖项安装：
- 运行npm install安装所有必需的Node.js包
- 执行npm run build编译TypeScript代码
配置设置：
- 如果不存在则创建.env文件
- 提示输入项目的基础目录
- 询问是否启用调试日志
- 保存您的配置首选项
Claude Desktop集成（可选）：
- 提供配置服务器以支持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
```

创建配置文件：

# 选项A：从示例配置开始
cp .env.example .env

# 选项B：创建最小配置
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
- 使用npx tsc --noEmit检查TypeScript错误
- 确保代码中的所有导入都正确解析
缺少依赖项：
- 如果看到关于缺少模块的错误，请再次运行npm install
- 对于原生依赖项，您可能需要Xcode命令行工具：xcode-select --install
权限问题：
- 确保您对安装目录具有写入权限
- 对于CocoaPods安装，您可能需要使用sudo gem install cocoapods
配置问题：
- 验证您的.env文件格式正确且路径有效
- 确保PROJECTS_BASE_DIR指向现有目录
- 检查路径不包含需要转义的特殊字符
Claude Desktop集成：
- 确保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工具

工具文档

有关所有可用工具及其使用的全面概述，请参阅工具概述。

有关详细的使用示例和最佳实践，请参阅用户指南。

常见工作流程

设置新项目

// 创建新的iOS应用项目
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// 添加Swift包依赖项
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

文件操作

// 使用特定编码读取文件
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

// 写入文件
await tools.write_file({
  path: "MyAwesomeApp/NewFile.swift",
  content: "import Foundation\n\nclass NewClass {}\n",
  createIfMissing: true
});

// 在文件中搜索文本
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

构建和测试

// 构建项目
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// 运行测试
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

项目结构

xcode-mcp-server/
├── src/
│   ├── index.ts                 # 入口点
│   ├── server.ts                # MCP服务器实现
│   ├── types/                   # 类型定义
│   │   └── index.ts             # 核心类型定义
│   ├── utils/                   # 实用函数
│   │   ├── errors.js            # 错误处理类
│   │   ├── pathManager.ts       # 路径验证和管理
│   │   ├── project.js           # 项目实用工具
│   │   └── simulator.js         # 模拟器实用工具
│   └── tools/                   # 工具实现
│       ├── project/             # 项目管理工具
│       │   └── index.ts         # 项目创建、检测、文件添加
│       ├── file/                # 文件操作工具
│       │   └── index.ts         # 文件读取、写入、搜索
│       ├── build/               # 构建和测试工具
│       │   └── index.ts         # 构建、测试、分析
│       ├── cocoapods/           # CocoaPods集成
│       │   └── index.ts         # Pod安装和管理
│       ├── spm/                 # Swift包管理器工具
│       │   └── index.ts         # 包管理和文档生成
│       ├── simulator/           # iOS模拟器工具
│       │   └── index.ts         # 模拟器控制和交互
│       └── xcode/               # Xcode实用工具
│           └── index.ts         # Xcode版本管理、资源工具
├── docs/                        # 文档
│   ├── tools-overview.md        # 全面工具文档
│   └── user-guide.md            # 使用示例和最佳实践
├── tests/                       # 测试
└── dist/                        # 编译后的代码（生成）

工作原理

Xcode MCP服务器使用模型上下文协议为AI模型提供与Xcode项目交互的标准化接口。服务器架构设计包含几个关键组件：

核心组件

服务器实现：处理工具注册和请求处理的主MCP服务器。
路径管理：通过验证所有路径是否在允许的目录中来确保安全的文件访问。
项目管理：检测、加载和管理不同类型的Xcode项目：
- 标准Xcode项目（.xcodeproj）
- Xcode工作区（.xcworkspace）
- Swift包管理器项目（Package.swift）
目录状态：维护活动目录上下文以进行相对路径解析。
工具注册表：将工具组织到不同Xcode操作的逻辑类别中。

请求流程

AI助手向MCP服务器发送工具执行请求。
服务器验证请求参数和权限。
调用适当的工具处理程序并传递验证后的参数。
工具执行请求的操作，通常使用原生Xcode命令。
结果被格式化并返回给AI助手。
全面的错误处理提供有意义的反馈以进行故障排除。

安全特性

路径验证：所有文件操作都限制在允许的目录内。
错误处理：详细的错误消息有助于诊断问题。
参数验证：使用Zod模式验证输入参数。
进程管理：外部进程使用适当的错误处理安全执行。

项目类型支持

服务器智能处理不同类型的项目：

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

这种架构允许AI助手无缝地与任何类型的Xcode项目一起工作，同时保持安全性并提供详细的反馈。

贡献指南

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

叉取仓库
创建您的功能分支（git checkout -b feature/amazing-feature）
提交您的更改（git commit -m 'Add some amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开Pull Request

开发指南

遵循现有的代码风格和组织
添加带有特定错误消息的全面错误处理
为新功能编写测试
更新文档以反映您的更改
确保与不同项目类型（标准、工作区、SPM）的兼容性

添加新工具

要向服务器添加新工具：

在src/tools/目录中确定适当的类别
使用现有模式和Zod模式验证实现工具
在类别的index.ts文件中注册工具
添加带有特定错误消息的错误处理
在适当的文档文件中记录工具

故障排除

常见问题

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

调试

使用调试日志启动服务器：npm start -- --debug
检查控制台输出以获取详细的错误消息
检查服务器日志以获取请求和响应的详细信息
对于特定于工具的问题，尝试直接在终端中运行等效的Xcode命令

许可证

此项目根据MIT许可证授权 - 有关详细信息，请参阅LICENSE文件。

致谢

感谢模型上下文协议团队提供的MCP SDK
使用TypeScript和Node.js构建
使用Xcode命令行工具和Swift包管理器
特别感谢所有帮助改进服务器功能和鲁棒性的贡献者

Xcode MCP 服务器

功能特性

项目管理

文件操作

构建与测试

CocoaPods集成

Swift包管理器

iOS模拟器工具

Xcode实用工具

安装指南

前提条件

安装步骤

选项1：自动化安装（推荐）

选项2：手动安装

安装故障排除

使用方法

启动服务器

配置选项

关键配置参数

连接到AI助手

工具文档

常见工作流程

设置新项目

文件操作

构建和测试

项目结构

工作原理

核心组件

请求流程

安全特性

项目类型支持

贡献指南

开发指南

添加新工具

故障排除

常见问题

调试

许可证

致谢

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐