mcp-graphql-enhanced

LLMとGraphQL API間の現実的な相互運用性の問題を解決する、拡張版MCP (Model Context Protocol) サーバーです。

mcp-graphql のドロップイン代替品であり、動的ヘッダー、堅牢な変数解析を備え、破壊的変更は一切ありません。

💬 コミュニティとサポート

会話に参加しましょう！Neo4j、Discordデータグラフ、または一般的なGraphQLでこのブリッジを使用することについて質問がある場合は、ぜひお越しください：

• Discordチャンネル: #mcp-graphql-enhanced

• サーバー: 公式 GraphQL Discord

フィードバックの共有、問題の報告、またはブリッジに対する新しい「拡張」機能の提案に最適な場所です。

Related MCP server: mcp-graphql-schema

✨ 主な拡張機能

• ✅ 組み込みGraphiQL IDE — http://localhost:MCP_PORT/ (または /graphiql) で利用可能な、ヘッダー設定済みのビジュアルプレイグラウンド。

• ✅ デュアルトランスポート — STDIO (ローカルCLI/クライアントツール用) と HTTP/JSON-RPC (外部/ブラウザクライアント用) の両方をサポート。

• ✅ 動的ヘッダー — ツール引数経由で Authorization、X-API-Key などを渡せます (設定の再起動は不要)

• ✅ 堅牢な変数解析 — “Query variables must be a null or an object” エラーを修正

• ✅ フィルタリングされたイントロスペクション — 特定の型のみをリクエスト可能 (例: typeNames: ["Query", "User"]) で、LLMのコンテキストノイズを低減

• ✅ 完全なMCP互換性 — Claude Desktop、Cursor、Glama で動作

• ✅ デフォルトでセキュア — 明示的に有効にしない限り、ミューテーションは無効

• ✅ 動的スキーマ進化 — (Neo4jのように) GraphQL型をオンザフライで再生成するサーバー向けのスマートな診断とギャップ分析。

• ✅ 詳細な可観測性 — GraphQL拡張からのCypher抽出とクリーニングを自動化。

🚀 マルチエンドポイントブロードキャスト (v3.9.0+ で試験的導入)

v3.9.0 から、サーバーは複数のGraphQLエンドポイントへの同時クエリをサポートしています。これは元々、異なる環境 (Node.jsやPythonのバックエンドなど) 間でミューテーションを同期するために設計されましたが、データ集約のための強力な可能性を切り開きます。

• 破壊的変更なし: ENDPOINT に単一のURLを指定した場合、サーバーは以前と全く同じように動作します。

• スマート集約: カンマ区切りで複数のURLが指定されると、サーバーはすべてのエンドポイントにクエリをブロードキャストし、結果の配列をマージします。

• 無料枠制限の回避: 「無料枠」のクラウドデータベース (Neo4j Auraなど) のユーザーに最適です。データを複数の無料インスタンスに分割し、このブリッジを使用してそれらを単一の統合グラフとしてクエリすることで、実質的にエンティティ数の制限を回避できます。

• 重複排除: ブリッジは一意のフィールドに基づいて重複オブジェクトを自動的に削除し、AIのコンテキストウィンドウをクリーンに保ちます。

⚠️ 自己責任で使用してください: この機能は、すべてのエンドポイントが同一 (または非常に類似した) GraphQLスキーマを共有していることを前提としています。イントロスペクションはリストの最初のエンドポイントに対して実行されます。

💡 ユースケース: WSLとWindows (PowerShell) のブリッジ

Windows開発者にとって共通の課題は、Windows Subsystem for Linux (WSL) とホストOS間のネットワーク分離です。この機能により、これら2つの世界を「統合神経系」にブリッジできます。

Claude Desktopの設定例:

{
  "ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
}

• ハイブリッドエコシステム: Windowsネイティブプロセス (PowerShell) とLinuxベース環境 (WSL) 間でシームレスにデータをクエリおよび集約します。

• mDNSサポート: .localアドレスを使用することで、ブリッジはWSL環境内からホストマシンのIPを自動的に解決します。

• 透過的な集約: AIアシスタントは、データが異なるオペレーティングシステムから同時に取得されていることを意識せず、単一の統合スキーマと対話します。

🔍 高度な可観測性とCypher

このブリッジは、LLMがグラフデータベースとどのように対話するかについての深い洞察を提供します。

🕸️ 自動Cypher抽出

クエリ実行プランを返すGraphQLサーバー実装 (例: @neo4j/graphql) に対して、ブリッジは自動的に以下を行います:

1. レスポンス内の extensions.cypher を検出します。

2. 内部ヘッダー (例: CYPHER 5 や空の PARAMS) を取り除いて出力をサニタイズします。

3. AIが分析できるように、クリーンなCypherブロックをツールの出力に直接注入します。

注: この機能を使用するには、GraphQLサーバーがレスポンス拡張にデバッグ情報を含めるように設定されている必要があります。

🎨 ビジュアルコマンドセンター (GraphiQL)

標準的なMCPサーバーとは異なり、本サーバーは人間用の視覚的インターフェースを提供します。ENABLE_HTTP=true で実行すると、ブラウザでフル機能の GraphiQL IDE を開くことができます。

• エンドポイント: http://localhost:6274/ (または /graphiql)

• ヘッダー同期: 環境で設定されたヘッダー (GitHubトークンなど) は、即座にテストできるようにGraphiQLの「Headers」タブに自動的に注入されます。

💻 HTTP / デュアルトランスポート

このサーバーは現在デュアルトランスポートモードで動作し、標準の STDIO 通信 (ほとんどのMCPクライアントで使用) と、ポート 6274 での新しい HTTP JSON-RPC エンドポイントの両方をサポートしています。

