AI导哈

Claude代码MCP桥接器

一个在Claude桌面版和Claude代码CLI之间实现透明通信的MCP无关消息传递桥接器，支持零开销的任务委托和会话管理。

  • by MagicTurtle-s
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 MagicTurtle-s/claude-code-mcp-bridge

使用说明

克劳德码MCP桥

Claude Desktop和Claude Code CLI之间的纯消息传输——与MCP无关，开销为零。

此MCP（模型上下文协议）服务器创建了一个透明的网桥，允许Claude Desktop使用任何MCP配置将任务委托给Claude Code CLI，而网桥不需要知道特定的MCP。

建筑：纯轮渡模式

这座桥是 简单信息管道 对MCP一无所知：

Claude Desktop/Code (Caller)
    ↓ Provides MCP config path
Bridge (Pure Ferry)
    ↓ Passes config transparently
Claude Code Subprocess
    ↓ Loads ANY MCP from config
Results flow back

关键原则： 网桥永远不知道存在哪些MCP。它简单地说：

  1. 接受具有可选MCP配置路径的执行请求
  2. 使用该配置生成Claude代码
  3. 返回结果
  4. 永远保持MCP的不可知性

特性

  • 零MCP知识：Bridge没有硬编码的MCP上下文
  • 无限的可扩展性：适用于任何MCP-现在或未来
  • 最小令牌开销：无论MCP数量如何，只有4个工具
  • 简单架构：纯消息传递，无编排逻辑
  • 完全克劳德代码访问：所有子代理、工具和功能
  • 流媒体响应：实时进度更新
  • 会话管理：跟踪和监控活动会话
  • 会话保持：OAuth会话在桌面重新启动时持续存在
  • 自动身份验证：无缝OAuth流程，浏览器自动打开
  • 速率限制保护：智能身份验证缓存可防止速率限制

快速开始

先决条件

  • Node.js 18+
  • 克劳德代码CLI 已安装并位于PATH中
  • 克劳德桌面 安装

安装

# Clone and setup
git clone https://github.com/MagicTurtle-s/claude-code-mcp-bridge.git
cd claude-code-mcp-bridge
npm install
npm run build

配置Claude桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code-bridge": {
      "command": "node",
      "args": ["/path/to/claude-code-mcp-bridge/build/index.js"],
      "env": {
        "DEBUG": "false",
        "CLAUDE_CODE_PATH": "claude"
      }
    }
  }
}

验证设置

重新启动克劳德桌面。桥接器应自动启动并露出4个工具。

可用工具

该桥提供4个通用的、与MCP无关的工具：

1. execute_task

使用Claude Code执行任何任务，也可以选择使用MCP上下文。

参数：

  • prompt （必填）：要执行的任务
  • mcpConfigPath （可选）：MCP配置文件的路径（调用者提供）
  • timeout （可选）：超时时间（毫秒）（默认值：120000）
  • permissionMode （可选）： plan | acceptEdits | default | bypassPermissions
  • streamProgress （可选）：启用流式更新（默认值：true）

例子：

execute_task({
  prompt: "Search codebase for authentication patterns",
  mcpConfigPath: "/tmp/my-mcp-config.json" // Optional
})

2. execute_with_tools

使用特定的工具过滤执行。

参数：

  • prompt （必填）：要执行的任务
  • allowedTools （可选）：允许的刀具模式数组
  • disallowedTools （可选）：不允许的刀具模式数组
  • mcpConfigPath （可选）：MCP配置路径
  • timeout （可选）：超时时间（毫秒）

例子：

execute_with_tools({
  prompt: "Analyze code structure",
  allowedTools: ["Read", "Grep", "Glob"],
  disallowedTools: ["Write", "Edit"]
})

3. execute_with_permission_mode

使用特定权限模式执行。

参数：

  • prompt （必填）：要执行的任务
  • permissionMode （必填）： plan | acceptEdits | default | bypassPermissions
  • mcpConfigPath （可选）：MCP配置路径
  • timeout （可选）：超时时间（毫秒）

例子：

execute_with_permission_mode({
  prompt: "Analyze what changes are needed",
  permissionMode: "plan"
})

4. get_session_info

获取有关Claude Code会话的信息。

参数：

  • sessionId （必填）：要查询的会话ID

与MCP一起使用

桥不知道MCP- 呼叫者管理MCP配置.

示例：与Asana MCP一起使用

步骤1：创建MCP配置文件

// Caller creates this file
const fs = require('fs');
const configPath = '/tmp/my-asana-config.json';

fs.writeFileSync(configPath, JSON.stringify({
  mcpServers: {
    asana: {
      type: "sse",
      url: "https://asana-mcp-railway-production.up.railway.app"
    }
  }
}));

步骤2：使用配置路径调用网桥

execute_task({
  prompt: "Search Asana for tasks assigned to Butch",
  mcpConfigPath: configPath
})

步骤3：使用该配置生成桥接代码

# Bridge runs this internally:
claude --mcp-config /tmp/my-asana-config.json --print "Search Asana for tasks..."

结果： 代码加载Asana MCP并执行任务。布里奇从来不知道“Asana”是什么。

这种方法的好处

✅ 添加新的MCP而不更改代码 -只需创建不同的配置文件 ✅ 代币开销零增长 -Bridge总是有4个工具 ✅ 完全灵活 -在配置中混合搭配任何MCP ✅ 真正的关注点分离 -网桥传送消息，呼叫者管理MCP

从v1.x迁移

v2.0.0删除了特定于MCP的委派工具，以恢复纯渡轮架构。

