# MCP Hub

聚合多个 MCP 服务器，统一暴露为一个标准 MCP 接口，供其他 Agent（如 Claude Code、Cursor 等）集成。

## 功能特性

- **多 MCP 聚合**：连接多个下游 MCP 服务器，将所有工具统一暴露
- **工具命名空间**：自动前缀隔离，`server_id_tool_name` 格式
- **双传输支持**：同时支持 stdio 和 HTTP (Streamable HTTP) 两种传输方式
- **热管理**：注册/启用/禁用下游服务器后**自动热重载**，无需重启网关
- **管理 API**：RESTful HTTP API 管理所有下游服务器
- **SQLite 持久化**：服务器配置持久存储，零外部依赖
- **自省工具**：内置 `gateway__list_servers` 和 `gateway__list_all_tools`

## 安装

### 前提条件

- Python >= 3.10
- Node.js >= 16（如需运行 npm MCP 包）

### 安装步骤

```bash
# 克隆或进入项目目录
cd mcp_demo

# 安装（开发模式）
pip install -e .
```

### 依赖

```
fastmcp >= 2.0      # MCP 框架
pydantic >= 2.0     # 数据模型校验
typer               # CLI 命令行
uvicorn             # HTTP 服务器
starlette           # HTTP 管理 API
aiosqlite           # SQLite 存储
httpx               # HTTP 客户端
```

## 快速开始

### 1. 注册下游 MCP 服务器

```bash
# 注册本地 Python MCP 服务器
mcp-gateway register \
  --server-id math \
  --display-name "Math Server" \
  --command python \
  --args "examples/downstream_servers/math_server.py"

# 注册天气服务器
mcp-gateway register \
  --server-id weather \
  --display-name "Weather Server" \
  --command python \
  --args "examples/downstream_servers/weather_server.py"

# 注册 bing-search（Windows 需要 cmd /c 包装）
mcp-gateway register \
  --server-id bing \
  --display-name "Bing Search" \
  --command cmd \
  --args "/c,npx,-y,bing-cn-mcp"

# 注册 HTTP 类型的 MCP 服务器
mcp-gateway register \
  --server-id remote-api \
  --display-name "Remote API" \
  --transport http \
  --url "https://api.example.com/mcp"
```

### 2. 查看已注册的服务器

```bash
# 基本列表
mcp-gateway list

# 显示连接状态和工具
mcp-gateway list --status --tools

# JSON 格式输出
mcp-gateway list --json
```

### 3. 启动网关

```bash
# stdio 模式（供 Claude Code 等 Agent 以子进程方式集成）
mcp-gateway serve

# HTTP 模式（供远程 Agent 连接）
mcp-gateway serve --transport http --port 8000

# 完整参数
mcp-gateway serve \
  --transport http \
  --host 0.0.0.0 \
  --port 8000 \
  --path /mcp \
  --management-port 9000 \
  --store gateway.db
```

## CLI 命令参考

| 命令 | 说明 |
|---|---|
| `mcp-gateway serve` | 启动网关服务器 |
| `mcp-gateway register` | 注册新的下游 MCP 服务器（自动通知运行中网关热重载） |
| `mcp-gateway list` | 列出所有已注册的服务器 |
| `mcp-gateway enable <id>` | 启用服务器（自动通知运行中网关热重载） |
| `mcp-gateway disable <id>` | 禁用服务器（自动通知运行中网关热重载） |
| `mcp-gateway remove <id>` | 永久移除服务器（自动通知运行中网关热重载） |
| `mcp-gateway health <id>` | 检查服务器健康状态 |
| `mcp-gateway reload` | 手动重载配置提示 |
| `mcp-gateway export-config` | 导出服务器配置 |
| `mcp-gateway import-config <file>` | 从 JSON 文件导入配置（自动通知运行中网关热重载） |

### `serve` 参数

| 参数 | 默认值 | 说明 |
|---|---|---|
| `--transport`, `-t` | `stdio` | 传输类型：`stdio` 或 `http` |
| `--host` | `127.0.0.1` | HTTP 监听地址 |
| `--port`, `-p` | `8000` | HTTP 端口 |
| `--path` | `/mcp` | MCP 协议的 HTTP 路径 |
| `--management-port` | `9000` | 管理 API 端口 |
| `--no-management` | — | 禁用管理 API |
| `--store` | `gateway_config.db` | SQLite 数据库路径 |
| `--name` | `MCP Gateway` | 网关名称 |
| `--log-level` | `INFO` | 日志级别 |

### `register` 参数

| 参数 | 说明 |
|---|---|
| `--server-id` | 唯一服务器标识（必填） |
| `--display-name` | 可读名称 |
| `--transport` | `stdio`（默认）或 `http` |
| `--command` | stdio 模式的启动命令 |
| `--args` | 逗号分隔的命令参数 |
| `--url` | HTTP 模式的服务器 URL |
| `--management-port` | 管理 API 端口，用于自动热重载（默认 9000） |
| `--no-auto-discover` | 注册后不立即连接 |
| `--tags` | 逗号分隔的标签 |
| `--store` | 存储路径 |

> **注意**：`register`、`enable`、`disable`、`remove`、`import-config` 命令执行后会自动通知运行中的网关热重载（通过管理 API）。如果网关未运行，重载请求会静默失败，不影响命令执行。

## HTTP 管理 API

管理 API 运行在独立端口（默认 9000）。

### 端点列表

