内容
# gqai
*graphql 转 ai*
**gqai** 是一个轻量级代理，暴露 GraphQL 操作作为
[模型上下文协议（MCP）](https://platform.openai.com/docs/guides/function-calling) 工具，供 AI（如 Claude、Cursor 和 ChatGPT）使用。
使用针对 GraphQL 后端的常规 GraphQL 查询/变异定义工具，gqai 会自动为您生成 MCP 服务器。
🔌 由您的 GraphQL 后端提供支持
⚙️ 由 `.graphqlrc.yml` 和普通的 `.graphql` 文件驱动
---
## ✨ 功能特点
- 🧰 使用 GraphQL 操作定义工具
- 🗂 从 `.graphqlrc.yml` 自动发现操作
- 🧾 工具元数据与 OpenAI 函数调用 / MCP 兼容
---
## 🛠️ 安装
```bash
go install github.com/fotoetienne/gqai@latest
```
## 🚀 快速开始
1. 创建 `.graphqlrc.yml`：
```yaml
schema: https://graphql.org/graphql/
documents: .
```
此文件告诉 gqai 在哪里找到您的 GraphQL 模式和操作。
*注意：`schema` 参数告诉 gqai 在哪里执行操作。这必须是实时服务器，而不是静态模式文件*
2. 添加 GraphQL 操作
`get_all_films.graphql`：
```graphql
# 获取所有星球大战电影
query get_all_films {
allFilms {
films {
title
episodeID
}
}
}
```
3. 在 `mcp.json` 文件中添加 gqai：
```
"gqai": {
"command": "gqai",
"args": [
"run",
"--config"
".graphqlrc.yml"
]
}
```
就这样！您的 AI 模型现在可以调用 `get_all_films` 工具。
## 使用
### 配置
#### GraphQL 配置
[graphql 配置](https://the-guild.dev/graphql/config/docs/user/schema) 文件是一个 YAML 文件，定义了 GraphQL 端点和您要暴露为工具的操作。它应该命名为 `.graphqlrc.yml` 并放置在您的项目根目录中。
```yaml
schema: https://graphql.org/graphql/
documents: operations
```
`schema` 字段指定 GraphQL 端点，`documents` 字段指定 GraphQL 操作文件的位置。
在此示例中，`operations` 目录包含您要暴露为工具的所有 GraphQL 操作。
操作在 `.graphql` 文件中定义，gqai 将自动发现它们。
##### 头部信息
您还可以指定在向 GraphQL 端点发送每个请求时要发送的头部信息。这对于身份验证或其他自定义头部信息很有用。
```yaml
schema:
- https://graphql.org/graphql/:
headers:
Authorization: Bearer YOUR_TOKEN
X-Custom-Header: CustomValue
documents: .
```
##### 在头部信息中使用环境变量
您可以使用 `${VARNAME}` 语法在头部信息值中引用环境变量。例如：
```yaml
schema:
- https://graphql.org/graphql/:
headers:
Authorization: Bearer ${MY_AUTH_TOKEN}
documents: .
```
您还可以使用 `${VARNAME:-default}` 语法提供默认值：
```yaml
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}` 语法：
```yaml
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 桌面版
要将 gqai 与 Claude 桌面版一起使用，您需要在 `mcp.json` 文件中添加以下配置：
```json
{
"gqai": {
"command": "gqai",
"args": [
"run",
"--config",
".graphqlrc.yml"
]
}
}
```
### 🧪 CLI 测试
#### 通过 CLI 调用工具进行测试：
```bash
gqai tools/call get_all_films
```
这将执行 `get_all_films` 工具并打印结果。
```shell
{
"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`：
```graphql
query get_film_by_id($id: ID!) {
film(filmID: $id) {
episodeID
title
director
releaseDate
}
}
```
使用参数调用工具：
```bash
gqai tools/call get_film_by_id '{"id": "1"}'
```
这将使用提供的参数执行 `get_film_by_id` 工具。
```shell
{
"data": {
"film": {
"episodeID": 1,
"title": "A New Hope",
"director": "George Lucas",
"releaseDate": "1977-05-25"
}
}
}
```
## 开发
### 先决条件
- Go 1.20+
### 构建
```bash
go build -o gqai main.go
```
### 测试
```bash
go test ./...
```
### 格式化
```bash
go fmt ./...
```
### 运行 MCP 服务器
```bash
./gqai run --config .graphqlrc.yml
```
### 运行 CLI
```bash
./gqai tools/call get_all_films
```
## 关于 GQAI
### 🤖 为什么使用 gqai？
gqai 使您轻松将 GraphQL 后端转换为模型-ready 工具层 — 无需代码，无需额外基础设施。只需定义操作，让 AI 调用它们。
### 📜 许可证
MIT — fork 它，构建它，所有事情。
### 👋 作者
由 Stephen Spalding 和 `<your-name-here>` 以 ❤️ 和 🤖vibes 制作
MCP 市场