mcp-graphql-forge

mcp-graphql-forge

厳選した GraphQL クエリをモジュール式のツールとして公開し、エージェントによる意図的な API 操作を可能にする、軽量で設定駆動型の MCP サーバーです。

目的

mcp-graphql-forge を使うと、GraphQL エンドポイントを MCP サーバーに変換できます。そのツールは、GraphQL クエリとそのパラメーターを指定する YAML ファイルで定義します。これにより、アプリケーションコードを変更せずに簡単に拡張できる、モジュール式で安全かつ最小限のサーバーを作成できます。

リリース

mcp-graphql-forge の公式バージョンはすべて、GitHub Releases で公開されています。この MCP サーバーは Go で記述されているため、各リリースでは macOS、Linux、Windows 用のコンパイル済み実行ファイルが提供され、ダウンロードしてすぐに実行できます。

また、Go がインストールされている場合は、次のコマンドを使って mcp-graphql-forge をソースから直接インストールできます。

go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest

設定

サーバーは、コマンドラインパラメーター、環境変数、YAML ファイルを使って設定します。

コマンドラインパラメーター

• --forgeConfig：YAML 設定ファイル（forge.yaml とツール定義）が格納されたフォルダーのパスを指定します。設定されている場合、FORGE_CONFIG 環境変数より優先されます。どちらも設定されていない場合、アプリケーションはエラーを返して終了します。
• --forgeDebug：指定すると、取得したトークンや GraphQL 呼び出しの HTTP リクエスト／レスポンス全体を含む詳細なデバッグログを stderr に出力します。設定されている場合、FORGE_DEBUG 環境変数より優先されます。

環境変数

• FORGE_CONFIG：YAML 設定ファイル（forge.yaml とツール定義）が格納されたフォルダーのパスを指定します。--forgeConfig が設定されていない場合に使用されます。
• FORGE_DEBUG：true（大文字と小文字を区別しません）に設定すると、取得したトークンや GraphQL 呼び出しの HTTP リクエスト／レスポンス全体を含む詳細なデバッグログを stderr に出力します。--forgeDebug が設定されていない場合に使用されます。

forge.yaml

設定フォルダーには、共通の設定属性を指定する特別な設定ファイル forge.yaml を使用します。

ファイルでは、次の属性を指定できます。

• name：MCP サーバーの名前
• url：GraphQL エンドポイントの URL
• token_command：Authorization ヘッダー用の Bearer トークンを取得するために実行するコマンド（省略可能）
• env：トークン取得コマンドに渡す環境変数のマップ（省略可能）
• env_passthrough：true に設定すると、mcp-graphql-forge の起動時に使用されるすべての環境変数をトークン取得コマンドに渡します。env と併用した場合は、env の変数が優先されます（省略可能。デフォルトは false）

設定例は次のとおりです。

name: "ExampleServer"
url: "https://api.github.com/graphql"
token_command: "gh auth token"

ツールの設定

フォルダー内にあるその他のすべての YAML ファイルは、設定ファイルとして扱われます。各 YAML ファイルは、MCP サーバーのツールを定義します。

ファイルでは、次の属性を指定できます。

• name：MCP ツールの名前
• description：MCP ツールの説明
• query：実行する GraphQL クエリ
• inputs：MCP ツールで定義され、変数として GraphQL クエリに渡される入力のリスト
  • name：入力の名前
  • type：パラメーターの型。'string' または 'number' を指定できます
  • description：MCP ツールが使用するパラメーターの説明
  • required：属性が必須かどうかを指定するブール値
• annotations：ツールの動作に関するヒントを提供する MCP アノテーション（任意）
  • title：UI 表示に便利な、人が読めるツールのタイトル（任意）
  • readOnlyHint：true の場合、ツールが環境を変更しないことを示します（任意、デフォルト：false）
  • destructiveHint：true の場合、ツールが破壊的な更新を実行する可能性があることを示します（readOnlyHint が false の場合のみ有効）（任意、デフォルト：true）
  • idempotentHint：true の場合、同じ引数でツールを繰り返し呼び出しても、追加の影響がないことを示します（readOnlyHint が false の場合のみ有効）（任意、デフォルト：false）
  • openWorldHint：true の場合、ツールが外部エンティティの「オープンワールド」とやり取りする可能性があることを示します（任意、デフォルト：true）
• output：GraphQL レスポンスの出力形式（任意、デフォルトは "raw"）
  • raw：サーバーのレスポンスをそのまま渡します（デフォルト）
  • json：不要な空白を削除した最小限の JSON を返します
  • toon：LLM のトークンを効率よく使用できるよう、JSON レスポンスを TOON（Token-Oriented Object Notation）形式に変換します

設定例は次のとおりです。

name: "getUser"
description: "Fetch basic information about a user by `login`, including their name, URL, and location."
query: |
  query ($login: String!) {
    user(login: $login) {
      id
      name
      url
      location
    }
  }
inputs:
  - name: "login"
    type: "string"
    description: "The user `login` that uniquely identifies their account."
    required: true
annotations:
  title: "Get User Information"
  readOnlyHint: true
  destructiveHint: false
  idempotentHint: true
  openWorldHint: true
output: "toon"  # Optional: "raw" (default), "json", or "toon"

出力形式

output 設定パラメーターを使用すると、GraphQL レスポンスの形式を指定できます。これは、さまざまな形式によってトークン効率を最適化できるため、LLM を使用する際に特に便利です。

利用可能な出力形式

raw（デフォルト）

• GraphQL サーバーのレスポンスを受け取ったとおりに渡します
• 変換や変更は適用されません
• サーバーからの元の形式が必要な場合に使用します

json

• 不要な空白をすべて削除した最小限の JSON を返します
• 整形済み JSON と比べてトークン使用量を削減します
• JSON との互換性を維持しながら、ペイロードサイズを削減するのに最適です
• レスポンスが有効な JSON でない場合は、自動的に raw 出力にフォールバックします

toon

• JSON レスポンスを TOON（Token-Oriented Object Notation）形式に変換します
• 均一な表形式のデータでは、トークン使用量を 30～60% 削減できます
• コンパクトで人が読みやすい出力により、LLM での利用に最適化されています
• toon-format/toon-go ライブラリを使用します
• レスポンスが有効な JSON でない場合、または変換に失敗した場合は、自動的に raw 出力にフォールバックします

ストリーミング可能な HTTP モードでの実行

デフォルトでは、サーバーは stdio モードで実行されます。ストリーミング可能な HTTP モードで実行するには、サーバーのアドレスとポートを指定して --http コマンドラインフラグを指定します（例：--http 8080）。これにより、MCP クライアントが接続できる次のエンドポイントでサーバーが実行されます。

http://localhost:8080/mcp

./mcp-graphql-forge --http 8080

設定で token_command を指定しない場合、MCP サーバーに渡された「Authorization」ヘッダーは、受信した MCP リクエストからバックエンドの GraphQL エンドポイントにそのまま渡されます。

制限事項

• mcp-graphql-forge の各インスタンスは、単一の URL にある単一の GraphQL サーバーでのみ使用できます。
• GraphQL クエリは、ミューテーションでない場合も含め、すべて Resource ではなく Tool として公開されます。