使用说明

xcsift mcp

包装的MCP（模型上下文协议）服务器 xcsift，使AI编码助手能够将Xcode构建输出解析为结构化、令牌高效的格式。

概述

xcsift-mcp 为AI编码助手（如Claude、OpenCode、Cursor等）提供以下工具：

解析原始 xcodebuild 或 swift build/test 输出为结构化JSON或TOON格式
执行构建命令并自动获取解析结果
提取包含文件/行信息的错误、警告、测试失败和链接器错误
分析测试运行的代码覆盖率

输出针对令牌效率进行了优化，与JSON相比，TOON格式提供的令牌减少了30-60%。

安装

先决条件

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

用法

运行服务器

# Run with stdio transport (default, for Claude Desktop/OpenCode)
xcsift-mcp

# Run with HTTP transport (for debugging/web clients)
xcsift-mcp --transport http --port 8000

与AI助手集成

克劳德桌面版

添加到您的 claude_desktop_config.json:

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

OpenCode

添加到您的 opencode.json （或 opencode.jsonc):

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

或者，运行 opencode mcp add 并按照交互式提示进行操作。

光标

在光标设置中添加到MCP配置，或添加到 .cursor/mcp.json:

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

可用工具

解析工具

工具	说明
`parse_xcodebuild_output`	将原始xcodebuild/swift输出解析为JSON或TOON格式
`extract_errors`	仅提取包含文件/行信息的错误
`extract_warnings`	仅提取带有文件/行/类型的警告
`extract_test_failures`	使用断言消息提取失败的测试
`get_build_summary`	获取错误/警告计数的快速摘要

构建执行工具

工具	说明
`xcodebuild`	运行xcodebuild并自动解析输出
`swift_build`	为SPM项目运行快速构建
`swift_test`	使用可选覆盖范围运行快速测试
`run_shell_build_command`	运行任意构建命令并解析输出

刀具参数

`parse_xcodebuild_output`

参数	类型	默认值	说明
`output`	string	必需	原始xcodebuild/swift输出（使用 `2>&1` 捕获stderr）
`format`	`"json"`	`"toon"`	`"json"`
`include_warnings` bool的。 `false`	包括详细的警告列表
`include_coverage` bool的。 `false`	包括覆盖范围数据（如果可用）

`xcodebuild`

参数	类型	默认值	说明
`action`	`"build"`	`"test"`	`"clean"`
`scheme`	string	none	要构建的方案
`project`	string	none	.xcodeproj的路径
`workspace`	string	none	.xcworkspace的路径
`destination`	string	none	目的地（例如。， `"platform=iOS Simulator,name=iPhone 15"`)
`configuration`	`"Debug"`	`"Release"`	none
`enable_code_coverage` bool的。 `false`	启用测试覆盖率
`output_format`	`"json"`	`"toon"`	`"json"`
`timeout`	int	`600`	超时时间（秒）

`swift_build`

参数	类型	默认值	说明
`configuration`	`"debug"`	`"release"`	`"debug"`
`package_path`	string	none	Swift包的路径
`target`	string	none	要构建的特定目标
`output_format`	`"json"`	`"toon"`	`"json"`
`timeout`	int	`300`	超时时间（秒）

`swift_test`

参数	类型	默认值	说明
`package_path`	string	none	Swift包的路径
`filter_test`	string	none	过滤测试（例如。， `"MyTests.testFoo"`)
`enable_code_coverage` bool的。 `false`	启用覆盖范围收集
`parallel` bool的。 `true`	并行运行测试
`output_format`	`"json"`	`"toon"`	`"json"`
`timeout`	int	`600`	超时时间（秒）

示例用法

解析现有构建输出

# In your AI assistant
result = parse_xcodebuild_output(
    output="<raw xcodebuild output>",
    format="toon",  # or "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>")
# Returns: [{"file": "main.swift", "line": 15, "message": "..."}]

输出格式

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：当您需要以编程方式解析输出或与其他工具集成时
卡通：发送到LLM以减少令牌使用和API成本时

可用资源

资源URI	描述
`xcsift://version`	xcsift版本和安装信息
`xcsift://config-template`	xcscreen.toml配置示例
`xcsift://output-formats`	关于输出格式的文档
`xcsift://help`	全面的帮助文档

可用提示

提示	描述	参数
`analyze_build_failure`	用于分析构建失败的模板	`errors`, `code_context`
`fix_compiler_errors`	修复Swift/ObjC编译器错误的模板	`errors`, `file_content`
`improve_test_coverage`	提高测试覆盖率的模板	`coverage_report`, `target_coverage`
`debug_test_failures`	调试测试失败模板	`test_output`, `test_code`
`fix_linker_errors`	用于修复链接器错误的模板	`linker_errors`, `project_structure`
`analyze_build_performance`	用于分析构建性能的模板	`build_info`

发展

运行测试

pytest

在覆盖范围内运行测试

pytest --cov=xcsift_mcp

代码格式化

ruff format .
ruff check .

项目结构

xcsift_mcp/
├── src/xcsift_mcp/
│   ├── __init__.py           # Package init
│   ├── __main__.py           # Entry point
│   ├── server.py             # FastMCP server
│   ├── xcsift_installer.py   # Auto-download xcsift
│   ├── resources.py          # MCP resources
│   ├── prompts.py            # Prompt templates
│   └── tools/
│       ├── parse.py          # Parsing tools
│       └── build.py          # Build execution tools
├── tests/
│   ├── fixtures/             # Sample build outputs
│   └── test_*.py             # Test files
├── pyproject.toml
└── README.md

建筑

┌─────────────────────────────────────────────────────────────────┐
│                 AI Assistant (Claude, OpenCode, etc.)           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MCP Protocol (stdio/HTTP)                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     xcsift MCP Server (Python)                   │
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────────┐  │
│  │   Tools (9)     │  │  Resources (4)   │  │  Prompts (6)   │  │
│  │ - parse_output  │  │ - version        │  │ - analyze      │  │
│  │ - xcodebuild    │  │ - config         │  │ - fix_errors   │  │
│  │ - swift_build   │  │ - formats        │  │ - coverage     │  │
│  │ - swift_test    │  │ - help           │  │ - debug        │  │
│  └─────────────────┘  └──────────────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     xcsift CLI (subprocess)                      │
└─────────────────────────────────────────────────────────────────┘

故障排除

未找到xcsift

如果xcsift无法自动下载，请手动安装：

brew install xcsift

权限不足

确保xcsift二进制文件具有执行权限：

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

构建超时

增加长版本的超时参数：

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

许可证

MIT许可证-请参阅许可证了解详情。

学分

xcsift -执行实际解析的Swift CLI工具
MCP Python SDK -模型上下文协议实现