Skip to content
w3ng-gitPublic

About

Better mcp hub for cloud based mcp

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

13 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BetterHub - Universal MCP Server Gateway

让你的AI助手访问任何地方的工具,无论它们在哪里运行

License: MIT MCP Compatible

🚀 项目简介

BetterHub 是一个创新的 MCP (Model Context Protocol) 反向代理系统,解决了 AI 助手无法直接访问 NAT 后面或远程设备上工具的问题。通过巧妙的反向连接架构,BetterHub 让 Claude Desktop 能够安全地访问运行在任何地方的 MCP 服务器 - 无论是你的家庭服务器、办公室电脑,还是云端实例。

核心特性

  • 🌐 NAT 穿透:无需端口映射,支持双方都在 NAT 后面
  • 🔐 安全连接:基于 UUID 的设备认领机制
  • 🚄 高性能:WebSocket 长连接,低延迟通信
  • 🔧 易于部署:简单的配置,开箱即用
  • 📦 多服务器支持:一个连接器管理多个 MCP 服务器
  • 🏗️ 灵活架构:支持 stdio、HTTP、SSE 等多种 MCP 协议
  • 🏷️ 设备命名:为设备设置友好名称,工具自动添加前缀
  • 👥 多设备管理:一个用户可以管理多个设备的所有工具

🏗️ 系统架构

┌─────────────────┐         ┌─────────────────┐           ┌─────────────────┐
│  Claude Desktop │         │   BetterHub     │           │  Remote Device  │
│                 │         │   (公网服务器)    │           │                 │
│ reverse-        │  HTTP   │                 │  WebSocket│ mcp-hub-        │
│ connector       ├────────►│  Hub Server     │◄──────────┤ connector       │
│ (虚拟MCP)       │         │  (中继&路由)      │           │ (设备代理)       │
└─────────────────┘         └─────────────────┘           └─────────────────┘
      NAT A                      Internet                      NAT B

工作流程

  1. 设备注册:远程设备上的 connector 通过 WebSocket 连接到 Hub
  2. 设备认领:用户通过 UUID 认领设备,建立所有权关系
  3. 请求转发:Claude 发起的 MCP 请求通过 reverse-connector 转发到 Hub
  4. 智能路由:Hub 根据工具名称路由请求到正确的设备和 MCP 服务器
  5. 响应返回:MCP 服务器的响应原路返回给 Claude

📚 文档结构

project_docs/
├── 1-需求与功能.md    # 项目需求和功能说明
├── 2-系统架构.md      # 架构设计和核心组件
├── 3-API接口.md       # 完整的 API 参考
└── 4-测试报告.md      # 测试结果和已知问题

📁 项目结构

betterhub/
├── betterhub-server/             # Hub 服务器
│   └── src/
│       ├── hub-v2.ts             # 主服务器实现
│       └── types.ts              # 类型定义
├── mcp-hub-connector/            # 设备端连接器
│   └── src/
│       ├── connector-v2.ts       # 连接器主程序
│       ├── mcp-manager.ts        # MCP 服务器管理
│       └── config.ts             # 配置加载
├── mcp-hub-reverse-connector/    # 客户端连接器
│   └── src/
│       ├── multi-device-reverse.ts # 多设备支持
│       └── index.ts              # 单设备版本
│   │
│   ├── reverse-connector/        # Claude 端虚拟 MCP 服务器
│   │   ├── index.ts              # 主程序入口
│   │   ├── api-client.ts         # Hub API 客户端
│   │   └── types.ts              # TypeScript 类型定义
│   │
│   ├── hub/                      # 中央 Hub 服务器
│   │   ├── server.ts             # Express 服务器主程序
│   │   ├── websocket.ts          # WebSocket 连接管理
│   │   ├── database.ts           # SQLite 数据库操作
│   │   ├── routes/               # REST API 路由
│   │   │   ├── device.ts         # 设备管理相关接口
│   │   │   └── user.ts           # 用户管理相关接口
│   │   └── types.ts              # TypeScript 类型定义
│   │
│   └── shared/                   # 共享代码
│       ├── protocol.ts           # MCP 协议定义
│       └── utils.ts              # 工具函数
│
├── dist/                         # 编译输出目录
│   └── [编译后的 JS 文件]
│
├── scripts/                      # 脚本目录
│   ├── setup.sh                  # 环境初始化脚本
│   └── deploy.sh                 # 部署脚本
│
├── config/                       # 配置文件目录
│   ├── connector.example.json    # 连接器配置示例
│   └── hub.example.json          # Hub 配置示例
│
├── tests/                        # 测试文件
│   ├── unit/                     # 单元测试
│   └── integration/              # 集成测试
│
├── docs/                         # 文档目录
│   ├── API.md                    # API 文档
│   ├── ARCHITECTURE.md           # 架构设计文档
│   └── DEPLOYMENT.md             # 部署指南
│
├── sample-mcp-hub-main/          # 参考项目 1(只读)
├── sample-mcphub-main/           # 参考项目 2(只读)
│
├── package.json                  # 项目依赖和脚本
├── tsconfig.json                 # TypeScript 配置
├── .env.example                  # 环境变量示例
├── .gitignore                    # Git 忽略配置
├── LICENSE                       # MIT 许可证
├── CLAUDE.md                     # Claude AI 开发指南
└── README.md                     # 本文档

