Xcode Build

Xcode构建服务器MCP

用于Xcode操作的轻量级模型上下文协议（MCP）服务器，设计时考虑了令牌效率和简单性。

主要特点

• 14统一工具 -以最少的工具数量完成Xcode工作流覆盖
• 智能输出滤波 -将冗长的xcodebuild输出减少80-95%，同时保留错误和失败
• 故障意识 -两步过滤确保测试失败和构建错误永远不会隐藏
• 智能自动检测 -自动检测项目类型并选择合适的模拟器
• 零依赖 -完全使用Go标准库构建
• 碰撞检测 -识别分段错误、Swift致命错误和无声失败
• 跳过测试跟踪 -报告跳过哪些测试以及类名和原因

设计理念

此服务器采用极简主义方法：

• 统一工具 而不是项目/工作空间、模拟器名称/ID等的单独变体。
• 过滤输出 在保留可操作信息的同时消除编译噪音
• 简单配置 存在合理的违约

快速开始

先决条件

• 达到1.24.4或更高
• Xcode 14.0或更高版本
• macOS 12.0或更高版本

安装

# Clone the repository
git clone https://github.com/jontolof/xcode-build-mcp.git
cd xcode-build-mcp

# Build the server
make build

# Or build manually
# go build -o bin/xcode-build-mcp cmd/server/main.go

# Install to PATH (optional)
sudo cp bin/xcode-build-mcp /usr/local/bin/

基本用法

# Run the MCP server
xcode-build-mcp

# Run with debug logging
MCP_LOG_LEVEL=debug xcode-build-mcp

与MCP客户端集成

添加到MCP客户端配置中：

{
  "mcpServers": {
    "xcode-build": {
      "type": "stdio",
      "command": "/usr/local/bin/xcode-build-mcp",
      "args": [],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

14工具

构建和测试工具

1. xcode_build

自动检测项目类型和模拟器的通用构建命令。

{
  "tool": "xcode_build",
  "parameters": {
    "project_path": ".",
    "project": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "configuration": "Debug"
  }
}

2. xcode_test

具有解析结果的通用测试执行。

{
  "tool": "xcode_test",
  "parameters": {
    "project_path": ".",
    "project": "MyApp.xcodeproj",
    "scheme": "MyAppTests"
  }
}

3. xcode_clean

清理构建工件和派生数据。

{
  "tool": "xcode_clean",
  "parameters": {
    "project_path": ".",
    "project": "MyApp.xcodeproj",
    "clean_build": true
  }
}

发现工具

4. discover_projects

在目录树中查找所有Xcode项目。

{
  "tool": "discover_projects",
  "parameters": {
    "root_path": ".",
    "max_depth": 3
  }
}

5. list_schemes

列出可用的构建方案。

{
  "tool": "list_schemes",
  "parameters": {
    "project_path": ".",
    "project": "MyApp.xcodeproj"
  }
}

6. list_simulators

列出可用的iOS/macOS模拟器。

{
  "tool": "list_simulators",
  "parameters": {
    "platform": "iOS",
    "available": true
  }
}

运行时工具

7. simulator_control

启动、关闭或重置模拟器。

{
  "tool": "simulator_control",
  "parameters": {
    "udid": "SIMULATOR-UDID-HERE",
    "action": "boot"
  }
}

8. install_app

将应用程序安装到模拟器或设备上。

{
  "tool": "install_app",
  "parameters": {
    "app_path": "build/MyApp.app",
    "device_type": "iPhone"
  }
}

9. launch_app

使用可选参数启动已安装的应用程序。

{
  "tool": "launch_app",
  "parameters": {
    "bundle_id": "com.example.myapp",
    "device_type": "iPhone",
    "arguments": ["--debug", "--mock-data"]
  }
}

调试工具

10. capture_logs

捕获和过滤设备/模拟器日志。

{
  "tool": "capture_logs",
  "parameters": {
    "device_type": "iPhone",
    "bundle_id": "com.example.myapp",
    "max_lines": 100
  }
}

11. screenshot

捕捉模拟器屏幕截图。

{
  "tool": "screenshot",
  "parameters": {
    "device_type": "iPhone",
    "output_path": "screenshots/login.png"
  }
}

12. describe_ui

获取UI元素层次结构以进行测试。

{
  "tool": "describe_ui",
  "parameters": {
    "device_type": "iPhone",
    "output_format": "tree"
  }
}

自动化工具

13. ui_interact

执行UI交互（点击、滑动、键入）。

{
  "tool": "ui_interact",
  "parameters": {
    "device_type": "iPhone",
    "action": "tap",
    "x": 100,
    "y": 200
  }
}

14. get_app_info

提取应用程序元数据和信息。

{
  "tool": "get_app_info",
  "parameters": {
    "app_path": "build/MyApp.app",
    "include_entitlements": true
  }
}

输出滤波

原始的xcodebuild输出可能非常冗长（典型的测试运行需要100K+个字符）。此服务器过滤输出以显示重要内容：

输出模式

什么被过滤

移除 （噪音）：

• 编译命令详细信息
• 框架加载消息
• SwiftDriver内部输出
• 对详细日志进行代码签名

保存的 （重要）：

• 构建/测试成功或失败
• 包含文件/行信息的错误消息
• 测试失败详细信息
• 跳过测试详细信息（类名、原因）
• 警告
• 最终总结

配置

环境变量

刀具参数

使用以下工具控制每个工具的输出详细程度 output_mode 参数：

{
  "tool": "xcode_build",
  "parameters": {
    "scheme": "MyApp",
    "output_mode": "minimal"
  }
}

可用模式：

• minimal -仅错误和关键信息
• standard -错误、警告和摘要（默认）
• verbose -完整构建输出

发展

从源头构建

# Clone repository
git clone https://github.com/jontolof/xcode-build-mcp.git
cd xcode-build-mcp

# Install dependencies (minimal)
go mod download

# Build
go build -o xcode-build-mcp cmd/server/main.go

# Run tests
go test ./...

# Run with race detection
go test -race ./...

# Generate coverage report
go test -cover ./...

项目结构

xcode-build-mcp/
├── cmd/server/          # Server entry point (main.go)
├── internal/
│   ├── mcp/            # MCP protocol implementation (JSON-RPC 2.0)
│   ├── xcode/          # Xcode command execution and parsing
│   ├── filter/         # Output filtering system
│   ├── cache/          # Smart caching for project/scheme detection
│   ├── tools/          # MCP tool implementations (14 tools)
│   ├── common/         # Shared interfaces and utilities
│   ├── metrics/        # Performance metrics tracking
│   └── session/        # Session management
├── pkg/types/          # Shared types and error handling
├── tests/              # Test fixtures and integration tests
│   ├── fixtures/       # Test data and mock files
│   ├── integration/    # Integration tests
│   └── mocks/          # Mock implementations
└── docs/               # Documentation and ADRs
    └── adr/            # Architectural Decision Records

测试

# Run all tests
make test

# Run integration tests
make test-integration

# Run benchmarks
make bench

# Check coverage
make coverage

文档

• 更新日志 -版本历史和发行说明
• 架构决策记录 -设计决策和基本原理
• 贡献 -如何为这个项目做出贡献

安全

• 没有记录或缓存敏感数据
• 所有用户路径都经过验证
• 指令注入保护
• 安全处理构建工件

许可证

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

支持

• -Bug报告和功能请求
• 讨论 -一般性讨论
• 维基 -其他文件

项目状态

此服务器稳定且得到积极维护。所有14个工具都已实施和测试。

请参阅 更新日志 查看最新更新。