MCP 网关、注册中心与代理：多服务器聚合与能力路由

# 痛点一: 客户端配置爆炸
#   每个 IDE/Agent 都要写 N 份 server 配置，改一次要改 N 处
# 痛点二: 命名冲突与能力发现
#   两个服务器都有 search 工具，客户端如何区分、如何选择
# 痛点三: 横切关注点无处安放
#   鉴权、配额、审计、限流、灰度——每个服务器重复实现
# 网关 = 把横切关注点从 N 个服务器收敛到 1 个入口

// 网关把多个后端的 tools/list 合并成一个
async function aggregateTools(): Promise<Tool[]> {
  const backends = registry.list();
  const merged: Tool[] = [];
  for (const b of backends) {
    const tools = await b.client.listTools();
    for (const t of tools) {
      merged.push({
        ...t,
        // 前缀式命名空间：<server>__<tool>
        name: `${b.namespace}__${t.name}`,
        // 保留原始名，便于回程路由
        _origin: { server: b.id, tool: t.name },
        // 注入配额/审计提示，模型可见
        description: `[${b.namespace}] ${t.description ?? ""}`,
      });
    }
  }
  return merged;
}

// 收到 tools/call 后，从命名空间解析目标服务器
async function routeCall(name: string, args: unknown, ctx: CallContext) {
  const sep = name.indexOf("__");
  if (sep < 0) throw new McpError(-32601, `unknown tool: ${name}`);
  const ns = name.slice(0, sep);
  const tool = name.slice(sep + 2);

  const backend = registry.get(ns);
  if (!backend) throw new McpError(-32601, `unknown namespace: ${ns}`);
  await quota.check(ctx.principal, backend.id);
  const res = await backend.client.callTool({ name: tool, arguments: args });
  audit.record({ principal: ctx.principal, ns, tool, args, res });
  return res;
}

# 1) 精确名路由: 工具名直接映射（最常用）
# 2) 标签路由: 工具带 tags（read/write/db/cloud），按标签批量启用
# 3) 权限路由: 不同主体看到不同工具子集（RBAC）
# 4) 版本路由: v1/v2 并存，灰度切换
# 5) 负载路由: 同一能力的多个副本间做负载均衡
# 6) 地理位置路由: 就近接入降低延迟

// 按主体权限裁剪可见工具：模型根本看不到无权使用的工具
async function listToolsFor(principal: Principal): Promise<Tool[]> {
  const all = await aggregateTools();
  return all.filter((t) => {
    const policy = policies.for(principal, t._origin);
    return policy.canSee;   // 不可见 = 不出现在列表里
  });
}

# gateway routes 配置
namespaces:
  github:
    transport: streamable-http
    url: https://mcp.internal/github
    tools: ["list_prs", "create_pr", "get_issue"]
    tags: [vcs, write]
  k8s:
    transport: streamable-http
    url: https://mcp.internal/k8s
    tags: [cloud, write]
  docs:
    transport: stdio
    command: ["mcp-docs", "--root", "/srv/docs"]
    tags: [read]
routing:
  strategy: namespace-prefix
  deny_untagged_write: true      # 未显式授权的写工具一律不可见

# 1) 服务器启动 → 向注册中心注册（或注册中心主动探测）
# 2) 网关拉取目录 → 建立本地路由表（带缓存）
# 3) 定期健康检查 → 更新 health 状态
# 4) 客户端请求 → 网关按路由表转发
# 5) 服务器下线 → 注销或健康检查失败 → 从路由表摘除
# 目录是"能力的真相来源"，网关只是它的消费者

# 服务器向注册中心注册
curl -X POST https://registry.internal/v1/servers \
  -H "Authorization: Bearer $REGISTRY_TOKEN" \
  -d '{
    "namespace": "github",
    "endpoint": "https://mcp.internal/github",
    "transport": "streamable-http",
    "capabilities": ["tools"],
    "owner": "platform-team",
    "version": "1.4.2",
    "ttl_seconds": 30
  }'

# 1) 客户端 → 网关: OAuth 2.1 令牌（含 scope）
# 2) 网关 → 后端: 服务身份（mTLS 或内部令牌）
# 3) 网关校验 scope 与目标工具所需权限是否匹配
# 4) 后端不再直接面对用户，只信任网关的服务身份
# 关键: 用户身份必须"透传"给后端（用于后端自己的授权与审计）

