Gqai GraphQL + AI

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

---

- Go 1.20+

go install github.com/fotoetienne/gqai@latest

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:

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.

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.
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.
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.

gqai tools/call get_all_films

This will execute the get_all_films tool and print the result.

{
  "data": {
    "allFilms": {
      "films": [
        {
          "id": 4,
          "title": "A New Hope"
        },
        {
          "id": 5,
          "title": "The Empire Strikes Back"
        },
        {
          "id": 6,
          "title": "Return of the Jedi"
        },
        ...
      ]
    }
  }
}

Create a GraphQL operation that takes arguments, and these will be the tool inputs:

get_film_by_id.graphql:

query get_film_by_id($id: ID!) {

  film(filmID: $id) {

    episodeID

    title

    director

    releaseDate

  }

}

Call the tool with arguments:

gqai tools/call get_film_by_id '{"id": "1"}'

This will execute the get_film_by_id tool with the provided arguments.

{
  "data": {
    "film": {
      "episodeID": 1,
      "title": "A New Hope",
      "director": "George Lucas",
      "releaseDate": "1977-05-25"
    }
  }
}