gqai

graphql → ai

gqai 是一个轻量级代理，它将 GraphQL 操作暴露为像 Claude、Cursor 和 ChatGPT 这样的 AI 的 模型上下文协议 (MCP) 工具。 通过针对你的 GraphQL 后端定义工具使用常规的 GraphQL 查询/变更操作，gqai 自动为你生成一个 MCP 服务器。

🔌 由你的 GraphQL 后端驱动
⚙️ 由 .graphqlrc.yml + 纯 .graphql 文件驱动

---

✨ 特性

• 🧰 使用 GraphQL 操作定义工具
• 🗂 自动从 .graphqlrc.yml 中发现操作
• 🧾 工具元数据与 OpenAI 函数调用 / MCP 兼容

---

🛠 安装

go install github.com/fotoetienne/gqai@latest

🚀 快速开始

1. 创建一个 .graphqlrc.yml 文件：

schema: https://graphql.org/graphql/
documents: .

此文件告诉 gqai 在哪里找到你的 GraphQL 模式和操作。

注意：schema 参数告诉 gqai 在哪里执行操作。这必须是一个实时服务器而不是静态模式文件。

2. 添加一个 GraphQL 操作

get_all_films.graphql:

# 获取所有星球大战电影
query get_all_films {
  allFilms {
    films {
      title
      episodeID
    }
  }
}

3. 将 gqai 添加到你的 mcp.json 文件中：

  "gqai": {
    "command": "gqai",
    "args": [
      "run",
      "--config"
      ".graphqlrc.yml"
    ]
  }

就这样！你的 AI 模型现在可以调用 get_all_films 工具了。

使用

配置

GraphQL 配置

graphql 配置 文件是一个 YAML 文件，用于定义 GraphQL 终端和你希望作为工具公开的操作。它应该命名为 .graphqlrc.yml 并放置在项目的根目录下。

schema: https://graphql.org/graphql/
documents: operations

schema 字段指定了 GraphQL 终端，而 documents 字段指定了你的 GraphQL 操作所在的目录。

在这个例子中，operations 目录包含了所有你想作为工具公开的 GraphQL 操作。 操作定义在 .graphql 文件中，gqai 会自动发现它们。

头部信息

你还可以指定发送给 GraphQL 终端的每个请求的头部信息。这对于身份验证或其他自定义头部信息很有用。

schema:
  - https://graphql.org/graphql/:
      headers:
        Authorization: Bearer YOUR_TOKEN
        X-Custom-Header: CustomValue
documents: .

在头部中使用环境变量

你可以在头部值中引用环境变量，使用 ${VARNAME} 语法。例如：

schema:
  - https://graphql.org/graphql/:
      headers:
        Authorization: Bearer ${MY_AUTH_TOKEN}
documents: .

你也可以使用 ${VARNAME:-default} 语法提供默认值：

schema:
  - https://graphql.org/graphql/:
      headers:
        Authorization: Bearer ${MY_AUTH_TOKEN:-default-token}
documents: .

当 gqai 加载配置时，它会将 ${MY_AUTH_TOKEN} 替换为 MY_AUTH_TOKEN 环境变量的值，如果变量未设置，则使用 default-token。这允许你在配置文件中不包含秘密信息。

如果环境变量未设置且没有提供默认值，值将保持不变。

在配置中使用环境变量

你可以在 .graphqlrc.yml 配置的任何部分使用环境变量：模式 URL、文档路径、包含/排除通配符以及头部值。使用 ${VARNAME} 或 ${VARNAME:-default} 语法：

schema:
  - ${MY_SCHEMA_URL:-https://default/graphql}:
      headers:
        Authorization: Bearer ${MY_AUTH_TOKEN}
documents:
  - ${MY_DOCS_PATH:-operations/**/*.graphql}
include: ${MY_INCLUDE:-operations/include.graphql}
exclude: ${MY_EXCLUDE:-operations/exclude.graphql}

gqai 会将这些替换为环境变量的值，如果没有设置则使用默认值。这使得秘密信息和特定于环境的路径不会出现在配置文件中。

MCP 配置

Claude Desktop

要使用 gqai 与 Claude Desktop，你需要在 mcp.json 文件中添加以下配置：

{
  "gqai": {
    "command": "gqai",
    "args": [
      "run",
      "--config",
      ".graphqlrc.yml"
    ]
  }
}

🧪 CLI 测试

通过 CLI 调用工具以进行测试：

gqai tools/call get_all_films

这将执行 get_all_films 工具并打印结果。

{
  "data": {
    "allFilms": {
      "films": [
        {
          "id": 4,
          "title": "A New Hope"
        },
        {
          "id": 5,
          "title": "The Empire Strikes Back"
        },
        {
          "id": 6,
          "title": "Return of the Jedi"
        },
        ...
      ]
    }
  }
}

带参数调用工具：

创建一个接受参数的 GraphQL 操作，这些参数将成为工具输入：

get_film_by_id.graphql:

query get_film_by_id($id: ID!) {
  film(filmID: $id) {
    episodeID
    title
    director
    releaseDate
  }
}

带参数调用工具：

gqai tools/call get_film_by_id '{"id": "1"}'

这将执行 get_film_by_id 工具，并使用提供的参数。

{
  "data": {
    "film": {
      "episodeID": 1,
      "title": "A New Hope",
      "director": "George Lucas",
      "releaseDate": "1977-05-25"
    }
  }
}

开发

先决条件

• Go 1.20+

构建

go build -o gqai main.go

测试

go test ./...

格式化

go fmt ./...

运行 MCP 服务器

./gqai run --config .graphqlrc.yml

运行 CLI

./gqai tools/call get_all_films

关于 GQAI

🤖 为什么是 gqai？

gqai 让你轻松地将 GraphQL 后端转换为模型就绪的工具层——无需编写代码，无需额外基础设施。只需定义你的操作，让 AI 调用它们。

📜 许可证

MIT — 分支它，构建它，一切皆有可能。

👋 作者

由 Stephen Spalding && <your-name-here> 制作，充满爱心和机器人气息。