gqai

# gqai *graphql → ai* **gqai** is a lightweight proxy that exposes GraphQL operations as [Model Context Protocol (MCP)](https://platform.openai.com/docs/guides/function-calling) 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 ```bash go install github.com/fotoetienne/gqai@latest ``` ## 🚀 Quick Start 1. Create a .graphqlrc.yml: ```yaml 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`: ```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](https://the-guild.dev/graphql/config/docs/user/schema) 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. ```yaml 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. ```yaml 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: ```yaml schema: - https://graphql.org/graphql/: headers: Authorization: Bearer ${MY_AUTH_TOKEN} documents: . ``` You can also provide a default value using the `${VARNAME:-default}` syntax: ```yaml schema: - https://graphql.org/graphql/: headers: Authorization: Bearer ${MY_AUTH_TOKEN:-default-token} documents: . ``` When 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. If the environment variable is not set and no default is provided, the value will be left as-is. ##### Using Environment Variables in Config You 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: ```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 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. #### MCP Configuration ##### Claude Desktop To use gqai with Claude Desktop, you need to add the following configuration to your `mcp.json` file: ```json { "gqai": { "command": "gqai", "args": [ "run", "--config", ".graphqlrc.yml" ] } } ``` ### 🧪 CLI Testing #### Call a tool via CLI to test: ```bash gqai tools/call get_all_films ``` This will execute the `get_all_films` tool and print the result. ```shell { "data": { "allFilms": { "films": [ { "id": 4, "title": "A New Hope" }, { "id": 5, "title": "The Empire Strikes Back" }, { "id": 6, "title": "Return of the Jedi" }, ... ] } } } ``` #### Call a tool with arguments: Create a GraphQL operation that takes arguments, and these will be the tool inputs: `get_film_by_id.graphql`: ```graphql query get_film_by_id($id: ID!) { film(filmID: $id) { episodeID title director releaseDate } } ``` Call the tool with arguments: ```bash gqai tools/call get_film_by_id '{"id": "1"}' ``` This will execute the `get_film_by_id` tool with the provided arguments. ```shell { "data": { "film": { "episodeID": 1, "title": "A New Hope", "director": "George Lucas", "releaseDate": "1977-05-25" } } } ``` ## Development ### Prerequisites - Go 1.20+ ### Build ```bash go build -o gqai main.go ``` ### Test ```bash go test ./... ``` ### Format ```bash go fmt ./... ``` ### Run MCP server ```bash ./gqai run --config .graphqlrc.yml ``` ### Run CLI ```bash ./gqai tools/call get_all_films ``` ## About GQAI ### 🤖 Why gqai? gqai 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. ### 📜 License MIT — fork it, build on it, all the things. ### 👋 Author Made with ❤️ and 🤖vibes by Stephen Spalding && `<your-name-here>`