目录功能说明

/src/connector/

设备端连接器,负责:

  • 建立和维护与 Hub 的 WebSocket 连接
  • 管理本地 MCP 服务器进程
  • 转发 MCP 请求和响应
  • 设备 UUID 管理和持久化

/src/reverse-connector/

Claude 端虚拟 MCP 服务器,负责:

  • 实现标准 MCP 服务器协议(stdio)
  • 通过 HTTP API 与 Hub 通信
  • 设备认领和连接管理
  • 动态能力发现和聚合

/src/hub/

中央 Hub 服务器,负责:

  • 管理所有设备连接
  • 用户认证和设备授权
  • 消息路由和转发
  • REST API 和 WebSocket 服务

/src/shared/

共享代码库,包含:

  • MCP 协议类型定义
  • 通用工具函数
  • 常量定义

🛠️ 安装指南

前置要求

  • Node.js 18+
  • npm 或 yarn
  • SQLite3(Hub 服务器)

1. 克隆项目

git clone https://github.com/yourusername/betterhub.git
cd betterhub

2. 安装依赖

npm install

3. 构建项目

npm run build

4. 部署 Hub 服务器

# 复制并编辑配置文件
cp config/hub.example.json config/hub.json

# 设置环境变量
cp .env.example .env
# 编辑 .env 文件,设置 JWT_SECRET 等

# 启动 Hub 服务器
npm run start:hub

5. 设置设备端 Connector

在拥有 MCP 服务器的设备上:

# 复制并编辑配置文件
cp config/connector.example.json config/connector.json

# 编辑配置文件,添加本地 MCP 服务器信息
{
  "hubUrl": "wss://your-hub-server.com",
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    }
  ]
}

# 启动 Connector
npm run start:connector

6. 配置 Claude Desktop

编辑 Claude Desktop 配置文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "betterhub": {
      "command": "node",
      "args": ["/path/to/betterhub/dist/reverse-connector/index.js"],
      "env": {
        "BETTERHUB_API_URL": "https://your-hub-server.com/api",
        "BETTERHUB_DEVICE_UUID": "your-device-uuid"
      }
    }
  }
}

📖 使用示例

1. 获取设备 UUID

Connector 首次启动时会生成 UUID:

$ npm run start:connector
[INFO] Generated new device UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
[INFO] Connecting to hub: wss://hub.example.com
[INFO] Connected successfully

2. 认领设备

在 Claude 中使用设备前,需要先认领:

# 通过 API 认领设备
curl -X POST https://hub.example.com/api/devices/claim \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

3. 在 Claude 中使用

认领成功后,重启 Claude Desktop,即可看到远程设备上的所有 MCP 工具。

🔧 配置说明

Hub 配置 (config/hub.json)

{
  "port": 3000,
  "database": {
    "path": "./data/hub.db"
  },
  "websocket": {
    "heartbeatInterval": 30000,
    "maxReconnectAttempts": 5
  },
  "security": {
    "jwtExpiry": "7d",
    "bcryptRounds": 10
  }
}

Connector 配置 (config/connector.json)

{
  "hubUrl": "wss://hub.example.com",
  "deviceName": "Home Server",
  "reconnectInterval": 5000,
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"],
      "protocol": "stdio"
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  ]
}

🚀 高级功能

多服务器管理

BetterHub 支持一个 Connector 管理多个 MCP 服务器,自动添加命名空间避免冲突:

// 原始工具名:search
// 转换后:filesystem__search, github__search

自动重连

Connector 内置自动重连机制,网络中断后会自动恢复连接。

设备分组

即将支持的功能:

  • 设备分组管理
  • 基于角色的访问控制
  • 设备共享

🔒 安全性

  • 端到端加密:所有通信使用 TLS 加密
  • 身份验证:基于 JWT 的用户认证
  • 设备授权:UUID 认领机制确保设备所有权
  • 访问控制:用户只能访问自己认领的设备

🤝 贡献指南

欢迎贡献代码!请遵循以下步骤:

  1. Fork 项目
  2. 创建功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

📝 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

📞 联系方式


BetterHub - 连接你的 AI 助手与整个世界 🌍

About

Better mcp hub for cloud based mcp

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages