GraphQLスキーマ埋め込みMCPサーバー

GraphQLスキーマをインデックス化し、埋め込みエンドポイントを介して type->field ごとの埋め込みを保存する、LLM向けのPython MCPサーバーです。関連する型が特定された後に run_query を実行してGraphQLエンドポイントからデータを取得する高速なルックアップを可能にします。

アーキテクチャ

• GraphQLスキーマ: 解析とインデックス化を行うためのスキーマファイル (SDL) を提供します。

• インデクサー: schema_indexer.py は、フィールドメタデータ、あいまい検索エイリアス、Queryルート座標を含むGraphQLフィールドノードのナビゲーションインデックスを構築し、生成された検索テキストを埋め込んで data/metadata.json + data/vectors.npz に永続化します。

• サーバー: server.py はMCPツール list_types と run_query を公開します。サーバーは起動時にスキーマインデックスが存在することを確認し、再インデックス化または新しいクエリの埋め込みを行う場合にのみ埋め込みエンドポイントを呼び出します。

• 永続化: data/ は .gitignore に含まれているため、リポジトリを汚染することなくローカルで再生成できます。

セットアップ

環境変数を設定します。.env.example から開始できます。

環境設定:

• GRAPHQL_EMBED_API_KEY (または OPENAI_API_KEY)

• GRAPHQL_EMBEDDINGS_URL (完全な埋め込みURL)

• GRAPHQL_EMBED_MODEL

• GRAPHQL_EMBED_API_KEY_HEADER / GRAPHQL_EMBED_API_KEY_PREFIX

• GRAPHQL_EMBED_HEADERS (追加ヘッダー用のJSONオブジェクト文字列) エンドポイント認証 (GRAPHQL_ENDPOINT_URL を使用する場合):

• GRAPHQL_ENDPOINT_HEADERS (JSONオブジェクト文字列、任意の --header フラグとマージされます)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 src/server.py

MCPサーバーの実行

python3 src/server.py                # SSE on 127.0.0.1:8000/sse by default
python3 src/server.py --transport sse     # explicit SSE
python3 src/server.py --transport streamable-http  # Streamable HTTP on 127.0.0.1:8000/mcp
# Or: point at a live GraphQL endpoint (requires introspection enabled)
python3 src/server.py --endpoint https://api.example.com/graphql
# Endpoint auth headers (repeat --header)
python3 src/src/server.py --endpoint https://api.example.com/graphql --header "Authorization: Bearer $TOKEN"
# Options: --host 0.0.0.0 --port 9000 --log-level DEBUG --mount-path /myapp

ローカルエンドポイントテスト (リポジトリ内のサンプルサーバー):

# Terminal 1
python3 examples/graphql_test_server/server.py

# Terminal 2
python3 src/server.py --transport sse --endpoint http://127.0.0.1:4000/graphql

ツール:

• list_types(query, limit=5) – GraphQLフィールドノードに対する埋め込み類似度検索。結果はコサイン類似度スコアで返され、coordinates (Query からのパスステップの配列) に加え、Query フィールド用の query とネストされたオブジェクトフィールド用の select が含まれます。

• run_query(query) – --endpoint が設定されている場合、クエリをエンドポイントにプロキシします。設定されていない場合は、ローカルスキーマに対して検証/実行します (リゾルバーはありません。主に検証/形状チェック用であり、データはnullになります)。 インデックス化とクエリの両方で同じ埋め込みモデル (text-embedding-3-small がデフォルト。設定/環境変数または --model で上書き可能) を使用します。

ランキング (list_types):

• 結果は、インデックス化されたフィールドノードの検索テキストに対する埋め込みコサイン類似度によって純粋にランク付けされます。

list_types の出力例:

[
  {
    "field": "users",
    "summary": "Query.users(limit: Int) -> [User!]!",
    "coordinates": ["Query.users(limit: <Int>)"],
    "query": "query { users(limit: <Int>) { id name orders { id total status } } }"
  },
  {
    "type": "Order",
    "field": "total",
    "summary": "Order.total -> Float!",
    "coordinates": ["Query.user(id: <ID!>)", "User.orders", "Order.total"]
  },
  {
    "type": "User",
    "field": "orders",
    "summary": "User.orders -> [Order!]!",
    "coordinates": ["Query.user(id: <ID!>)", "User.orders"],
    "select": "orders { id total status }"
  }
]

注意:

• python3 src/server.py はデフォルトで sse トランスポートを使用します。HTTPを使用したい場合は --transport streamable-http を渡してください。

• FASTMCP_ をプレフィックスとする環境変数 (例: FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL) を設定してデフォルトを上書きすることもできます。

• サーバーは起動時にスキーマインデックスが構築されていることを確認します。埋め込みが計算されると、単純なプログレスバーが表示されます。バッチサイズを調整するには GRAPHQL_EMBED_BATCH_SIZE を設定してください。

• サーバーはMCP instructions ( MCP_INSTRUCTIONS で上書き可能) を公開します。これはサーバーを抽象化レイヤーとして記述し、LLMに対して list_types を使用してから最小限のツール呼び出しで run_query を使用するように指示します。

MCP Inspectorによるクイックテスト

PATHに npm/npx が必要です。

実行中のSSEサーバーに接続する

1つのターミナルで (サーバーを起動):

python3 src/server.py --transport sse --port 8000

別のターミナルで (Inspectorを起動し /sse を指定):

npx @modelcontextprotocol/inspector --transport sse --server-url http://127.0.0.1:8000/sse

Claude Desktop / CLIでの設定

このサーバーをSSE経由でローカルで実行している場合 (デフォルト)、Claudeに /sse URLを指定します。

claude mcp add --transport sse graphql-mcp http://127.0.0.1:8000/sse

JSON経由で設定することもできます (例: 設定ファイル):

{
  "mcpServers": {
    "graphql-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

このサーバーを認証の背後に公開する場合は、ヘッダーを渡します:

claude mcp add --transport sse private-graphql http://127.0.0.1:8000/sse \
  --header "Authorization: Bearer your-token-here"