// 网关把用户身份转为后端可验证的签名头
function forwardHeaders(ctx: CallContext): Record<string, string> {
  return {
    // 服务身份（网关自己）
    "x-mcp-gateway": "gw-prod-01",
    // 用户身份（签名，防伪造）
    "x-mcp-principal": ctx.principal.id,
    "x-mcp-scopes": ctx.scopes.join(" "),
    "x-mcp-signature": sign(ctx.principal.id + ctx.scopes, GW_PRIVATE_KEY),
    // 追踪
    "x-request-id": ctx.requestId,
  };
}

# 令牌桶限流（按主体 + 工具）
class TokenBucket:
    def __init__(self, rate: float, burst: int):
        self.rate, self.burst = rate, burst
        self.tokens, self.ts = burst, time.monotonic()

    def allow(self, cost: float = 1.0) -> bool:
        now = time.monotonic()
        self.tokens = min(self.burst, self.tokens + (now - self.ts) * self.rate)
        self.ts = now
        if self.tokens >= cost:
            self.tokens -= cost
            return True
        return False

// 把本地 stdio 服务器的 JSON-RPC 转发为网关内部的调用
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "mcp-docs",
  args: ["--root", "/srv/docs"],
  stderr: "pipe",       // 后端日志走 stderr，别污染 JSON-RPC 通道
});
const client = new Client({ name: "gw-bridge", version: "1.0.0" });
await client.connect(transport);

# 1) 保留原始 id 映射: 网关自己的 id 与后端 id 要建立映射表
# 2) 能力协商在连接建立时完成: initialize 握手各自独立
# 3) 通知（notifications）要双向转发: tools/list_changed 等
# 4) 错误码透传: -32601/-32602 等标准码不要被网关改写
# 5) 大响应分块: HTTP 侧要处理流式与截断
# 网关是"协议透明"的，改协议细节会破坏客户端的兼容假设

# 1) 调用量: 按主体/命名空间/工具/状态
# 2) 延迟: P50/P95/P99，区分网关自身开销与后端耗时
# 3) 错误率: 按错误码分类（协议错/鉴权错/后端错/超时）
# 4) 配额命中: 限流触发次数
# 5) 后端健康: 各服务器可用率、连接复用率
# 6) 工具热度: 哪些工具被高频调用、哪些从没被用过

{
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span": "tools/call",
  "name": "github__create_pr",
  "attributes": {
    "mcp.principal": "user:alice",
    "mcp.namespace": "github",
    "mcp.tool": "create_pr",
    "mcp.backend_latency_ms": 412,
    "mcp.gateway_latency_ms": 18,
    "mcp.status": "ok"
  }
}

class CircuitBreaker {
  private failures = 0;
  private state: "closed" | "open" | "half" = "closed";
  private openedAt = 0;

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === "open") {
      if (Date.now() - this.openedAt > 30_000) this.state = "half";
      else throw new McpError(-32000, "backend circuit open");
    }
    try {
      const r = await fn();
      this.failures = 0;
      this.state = "closed";
      return r;
    } catch (e) {
      if (++this.failures >= 5) {
        this.state = "open";
        this.openedAt = Date.now();
      }
      throw e;
    }
  }
}

# 客户端(IDE/Agent)
#      │  HTTPS + OAuth
#      ▼
#  [ LB / Ingress ]
#      │
#      ▼
#  [ MCP 网关 x3 ]  ←→  [ Redis: 会话/配额 ]  ←→  [ 注册中心 ]
#      │
#      ├── HTTP ──→ [ github-mcp ]  [ k8s-mcp ]
#      └── stdio ─→ [ docs-mcp (sidecar) ]
# 网关无状态、后端可异构、注册中心是真相来源

# 1) 网关旁路部署: 只做观测，不改变流量（影子模式）
# 2) 单个服务器试点: 把一个服务器接入网关，客户端改为连网关
# 3) 验证: 对比直连与网关的工具列表、调用结果一致性
# 4) 批量迁移: 按命名空间逐步迁移
# 5) 收敛: 直连配置退役，客户端只剩网关一个入口
# 影子模式先看清流量，再动真格

# 迁移前确认
# 1) 客户端支持命名空间前缀吗（名字变长）
# 2) 客户端支持 Streamable HTTP 吗（原为 stdio）
# 3) 后端的能力协商字段是否被网关完整透传
# 4) notifications 是否双向可达
# 5) 大响应/流式是否被网关缓冲破坏