gqai

1# gqai
2*graphql → ai*
3 
4**gqai** is a lightweight proxy that exposes GraphQL operations as
5[Model Context Protocol (MCP)](https://platform.openai.com/docs/guides/function-calling) tools for AI like
6Claude, Cursor, and ChatGPT.  
7Define tools using regular GraphQL queries/mutations against your GraphQL backend, and gqai automatically
8generates an MCP server for you.
9 
10🔌 Powered by your GraphQL backend  
11⚙️ Driven by `.graphqlrc.yml` + plain `.graphql` files  
12 
13---
14 
15## ✨ Features
16 
17- 🧰 Define tools using GraphQL operations
18- 🗂 Automatically discover operations from `.graphqlrc.yml`
19- 🧾 Tool metadata compatible with OpenAI function calling / MCP
20 
21---
22 
23## 🛠️ Installation
24 
25```bash
26go install github.com/fotoetienne/gqai@latest
27```
28 
29 
30## 🚀 Quick Start
311. Create a .graphqlrc.yml:
32 
33```yaml
34schema: https://graphql.org/graphql/
35documents: .
36```
37 
38This file tells gqai where to find your GraphQL schema and operations.
39 
40*Note: The `schema` parameter tells gqai where to execute the operations. This must be a live server rather than a static schema file*
41 
422. Add a GraphQL operation
43 
44`get_all_films.graphql`:
45```graphql
46# Get all Star Wars films
47query get_all_films {
48  allFilms {
49    films {
50      title
51      episodeID
52    }
53  }
54}
55```
56 
573. Add gqai to your `mcp.json` file:
58 
59```
60  "gqai": {
61    "command": "gqai",
62    "args": [
63      "run",
64      "--config"
65      ".graphqlrc.yml"
66    ]
67  }
68```
69 
70That's it! Your AI model can now call the `get_all_films` tool.
71 
72## Usage
73### Configuration
74#### GraphQL Config
75The [graphql config](https://the-guild.dev/graphql/config/docs/user/schema)
76file is a YAML file that defines the GraphQL endpoint and the operations
77you want to expose as tools. It should be named `.graphqlrc.yml` and placed in the root of your project.
78 
79```yaml
80schema: https://graphql.org/graphql/
81documents: operations
82```
83 
84The `schema` field specifies the GraphQL endpoint, and the `documents` field specifies the directory where your GraphQL operations are located.
85 
86In this example, the `operations` directory contains all the GraphQL operations you want to expose as tools.
87Operations are defined in `.graphql` files, and gqai will automatically discover them.
88 
89##### Headers
90You can also specify headers to be sent with each request to the GraphQL endpoint. This is useful for authentication or other custom headers.
91 
92```yaml
93schema:
94  - https://graphql.org/graphql/:
95      headers:
96        Authorization: Bearer YOUR_TOKEN
97        X-Custom-Header: CustomValue
98documents: .
99```
100 
101##### Using Environment Variables in Headers
102You can reference environment variables in header values using the `${VARNAME}` syntax. For example:
103 
104```yaml
105schema:
106  - https://graphql.org/graphql/:
107      headers:
108        Authorization: Bearer ${MY_AUTH_TOKEN}
109documents: .
110```
111 
112You can also provide a default value using the `${VARNAME:-default}` syntax:
113 
114```yaml
115schema:
116  - https://graphql.org/graphql/:
117      headers:
118        Authorization: Bearer ${MY_AUTH_TOKEN:-default-token}
119documents: .
120```
121 
122When gqai loads the config, it will substitute `${MY_AUTH_TOKEN}` with the value of the `MY_AUTH_TOKEN` environment variable, or use `default-token` if the variable is not set. This allows you to keep secrets out of your config files.
123 
124If the environment variable is not set and no default is provided, the value will be left as-is.
125 
126##### Using Environment Variables in Config
127You can use environment variables in any part of your `.graphqlrc.yml` config: schema URLs, document paths, include/exclude globs, and header values. Use `${VARNAME}` or `${VARNAME:-default}` syntax:
128 
129```yaml
130schema:
131  - ${MY_SCHEMA_URL:-https://default/graphql}:
132      headers:
133        Authorization: Bearer ${MY_AUTH_TOKEN}
134documents:
135  - ${MY_DOCS_PATH:-operations/**/*.graphql}
136include: ${MY_INCLUDE:-operations/include.graphql}
137exclude: ${MY_EXCLUDE:-operations/exclude.graphql}
138```
139 
140gqai will substitute these with the value of the environment variable, or use the default if not set. This keeps secrets and environment-specific paths out of your config files.
141 
142#### MCP Configuration
143##### Claude Desktop
144To use gqai with Claude Desktop, you need to add the following configuration to your `mcp.json` file:
145 
146```json
147{
148  "gqai": {
149    "command": "gqai",
150    "args": [
151      "run",
152      "--config",
153      ".graphqlrc.yml"
154    ]
155  }
156}
157```
158 
159 
160### 🧪 CLI Testing
161#### Call a tool via CLI to test:
162 
163```bash
164gqai tools/call get_all_films
165```
166 
167This will execute the `get_all_films` tool and print the result.
168 
169```shell
170{
171  "data": {
172    "allFilms": {
173      "films": [
174        {
175          "id": 4,
176          "title": "A New Hope"
177        },
178        {
179          "id": 5,
180          "title": "The Empire Strikes Back"
181        },
182        {
183          "id": 6,
184          "title": "Return of the Jedi"
185        },
186        ...
187      ]
188    }
189  }
190}
191```
192#### Call a tool with arguments:
193 
194Create a GraphQL operation that takes arguments, and these will be the tool inputs:
195 
196`get_film_by_id.graphql`:
197```graphql
198query get_film_by_id($id: ID!) {
199  film(filmID: $id) {
200    episodeID
201    title
202    director
203    releaseDate
204  }
205}
206```
207 
208Call the tool with arguments:
209 
210```bash
211gqai tools/call get_film_by_id '{"id": "1"}'
212```
213 
214This will execute the `get_film_by_id` tool with the provided arguments.
215 
216```shell
217{
218  "data": {
219    "film": {
220      "episodeID": 1,
221      "title": "A New Hope",
222      "director": "George Lucas",
223      "releaseDate": "1977-05-25"
224    }
225  }
226}
227```
228 
229## Development
230 
231### Prerequisites
232- Go 1.20+
233 
234### Build
235```bash
236go build -o gqai main.go
237```
238 
239### Test
240```bash
241go test ./...
242```
243 
244### Format
245```bash
246go fmt ./...
247```
248 
249### Run MCP server
250```bash
251./gqai run --config .graphqlrc.yml
252```
253 
254### Run CLI
255```bash
256./gqai tools/call get_all_films
257```
258 
259 
260## About GQAI
261 
262### 🤖 Why gqai?
263gqai makes it easy to turn your GraphQL backend into a model-ready tool layer — no code, no extra infra. Just define your operations and let AI call them.
264 
265### 📜 License
266MIT — fork it, build on it, all the things.
267 
268### 👋 Author
269Made with ❤️ and 🤖vibes by Stephen Spalding && `<your-name-here>`
270