Xcsift MCP

🚀 xcsift-mcp

xcsift-mcp 是一個 MCP（模型上下文協議）服務器，它封裝了 xcsift，使 AI 編碼助手能夠將 Xcode 構建輸出解析為結構化、高效利用令牌的格式。

🚀 快速開始

xcsift-mcp 為 AI 編碼助手（如 Claude、OpenCode、Cursor 等）提供了以下工具：

• 解析：將原始的 xcodebuild 或 swift build/test 輸出解析為結構化的 JSON 或 TOON 格式。
• 執行：執行構建命令並自動獲取解析結果。
• 提取：提取錯誤、警告、測試失敗信息和鏈接器錯誤，並附帶文件/行信息。
• 分析：從測試運行中分析代碼覆蓋率。

輸出經過優化，以提高令牌使用效率，TOON 格式比 JSON 格式的令牌數量減少 30 - 60%。

✨ 主要特性

• 支持多種 AI 編碼助手集成。
• 提供多種解析和構建執行工具。
• 支持 JSON 和 TOON 兩種輸出格式，可根據需求選擇。
• 提供豐富的資源和提示模板，方便開發和調試。

📦 安裝指南

前提條件

• Python 3.10 及以上版本。
• macOS 系統（xcsift 僅支持 macOS）。
• pipx（可通過 brew install pipx 進行安裝）。

從源代碼安裝

git clone https://github.com/johnnyclem/xcsift_mcp.git
cd xcsift_mcp
pipx install -e ".[dev]"

通過 Homebrew 安裝

brew install johnnyclem/xcsift-mcp/xcsift-mcp

xcsift 二進制文件

服務器在首次運行時，如果 xcsift 二進制文件尚未安裝，將自動從 GitHub 發佈版本中下載。該二進制文件將緩存到 ~/.local/share/xcsift-mcp/bin/ 目錄下。

你也可以通過 Homebrew 手動安裝：

brew install xcsift

💻 使用示例

運行服務器

# 使用標準輸入輸出傳輸（默認，適用於 Claude Desktop/OpenCode）
xcsift-mcp

# 使用 HTTP 傳輸（用於調試/網頁客戶端）
xcsift-mcp --transport http --port 8000

與 AI 助手集成

Claude Desktop

在 claude_desktop_config.json 中添加以下內容：

{
  "mcpServers": {
    "xcsift": {
      "command": "xcsift-mcp"
    }
  }
}

OpenCode

在 opencode.json（或 opencode.jsonc）中添加以下內容：

{
  "mcp": {
    "xcsift": {
      "type": "local",
      "command": ["xcsift-mcp"]
    }
  }
}

或者運行 opencode mcp add 並按照交互式提示操作。

Cursor

在 Cursor 設置的 MCP 配置中添加，或在 .cursor/mcp.json 中添加以下內容：

{
  "mcpServers": {
    "xcsift": {
      "command": "xcsift-mcp"
    }
  }
}

示例代碼

解析現有構建輸出

# 在你的 AI 助手中
result = parse_xcodebuild_output(
    output="<raw xcodebuild output>",
    format="toon",  # 或 "json"
    include_warnings=True
)

運行構建並獲取解析結果

result = xcodebuild(
    action="build",
    scheme="MyApp",
    destination="platform=iOS Simulator,name=iPhone 15",
    output_format="json"
)

運行帶覆蓋率的測試

result = swift_test(
    enable_code_coverage=True,
    output_format="toon"
)

僅提取錯誤信息

errors = extract_errors(output="<raw xcodebuild output>")
# 返回: [{"file": "main.swift", "line": 15, "message": "..."}]

📚 詳細文檔

可用工具

解析工具

構建執行工具

工具參數

parse_xcodebuild_output

xcodebuild

swift_build

swift_test

輸出格式

JSON 格式

標準的結構化 JSON 輸出：

{
  "status": "failed",
  "summary": {
    "errors": 1,
    "warnings": 3,
    "failed_tests": 0,
    "linker_errors": 0,
    "build_time": "3.2s"
  },
  "errors": [
    {
      "file": "main.swift",
      "line": 15,
      "message": "use of undeclared identifier 'unknown'"
    }
  ],
  "warnings": [
    {
      "file": "view.swift",
      "line": 20,
      "message": "variable 'temp' was never used",
      "type": "compile"
    }
  ]
}

TOON 格式（令牌優化）

比 JSON 格式的令牌數量減少 30 - 60%：

status: failed
summary:
  errors: 1
  warnings: 3
  failed_tests: 0
  linker_errors: 0
  build_time: 3.2s
errors[1]{file,line,message}:
  main.swift,15,"use of undeclared identifier 'unknown'"
warnings[1]{file,line,message,type}:
  view.swift,20,"variable 'temp' was never used","compile"

何時使用每種格式：

• JSON：當你需要以編程方式解析輸出或與其他工具集成時使用。
• TOON：當發送給大語言模型以減少令牌使用和 API 成本時使用。

可用資源

可用提示

🔧 技術細節

項目結構

xcsift_mcp/
├── src/xcsift_mcp/
│   ├── __init__.py           # 包初始化
│   ├── __main__.py           # 入口點
│   ├── server.py             # FastMCP 服務器
│   ├── xcsift_installer.py   # 自動下載 xcsift
│   ├── resources.py          # MCP 資源
│   ├── prompts.py            # 提示模板
│   └── tools/
│       ├── parse.py          # 解析工具
│       └── build.py          # 構建執行工具
├── tests/
│   ├── fixtures/             # 示例構建輸出
│   └── test_*.py             # 測試文件
├── pyproject.toml
└── README.md

架構

┌─────────────────────────────────────────────────────────────────┐
│                 AI 助手 (Claude, OpenCode, 等)                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MCP 協議 (標準輸入輸出/HTTP)                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     xcsift MCP 服務器 (Python)                   │
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────────┐  │
│  │   工具 (9)      │  │  資源 (4)       │  │  提示 (6)      │  │
│  │ - parse_output  │  │ - version        │  │ - analyze      │  │
│  │ - xcodebuild    │  │ - config         │  │ - fix_errors   │  │
│  │ - swift_build   │  │ - formats        │  │ - coverage     │  │
│  │ - swift_test    │  │ - help           │  │ - debug        │  │
│  └─────────────────┘  └──────────────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     xcsift 命令行工具 (子進程)                     │
└─────────────────────────────────────────────────────────────────┘

🔧 故障排除

找不到 xcsift

如果無法自動下載 xcsift，請手動安裝：

brew install xcsift

權限被拒絕

確保 xcsift 二進制文件具有執行權限：

chmod +x ~/.local/share/xcsift-mcp/bin/xcsift

構建超時

對於長時間的構建，可以增加超時參數：

xcodebuild(scheme="MyApp", timeout=1200)  # 20 分鐘

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

致謝

• xcsift - 實際執行解析的 Swift 命令行工具。
• MCP Python SDK - 模型上下文協議的實現。