使用说明

通用云连接器

状态：生产就绪✅ （个人/小团队使用） 最后更新：2025年12月6日

通过HTTP/SSE传输将Claude Desktop连接到远程基于SSE的MCP服务器的通用网桥。

适用于：

个人项目
小团队（<10名用户）
自托管部署

对于企业使用，考虑添加：

CI/CD管道（GitHub操作）
语义版本控制
自动安全扫描

概述

通用云连接器使Claude Desktop能够与使用HTTP/SSE而不是stdio的MCP服务器通信。它充当协议适配器，在以下之间进行转换：

克劳德桌面版 ← 标准 → 桥 ← HTTP/SSE→ 远程MCP服务器

支持的部署目标

Docker容器（当前生产使用）
虚拟专用服务器（VPS）
任何支持HTTP/SSE的服务器
本地开发服务器

备注：由于CPU时间限制，Cloudflare Workers不受支持（请参阅 docs/LESSONS_LEARNED_CONSOLIDATED.md).

快速开始

当前生产部署

网桥目前已部署并与以下MCP服务器一起工作：

服务器	端口	工具
数学桥	3001	计算，阶乘
圣克拉拉大桥	3002	物业信息
youtube转录桥	3003	get_transcript，list_available_languages
youtube-to-mp3-bridge	3004	youtube_to_mp3
github远程网桥	3005	存储库操作、问题、PR、代码搜索

先决条件

Node.js 24+（用v24.11.1测试）
npm或纱线
克劳德桌面版
Docker（用于运行MCP服务器容器）

安装

# 1. Clone the repository
cd /home/jcornell/universal-cloud-connector

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# Output: dist/index.js (ready to use)

配置

添加到Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "math-bridge": {
      "command": "wsl",
      "args": [
        "bash", "-c",
        "cd /home/jcornell/universal-cloud-connector && export server_url='http://127.0.0.1:3001/sse' && export api_token='default-api-key' && /home/jcornell/.nvm/versions/node/v24.11.1/bin/node dist/index.js"
      ]
    }
  }
}

环境变量:

server_url：SSE端点的完整URL（必须以结尾 /sse)
api_token：用于身份验证的承载令牌

建筑

通信流

1. Bridge connects to /sse endpoint
2. Server sends: event: endpoint
               data: /messages?session_id=abc123
3. Bridge extracts session_id
4. Claude Desktop sends request via stdin
5. Bridge POSTs to /messages?session_id=abc123
6. Server responds via SSE stream
7. Bridge forwards response to stdout

主要特点

✅ SSE端点事件模式：在处理请求之前等待session_id ✅ 请求ID关联：跟踪待处理的请求以匹配响应 ✅ 邮件重复数据删除：防止重新连接时出现重复消息 ✅ 自动重试：优雅地处理连接失败 ✅ 综合录井：用于故障排除的详细诊断

最近的修复（2025年12月6日）

SSE端点竞争条件 ✅ 固定的
- 扩展的 waitForSessionId() 超时时间从1秒到10秒
- 添加了进度日志记录
- 消除了HTTP 400错误和无限次重新连接
- 影响：所有网桥服务器现在都可靠工作
GitHub包装器架构 ✅ 固定的
- 从共享流程更改为每会话流程模型
- 每个SSE连接都有专用的GitHub服务器进程
- 正确的stdio流隔离
- 影响：GitHub工具现在可以使用了

看 docs/ARCHITECTURE.md 了解完整的技术细节。

项目结构

universal-cloud-connector/
├── src/
│   └── index.ts              # Main bridge implementation
├── dist/
│   └── index.js              # Compiled output (used by Claude Desktop)
├── docs/
│   ├── ARCHITECTURE.md       # Complete architecture documentation
│   ├── BUILD.md              # Build instructions
│   ├── DEPLOYMENT.md         # Deployment guide
│   ├── QUICK_START.md        # Getting started guide
│   └── LESSONS_LEARNED.md    # Development insights
├── tests/
│   ├── test-eventsource.mjs         # EventSource library test
│   ├── test-claude-desktop-simulation.js  # Protocol flow test
│   └── run-all-tests.sh             # Automated test suite
├── package.json
├── tsconfig.json
└── README.md

测试

自动化测试

运行完整的测试套件：

cd /home/jcornell/universal-cloud-connector
./run-all-tests.sh

测试包括:

EventSource库验证
Claude Desktop协议流模拟（竞争条件测试）

预期输出:

✅ Test 1 PASSED: EventSource library works correctly
✅ Test 2 PASSED: Bridge handles Claude Desktop protocol flow correctly

ALL TESTS PASSED ✅

手动测试

# Test direct connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  server_url="http://127.0.0.1:3001/sse" \
  api_token="default-api-key" \
  node dist/index.js

健康检查

