ガカイ

グラフQL → AI

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

🔌 GraphQLバックエンドを搭載
⚙️ .graphqlrc.yml + プレーンな.graphqlファイルによって駆動

✨ 特徴

• 🧰 GraphQL 操作を使用してツールを定義する

• 🗂 .graphqlrc.ymlから操作を自動的に検出する

• 🧾 OpenAI 関数呼び出し / MCP と互換性のあるツールメタデータ

Related MCP server: mcp-graphql-forge

🛠️ インストール

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 設定ファイルは、GraphQL エンドポイントとツールとして公開する操作を定義する YAML ファイルです。.graphqlrc.yml .graphqlrc.yml名前で、プロジェクトのルートに配置します。

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

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

この例では、ツールとして公開したいすべてのGraphQL操作がoperationsディレクトリに含まれています。操作は.graphqlファイルで定義され、gqai によって自動的に検出されます。

ヘッダー

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

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

MCP構成

クロードデスクトップ

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"
    }
  }
}

発達

前提条件

• 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>が ❤️ と 🤖 の気持ちを込めて作りました