これにより、外部システム、Webアプリケーション、および直接の curl コマンドが、ターミナルでのライブリクエストログ ([HTTP-RPC] ログ) を伴ってサーバーのツールにアクセスできるようになります。

自動ポート選択

サーバーはデフォルトでポート 6274 を使用します。EADDRINUSE エラーが発生した場合、サーバーは自動的に次に利用可能なポートを見つけます。最終的にバインドされたポートについてはサーバーログを確認してください (例: [HTTP] Started server on http://localhost:6275)。

ポート競合 (EADDRINUSE) の解決と自動ポート選択

サーバーはデフォルトでポート 6274 を使用します。EADDRINUSE: address already in use :::6274 エラー (古いプロセスが残っているためローカル開発でよく発生します) が発生した場合、サーバーは自動的に次に利用可能なポートを見つけます (最大10回試行、複数のサーバーを起動することはありません)。

これにより、デフォルトがブロックされている場合でもサーバーは正常に起動します。curl やクライアントツールがデフォルトの 6274 で失敗した場合は、常にサーバーログで最終的にバインドされたポートを確認してください (例: [HTTP] Started server on http://localhost:6275)。

特定のポートを強制する場合 (例: 外部ファイアウォールの設定を保証するため) は、引き続き MCP_PORT 環境変数を明示的に設定できます:

HTTPエンドポイントのテスト

サーバーが実行中であれば (例: npm run dev 経由)、curl を使用してエンドポイントをテストできます:

# Test the health check (assuming the server bound to the default or found the next available port)
curl http://localhost:6274/health

# Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'

## 🔍 Filtered Introspection
Avoid 50k-line schema dumps. Ask for only what you need:
`@introspect-schema typeNames ["Query", "User"]`
## 🔍 Debug & Inspect
Use the official MCP Inspector to test your server live:
```bash
npx @modelcontextprotocol/inspector \
  -e ENDPOINT=https://api.example.com/graphql \
  npx @letoribo/mcp-graphql-enhanced

環境変数 (1.0.0での破壊的変更)

注: バージョン1.0.0より、コマンドライン引数は環境変数に置き換えられました。

• auto (デフォルト): MCP Inspectorで実行されている場合のみ自動的にHTTPを有効にします...

• true: 常にHTTPサーバーを有効にする

• false: HTTPサーバーを完全に無効にする

例

# Basic usage
ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
# With auth header
ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced
# Enable mutations
ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced
# Use local schema file
ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced
# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
# Disable HTTP transport (fastest, recommended for Claude Desktop)
ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
# Test the surgical precision and the IDE immediately:
ENDPOINT=https://api.github.com/graphql \
HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
ENABLE_HTTP=true \
npx @letoribo/mcp-graphql-enhanced

# Then visit http://localhost:6274/graphiql

🖥️ Claude Desktop設定例

npxパッケージ (シンプルさのために推奨) またはDockerイメージ (再現性と分離のために理想的) のいずれかを使用して、Claude DesktopをGraphQL APIに接続できます。

✅ オプション1: npxを使用する

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "npx",
      "args": ["@letoribo/mcp-graphql-enhanced"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql"
      }
    }
  }
}

🐳 オプション2: Dockerを使用する (自動プル対応)

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "sh",
      "args": [
        "-c",
        "docker run --rm -i -e ENDPOINT=$ENDPOINT -e HEADERS=$HEADERS -e ALLOW_MUTATIONS=$ALLOW_MUTATIONS ghcr.io/letoribo/mcp-graphql-enhanced:main"
      ],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "HEADERS": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",
        "ALLOW_MUTATIONS": "false"
      }
    }
  }
}

🧪 オプション3: ローカルビルドでnodeを使用する (開発用)

リポジトリをクローンしてプロジェクトをビルドした場合 (npm run build → dist/ に出力):

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

リソース

• graphql-schema: サーバーはGraphQLスキーマをクライアントがアクセス可能なリソースとして公開します。これは、ローカルスキーマファイル、URLでホストされているスキーマファイル、またはイントロスペクションクエリに基づいています。

利用可能なツール

サーバーは2つの主要なツールを提供します:

1. introspect-schema: このツールは、GraphQLスキーマまたはフィルタリングされたサブセット (typeNames経由) を取得します。スキーマにリソースとしてアクセスできない場合は、まずこれを使用してください。 これは、ローカルスキーマファイル、URLでホストされているスキーマファイル、またはイントロスペクションクエリのいずれかを使用します。 フィルタリングされたイントロスペクション (typeNames) は、ライブGraphQLエンドポイントを使用している場合にのみ利用可能です (SCHEMAファイルやURLでは利用できません)。

2. query-graphql: エンドポイントに対してGraphQLクエリを実行します。デフォルトでは、ALLOW_MUTATIONS が true に設定されていない限り、ミューテーションは無効です。

セキュリティに関する考慮事項

意図しないデータ変更を防ぐため、ミューテーションはデフォルトで無効になっています。本番環境では常にHEADERSとSCHEMAの入力を検証してください。可能な限りHTTPSエンドポイントと短命トークンを使用してください。

独自のサーバー用にカスタマイズする

これは非常に汎用的な実装であり、完全なイントロスペクションを可能にし、ユーザーが (ミューテーションを含む) 何でもできるようにしています。より具体的な実装が必要な場合は、独自のMCPを作成し、クライアントが特定のクエリフィールドや変数のみを入力できるようにツール呼び出しを制限することをお勧めします。これをリファレンスとして使用できます。