Gqai GraphQL + AI

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 和操作。

注意：schema 参数会告知 gqai 在哪里执行操作。这里必须是一个在线服务，而不是静态 schema 文件

2. 添加一个 GraphQL 操作

get_all_films.graphql：

# Get all Star Wars films
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 配置的任何部分使用环境变量：schema URL、文档路径、包含/排除 glob 和请求头值。使用 ${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

若要在 Claude Desktop 中使用 gqai，你需要将以下配置添加到 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> 用 ❤️ 和 🤖氛围打造