GraphQL → ai

gqai 是一个轻量级代理，可以将 GraphQL 操作暴露为 模型上下文协议（MCP）用于人工智能的工具，如 Claude、光标和ChatGPT。 在你的GraphQL后端定义使用常规GraphQL查询/变异的工具，并自动生成gqai。 为你生成一个MCP服务器。

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

---

✨ 特色

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

---

🛠️ 安装

🚀 快速启动

1. 创建.graphqlrc.yml：

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

注意：schema 参数指示 gqai 执行操作的位置。这必须是实时服务器，而非静态模式文件

2. 添加GraphQL操作

get_all_films.graphql：

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

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

用途

配置

GraphQL 配置

GraphQL 配置 file 是一个定义 GraphQL 端点及其操作的 YAML 文件 你想把它当作工具来揭露。

gqai

graphql → ai

gqai is a lightweight proxy that exposes GraphQL operations as Model Context Protocol (MCP) tools for AI like Claude, Cursor, and ChatGPT.
Define tools using regular GraphQL queries/mutations against your GraphQL backend, and gqai automatically generates an MCP server for you.

🔌 Powered by your GraphQL backend
⚙️ Driven by .graphqlrc.yml + plain .graphql files

---

✨ Features

• 🧰 Define tools using GraphQL operations
• 🗂 Automatically discover operations from .graphqlrc.yml
• 🧾 Tool metadata compatible with OpenAI function calling / MCP

---

🛠️ Installation

go install github.com/fotoetienne/gqai@latest

🚀 Quick Start

1. Create a .graphqlrc.yml:

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

This file tells gqai where to find your GraphQL schema and operations.

Note: The schema parameter tells gqai where to execute the operations. This must be a live server rather than a static schema file

2. Add a GraphQL operation

get_all_films.graphql:

# Get all Star Wars films
query get_all_films {
  allFilms {
    films {
      title
      episodeID
    }
  }
}

3. Add gqai to your mcp.json file:

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

That’s it! Your AI model can now call the get_all_films tool.

Usage

Configuration

GraphQL Config

The graphql config file is a YAML file that defines the GraphQL endpoint and the operations you want to expose as tools. It should be named .graphqlrc.yml and placed in the root of your project.

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

The schema field specifies the GraphQL endpoint, and the documents field specifies the directory where your GraphQL operations are located.

In this example, the operations directory contains all the GraphQL operations you want to expose as tools. Operations are defined in .graphql files, and gqai will automatically discover them.

Headers

You can also specify headers to be sent with each request to the GraphQL endpoint. This is useful for authentication or other custom headers.

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

Using Environment Variables in Headers

You can reference environment variables in header values using the ${VARNAME} syntax. For example:

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

You can also provide a default value using the ${VARNAME:-default} syntax:

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