项目简介

'mcp-graphql-forge' 是一个轻量级、配置驱动的 MCP 服务器实现。它的主要功能是将指定的 GraphQL API 接口转换为一个 MCP 服务器，并把在 YAML 文件中定义的 GraphQL 查询作为模块化的 工具（Tools） 暴露给兼容 MCP 协议的 LLM 客户端（如智能体）。通过这种方式，可以在不修改服务器代码的情况下，轻松、安全地为 LLM 应用提供结构化的数据访问和功能调用能力。

主要功能点

GraphQL 转 MCP 工具: 将任意 GraphQL 端点的查询或变异操作定义为 MCP 服务器的工具。
配置驱动: 服务器行为和可用工具完全通过 YAML 文件配置，无需修改或重新编译代码。
支持多种传输协议: 兼容 MCP 标准，支持 Stdio (标准输入输出) 和 SSE (Server-Sent Events) 两种工作模式。
认证支持: 支持执行外部命令获取 Bearer Token 用于 GraphQL 请求认证。
模块化扩展: 通过添加新的 YAML 文件即可轻松增加新的工具。

安装步骤

'mcp-graphql-forge' 是一个 Go 语言项目，你可以通过 Go 工具链进行编译生成可执行文件。

安装 Go: 如果你还没有安装 Go，请访问 https://golang.org/dl/ 下载并安装适合你操作系统的最新版本。

获取源码: 打开终端或命令提示符，克隆项目仓库：

git clone https://github.com/UnitVectorY-Labs/mcp-graphql-forge.git
cd mcp-graphql-forge

编译: 在项目根目录下执行编译命令：
```
go build .
```
这会在当前目录下生成一个名为 'mcp-graphql-forge' (Windows 上是 'mcp-graphql-forge.exe') 的可执行文件。

服务器配置

MCP 服务器的配置主要通过环境变量和 YAML 文件进行。在运行服务器的可执行文件时，需要确保配置文件存在于指定位置。

环境变量 'FORGE_CONFIG': 指定存放配置文件的目录路径。如果未设置，默认为当前工作目录。

'forge.yaml' 文件: 存放在 'FORGE_CONFIG' 指定的目录下，用于配置全局服务器信息。

name: "YourServerName"       # MCP服务器的名称，供客户端识别
version: "1.0.0"             # 服务器版本
url: "https://your.graphql.api/graphql" # 目标GraphQL端点URL
token_command: "your-auth-script.sh" # (可选) 执行该命令获取Bearer Token

'token_command' 是可选的，如果需要认证，可以指定一个命令，该命令的输出（标准输出）会被用作 GraphQL 请求的 'Authorization: Bearer <token>' 头部的 '<token>' 部分。

工具配置文件 (*.yaml): 在 'FORGE_CONFIG' 目录下创建额外的 '.yaml' 文件来定义每个 MCP 工具。

name: "getToolName"           # MCP工具的名称，供LLM调用
description: "工具功能描述，LLM会参考此描述决定是否调用及如何调用。" # 工具用途的详细描述
query: |                      # 对应的GraphQL查询或变异
  query ($param1: String!, $param2: Int) {
    yourQuery(arg1: $param1, arg2: $param2) {
      ...
    }
  }
inputs:                       # 工具的输入参数，对应GraphQL查询的变量
  - name: "param1"            # 输入参数名称
    type: "string"            # 参数类型，可以是 'string' 或 'number'
    description: "第一个参数的用途描述。" # 参数描述，供LLM理解
    required: true            # 是否必须提供此参数
  - name: "param2"
    type: "number"
    description: "第二个参数的用途描述。"
    required: false

MCP 客户端配置

MCP 客户端（例如某些 LLM 智能体框架）需要知道如何启动并连接到这个 MCP 服务器。通常，这涉及到配置服务器的启动命令及其参数。客户端的配置信息通常是 JSON 格式。

以下是一个示例的 MCP 客户端配置结构说明：

{
  "serverName": "YourServerName", // 这是 forge.yaml 中配置的服务器名称
  "command": [
    "/path/to/mcp-graphql-forge" // 指定MCP服务器可执行文件的完整路径
    // 根据需要添加启动参数，例如 SSE 模式：
    // "--sse", ":8080"
  ]
}

'serverName': 这个名称必须与你在 'forge.yaml' 中设置的 'name' 完全一致。客户端使用它来标识和管理连接。
'command': 这是一个字符串数组，第一个元素是 MCP 服务器可执行文件的完整路径。后续元素是启动服务器时需要的命令行参数。
- 对于默认的 Stdio 模式，通常只需要可执行文件路径，例如 '["/path/to/mcp-graphql-forge"]'。你需要确保 'FORGE_CONFIG' 环境变量在执行该命令的环境中被正确设置，或者将配置文件直接放在可执行文件所在目录或当前工作目录。
- 对于 SSE 模式，需要添加 '--sse <地址>' 参数，例如 '["/path/to/mcp-graphql-forge", "--sse", ":8080"]'。此时服务器会在指定的地址和端口启动 HTTP 服务。客户端需要通过网络连接到 '/mcp/sse' 和 '/mcp/message' 端点。具体连接方式取决于客户端实现，通常客户端配置会包含网络地址信息，或者客户端会自行解析 '--sse' 参数来建立网络连接。

基本使用方法

准备配置文件: 创建一个目录，并在其中创建 'forge.yaml' 和至少一个工具 YAML 文件（例如 'getUser.yaml'），按照上述格式填写内容。
设置环境变量: 设置 'FORGE_CONFIG' 环境变量指向你存放配置文件的目录。
启动服务器 (由MCP客户端执行): 将编译好的 'mcp-graphql-forge' 可执行文件路径配置到你的 MCP 客户端中，并根据需要（Stdio 或 SSE）添加参数。当 MCP 客户端启动并需要与服务器交互时，它会按照配置自动启动 'mcp-graphql-forge' 进程。
LLM调用: 配置好的 MCP 服务器会将其 YAML 文件中定义的工具暴露给 LLM 客户端。LLM 客户端（智能体）可以根据工具的名称、描述和参数定义，决定何时以及如何调用这些工具来与底层的 GraphQL API 进行交互。

关键词

信息