AI导哈

GraphQL转AI工具代理

gqai是一个轻量级代理，将GraphQL操作暴露为AI模型（如Claude、Cursor和ChatGPT）的工具，通过GraphQL后端自动生成MCP服务器。

  • by fotoetienne
  • Go
  • 本地部署
  • 22 星标
  • 更新于
在 GitHub 查看 fotoetienne/gqai

使用说明

盖伊

图查询语言→ ai

盖伊 是一个轻量级的代理，它将GraphQL操作公开为 模型上下文协议（MCP） AI类工具 Claude、Cursor和ChatGPT。
对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在哪里执行操作。这必须是一个实时服务器，而不是一个静态架构文件

  1. 添加GraphQL操作

get_all_films.graphql:

# Get all Star Wars films
query get_all_films {
  allFilms {
    films {
      title
      episodeID
    }
  }
}
  1. 将gqai添加到您的 mcp.json 文件：
  "gqai": {
    "command": "gqai",
    "args": [
      "run",
      "--config"
      ".graphqlrc.yml"
    ]
  }

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

用法

配置

GraphQL配置

这 graphql配置 file是一个定义GraphQL端点和操作的YAML文件 你想作为工具公开。它应该被命名 .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 config:模式URL、文档路径、包含/排除globs和标头值。使用 ${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，您需要将以下配置添加到您的 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"
    }
  }
}

发展

先决条件

  • 转到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调用它们。

📜 许可证

麻省理工学院——分叉它，建立它，所有的东西。

👋 作者

由以下材料制成❤️ 和🤖斯蒂芬·斯伯丁&& <your-name-here>

相关 MCP