Agent (LangGraph / 自研 Harness / IDE / MCP Client)
   │  Streamable HTTP (Mcp-Method / Mcp-Name 头路由)      │ stdio 桥(本地)
   ▼                                                       ▼
┌────────────────────── 无状态 MCP 网关 (水平扩容) ──────────────────────┐
│  OAuth 2.1 (issuer/JWKS) ─ RBAC 白名单 ─ 金丝雀版本路由                 │
│  MRTR 人工二次确认 ─ 速率配额(Redis) ─ 两级结果缓存(L1 LRU + L2 Redis)  │
│  韧性层: 熔断 + 舱壁 + 全抖动重试 ─ 凭证托管代理层                      │
│  截断/脱敏 ─ MCP Apps 富结果渲染 ─ 审计 JSONL ─ Prometheus             │
│  DAG 工作流引擎(拓扑并行 + 模板引用 + 检查点恢复)                        │
└──────┬──────────┬──────────┬──────────┬──────────┬──────────┬────────┘
   kb Server   db Server  repo Server  ticket Srv  browser Srv  terminal Srv
  知识库检索   只读SQL     代码仓库     工单系统     浏览器       沙箱终端
        （23 个原子工具 + 60 个实例级变体 = 83 工具目录）

curl -X POST http://127.0.0.1:8080/admin/flows/incident_triage/run \
  -H "Authorization: Bearer dev-token-1"

# 安装
pip install -e ".[test]"          # LangGraph 集成: pip install ".[langgraph]"

# 启动网关（dev 模式自带静态令牌）
cp .env.example .env
python -m uvicorn mcp_toolhub.gateway.app:app --port 8080

# 头路由调用（不解包 JSON-RPC）
curl -s http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer dev-token-1" \
  -H "Mcp-Method: tools/call" -H "Mcp-Name: kb.search" \
  -H "Mcp-Protocol-Version: 2026-07-28" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kb.search","arguments":{"query":"oauth"}}}'

# 工具目录（带 ttlMs 缓存约定）
curl -s http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer dev-token-1" -H "Mcp-Method: tools/list" -d '{}'

# 本地 stdio 一键切换（给 IDE / Claude Desktop 用）
python -m clients.stdio_bridge --url http://127.0.0.1:8080 --token dev-token-1

# 测试
pytest -q

from mcp_toolhub.adapters.gateway_client import GatewayClient
from mcp_toolhub.adapters.tool_mounting import ToolMounter
from mcp_toolhub.adapters.langgraph_adapter import to_langchain_tools
from mcp_toolhub.servers.catalog import build_catalog

mounter = ToolMounter(build_catalog(), top_k=8, token_budget=2048)
client = GatewayClient("http://127.0.0.1:8080", token="dev-token-1")

# 只挂载与当前意图相关的 Top-K 工具(而不是 80+ 全量)
tools = to_langchain_tools(mounter, client, query="查询数据库表结构")
# tools 直接喂给 langgraph.prebuilt.ToolNode

from mcp_toolhub.adapters.harness_adapter import Harness, EchoModelClient

harness = Harness(mounter, client, model=MyModelClient(), max_steps=8)
run = await harness.run("统计上周工具调用成功率")
if run.paused_for_confirmation:      # MRTR: 等人工确认
    run = await harness.resume(run, confirmationToken=approved_token)
print(run.to_dict())

docker compose up -d   # gateway x2(无状态,轮询LB) + redis + prometheus + grafana

mcp_toolhub/
├── common/        统一错误码 / 输出截断 / Tool 抽象
├── servers/       6 个 MCP Server + variants.json 目录扩展
├── gateway/       无状态网关: app / router / registry(金丝雀) / resilience(熔断舱壁重试) / cache(两级) / apps(富结果) / ratelimit / metering / audit / credentials
├── auth/          OAuth 2.1 校验 / RBAC 策略
├── mrtr/          人工二次确认(HMAC 令牌)
├── retrieval/     混合检索: BM25 + 哈希向量 + 加权 RRF + 评测集(105 case)
├── orchestration/ DAG 工作流引擎 + 内置流
└── adapters/      工具按需挂载 / GatewayClient / LangGraph / Harness
clients/           stdio 桥
scripts/           benchmark.py(本 README 与 docs/benchmarks.md 数据来源) / smoke
tests/             pytest 82 用例(检索评测门/韧性/缓存/编排/金丝雀/网关端到端)
deploy/            prometheus / grafana 看板