# Check all servers
for port in 3001 3002 3003 3004 3005; do
  echo "Port $port:"
  curl -s http://127.0.0.1:$port/health
done

用法

在克劳德桌面

配置并重新启动后：

数学工具:

Ask Claude: "What is 15 + 27?"
Claude uses: math-bridge → calculate tool

YouTube工具:

Ask Claude: "Get the transcript of https://youtube.com/watch?v=..."
Claude uses: youtube-transcript-bridge → get_transcript

GitHub工具:

Ask Claude: "Search for Python repos with 50k+ stars"
Claude uses: github-remote-bridge → search_repositories

日志和调试

克劳德桌面日志:

Help → 导出日志→ 解压.zip
检查 mcp-server-[name]-bridge.log

寻找:

✅ [ENDPOINT-EVENT] Received
✅ Session ID extracted
✅ Session ID ready after Xms
❌ POST request failed with status 400 （坏-表示问题）

故障排除

常见问题

1.工具在Claude Desktop中不可用

原因：聊天会话隔离（Claude Desktop将工具绑定到特定聊天）
修复：重新启动Claude Desktop，创建新的聊天会话

2.HTTP 400“需要session_id”

原因：网桥未等待端点事件
修复：确保使用最新版本，超时10秒
验证：检查日志 [ENDPOINT-EVENT] Received

3.服务器没有响应

检查：Docker容器正在运行(docker-compose ps)
检查：服务器运行状况终结点(curl http://localhost:3001/health)
修复：重新启动容器(docker-compose restart)

看 ../mcp开发环境/docs/TROUBLESHOOTING.md 获取全面的故障排除指南。

发展

从源头构建

npm install
npm run build

运行测试

./run-all-tests.sh

进行更改

编辑 src/index.ts
跑 npm run build
测试用 ./run-all-tests.sh
在Claude Desktop中进行测试
提交更改

开发流程

有关详细的开发实践，请参阅：

Windows开发人员

重要提示： 此项目需要WSL（Linux的Windows子系统）。

先决条件：

WSL 2（Ubuntu推荐）
带有“Remote-WSL”扩展名的VS代码
WSL中已安装Node.js 24+（非Windows）

设置：

# 1. Open WSL terminal
wsl

# 2. Navigate to project
cd ~/universal-cloud-connector

# 3. Open in VS Code (opens in WSL mode)
code .

# 4. Verify WSL mode
# Look for "WSL: Ubuntu" in VS Code bottom-left corner

运行命令：

# ✅ CORRECT - Run in WSL terminal
./run-all-tests.sh
npm run build
npm install

# ❌ WRONG - Do NOT run in PowerShell or CMD
# .sh scripts require bash (WSL/Linux)

为什么需要WSL？

Bridge使用与Claude Desktop的stdio通信
stdio需要兼容的进程执行
WSL为Node.js提供Linux环境
直接执行PowerShell会导致编码问题

路径映射：

窗户： C:\Users\jcorn\...
WSL： /mnt/c/Users/jcorn/... 或 /home/jcornell/...
始终在Claude Desktop配置中使用WSL路径

看 ../mcp开发环境/docs/SETUP_GUIDE.md 获取完整的路径映射指南。

文档

核心文件

建筑.md -完整的技术架构
快速启动.md -入门指南
构建.md -构建和开发说明
部署.md -部署指南

已知限制

聊天会话隔离：工具绑定到特定的Claude Desktop聊天会话（重新启动Claude Desktop以在新聊天中使用）
WSL要求：当前设置需要Windows上的WSL（可以适用于本机Windows）
无动态路由：每台服务器都需要单独的网桥实例（可以增强）

演出

SSE连接：约10-60ms建立
请求处理：<10ms桥式架空
总延迟时间：~100-600ms端到端（因服务器操作而异）

许可证

看许可证文件以获取详细信息。

支持

对于问题:

检查故障排除.md
审查问题_AND_FIXES_CONSOLIDATED.md
运行测试套件： ./run-all-tests.sh
导出Claude桌面日志（帮助→ 导出日志）

关于发展问题:

看课程_学习_巩固.md
看建筑.md

更新日志

2025年12月6日

✅ 修复了SSE端点竞争条件（延长超时1秒→ 10s)
✅ 修复了GitHub包装器架构（每个会话进程）
✅ 所有5台网桥服务器均已生产就绪并经过测试
✅ 全面的文档整合
✅ 用当前状态更新README

先前版本

有关详细的更改日志，请参阅git历史记录。

状态

生产就绪 ✅

所有网桥服务器均已测试并正常工作：

✅ 数学桥
✅ 圣克拉拉大桥
✅ youtube转录桥
✅ youtube到mp3-bridge
✅ github远程网桥

测试套件通过，文档完整，可用于生产。