xcode麦普服务器

Name: xcode麦普服务器
Author: r-huijts

作者：r-huijts331 星标更新：2025-08-26

安装使用来源：spider==github.com

项目介绍

Xcode MCP 服务器

Xcode MCP 服务器提供全面的 Xcode 集成，适用于 AI 助手。此服务器使 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：自动化设置（推荐）

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

# 将脚本设为可执行
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 项目进行交互，同时保持安全性并提供详细的反馈。

贡献

欢迎贡献！请随意提交拉取请求。

分叉仓库
创建您的功能分支（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 包管理器
特别感谢所有帮助改进服务器功能和健壮性的贡献者