金大哥 - xcodemcpwrapper MCP 详情

article

README

🚀 XcodeMCPWrapper - mcpbridge-wrapper

XcodeMCPWrapper 是一个 Python 包装器，它使 Xcode 26.3 的 MCP 桥与 Cursor 等严格符合 MCP 规范的客户端兼容，解决了 Xcode mcpbridge 返回响应时缺少 structuredContent 字段的问题。

🚀 快速开始

前提条件

安装了 Xcode 26.3 或更高版本的 macOS 系统。
Python 3.9 或更高版本。
启用 Xcode Tools MCP Server（详见下文）。

⚠️ 重要提示

必须在 Xcode 设置中启用 Xcode Tools MCP：

打开 Xcode > Settings（⌘,）。

在侧边栏中选择 Intelligence。

在 Model Context Protocol 下，将 Xcode Tools 开关打开。

如果在 MCP 客户端日志中看到 "Found 0 tools"，则表示此设置未启用。

Cursor 快速设置

如果使用 Cursor，无需安装，只需将以下内容添加到 ~/.cursor/mcp.json 中：

代理模式（推荐）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
    }
  }
}

使用 Web UI 仪表盘（可选，可在 http://localhost:8080 进行实时监控）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "mcpbridge-wrapper[webui]",
        "mcpbridge-wrapper",
        "--broker",
        "--web-ui",
        "--web-ui-config",
        "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
      ]
    }
  }
}

直接模式（可选）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
    }
  }
}

如果升级后想确认当前运行的仪表盘进程版本：

PORT=8080
PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
PY=$(ps -p "$PID" -o command= | awk '{print $1}')
"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'

如有需要，进行一次性刷新启动：

uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080

重启 Cursor 即可。如需了解其他客户端或安装方法，请继续阅读。

代理模式

代理模式允许多个短生命周期的 MCP 客户端会话共享一个持久的上游桥接会话。

模式存在原因：Apple 在 Xcode 26.4 的编码智能文档中指出一个已知问题，外部开发工具在正常使用过程中可能会触发重复的 "Allow Connection?" 对话框（170721057）。通过代理模式重用一个长生命周期的上游会话可以减少重新连接的次数，从而避免出现此提示。详见 Apple 官方 Xcode 26.4 发行说明。
使用 --broker 进行自动检测：如果守护进程存活则连接，否则启动（推荐）。
当希望启动的或守护进程的主机拥有一个共享的仪表盘端点时，添加 --web-ui（可选 --web-ui-config）。
如果希望有一个明确的守护进程所有者以及跨多个编辑器的可见监控界面，建议使用专用主机：启动一次 --broker-daemon --web-ui，让客户端使用 --broker，并将浏览器仪表盘和/或 --tui 连接到该主机。

快速迁移示例：

# Claude Code
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker

# Codex CLI
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker

有关完整的启动/停止/状态命令、Cursor JSON 代码片段、故障排除以及回退到直接模式的信息，请参阅代理模式指南。

多代理指导

当同时运行多个 MCP 客户端进程时：

专用主机前端工作流（当可见性很重要时推荐）：启动一个 --broker-daemon --web-ui 进程，让每个编辑器/客户端使用 --broker，并将浏览器仪表盘和/或 mcpbridge-wrapper --tui 连接到同一主机。
统一单配置自动启动：当希望减少设置并能接受隐式主机所有权时，为每个客户端配置 --broker --web-ui --web-ui-config <shared-path>。
运行时预期：专用主机是控制生命周期最清晰的方式；在统一自动启动中，第一个必须启动代理的客户端将启动代理主机和仪表盘，后续客户端将重用它。
所有权规则：只有一个进程可以绑定给定的 Web UI host:port（例如 127.0.0.1:8080）。
连接行为：当代理已经在运行时，--broker 将重用它，并且不会将仪表盘设置应用到现有主机上。
回退行为：如果仪表盘绑定失败（端口已被使用），代理 MCP 传输将继续，仅跳过仪表盘启动。
验证流程：使用 mcpbridge-wrapper --broker-status、~/.mcpbridge_wrapper/ 下的文件以及共享仪表盘/TUI 状态来验证两个编辑器是否连接到同一个守护进程。

详见代理模式指南、Web UI 设置指南和故障排除。

