Gqai GraphQL + AI

gqai

graphql → ai

gqai は、GraphQL オペレーションを Claude、Cursor、ChatGPT などの AI 向けの Model Context Protocol (MCP) ツールとして公開する軽量なプロキシです。
GraphQL バックエンドに対する通常の GraphQL クエリ／ミューテーションを使ってツールを定義すると、gqai が MCP サーバーを自動的に生成します。

🔌 GraphQL バックエンドを活用
⚙️ .graphqlrc.yml と通常の .graphql ファイルで動作

---

✨ 機能

• 🧰 GraphQL オペレーションを使ってツールを定義
• 🗂 .graphqlrc.yml からオペレーションを自動検出
• 🧾 OpenAI function calling／MCP と互換性のあるツールメタデータ

---

🛠️ インストール

go install github.com/fotoetienne/gqai@latest

🚀 クイックスタート

1. .graphqlrc.yml を作成します：

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

このファイルで、GraphQL スキーマとオペレーションの場所を gqai に指定します。

注：schema パラメーターは、オペレーションの実行先を gqai に指定します。静的なスキーマファイルではなく、稼働中のサーバーを指定する必要があります。

2. GraphQL オペレーションを追加します

get_all_films.graphql:

# Get all Star Wars films
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 config ファイルは、GraphQL エンドポイントとツールとして公開するオペレーションを定義する YAML ファイルです。.graphqlrc.yml という名前を付け、プロジェクトのルートに配置してください。

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

schema フィールドでは GraphQL エンドポイントを指定し、documents フィールドでは GraphQL オペレーションが配置されているディレクトリを指定します。

この例では、operations ディレクトリに、ツールとして公開するすべての GraphQL オペレーションが含まれています。 オペレーションは .graphql ファイルで定義し、gqai が自動的に検出します。

ヘッダー

GraphQL エンドポイントへの各リクエストとともに送信するヘッダーも指定できます。認証やその他のカスタムヘッダーに便利です。

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

ヘッダーでの環境変数の使用

${VARNAME} 構文を使うと、ヘッダー値で環境変数を参照できます。たとえば、次のように指定します：

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

${VARNAME:-default} 構文を使って、デフォルト値を指定することもできます：

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、ドキュメントパス、include／exclude グロブ、ヘッダー値など、どの箇所でも環境変数を使用できます。${VARNAME} または ${VARNAME:-default} 構文を使います：

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 Desktop

Claude Desktop で gqai を使用するには、mcp.json ファイルに次の設定を追加します：

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

🧪 CLI でのテスト

CLI からツールを呼び出してテストします：

gqai tools/call get_all_films

これにより、get_all_films ツールが実行され、結果が出力されます。

{
  "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:

query get_film_by_id($id: ID!) {
  film(filmID: $id) {
    episodeID
    title
    director
    releaseDate
  }
}

引数を指定してツールを呼び出します：

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

これにより、指定した引数を使って get_film_by_id ツールが実行されます。

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

開発

前提条件

• Go 1.20+

ビルド

go build -o gqai main.go

テスト

go test ./...

フォーマット

go fmt ./...

MCP サーバーの実行

./gqai run --config .graphqlrc.yml

CLI の実行

./gqai tools/call get_all_films

GQAI について

🤖 gqai を使う理由

gqai を使うと、GraphQL バックエンドをモデル向けのツールレイヤーに簡単に変換できます。コードも追加のインフラも必要ありません。オペレーションを定義するだけで、AI がそれらを呼び出せます。

📜 ライセンス

MIT — フォークして、活用して、自由にお使いください。

👋 作者

Stephen Spalding && <your-name-here> が ❤️ と 🤖vibes を込めて作成しました