XcodeMCPWrapper-mcpbridge包装器
一个Python包装器，使Xcode 26.3的MCP桥与Cursor和 其他严格遵守MCP规范的客户。
问题
Xcode的 mcpbridge 在中返回工具响应 content 字段，但省略了必填项 structuredContent 当工具声明 outputSchema根据MCP规范，当 outputSchema 已声明，响应 必须 包括 structuredContent.
- ✅ Claude Code和Codex CLI工作（它们对苹果的响应有特殊处理）
- ❌ 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) │
└─────────────┘ └──────────────────┘ └────────────┘ └─────────┘快速开始
先决条件
- macOS与Xcode 26.3+
- Python 3.9+
- Xcode工具MCP服务器已启用 （见下文）
⚠️ 重要提示： 您必须在Xcode设置中启用Xcode工具MCP： 1. 打开 Xcode > 设置 (⌘,) 1. 选择 智能 在侧边栏中 1. 在...之下 模型上下文协议，切换 Xcode工具 开 如果您在MCP客户端日志中看到“找到0个工具”，则表示此设置未启用。
光标快速设置
如果你使用 光标，无需安装——只需将其添加到 ~/.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中记录了一个已知的Coding Intelligence问题，在正常使用过程中，外部开发工具可能会触发重复的“允许连接？”对话框(
170721057).通过代理模式重用一个长期的上游会话可以减少出现这种提示模式的重新连接流失。查看苹果官方 Xcode 26.4发行说明. - 使用
--broker自动检测——如果守护进程处于活动状态，则连接，否则生成（推荐）。 - 添加
--web-ui（加可选--web-ui-config)当您希望生成的主机或守护进程主机拥有一个共享仪表板端点时。 - 如果你想要一个显式的守护进程所有者和一个跨多个编辑器的可见监控界面，最好使用专用主机：start
--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对于完整的启动/停止/状态命令、游标JSON片段、故障排除和 回滚到直接模式，请参阅 经纪人模式指南.
多智能体指导
当您同时运行多个MCP客户端进程时：
- 专用主机前端工作流程（在可见性重要时推荐）： 开始一个
--broker-daemon --web-ui流程，让每个编辑/客户都保持在线--broker，并附加浏览器仪表板和/或mcpbridge-wrapper --tui同一个主机。 - 统一的单配置自动生成： 为每个客户端配置
--broker --web-ui --web-ui-config当您希望减少设置并可以接受隐式主机所有权时。 - 运行时间预期： 专用主机是控制生命周期的最清晰方式；在统一自动生成中，必须生成代理的第一个客户端启动代理主机和仪表板，以后的客户端会重用它。
- 所有权规则： 只有一个进程可以绑定给定的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/... 而环境是活跃的。
安装
选项1：使用uvx（推荐-最简单）
最快的安装方法是使用 uvx （要求 uv 待安装）：
# No manual installation needed - uvx will automatically download and run
uvx --from mcpbridge-wrapper mcpbridge-wrapper或者直接添加到MCP客户端配置中（请参阅下面的配置部分）。
选项2：通过MCP注册表
如果您的MCP客户端支持MCP注册表：
服务器名称： io.github.SoundBlaster/xcode-mcpbridge-wrapper
# Using 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 args，显式安装Web UI附加组件：
./scripts/install.sh --webui将以下内容添加到您的 ~/.bashrc 或 ~/.zshrc:
export PATH="$HOME/bin:$PATH"然后重新加载：
source ~/.zshrc
# or
. ~/.zshrc方案5：地方发展（venv）
对于开发，或者如果您想直接从克隆的存储库运行：
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
make install # or: make install-webui (for Web UI support)入口点是 .venv/bin/mcpbridge-wrapper.使用 完全绝对路径 配置MCP客户端时（请参阅下面的配置部分）。
卸载
要从系统中删除xcodemcpwrapper：
./scripts/uninstall.sh选项：
--dry-run或-n：显示在不删除的情况下要删除的内容--yes或-y：跳过确认提示
配置
光标
首先列出了代理设置示例。
在代理模式下使用uvx（推荐）：
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
}
}
}在代理模式下使用带有Web UI的uvx（可选）：
{
"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"]
}
}
}在Web UI的直接模式下使用uvx（可选）：
{
"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"]
}
}
}克劳德代码
首先列出了代理设置示例。
在代理模式下使用uvx（推荐）：
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker在代理模式下使用带有Web UI的uvx（可选）：
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在Web UI的直接模式下使用uvx（可选）：
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 8080Codex CLI
首先列出了代理设置示例。
在代理模式下使用uvx（推荐）：
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker在代理模式下使用带有Web UI的uvx（可选）：
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在Web UI的直接模式下使用uvx（可选）：
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 8080Zed代理人
使用uvx（推荐）：
编辑 ~/.zed/settings.json:
{
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
"env": {}
}
}使用带有Web UI的uvx（可选）：
{
"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": {}
}
}化学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": {}
}
}用法
配置后，让你的AI助手使用Xcode工具：
"Build my project"
"Run the tests"
"Find all Swift files in the project"
"Show me the build errors"Web UI仪表板（可选）
包装器包括一个可选的Web UI仪表板，用于实时监控和审计日志记录：
# Start with Web UI
make webui
# Or directly
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设置指南 详细配置。
已知问题
- Broker冷启动--Xcode审批时间竞赛（0个工具带绿点）： 当代理守护进程启动新的
xcrun mcpbridge在首次启动或守护进程重启后，Xcode会显示每个进程的“允许连接？”对话框。如果您的MCP客户端发送tools/list*之前* Xcode授予批准，它收到一个空列表 将其永久缓存 --显示0个工具，绿色连接指示器，无错误消息。每个唯一的二进制路径（直接包装器vs代理守护进程）都会触发一个 *分开* 对话。批准后，权限仍然有效——后续会话不需要重新批准。 解决方法： 启用代理模式后立即查看Xcode对话框；单击“允许”后，在客户端中重新加载MCP连接（禁用→ 在设置中重新启用）。看 故障排除：首次连接代理后0个工具 用于客户端特定的恢复步骤和诊断命令。 - BUG-T5→ FU-P13-T7（P0）： 空内容工具结果仍可能违反严格
structuredContent严格的MCP客户的期望。 - BUG-T6→ FU-P13-T8（P0）： 当多个MCP会话以相同的方式启动时，可能会发生Web UI端口冲突
--web-ui-port（例如8080)，生产address already in use. - BUG-T7→ FU-P13-T9（P0）：
resources/list和resources/templates/list探测可能会在某些客户端路径中返回非标准错误形状。 - Codex Desktop资源探测行为： Xcode MCP是一个专注于工具的服务器。某些Codex Desktop路径仍可能探测
resources/list和resources/templates/list;-32601（“未知方法”） 不 平均工具连接中断。使用实际的Xcode工具调用验证运行状况（例如XcodeListWindows). - Codex代理模式超时回退： 如果Codex工具在代理模式下调用超时，请切换到直接模式（删除
--broker)并通过以下方式进行验证XcodeListWindows.
免责声明（Codex App）
mcpbridge-wrapper 规范Xcode MCP响应，但它不控制Codex App内部。Codex App传输/会话行为可能独立于Codex CLI和此包装器而变化。如果App和CLI不同，请首先将其视为特定于客户端的行为，并使用确切的版本、配置和日志进行验证。
文档
- 安装指南
- 经纪人模式指南 -配置、迁移、回滚和操作
- Web UI仪表板 -实时监控和审计日志记录
- 光标设置
- Claude代码设置
- Codex CLI设置
- 故障排除
- 工具参考
- 建筑
- 贡献 -发展指南和质量门
发展
看 贡献.md 用于开发设置和贡献指南。
快速质量门检查：
make test # Run tests with coverage
make lint # Run ruff linter
make typecheck # Run mypy type checker或者打开所有的门：
make test && make lint && make typecheck演出
- 管理费用： 每次转换小于0.01毫秒
- 内存： 占用空间\<10MB
- 新闻报道： 91.62%的测试覆盖率
许可证
MIT许可证-请参阅 许可证 了解详情。
致谢
- Apple的Xcode团队负责MCP桥功能
- MCP协议规范
- Cursor、Claude和Codex团队负责人工智能驱动的开发工具