Python 环境设置（开发）

如果计划运行 make install、pytest 或其他开发命令，请先创建并激活虚拟环境，以避免 Homebrew Python 的 externally-managed-environment（PEP 668）错误。

cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
make install

快速检查：

which python3
which pip

在环境激活时，两者都应指向 .venv/bin/...。

✨ 主要特性

拦截 xcrun mcpbridge 的响应，并将 content 中的数据复制到 structuredContent 中，使 Xcode 的 MCP 工具与所有 MCP 客户端完全兼容。
提供代理模式，允许多个短生命周期的 MCP 客户端会话共享一个持久的上游桥接会话，减少重新连接的次数。
包含可选的 Web UI 仪表盘，用于实时监控和审计日志记录。

📦 安装指南

选项 1：使用 uvx（推荐 - 最简单）

最快的安装方法是使用 uvx（需要安装 uv）：

# 无需手动安装 - uvx 将自动下载并运行
uvx --from mcpbridge-wrapper mcpbridge-wrapper

或者直接添加到 MCP 客户端配置中（详见下文配置部分）。

选项 2：通过 MCP 注册表

如果 MCP 客户端支持 MCP 注册表： 服务器名称：io.github.SoundBlaster/xcode-mcpbridge-wrapper

# 使用 mcp-publisher CLI
mcp-publisher install io.github.SoundBlaster/xcode-mcpbridge-wrapper

选项 3：使用 pip

python3 -m pip install mcpbridge-wrapper

然后使用 mcpbridge-wrapper 或 xcodemcpwrapper 命令。

选项 4：手动安装（通过安装脚本）

git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
./scripts/install.sh

安装脚本将创建一个虚拟环境，安装软件包，并在 ~/bin/xcodemcpwrapper 处放置一个包装器。

如果计划使用 --web-ui MCP 参数，请显式安装 Web UI 额外组件：

./scripts/install.sh --webui

将以下内容添加到 ~/.bashrc 或 ~/.zshrc 中：

export PATH="$HOME/bin:$PATH"

然后重新加载：

source ~/.zshrc
# 或者
. ~/.zshrc

选项 5：本地开发（venv）

如果进行开发或希望直接从克隆的存储库运行：

git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
make install          # 或者：make install-webui（支持 Web UI）

入口点是 .venv/bin/mcpbridge-wrapper。在配置 MCP 客户端时，请使用 完整的绝对路径（详见下文配置部分）。

卸载

要从系统中移除 xcodemcpwrapper：

./scripts/uninstall.sh

选项：

--dry-run 或 -n：显示将被移除的内容，但不实际移除。
--yes 或 -y：跳过确认提示。

💻 使用示例

基础用法

配置完成后，让 AI 助手使用 Xcode 工具：

"Build my project"
"Run the tests"
"Find all Swift files in the project"
"Show me the build errors"

📚 详细文档

配置

Cursor

首先列出代理设置示例。

使用 uvx 代理模式（推荐）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
    }
  }
}

使用 uvx 代理模式并启用 Web UI（可选）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "mcpbridge-wrapper[webui]",
        "mcpbridge-wrapper",
        "--broker",
        "--web-ui",
        "--web-ui-config",
        "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
      ]
    }
  }
}

使用 uvx 直接模式：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
    }
  }
}

使用 uvx 直接模式并启用 Web UI（可选）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "mcpbridge-wrapper[webui]",
        "mcpbridge-wrapper",
        "--web-ui",
        "--web-ui-port",
        "8080"
      ]
    }
  }
}

手动安装（直接模式）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
      "args": []
    }
  }
}

手动安装并启用 Web UI（直接模式，可选）：

需要使用 ./scripts/install.sh --webui 进行安装（或等效的 .[webui] 依赖项）。

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
      "args": ["--web-ui", "--web-ui-port", "8080"]
    }
  }
}

本地开发（venv，直接模式）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper"
    }
  }
}

本地开发并启用 Web UI（直接模式，可选）：

{
  "mcpServers": {
    "xcode-tools": {
      "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
      "args": ["--web-ui", "--web-ui-port", "8080"]
    }
  }
}

Claude Code

首先列出代理设置示例。

使用 uvx 代理模式（推荐）：

claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker

使用 uvx 代理模式并启用 Web UI（可选）：

claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json"

使用 uvx 直接模式：

claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper

使用 uvx 直接模式并启用 Web UI（可选）：

claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080

手动安装（直接模式）：

claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper

手动安装并启用 Web UI（直接模式，可选）：需要使用 ./scripts/install.sh --webui 进行安装（或等效的 .[webui] 依赖项）。

claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080

本地开发（venv，直接模式）：

claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper

本地开发并启用 Web UI（直接模式，可选）：

claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080

Codex CLI

首先列出代理设置示例。

使用 uvx 代理模式（推荐）：

codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker

使用 uvx 代理模式并启用 Web UI（可选）：

codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json"

使用 uvx 直接模式：

codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper

使用 uvx 直接模式并启用 Web UI（可选）：

codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080

手动安装（直接模式）：

codex mcp add xcode -- ~/bin/xcodemcpwrapper

手动安装并启用 Web UI（直接模式，可选）：需要使用 ./scripts/install.sh --webui 进行安装（或等效的 .[webui] 依赖项）。

codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080

本地开发（venv，直接模式）：

codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper

本地开发并启用 Web UI（直接模式，可选）：

codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080

Zed Agent

使用 uvx（推荐）：编辑 ~/.zed/settings.json：

{
  "xcode-tools": {
    "command": "uvx",
    "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
    "env": {}
  }
}

使用 uvx 并启用 Web UI（可选）：

{
  "xcode-tools": {
    "command": "uvx",
    "args": [
      "--from",
      "mcpbridge-wrapper[webui]",
      "mcpbridge-wrapper",
      "--web-ui",
      "--web-ui-port",
      "8080"
    ],
    "env": {}
  }
}

手动安装：

{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": [],
    "env": {}
  }
}

手动安装并启用 Web UI（可选）：需要使用 ./scripts/install.sh --webui 进行安装（或等效的 .[webui] 依赖项）。

{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": ["--web-ui", "--web-ui-port", "8080"],
    "env": {}
  }
}

本地开发（venv，直接模式）：

{
  "xcode-tools": {
    "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
    "args": [],
    "env": {}
  }
}

本地开发并启用 Web UI（直接模式，可选）：

{
  "xcode-tools": {
    "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
    "args": ["--web-ui", "--web-ui-port", "8080"],
    "env": {}
  }
}

Kimi CLI

使用 uvx（推荐）：编辑 ~/.kimi/mcp.json：

{
  "xcode-tools": {
    "command": "uvx",
    "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
    "env": {}
  }
}

手动安装：

{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": [],
    "env": {}
  }
}

Web UI 仪表盘（可选）

包装器包含一个可选的 Web UI 仪表盘，用于实时监控和审计日志记录：

# 启动 Web UI
make webui

# 或者直接启动
python -m mcpbridge_wrapper --web-ui --web-ui-port 8080

特性：

实时指标：请求每秒（RPS）、延迟百分位数（p50、p95、p99）、错误率。
工具使用分析：最常用工具的可视化图表。
审计日志：所有 MCP 工具调用的持久日志，支持导出（JSON/CSV）。
请求检查器：带有过滤功能的实时日志流。

在浏览器中打开 http://localhost:8080 查看仪表盘。

多代理设置的重要注意事项：

仪表盘由一个包装器进程托管，而不是由 Xcode 或 mcpbridge 托管。
单个 host:port 只能有一个监听器；同一端口上的其他进程将跳过仪表盘启动并继续 MCP 流量。
对于明确的阶段 6 操作员工作流，使用 --broker-daemon --web-ui 运行一个专用的代理主机，然后从浏览器仪表盘和/或 mcpbridge-wrapper --tui 监控同一主机。

详见 Web UI 设置指南以获取详细配置信息。

🔧 技术细节

问题描述

Xcode 的 mcpbridge 在 content 字段中返回工具响应，但当工具声明 outputSchema 时，会省略所需的 structuredContent 字段。根据 MCP 规范，当声明 outputSchema 时，响应必须包含 structuredContent。

✅ Claude Code 和 Codex CLI 可以正常工作（它们对 Apple 的响应有特殊处理）。
❌ Cursor 严格遵循规范，会拒绝不符合规范的响应。

解决方案

