MCP Link 🚀

MCP Link 是一个 MCP 服务聚合与编排层，通过 HTTP 对外暴露统一的 MCP 接口，支持多类传输（stdio / SSE / HTTP / streamable-http），并提供任务规划能力，让 AI 助手能按计划调用下游 MCP 服务与工具。

为什么要用 MCP Link？

当你在 Cursor、Claude Desktop 等客户端里挂载多个 MCP 服务（GitHub、邮件、地图、绘图……）时，会面临三类典型问题，MCP Link 正是为此设计的：

问题	说明	MCP Link 的解决方式
多工具 Token 爆炸	所有服务的工具列表、参数 schema 一次性灌进上下文，token 消耗巨大，长对话更容易超限。	只暴露「规划 + 按需发现」的少量工具（如 create_plan、list_tools、call_tool），工具详情在需要时再通过 get_tool 拉取，显著压缩上下文。
多工具导致上下文腐烂	大量工具名、参数混在一起，模型容易选错工具、填错参数，或重复尝试无效调用。	先 make plan：用 create_plan 让规划器拆解任务、推荐「用哪个服务 / 哪个工具」；再按计划逐步 call_tool，减少试错与噪音。
支持 Make-Plan Agent 工作流	希望 AI 先规划、再执行，而不是一上来就乱试工具。	内置 Planner：收到任务后先生成子任务计划（含推荐 MCP 与工具），再按计划调用，天然支持「规划 → 发现 → 执行」的 Agent 流程。

总结：一个 HTTP 端点聚合所有 MCP，用「规划 + 按需发现」控 token，用「先计划再执行」减轻上下文腐烂，并支持 make-plan 式 Agent。

怎么使用？

1. 部署与连接：按下面「快速开始」安装、配置环境变量与 mcp-servers.json，启动后得到单一 HTTP 端点（如 http://host:8000/mcp），在 Cursor / Claude Desktop 里只配置这一个 MCP 地址即可。
2. 推荐流程（Make-Plan Agent）：
   规划 → 调用 create_plan 传入任务与上下文，拿到子任务计划（含推荐服务与工具）。
   确认 → 用 list_tools / get_tool 按需查看工具与参数，避免一次性加载全部。
   执行 → 按计划用 call_tool（服务器名 + 工具名 + 参数）逐步执行。
3. 日常：客户端只需与 MCP Link 对话；Link 负责管理下游 MCP 的注册、发现与调用，你无需在每个客户端里配置多套服务。

功能特性

• 任务规划：收到用户任务后，先调用 create_plan 生成可执行的子任务计划（含推荐的 MCP 服务与工具）。
• 服务与工具发现：通过 list_servers、list_tools、get_tool 查看已注册的 MCP 服务及其工具列表与参数。
• 工具调用：按计划通过 call_tool（服务器名 + 工具名 + 参数）执行各步骤。
• 服务管理：通过 register_server 注册新 MCP 服务，通过 unregister_server 注销服务。
• 多传输支持：支持 stdio、SSE、HTTP、streamable-http 等 MCP 传输方式。

环境要求

• Python >= 3.12
• uv（推荐）或 pip

快速开始

1. 克隆并安装依赖

git clone <repo-url>
cd mcp-link
uv sync

2. 配置环境变量

复制示例环境文件并编辑：

cp .env.example .env

在 .env 中配置：

变量	说明
MCP_CONFIG_PATH	MCP 服务器配置文件路径（如 mcp-servers.json）
PLANNER_LLM_API_KEY	规划器使用的 LLM API Key（如 DeepSeek）
PLANNER_LLM_BASE_URL	LLM API 基础 URL（默认 https://api.deepseek.com/v1）
PLANNER_LLM_MODEL_NAME	规划器模型名称（默认 deepseek-reasoner）

3. 配置 MCP 服务器

复制示例配置并按需修改：

cp mcp-servers.example.json mcp-servers.json

mcp-servers.json 示例：

{
  "servers": [
    {
      "name": "time",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-time"],
      "env": {}
    },
    {
      "name": "github",
      "transport": "streamable-http",
      "url": "http://github-mcp.com/mcp",
      "headers": {
        "Authorization": "bearer xxxx"
      }
    }
  ]
}

支持的 transport：stdio、sse、http、streamable-http。

4. 启动服务

uv run main.py  --transport http --port 8000

服务将在 http://0.0.0.0:8000/mcp 启动，可作为 MCP HTTP 端点供 Cursor、Claude Desktop 等客户端连接。

使用 Docker

# 构建
docker build -t mcp-link .

# 运行（需挂载配置与 .env 或传入环境变量）
docker run -p 8000:8000 \
  -v $(pwd)/mcp-servers.json:/app/mcp-servers.json \
  -e MCP_CONFIG_PATH=/app/mcp-servers.json \
  -e PLANNER_LLM_API_KEY=sk-xxx \
  -e PLANNER_LLM_BASE_URL=https://api.deepseek.com/v1 \
  -e PLANNER_LLM_MODEL_NAME=deepseek-reasoner \
  mcp-link

推荐使用流程（Make-Plan 速查）

1. 规划：先调用 create_plan，传入任务描述和上下文，获取子任务计划。
2. 确认：用 list_tools / get_tool 确认各步骤的工具与参数。
3. 执行：按计划用 call_tool 逐步执行。

项目结构

mcp-link/
├── main.py                 # 入口，暴露 MCP 工具与 HTTP 服务
├── pyproject.toml
├── mcp-servers.example.json
├── .env.example
├── Dockerfile
└── src/
    ├── mcp_manager/        # MCP 连接与注册、调用管理
    │   └── manager.py
    └── planner/            # 任务规划 Agent
        └── agent.py

开发

• 依赖管理：uv sync / uv add <package>
• 运行：uv run main.py

License

按项目仓库约定。