mcp-graphql-forge

mcp-graphql-forge

一个轻量、由配置驱动的 MCP 服务，可将精选的 GraphQL 查询公开为模块化工具，让 Agent 能够有针对性地与 API 交互。

用途

mcp-graphql-forge 可将任意 GraphQL 端点转换为 MCP 服务，其工具由 YAML 文件定义，文件中指定 GraphQL 查询及其参数。这样，您无需修改应用程序代码，即可创建一个模块化、安全且精简的服务，并轻松对其进行扩展。

发布版本

mcp-graphql-forge 的所有正式版本均发布在 GitHub Releases 上。由于此 MCP 服务使用 Go 编写，每次发布都会提供适用于 macOS、Linux 和 Windows 的预编译可执行文件，可直接下载并运行。

或者，如果您已安装 Go，也可以使用以下命令直接从源代码安装 mcp-graphql-forge：

go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest

配置

服务通过命令行参数、环境变量和 YAML 文件进行配置。

命令行参数

• --forgeConfig：指定包含 YAML 配置文件（forge.yaml 和工具定义）的文件夹路径。如果设置了此参数，其优先级高于 FORGE_CONFIG 环境变量。如果两者均未设置，应用程序将返回错误并退出。
• --forgeDebug：如果提供此参数，则会启用详细调试日志，并将其输出到 stderr，包括获取的令牌以及 GraphQL 调用的完整 HTTP 请求和响应。如果设置了此参数，其优先级高于 FORGE_DEBUG 环境变量。

环境变量

• FORGE_CONFIG：指定包含 YAML 配置文件（forge.yaml 和工具定义）的文件夹路径。如果未设置 --forgeConfig，则使用此变量。
• FORGE_DEBUG：如果设为 true（不区分大小写），则会启用详细调试日志，并将其输出到 stderr，包括获取的令牌以及 GraphQL 调用的完整 HTTP 请求和响应。如果未设置 --forgeDebug，则使用此变量。

forge.yaml

配置文件夹使用一个特殊配置文件 forge.yaml，用于指定通用配置属性。

文件中可以指定以下属性：

• name：MCP 服务的名称
• url：GraphQL 端点的 URL
• token_command：用于请求 Bearer 令牌并设置到 Authorization 标头的命令（可选）
• env：要传递给令牌命令的环境变量映射（可选）
• env_passthrough：如果设为 true，则会将调用 mcp-graphql-forge 时使用的所有环境变量传递给令牌命令；如果同时使用 env，则 env 中的变量优先（可选，默认为 false）

配置示例如下：

name: "ExampleServer"
url: "https://api.github.com/graphql"
token_command: "gh auth token"

工具配置

文件夹中的其他所有 YAML 文件都视为配置文件。每个 YAML 文件都会为 MCP 服务定义一个工具。

文件中可以指定以下属性：

• name：MCP 工具的名称
• description：MCP 工具的描述
• query：要执行的 GraphQL 查询
• inputs：MCP 工具定义的输入列表，这些输入会作为变量传递给 GraphQL 查询
  • name：输入的名称
  • type：参数类型；可以是 'string' 或 'number'
  • description：供 MCP 工具使用的参数描述
  • required：布尔值，用于指定该属性是否必填
• annotations：提供工具行为提示的 MCP 注释（可选）
  • title：便于在 UI 中显示的工具可读标题（可选）
  • readOnlyHint：若为 true，表示该工具不会修改其环境（可选，默认值：false）
  • destructiveHint：若为 true，该工具可能执行破坏性更新（仅当 readOnlyHint 为 false 时有意义）（可选，默认值：true）
  • idempotentHint：若为 true，使用相同参数重复调用该工具不会产生额外影响（仅当 readOnlyHint 为 false 时有意义）（可选，默认值：false）
  • openWorldHint：若为 true，该工具可能与外部实体的“开放世界”交互（可选，默认值：true）
• output：GraphQL 响应的输出格式（可选，默认值为 "raw"）
  • raw：按原样传递服务器响应（默认）
  • json：返回移除了多余空白的精简 JSON
  • toon：将 JSON 响应转换为 TOON 格式（面向令牌的对象表示法），以高效使用 LLM 令牌

配置示例如下：

name: "getUser"
description: "Fetch basic information about a user by `login`, including their name, URL, and location."
query: |
  query ($login: String!) {
    user(login: $login) {
      id
      name
      url
      location
    }
  }
inputs:
  - name: "login"
    type: "string"
    description: "The user `login` that uniquely identifies their account."
    required: true
annotations:
  title: "Get User Information"
  readOnlyHint: true
  destructiveHint: false
  idempotentHint: true
  openWorldHint: true
output: "toon"  # Optional: "raw" (default), "json", or "toon"

输出格式

output 配置参数允许你指定 GraphQL 响应的格式。处理 LLM 时，这尤其有用，因为不同格式可以优化令牌使用效率。

可用的输出格式

raw（默认）

• 按接收时的原样传递 GraphQL 服务响应
• 不进行任何转换或修改
• 需要服务器原始格式时使用

json

• 返回移除了所有多余空白的精简 JSON
• 与格式化 JSON 相比，可减少令牌使用量
• 在保持 JSON 兼容性的同时，适合缩减负载大小
• 如果响应不是有效的 JSON，则自动回退到 raw 输出

toon

• 将 JSON 响应转换为 TOON 格式（面向令牌的对象表示法）
• 对于结构均匀的表格数据，可减少 30-60% 的令牌使用量
• 针对 LLM 使用进行了优化，输出紧凑且易读
• 使用 toon-format/toon-go 库
• 如果响应不是有效的 JSON 或转换失败，则自动回退到 raw 输出

以可流式传输的 HTTP 模式运行

默认情况下，服务以 stdio 模式运行；如果要以可流式传输的 HTTP 模式运行，可以使用 --http 命令行标志指定服务地址和端口（例如：--http 8080）。服务将通过以下端点运行，MCP 客户端可以连接到该端点：

http://localhost:8080/mcp

./mcp-graphql-forge --http 8080

如果未在配置中指定 token_command，那么传递给 MCP 服务的 "Authorization" 标头（如果有）将从传入的 MCP 请求透传到后端 GraphQL 端点。

限制

• 每个 mcp-graphql-forge 实例只能连接到单个 URL 上的单个 GraphQL 服务。
• 所有 GraphQL 查询都会作为工具公开，而不是作为资源公开，即使它们不是 mutation 也是如此。