mcpbridge-wrapper 拦截 xcrun mcpbridge 的响应，并将 content 中的数据复制到 structuredContent 中，使 Xcode 的 MCP 工具与所有 MCP 客户端完全兼容。

┌─────────────┐    MCP Protocol    ┌──────────────────┐   MCP Protocol   ┌────────────┐    XPC    ┌─────────┐
│   Cursor    │ ◄────────────────► │ mcpbridge-wrapper│ ◄──────────────► │ mcpbridge  │ ◄───────► │  Xcode  │
│ (MCP Client)│                    │  (This Project)  │                  │  (Bridge)  │           │  (IDE)  │
└─────────────┘                    └──────────────────┘                  └────────────┘           └─────────┘

已知问题

代理冷启动 — Xcode 批准时间竞争（显示 0 个工具但有绿色圆点）：当代理守护进程启动一个新的 xcrun mcpbridge 进程（首次启动或守护进程重启后），Xcode 会显示一个每个进程的 "Allow Connection?" 对话框。如果 MCP 客户端在 Xcode 批准之前发送 tools/list 请求，它将收到一个空列表并 永久缓存 — 显示 0 个工具并带有绿色连接指示器，且没有错误消息。每个唯一的二进制路径（直接包装器与代理守护进程）都会触发一个 单独的 对话框。批准后，权限将持续存在 — 后续会话无需重新批准。解决方法：在启用代理模式后立即关注 Xcode 对话框；点击允许后，在客户端中重新加载 MCP 连接（在设置中禁用 → 重新启用）。详见故障排除：首次代理连接后显示 0 个工具以获取特定客户端的恢复步骤和诊断命令。
BUG-T5 → FU-P13-T7 (P0)：空内容的工具结果仍可能违反严格 MCP 客户端对 structuredContent 的严格要求。
BUG-T6 → FU-P13-T8 (P0)：当多个 MCP 会话使用相同的 --web-ui-port（例如 8080）启动时，可能会发生 Web UI 端口冲突，导致 address already in use 错误。
BUG-T7 → FU-P13-T9 (P0)：在某些客户端路径中，resources/list 和 resources/templates/list 探测可能会返回非标准的错误格式。

免责声明（Codex App）

mcpbridge-wrapper 对 Xcode MCP 响应进行规范化处理，但它无法控制 Codex App 的内部行为。Codex App 的传输/会话行为可能独立于 Codex CLI 和此包装器发生变化。如果 App 和 CLI 表现不同，请首先将其视为客户端特定行为，并使用确切的版本、配置和日志进行验证。

文档

安装指南
代理模式指南 - 配置、迁移、回退和操作
Web UI 仪表盘 - 实时监控和审计日志记录
Cursor 设置
Claude Code 设置
Codex CLI 设置
故障排除
工具参考
架构
贡献指南 - 开发指南和质量检查

开发

详见 CONTRIBUTING.md 以获取开发设置和贡献指南。

快速质量检查：

make test      # 运行测试并生成覆盖率报告
make lint      # 运行 ruff 代码检查
make typecheck # 运行 mypy 类型检查

或者运行所有检查：

make test && make lint && make typecheck

性能

开销：每次转换 <0.01ms
内存：占用 <10MB
覆盖率：测试覆盖率为 91.62%

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

致谢

Apple 的 Xcode 团队提供了 MCP 桥接功能。
MCP 协议规范。
Cursor、Claude 和 Codex 团队提供的人工智能开发工具。

xcodemcpwrapper

README

🚀 XcodeMCPWrapper - mcpbridge-wrapper

🚀 快速开始

前提条件

Cursor 快速设置

代理模式

多代理指导

Python 环境设置（开发）

✨ 主要特性

📦 安装指南

选项 1：使用 uvx（推荐 - 最简单）

选项 2：通过 MCP 注册表

选项 3：使用 pip

选项 4：手动安装（通过安装脚本）

选项 5：本地开发（venv）

卸载

💻 使用示例

基础用法

📚 详细文档

配置

Cursor

Claude Code

Codex CLI

Zed Agent

Kimi CLI

Web UI 仪表盘（可选）

🔧 技术细节

问题描述

解决方案

已知问题

免责声明（Codex App）

文档

开发

性能

📄 许可证

致谢

运行方式说明

托管运行

本地运行 / 其它方式