Xcode MCP Server

](https://mseep.ai/app/r-huijts-xcode-mcp-server)

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

安装脚本的作用：

1. 环境验证:

- 检查您是否在macOS上运行 - 验证Xcode是否已安装并可访问 - 确认Node.js（v16+）和npm可用 - 检查Ruby安装 - 验证CocoaPods安装（如果缺少，则提供安装）

1. 依赖安装:

- 跑 npm install 安装所有必需的Node.js包 - 执行 npm run build 编译TypeScript代码

1. 配置设置:

- 创建一个 .env 文件（如果不存在） - 提示您输入项目的基本目录 - 询问是否要启用调试日志记录 - 保存您的配置首选项

1. Claude桌面集成 （可选）：

- 提供为Claude Desktop配置服务器 - 创建或更新Claude Desktop配置文件 - 设置启动服务器的正确命令和参数

何时使用安装脚本：

• 首次安装以确保满足所有先决条件
• 当您希望使用交互式提示进行引导配置时
• 如果您想快速设置Claude Desktop集成
• 验证您的环境是否具有所有必要的组件

该脚本将通过清晰的提示和有用的反馈引导您完成配置过程。

选项2：手动设置

何时使用手动设置：

• 您更喜欢对每个安装步骤进行明确控制
• 您有自定义环境或非标准配置
• 您正在CI/CD管道或自动化环境中进行设置
• 您想自定义安装过程的特定方面
• 您是一位熟悉Node.js项目的经验丰富的开发人员

按照以下步骤进行手动安装：

1. 克隆存储库：

   git clone https://github.com/r-huijts/xcode-mcp-server.git
   cd xcode-mcp-server

1. 验证先决条件（必须安装这些先决条件）：

- Xcode和Xcode命令行工具 - Node.js v16或更高版本 - npm - Ruby（用于CocoaPods支持） - CocoaPods（可选，用于pod相关功能）

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 创建配置文件：

   # 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 文件来设置您的首选配置。

1. 对于Claude Desktop集成（可选）：

- 编辑或创建 ~/Library/Application Support/Claude/claude_desktop_config.json - 添加以下配置（根据需要调整路径）：

   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/path/to/xcode-mcp-server/dist/index.js"]
       }
     }
   }

安装故障排除

常见设置问题：

1. 构建错误:

- 确保你有正确的Node.js版本（v16+） - 尝试删除 node_modules 跑步 npm install 再次 - 检查TypeScript错误 npx tsc --noEmit - 确保代码中的所有导入都已正确解析

1. 缺少的依赖:

- 如果您看到有关缺少模块的错误，请运行 npm install 再次 - 对于本机依赖项，您可能需要Xcode命令行工具： xcode-select --install

1. 权限问题:

- 确保您对安装目录具有写入权限 - 对于CocoaPods安装，您可能需要使用 sudo gem install cocoapods

1. 配置问题:

- 验证您的 .env 文件具有正确的格式和有效的路径 - 确保 PROJECTS_BASE_DIR 指向现有目录 - 检查路径是否不包含需要转义的特殊字符

1. Claude桌面集成:

- 确保Claude配置中的路径指向正确的位置 index.js - 更改配置后重新启动Claude Desktop - 在尝试与Claude一起使用之前，请检查服务器是否正在运行

用法

启动服务器

npm start

对于自动重启的开发模式：

npm run dev

配置选项

您可以通过两种方式配置服务器：

1. 环境变量 .env 文件：

   PROJECTS_BASE_DIR=/path/to/your/projects
   DEBUG=true
   ALLOWED_PATHS=/path/to/additional/allowed/directory
   PORT=8080

1. 命令行参数：

   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助手兼容。要连接，请执行以下操作：

1. 启动Xcode MCP服务器
2. 配置您的AI助手以使用服务器URL（通常 http://localhost:3000)
3. 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项目交互提供标准化接口。服务器架构设计有几个关键组件：

核心组件

1. 服务器实现：处理工具注册和请求处理的主MCP服务器。

1. 路径管理：通过根据允许的目录验证所有路径来确保安全的文件访问。

1. 项目管理：检测、加载和管理不同类型的Xcode项目：

- 标准Xcode项目（.xcodeproj） - Xcode工作区（.xcworkspace） - Swift包管理器项目（Package.Swift）

1. 目录状态：维护活动目录上下文以进行相对路径解析。

1. 工具注册表：将工具组织到不同Xcode操作的逻辑类别中。

请求流

1. AI助手向MCP服务器发送工具执行请求。

1. 服务器验证请求参数和权限。

1. 使用经过验证的参数调用相应的工具处理程序。

1. 该工具执行请求的操作，通常使用本机Xcode命令。

1. 结果被格式化并返回给AI助手。

1. 全面的错误处理为故障排除提供了有意义的反馈。

安全功能

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

项目类型支持

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

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

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

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

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

添加新工具

要向服务器添加新工具，请执行以下操作：

1. 在 src/tools/ 目录
2. 使用Zod模式验证的现有模式实现该工具
3. 在类别中注册该工具 index.ts 文件
4. 添加带有特定错误消息的错误处理
5. 在相应的文档文件中记录该工具

故障排除

常见问题

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

调试

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

许可证

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

致谢

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