MCP 代理服务器 - mcp-proxy

使用说明

• 项目概述
  • 该仓库实现了一个 MCP 服务器代理（proxy），用于将上游 MCP 服务器与客户端对接，提供资源、工具、提示模板的统一暴露，并在代理端执行治理逻辑（G2、E-H8、G5 等），以确保对上下文信息的管理和对外调用的安全性。
• 主要功能点
  • MCP 核心能力：处理 MCP 的 JSON-RPC 请求与响应，支持 initialize、tools/list、tools/call、notifications 等方法。
  • 上下文治理：内置 G2（约束）、E-H7/E-H8（身份与权限）、G5（ containment attribution）与收敛性检查，提供探索性、可追溯的调用治理。
  • 工具与资源管理：托管上游工具集合，合并治理元工具，并对工具调用产出 receipts（带哈希、上一哈希、目标提取等元数据）。
  • 安全与可观测性：收集并持久化 receipts、限制重复失败的调用、支持再握手与重新初始化以恢复会话。
  • 多种传输协议接入：下游客户端可通过 STDIO、SSE、WebSocket 等传输与 MCP 服务器通信（实现以 STDIO 为核心运输并包含扩展逻辑）。
• 安装步骤
  • 先安装依赖（Node 环境要求 Node.js >= 18，使用 bun 作为可执行环境）。
  • 获取代码后，进入仓库根目录执行安装。
  • 运行测试前，请确保本地环境具备 bun、node 和必要的权限。
• 服务器配置
  • 服务器名称（serverName）: "@sovereign-labs/mcp-proxy"
  • 启动命令（command）: bun
  • 启动参数（args）(示例，实际按需要替换上游服务与路径)：
    • "run"
    • "src/index.ts"
    • "--upstream", "<上游 MCP 服务器启动命令，例如 bun run upstream-server.ts>"
    • "--state-dir", "<状态目录路径，例如 ./state>"
    • "--enforcement", "strict"（也可设为 "advisory"） 注释说明：
  • upstream 用于指定要代理的上游 MCP 服务器实现，可以替换为具体的上游服务器命令或脚本。
  • state-dir 指定用于存放 receipts、约束、授权等治理状态的本地目录，建议在持久化环境中使用明确路径。
  • enforcement 指代理对治理策略的执行模式：strict 为严格阻断，advisory 为告警+转发。
• 基本使用方法
  • 启动代理：按照上述配置启动命令，代理启动完成后即可与下游 MCP 客户端建立 JSON-RPC 通道。
  • 客户端交互：通过发送 initialize、tools/list、tools/call、notifications/initialized 等 JSON-RPC 请求来驱动工具发现、调用与治理过程，代理会返回工具输出和治理结果，同时在本地记录 receipts 与约束。
  • 查看与调试：可以查看 stateDir 下的 receipts.jsonl、constraints.json、controller.json、authority.json 等文件来审计与复核历史记录。
  • 重新握手与会话更新：authority 升级后，下一次工具调用可能被阻塞，需通过 initialize 重新握手以完成会话重同步。
  • 流程容错：代理具备对未知方法的透明转发能力，以及对错误的收敛性处理和日志记录能力。