发生了什么变化

远离的：

  • delegate_hubspot_task
  • delegate_asana_task
  • delegate_sharepoint_task
  • delegate_batch_tasks

原因： 这些工具在网桥和MCP之间创建了耦合，破坏了令牌保存的目的。

如何迁移

在（v1.x）之前：

delegate_asana_task({
  prompt: "Search for tasks"
})

在（v2.0）之后：

// You manage the MCP config
const configPath = "/tmp/asana-config.json";
fs.writeFileSync(configPath, JSON.stringify({
  mcpServers: { asana: { type: "sse", url: "..." } }
}));

// Use generic tool
execute_task({
  prompt: "Search for tasks",
  mcpConfigPath: configPath
})

建筑细部

为什么选择“渡船”而不是“编舞家”？

轮渡模式（v2.0）：

  • Bridge不了解MCP
  • 呼叫者提供配置
  • 无限缩放
  • 简单的代码库

编排器模式（v1.x-已删除）：

  • Bridge对MCP上下文进行了硬编码
  • 内部生成的配置
  • 新MCP所需的代码更改
  • 违反单一责任

数据流

1. Caller creates MCP config file (if needed)
2. Caller calls execute_task with mcpConfigPath
3. Bridge receives request
4. Bridge spawns: claude --mcp-config <path> --print "<prompt>"
5. Code subprocess loads MCPs from config
6. Code executes task with MCP tools
7. Results stream back through bridge
8. Bridge returns results to caller
9. Bridge never inspected the config

编码结构

最小、专注的代码库：

src/
├── index.ts              # Entry point
├── server.ts             # MCP server (4 tools)
├── executor.ts           # Code subprocess spawner
├── session-manager.ts    # Session lifecycle
├── types.ts              # Type definitions
└── tools/
    └── index.ts          # 4 generic tools

任何地方都没有MCP特定代码！

发展

构建

npm run build

发展模式

npm run dev  # Watch mode

测试

# Test basic execution
node test-executor.js

# Test with MCP config
# (Create a test config first, then run)

故障排除

桥未启动

  • 检查克劳德桌面日志： %APPDATA%\Claude\logs\
  • 验证Node.js版本： node --version （需要18+）
  • 检查克劳德代码路径： claude --version

任务无输出

  • 确保 --verbose 标志用于executor（自v1.0.1起内置）
  • 检查executor是否关闭stdin（自v1.0.1起内置）
  • 启用调试模式：设置 DEBUG: "true" 在配置中

MCP配置未加载

  • 验证配置文件是否存在于您提供的路径中
  • 检查配置文件中的JSON语法
  • 确保MCP URL可访问
  • 记住：Bridge不会验证配置，代码会验证

铁路MCP连接问题

  • 请参阅综合指南： docs/RAILWAY-SSE-DEBUGING.md
  • 快速检查： curl https://your-mcp.railway.app/health
  • 已知问题：Claude Code v2.0.45存在SSE传输错误-使用stdio进行生产

MCP传输兼容性

该网桥支持所有MCP传输类型，但Claude Code CLI的兼容性各不相同：

运输 克劳德代码v2.0.4 生产就绪 建议用于
标准 ✅ 完美运行 ✅ 是 ✅ 客户端部署
上海证券交易所 ❌ 损坏（3个错误） ❌ 否 ⚠️ 等待克劳德代码修复
超文本传输协议 ❓ 未测试 ❓ 未知 ❓ TBD

交通建议

对于生产客户端部署：

{
  "mcpServers": {
    "hubspot": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/hubspot-mcp/dist/index.js"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

在修复之前避免使用SSE（Claude Code v2.0.45错误）：

  • 缺失 Accept: text/event-stream 标头
  • 握手时GET与POST的混淆
  • SSE流解析失败

看 生产管理.md 获取详细的传输兼容性信息。

用例

1.桌面代表进行编码

Claude Desktop使用该桥来利用Code强大的子代理。

2.使用MCP进行编码的代码委托

全局代码实例（带桥）委托给具有特定MCP上下文的子流程。

3.自动化工作流程

脚本使用各种MCP配置以编程方式调用桥接工具。

技术细节

会话管理

  • 会话保持：MCP OAuth会话已保存到 %APPDATA%\Claude\.claude-mcp-sessions.json
  • 智能验证：已保存的会话在启动时验证，如果仍然有效，则重复使用
  • 自动清理：自动清除无效会话
  • 速率限制保护：本地身份验证缓存可防止重复的OAuth提示
  • 优雅地关闭：SIGINT/SIGTERM上的干净关机
  • 事件驱动：用于监控的生命周期挂钩
  • 安全：具有限制权限的每个用户文件隔离

流媒体

  • 通过流式JSON实时更新进度
  • 解析克劳德代码 --output-format stream-json
  • 非阻塞异步I/O

错误处理

  • 超时保护（可配置）
  • 错误处理清理
  • 带有上下文的详细错误消息

贡献

欢迎投稿！该架构故意简单：

核心原则： 桥梁绝不能知道具体的MCP。

如果PR添加了MCP特定代码，它将被拒绝。调用者应管理MCP配置。

许可证

麻省理工学院

链接

  • GitHub: https://github.com/MagicTurtle-s/claude-code-mcp-bridge
  • NPM：@magicture/claude编排器（GitHub软件包）
  • 克劳德代码文档: https://docs.claude.com/claude-code
  • MCP规范: https://github.com/anthropics/mcp

版本

当前： 2.0.0 （纯渡船建筑）

看 更改日志.md 版本历史。

相关 MCP