Xcode项目管理服务

MCP Xcode服务器

一个模型上下文协议（MCP）服务器，使人工智能助手能够通过自然语言交互构建、测试、运行和管理苹果平台项目。

版本：0.6.0

目的

这个MCP服务器弥合了AI助手和苹果开发生态系统之间的差距。它允许像Claude这样的人工智能工具直接执行Xcode和Swift包管理器命令，实现自动化开发工作流程，无需人工干预。该服务器旨在提高令牌效率，提供简洁的输出，同时保持全面的错误报告和调试功能。

为什么使用MCP Xcode服务器？

关键优势

• AI原生开发：使AI助手能够直接构建、测试和运行iOS/macOS应用程序
• 代币效率：优化的输出仅显示基本信息（错误、警告、测试结果）
• 智能错误处理：分析构建错误并提供可操作的建议
• 可视化调试：捕获模拟器屏幕截图以验证UI更改
• 自动模拟器管理：智能地重用正在运行的模拟器以节省时间
• Xcode集成：通过钩子自动将文件操作与Xcode项目同步
• 持续日志记录：所有操作保存到 ~/.mcp-xcode-server/logs/ 用于调试
• 多平台：从单个界面支持iOS、macOS、tvOS、watchOS和visionOS

用例

• 自动化测试：AI可以运行您的测试套件并分析故障
• 构建验证：快速验证跨平台编译的代码更改
• 前端开发：构建和截图应用程序以验证视觉变化
• 依赖管理：以编程方式添加、更新或删除Swift包
• 跨平台开发：在多个苹果平台上测试相同的代码
• CI/CD集成：通过自然语言自动化构建和测试工作流程

局限性

它不能做什么

• 没有SwiftUI预览：Xcode的实时预览需要完整的IDE
• 无交互式UI测试：无法模拟用户交互（点击、滑动）
• 无物理设备：模拟器仅适用于iOS/tvOS/watchOS/visionOS
• 无调试：无断点、单步调试或LLDB访问
• 没有Xcode UI功能：项目配置、故事板编辑需要Xcode
• 平台要求：需要macOS 14+、Xcode 16+、iOS 17+模拟器

当你仍然需要Xcode时

• 使用Interface Builder或SwiftUI预览设计UI
• 使用断点和变量检查进行调试
• 使用仪器进行分析
• 管理证书和配置文件
• 物理设备测试
• 使用Xcode特有的功能（游乐场、AR工具等）

核心功能

构建和测试自动化

• 构建并运行Xcode项目/工作区
• 执行Swift包管理器包
• 运行XCTest和Swift测试套件
• Xcode项目：支持自定义构建配置（调试、发布、测试、暂存等）
• Swift软件包：标准SPM配置（仅调试/发布-SPM限制）

模拟器管理

• 列出适用于任何Apple平台的模拟器并启动
• 捕获屏幕截图以进行视觉验证
• 安装/卸载应用程序
• 通过筛选检索设备日志

错误情报

• 编译错误：显示带有错误消息的文件、行、列
• 方案错误：建议使用 list_schemes 工具
• 代码签名：识别证书和配置问题
• 依赖项：检测缺失的模块和版本冲突

文件同步挂钩

• 自动将文件操作与Xcode项目同步
• 智能地将文件分配到正确的构建阶段（源、资源等）
• 尊重 .no-xcode-sync 选择退出文件
• 在Xcode中保持正确的组结构

安装

先决条件

• macOS 14.0或更高版本
• Xcode 16.0或更高版本
• Node.js 18+
• Xcode命令行工具
• 目标平台模拟器

快速设置

# Install globally
npm install -g mcp-xcode-server

# Run interactive setup
mcp-xcode-server setup

安装向导将：

• 为Claude配置MCP服务器
• 可选择设置Xcode同步挂钩
• 构建必要的辅助工具

手动配置

增添 ~/.claude.json （全球）或 .claude/settings.json （项目）：

{
  "mcpServers": {
    "mcp-xcode-server": {
      "type": "stdio",
      "command": "mcp-xcode-server",
      "args": ["serve"],
      "env": {}
    }
  }
}

可用工具

建筑

• build_xcode：构建Xcode项目/工作区（支持自定义配置）
• build_swift_package：构建Swift包（仅根据SPM规范调试/发布）
• run_xcode：在模拟器/macOS上构建和运行
• run_swift_package：执行Swift包可执行文件

测试

• test_xcode：运行XCTest/Swift测试套件
• test_swift_package：测试Swift包
• 支持按类/方法进行测试筛选

项目信息

• list_schemes：获取可用的Xcode方案
• get_project_info：全面的项目细节
• list_targets：列出所有构建目标
• get_build_settings：获取方案配置

模拟器管理

• list_simulators：显示可用设备
• boot_simulator：启动模拟器
• shutdown_simulator：停止模拟器
• view_simulator_screen：捕获屏幕截图

应用程序管理

• install_app：在模拟器上安装应用程序
• uninstall_app：按捆绑包ID删除应用程序
• get_device_logs：检索已筛选的设备日志

分布

• archive_project：创建.xarchive
• export_ipa：从存档导出IPA

维护

• clean_build：干净的构建工件/Drivedata
• manage_dependencies：添加/删除/更新Swift包

平台支持

建筑

服务器遵循具有SOLID原则的干净/六边形架构：

核心结构

src/
├── features/         # Feature-based vertical slices
│   ├── build/       # Build feature
│   │   ├── domain/  # Build domain objects
│   │   ├── use-cases/
│   │   ├── infrastructure/
│   │   ├── controllers/
│   │   └── factories/
│   ├── simulator/   # Simulator management
│   │   └── ...same structure...
│   └── app-management/ # App installation
│       └── ...same structure...
├── shared/          # Cross-feature shared code
│   ├── domain/      # Shared value objects
│   └── infrastructure/
├── application/     # Application layer ports
│   └── ports/       # Interface definitions
├── presentation/    # MCP presentation layer
│   ├── interfaces/  # MCP contracts
│   └── formatters/  # Output formatting
└── infrastructure/  # Shared infrastructure
    ├── repositories/
    └── services/

关键设计原则

• 清洁建筑：依赖规则-内层对外层一无所知
• 领域驱动设计：具有嵌入式验证的丰富域模型
• 类型安全：带有域原语和解析不生效模式的完整TypeScript
• 安全第一：路径验证、边界处的命令注入保护
• 错误恢复：键入域错误，处理优雅，并提供有用的建议

日志记录

所有操作都记录到 ~/.mcp-xcode-server/logs/:

• 每日文件夹（例如。， 2025-01-27/)
• 7天自动保留
• 保留完整的xcodebuild/swift输出
• Symlinks可轻松访问最新日志

发展

# Build
npm run build

# Test
npm test              # All tests
npm run test:unit    # Unit tests only
npm run test:e2e     # End-to-end tests
npm run test:coverage # With coverage

# Development
npm run dev          # Build and run

贡献

欢迎投稿！请确保：

• 测试通过(npm test)
• 代码遵循SOLID原则
• 新工具包括测试
• 文件已更新

许可证

麻省理工学院

支持

• 报告问题： GitHub问题
• 文档： MCP协议