```
GET    /api/v1/servers                      列出所有服务器
POST   /api/v1/servers                      注册新服务器
GET    /api/v1/servers/{server_id}          获取服务器详情
PUT    /api/v1/servers/{server_id}          更新服务器配置
DELETE /api/v1/servers/{server_id}          删除服务器
POST   /api/v1/servers/{server_id}/enable   启用服务器
POST   /api/v1/servers/{server_id}/disable  禁用服务器
GET    /api/v1/servers/{server_id}/health   健康检查
GET    /api/v1/tools                        查看所有聚合工具
GET    /api/v1/gateway/status               网关状态概览
POST   /api/v1/gateway/reload               热重载配置
GET    /api/v1/gateway/export               导出配置
POST   /api/v1/gateway/import               导入配置
```

### 使用示例

```bash
# 注册服务器
curl -X POST http://localhost:9000/api/v1/servers \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "weather",
    "display_name": "Weather Service",
    "transport": "stdio",
    "stdio_config": {"command": "python", "args": ["weather_server.py"]}
  }'

# 查看所有服务器
curl http://localhost:9000/api/v1/servers

# 查看聚合工具
curl http://localhost:9000/api/v1/tools

# 查看网关状态
curl http://localhost:9000/api/v1/gateway/status

# 启用/禁用
curl -X POST http://localhost:9000/api/v1/servers/weather/enable
curl -X POST http://localhost:9000/api/v1/servers/weather/disable

# 热重载
curl -X POST http://localhost:9000/api/v1/gateway/reload
```

## 供其他 Agent 集成

### Claude Code 集成

在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "gateway": {
      "command": "python",
      "args": ["-m", "mcp_gateway", "serve", "--transport", "stdio"]
    }
  }
}
```

或使用全局 CLI 命令：

```bash
claude mcp add gateway -s project -- python -m mcp_gateway serve --transport stdio
```

### 自定义 Agent 集成

```python
# 通过 stdio
from fastmcp import Client
from fastmcp.client.transports import StdioTransport

async with Client(StdioTransport(
    command="python",
    args=["-m", "mcp_gateway", "serve", "--transport", "stdio"],
)) as client:
    # 列出所有工具（含命名空间前缀）
    tools = await client.list_tools()
    for tool in tools:
        print(tool.name)  # 如: math__add, weather__get_forecast

    # 调用代理工具
    result = await client.call_tool("math__add", {"a": 3, "b": 5})
    print(result)
```

```python
# 通过 HTTP
from fastmcp import Client

async with Client("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()
    result = await client.call_tool("weather__get_current", {"city": "Beijing"})
    print(result)
```

### 远程 Agent 集成

作为标准 MCP HTTP 服务器，任何支持 MCP Streamable HTTP 协议的 Agent 都可以连接：

```json
{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "http://gateway-host:8000/mcp"
    }
  }
}
```

## 工具命名规则

所有下游服务器的工具自动添加 `server_id_` 前缀：

| 下游服务器 | 原始工具名 | 网关中的名称 |
|---|---|---|
| math | `add` | `math_add` |
| math | `multiply` | `math_multiply` |
| weather | `get_forecast` | `weather_get_forecast` |
| bing | `bing_search` | `bing_bing_search` |
| bing | `crawl_webpage` | `bing_crawl_webpage` |

网关自省工具使用双下划线 `gateway__` 前缀（不被 mount 改写）：

| 工具名 | 功能 |
|---|---|
| `gateway__list_servers` | 列出所有服务器及连接状态 |
| `gateway__list_all_tools` | 列出所有聚合的工具 |

## 项目架构

```
外部 Agent (Claude Code / Cursor / 其他)
         │
    ┌────┴────┐
   stdio     HTTP (streamable-http)
    └────┬────┘
         ▼
  ┌──────────────────┐
  │  GatewayServer    │  ← 统一的 FastMCP 实例
  │  (FastMCP)        │
  └────┬────┬─────────┘
       │    │
  ┌────▼─┐ ┌▼────────────┐
  │Proxy  │ │Management   │
  │Manager│ │API          │
  └──┬──┬─┘ └─────────────┘
     │  │
 ┌───▼┐ ┌▼────┐
 │MCP A│ │MCP B│  ...
 └────┘ └─────┘
```

## 配置导入/导出

```bash
# 导出当前配置
mcp-gateway export-config --output servers.json

# 从 JSON 文件导入
mcp-gateway import-config servers.json

# 示例配置文件格式 (examples/config.yaml)
```

示例配置 (`examples/config.yaml`)：

```json
{
  "mcpServers": {
    "math": {
      "command": "python",
      "args": ["examples/downstream_servers/math_server.py"]
    },
    "weather": {
      "command": "python",
      "args": ["examples/downstream_servers/weather_server.py"]
    },
    "bing-search": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "bing-cn-mcp"]
    }
  }
}
```

## 注意事项

1. **Windows stdio**：Windows 下注册 npm 类 MCP 需使用 `cmd` 命令：`--command cmd --args "/c,npx,-y,<package-name>"`
2. **网络环境**：HTTP 类型的下游服务器需要可访问的网络连接
3. **端口冲突**：默认 MCP 端口 8000，管理端口 9000，确保未被占用
4. **无 unmount**：FastMCP 暂不支持运行时 unmount，禁用/删除服务器后建议重启网关获得干净状态
5. **单机设计**：SQLite 适合单机部署，如需集群可通过 `AbstractStore` 接口扩展 PostgreSQL 等