AI导哈

GraphQL工具服务器

一个轻量级、配置驱动的MCP服务器，通过YAML文件定义GraphQL查询作为模块化工具，实现代理的API交互。

  • by UnitVectorY-Labs
  • Go
  • 混合部署
  • 5 星标
  • 更新于
在 GitHub 查看 UnitVectorY-Labs/mcp-graphql-forge

使用说明

mcp图形库伪造

一个轻量级的、配置驱动的MCP服务器，将精心策划的GraphQL查询公开为模块化工具，使您的代理能够进行有意的API交互。

目的

mcp-graphql-forge 允许您将任何GraphQL端点转换为MCP服务器，其工具在指定GraphQL查询及其参数的YAML文件中定义。这允许您创建一个模块化、安全和最小的服务器，可以在不修改应用程序代码的情况下轻松扩展。

发布

所有官方版本 mcp图形库伪造 发表于 GitHub发布。由于此MCP服务器是用Go编写的，因此每个版本都为macOS、Linux和Windows提供了预编译的可执行文件，可以随时下载和运行。

或者，如果您已安装Go，则可以安装 mcp图形库伪造 使用以下命令直接从源代码获取：

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 未设置。

伪造yaml

配置文件夹使用特殊的配置文件 forge.yaml 指定通用配置属性。

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

  • name：MCP服务器的名称
  • url：GraphQL端点的URL
  • token_command：用于请求Bearer令牌的命令 Authorization 标题（可选）
  • env：传递给token命令的环境变量映射（可选）
  • env_passthrough：如果设置为 true，将调用mcp-graphqlforge时使用的所有环境变量传递给token命令；如果与 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：参数类型；可以是“字符串”或“数字”
    • 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时特别有用，因为不同的格式可以优化令牌效率。

可用输出格式

生 （默认）

  • 完全按照收到的信息传递GraphQL服务器响应
  • 未进行任何转换或修改
  • 当您需要服务器提供原始格式时使用

JSON

  • 返回最小化的JSON，删除所有不必要的空格
  • 与格式化JSON相比，减少了令牌的使用
  • 非常适合在保持JSON兼容性的同时减少有效载荷大小
  • 如果响应不是有效的JSON，则自动回退到原始输出

卡通

  • 将JSON响应转换为TOON格式（面向令牌的对象表示法）
  • 对于统一的表格数据，可以将令牌使用量减少30-60%
  • 针对LLM消费进行了优化，具有紧凑、人类可读的输出
  • 使用 卡通格式/卡通走 图书馆
  • 如果响应不是有效的JSON或转换失败，则自动回退到原始输出

在流式HTTP模式下运行

默认情况下，服务器在stdio模式下运行，但如果要在可流式传输的HTTP模式中运行，可以指定 --http 带有服务器地址和端口的命令行标志（例如： --http 8080).这将使用MCP客户端可以连接到的以下端点运行服务器：

http://localhost:8080/mcp

./mcp-graphql-forge --http 8080

如果您没有指定 token_command 在配置中，如果将“Authorization”标头传递给MCP服务器，它将从传入的MCP请求传递到后端GraphQL端点。

局限性

  • 每个实例 mcp-graphql-forge 只能与单个URL上的单个GraphQL服务器一起使用。
  • GraphQL查询都是作为工具而不是资源公开的，即使它们不是突变。

相关 MCP