Universal Cloud Connector

通用云连接器

状态：生产就绪✅ （个人/小团队使用） 最后更新：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服务器一起工作：

先决条件

• 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日）

1. SSE端点竞争条件 ✅ 固定的

- 扩展的 waitForSessionId() 超时时间从1秒到10秒 - 添加了进度日志记录 - 消除了HTTP 400错误和无限次重新连接 - 影响：所有网桥服务器现在都可靠工作

1. 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

测试包括:

1. EventSource库验证
2. 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

______________________________________________________________________

用法

在克劳德桌面

配置并重新启动后：

1. 数学工具:

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

1. YouTube工具:

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

1. 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

进行更改

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

开发流程

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

• docs/BUILD.md
• docs/ARCHITECTURE.md
• ../mcp开发环境/docs/LESSONS_LEARNED_CONSOLIDATED.md

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 -部署指南

相关文档（mcp-dev环境）

• 故障排除.md -故障排除指南
• 问题_AND_FIXES_CONSOLIDATED.md -所有已知问题和修复
• 课程_学习_巩固.md -发展经验教训
• SETUP_GUIDE.md -完整的设置指南

______________________________________________________________________

已知限制

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

______________________________________________________________________

演出

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

______________________________________________________________________

许可证

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

______________________________________________________________________

支持

对于问题:

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

关于发展问题:

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

______________________________________________________________________

更新日志

2025年12月6日

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

先前版本

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

______________________________________________________________________

状态

生产就绪 ✅

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

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

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