高度な Hasura GraphQL MCP サーバー
バージョン: 1.1.0
このモデルコンテキストプロトコル（MCP）サーバーは、AIエージェント（CursorやClaude Desktopなど）がHasura GraphQLエンドポイントと対話するための高度なインターフェースを提供します。エージェントは、API構造の検出、読み取り専用クエリとミューテーション（注意して実行）、データのプレビュー、集計の実行、サービスの健全性チェックなどを行うことができます。
このサーバーは、自然言語のリクエストに基づいて Hasura API を動的に活用できるようにすることで、LLM 機能を強化します。
特徴
このサーバーは、次の MCP 機能を公開します。
リソース：
- Hasura GraphQL スキーマ (
hasura:/schema )- 標準のイントロスペクションによって取得された完全な GraphQL スキーマ定義を提供します。
- MIMEタイプ:
application/json - エージェントはこのリソースを読んで、型、フィールド、引数、ディレクティブなどを含む API の完全な構造を理解できます。
ツール:
run_graphql_query- 説明: Hasuraエンドポイントに対して読み取り専用のGraphQLクエリを実行します。特定のツールが利用できない場合にデータを取得するために使用します。クエリによってデータが変更されないようにしてください。例:
query { users { id name } } - 入力:
{ query: string, variables?: object } - 注:
mutationで始まる文字列の実行を防ぐための基本的なチェックを実行します。主にクエリ自体が読み取り専用であることを前提としています。
run_graphql_mutation- 説明: GraphQLミューテーションを実行して、データを挿入、更新、または削除します。操作が意図されたものであり、安全であることを確認した上で、慎重に使用してください。指定された管理者シークレットまたはデフォルトのロールに設定されたHasura権限に依存します。例:
mutation { insert_users_one(object: {name: "Test"}) { id } } - 入力:
{ mutation: string, variables?: object } - セキュリティ: Hasuraロールで許可されたすべての変更を許可します。適切なHasura権限が設定されていることを確認してください。
list_tables- 説明: Hasura によって管理されている利用可能なデータテーブル（またはコレクション）を、イントロスペクションヒューリスティック（内部/集約型を除く、「id」フィールドを持つオブジェクト型を検索）に基づいて、スキーマと説明ごとに整理して一覧表示します。利用可能なデータソースの検出に役立ちます。
- 入力:
{ schemaName?: string } (オプションのスキーマ名、可能な場合はフィールドの説明から推測を試みます。概念的にはデフォルトは「public」です)
describe_table- **説明:**特定のテーブルの構造を、そのすべての列 (フィールド) とその GraphQL タイプおよび説明とともに表示します。
- 入力:
{ tableName: string, schemaName?: string }
list_root_fields- 説明: GraphQLスキーマから利用可能な最上位レベルのクエリ、ミューテーション、またはサブスクリプションフィールドを一覧表示します。操作の主要なエントリポイントを理解するのに役立ちます。
- 入力:
{ fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } (オプションのフィルター)
describe_graphql_type- **説明:**スキーマイントロスペクションを用いて、特定のGraphQL型（オブジェクト、入力、スカラー、列挙型、インターフェース、ユニオン）の詳細を提供します。特定の型を含むクエリやミューテーションの構造化方法を理解する上で不可欠です。
- 入力:
{ typeName: string } (大文字と小文字を区別する型名)
preview_table_data- **説明:**指定されたテーブルから限られた行数（デフォルトは5行）のサンプルを取得し、そのデータ構造と内容をプレビューします。共通のスカラーフィールドと列挙型フィールドは自動的に選択されます。
- 入力:
{ tableName: string, limit?: number }
aggregate_data- **説明:**指定されたテーブルに対して、単純な集計（count、sum、avg、min、max）を実行します。オプションでHasuraの「where」フィルターを適用できます。テーブル名を検索するには「list_tables」を使用してください。count以外の集計には「field」が必要です。
- 入力:
{ tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }
health_check- **説明:**設定されたHasura GraphQLエンドポイントが到達可能であり、基本的なGraphQLクエリ(
{ __typename } )に応答するかどうかを確認します。オプションで、特定のHTTPヘルスエンドポイントURLがわかっている場合は、そのURLをチェックすることもできます。 - 入力:
{ healthEndpointUrl?: string } (オプションの特定のヘルス URL)
要件
- Node.js (v18 以上を推奨、指定されている場合は
.nvmrcまたはpackage.json enginesを確認してください) pnpm (またはnpm / yarn 、コマンドは適宜調整してください)- 実行中の Hasura GraphQL エンドポイントへのアクセス。
- (オプションですが推奨) 特権アクセス用の Hasura 管理者シークレット、または適切に構成されたデフォルトのロール権限。
セットアップとインストール
- リポジトリをクローンします (該当する場合)。
# git clone <repository_url>
# cd mcp-hasura-advanced
- 依存関係をインストールします:
- サーバーを構築する:これにより、TypeScript コードが
distディレクトリにコンパイルされます。
サーバーの実行
Hasura エンドポイント URL とオプションで管理者シークレットを指定して、ターミナルからコンパイルされたスクリプトを実行します。
# Using pnpm start script (defined in package.json)
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]
# Or using Node directly
node dist/index.js <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]
例：
pnpm start https://my-hasura.cloud/v1/graphql mysecretkey123
または
node dist/index.js https://my-hasura.cloud/v1/graphql mysecretkey123
管理者シークレットが必要ない場合（デフォルトのロール権限を使用）：
pnpm start https://my-hasura.cloud/v1/graphql
サーバーが起動し、初期のスキーマイントロスペクションを試行し、STDIOトランスポートに接続し、ステータスメッセージをstderrに記録します。stdin stdin MCP JSON-RPCリクエストをリッスンし、 stdoutに応答を送信します。
MCP クライアント (例: Cursor、Claude Desktop) での使用
このサーバーを Cursor などの MCP クライアントに接続するには:
- 絶対パスを見つける:
- ノード実行ファイル: ターミナルで
which nodeを実行します。 - サーバースクリプト:
mcp-hasura-advancedディレクトリに移動し、 pwdを実行します。結果に/dist/index.jsを追加します。 - プロジェクト ディレクトリ:
pwdの出力。
- **クライアントを構成する:**クライアントの構成ファイルを開きます (例: Cursor の場合は
settings.json 、Claude Desktop の場合はclaude_desktop_config.json )。 - **サーバー エントリの追加:**適切なキーの下にエントリを追加します (例: Cursor の場合は
cursor.customMcpServers配列、Claude Desktop の場合はmcpServersオブジェクト)。
カーソルsettings.json例.json:
{
// ... other settings ...
"cursor.customMcpServers": [
// ... other servers ...
{
"name": "My Advanced Hasura Server", // Name shown in Cursor UI
"command": "/path/to/your/node", // <<< Absolute path from 'which node'
"args": [
"/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to compiled script
"https://YOUR_HASURA_ENDPOINT.com/v1/graphql", // <<< Your endpoint
"YOUR_ADMIN_SECRET" // <<< Your secret (REMOVE if no secret)
],
// Optional but recommended for module resolution consistency:
"cwd": "/absolute/path/to/mcp-hasura-advanced" // <<< Absolute path to project root
}
]
}
Claude Desktop の例claude_desktop_config.json :
{
"mcpServers": {
// ... other servers ...
"hasura-advanced": { // Key used internally by Claude
"command": "/path/to/your/node", // <<< Absolute path from 'which node'
"args": [
"/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to compiled script
"https://YOUR_HASURA_ENDPOINT.com/v1/graphql", // <<< Your endpoint
"YOUR_ADMIN_SECRET" // <<< Your secret (REMOVE if no secret)
],
// Optional:
// "cwd": "/absolute/path/to/mcp-hasura-advanced"
}
}
}
- **プレースホルダーの置き換え:**すべてのプレースホルダー (
/path/to/... 、 https://YOUR... 、 YOUR_ADMIN_SECRET ) を実際の値に更新します。 - **クライアントの再起動/リロード:**構成を保存し、MCP クライアント アプリケーションを再起動またはリロードします。
- **サーバーの選択:**クライアントの UI で「My Advanced Hasura Server」(または指定した名前) を選択します。
- **対話:**クライアントのチャットで自然言語プロンプトを使用して、サーバーのツールを活用します (例: 「Hasura サーバーを使用してテーブルを一覧表示する」、「「users」テーブルについて説明する」、「「orders」テーブルからデータをプレビューする」、「Hasura サーバーを使用してクエリ
{ products { name price } }を実行する」)。
発達
- 開発モードで実行:
pnpm run dev <ENDPOINT> [SECRET]を使用して、 ts-nodeでサーバーを直接実行し、反復処理を高速化します (ビルド ステップは不要)。 - **テスト:**サーバーを手動で実行し (
pnpm start ... )、JSON-RPC リクエストをstdinにパイプして、個々のツールをテストします。