GH-AW MCP Gateway

关键词

后端网关容器化MCPJSON-RPC路由与聚合流式传输

使用说明（Markdown 格式）

  • 项目简介

    • 本仓库实现的是一个 MCP 网关（Gateway），用于将多个 MCP 服务器后端接入到一个统一的对外入口。网关本身提供路由（路由到具体后端）、会话管理、工具/资源相关能力的聚合，以及对 MCP 客户端的 JSON-RPC 通信支持。它支持以 Docker 容器启动后端 MCP 服务器（stdio 传输）、也可通过 HTTP 后端进行接入，并提供两种配置方式（TOML 和 JSON（从标准输入读取））。
    • MCP 客户端可以通过网关的路由端点 /mcp/{serverID}（逐个路由）或统一端点 /mcp（聚合到所有后端），以 JSON-RPC 2.0 形式进行调用，如读取工具列表、执行工具、获取资源等。网关还提供健康检查、日志、调试信息等运维能力。

  • 主要功能点

    • 两种配置格式：TOML 文件配置和通过标准输入传入的 JSON 配置，且具备快速校验和错误提示。
    • 传输模式：stdio（后端直接在网关里以标准输入输出形式运行）和 HTTP（后端通过 HTTP 接入）。
    • 路由模式：Routed（/mcp/{server} 路由到各后端）与 Unified（/mcp 统一入口路由到所有后端）。
    • 后端启动和容器化支持：通过 Docker 容器启动后端 MCP 服务器，支持自定义 entrypoint、挂载、环境变量等。
    • 安全与鉴权：基于 API Key 的简单认证机制，客户端通过 Authorization 请求头携带 API Key。
    • 对后端能力的代理：网关对后端的 Tools/Resources 等能力进行管理、聚合、并向客户端暴露相应接口。
    • 增强调试与诊断：提供详细的启动、后端启动、请求与响应日志，以及对命令执行失败的调试信息。
    • 对大 payload 的处理与持久化：支持将工具调用产生的 payload 保存到本地并提供简要的预览信息，便于大对象管理。
    • 流式传输与错误处理：对部分传输实现了流式响应的支持（如 SSE），并提供对错误信息的友好显示和定位帮助。

  • 安装步骤

    • 先确保环境具备 Go 语言开发环境（如 Go 1.20+），并具备 Docker（如需要使用容器启动后端 MCP 服务器）。
    • 获取源码后进行编译运行：
      • 本地构建：将代码编译成可执行文件（示例命令在不同环境下可用，具体以项目根目录下的构建脚本/文档为准）。
      • 也可以使用仓库提供的镜像方式直接运行（如 ghcr.io/github/gh-aw-mcpg:latest），具体请参考 README。
    • 运行网关：
      • 通过配置文件启动：awmg --config <path-to-config.toml>，可选启用路由或统一模式。
      • 通过 JSON stdin 启动：awmg --config-stdin < <config.json>，以 JSON 形式配置后端 MCP 服务器。
    • 配置后端 MCP 服务器（示例说明，实际客户端不需要直接看此处）：
      • 服务器需要的核心信息包括服务器名称、启动方式、命令及参数等，以便网关能够启动并连接后端。
      • 典型配置要素包括：
        • 服务器名称（必选）如 github
        • 传输类型（stdio 或 http 等）
        • 启动信息：容器镜像和启动参数（如果使用容器化后端）
        • 环境变量、挂载点、Entrypoint 等
        • 如使用 HTTP 后端，需提供后端的访问地址与必要头信息等
    • 运行后端容器的常见要点
      • 需要确保后端镜像可访问（如 ghcr.io/github/github-mcp-server:latest）。
      • 运行时需挂载 Docker 套接字以便网关能在需要时启动新的后端容器。
      • 挂载点、环境变量以及入口参数按后端具体要求配置。
    • 服务器配置要点（MCP 服务器给 MCP 客户端使用时的可选示例描述）
      • 每个 MCP 服务器需要在网关的配置中指定名称、启动类型、镜像或命令及参数，以及必要的环境变量。
      • MCP 客户端若要连接，至少需要知道该 MCP 服务器的启动命令（command）及其参数（args）等信息（网关端提供的配置信息不需要客户端直接依赖，仅用于理解交互方式）。
    • 基本使用方法
      • 启动网关后，使用健康检查端点 /health 监控网关状态。
      • 通过路由端点 /mcp/{serverID} 进行具体服务器的 JSON-RPC 调用，或通过统一端点 /mcp 将请求转发至配置的第一个后端/聚合处理。
      • 常见的 MCP 调用包括 tools/list、tools/call、resources/list、initialize 等，具体方法名称由后端实现和 MCP 版本决定。
      • 当需要对后端进行调试时，可启用 DEBUG 变量来增加日志输出，便于排错。

  • 服务器配置（对 MCP 客户端的说明，非网关配置示例）

    • 服务器名称：如 github
    • 启动命令（command）：docker
    • 启动参数（args）：run --rm -i ghcr.io/github/github-mcp-server:latest
    • 说明：以上为一个典型后端 MCP 服务器的启动方案，实际使用中可以通过网关的配置将该启动信息传递给网关，以便网关在需要时能够启动并管理后端容器。
    • 备注：MCP 客户端在建立连接时不需要直接看到网关的实现细节，但需要了解 MCP 服务器的名称、启动方式和访问方式（如路由路径和端点）。

  • 基本使用示例（简要）

    • 启动网关并加载配置
    • 调用路由端点进行初始化与工具查询
    • 通过工具调用获得工具列表、参数、结果等
    • 如需扩展新的后端服务器，只需在网关配置中添加相应条目，确保后端镜像与启动参数正确即可

  • 关键词

    • MCP 网关、后端路由、容器化后端、JSON-RPC、工具与资源

  • 分类ID

    • 6

服务器信息

访问项目