【技术文档摘要】：

mcp-graphql-forge

一个轻量级、配置驱动的MCP服务器，它暴露经过策划的GraphQL查询作为模块化工具，使您的代理能够进行有意的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：用于请求Authorization头中的Bearer令牌的命令（可选）
• 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）

一个示例配置如下：

name: "getUser"
description: "通过`login`获取用户的基本信息，包括他们的名字、URL和位置。"
query: |
  query ($login: String!) {
    user(login: $login) {
      id
      name
      url
      location
    }
  }
inputs:
  - name: "login"
    type: "string"
    description: "唯一标识账户的用户`login`。"
    required: true
annotations:
  title: "获取用户信息"
  readOnlyHint: true
  destructiveHint: false
  idempotentHint: true
  openWorldHint: true

在流式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查询也全部作为工具而不是资源公开。