PuppyGraph MCP Server

PuppyGraph MCP サーバー

PuppyGraph 用の Model Context Protocol（MCP）サーバーです。Claude Code、Claude Desktop、Cursor などの AI エージェントが PuppyGraph をデータに接続し、グラフスキーマを構築して、Cypher または Gremlin でグラフをクエリできるようにします。

npx -y @puppygraph/mcp-server

ツール

ツール	機能
puppygraph_query	Cypher または Gremlin クエリを実行し、行、PuppyGraph のクエリ警告、および失敗時には PuppyGraph のエラーメッセージを返します
puppygraph_schema	グラフスキーマ（ノードとエッジのラベル、属性）を返します。大きなスキーマの場合は構造のみを返します
puppygraph_status	接続状態と読み取り専用モードが有効かどうかを報告します

この3つのツールはそれぞれ、LLM プラットフォームによっては互換性のために mcp__ プレフィックス付き（例：mcp__puppygraph_query）でも利用できます。

空の PuppyGraph からクエリ可能なグラフを作成するためのセットアップツールです。PuppyGraph のウェブ UI にある AI アシスタントでできることに対応しています。

ツール	機能
puppygraph_guide	これらのツールの使い方を説明します。グラフのクエリまたは構築手順、および正しいキー、型、エッジのルールを確認できます
puppygraph_catalog_spec	サポートされているカタログの種類と、各種類の接続フィールド（正確な名前付き）を返します
puppygraph_list_catalogs	登録済みデータソース（カタログ）を一覧表示します。認証情報はマスキングされます
puppygraph_create_catalog	データソース（データベース、ウェアハウス、レイク、または DuckDB ファイル）をカタログとして登録します
puppygraph_test_catalog	PuppyGraph がカタログ経由でデータを読み取れるか確認します
puppygraph_list_tables	カタログのデータベース、またはその中のテーブルを一覧表示します
puppygraph_describe_table	テーブルの列と PuppyGraph の型を一覧表示します
puppygraph_sample_table	テーブルから数行を返します
puppygraph_profile_column	列のプロファイルを取得します。NULL 件数と一意な値の件数、および ID にできるか、別のテーブルを参照しているかを確認します
puppygraph_table_row_count	テーブルの行数を数えます
puppygraph_check_join	データを調べ、ある列の値が別のテーブルの列にいくつ存在するかを確認します
puppygraph_schema_template	注釈付きの 1.x グラフスキーマの例を返します
puppygraph_validate_schema	スキーマを変更せずにドライランします。構造、テーブルと列の存在、各型とソース列の型の一致、およびエッジキーと接続先ノードの ID の一致を確認します
puppygraph_upload_schema	スキーマ全体をインストールします。インストール済みスキーマを置き換えるには replace: true が必要です
puppygraph_search_schema	キーワードでインストール済みスキーマのノード型とエッジ型を検索します
puppygraph_get_schema_element	1つのノードまたはエッジについて、ID、属性、ソーステーブル、キー、Cypher で使用する関係ラベルを表示します
puppygraph_add_node、puppygraph_update_node、puppygraph_remove_node	インストール済みスキーマのノード型を1つ変更します
puppygraph_add_edge、puppygraph_update_edge、puppygraph_remove_edge	インストール済みスキーマのエッジ型を1つ変更します
puppygraph_add_node_attribute、puppygraph_add_edge_attribute	ノード型またはエッジ型に属性を1つ追加します
puppygraph_check_edges	インストール済みグラフとそのデータを照合します。エッジ型ごとに、既存の始点ノードと終点ノードに到達する行数、およびノード ID が一意かどうかを確認します

puppygraph_create_catalog、puppygraph_upload_schema、および追加・更新・削除ツールは PuppyGraph を変更するため、読み取り専用モードでは利用できません。セットアップツールには PuppyGraph 1.x が必要で、ポート 8081 の HTTP API を使用します。

スキーマを要素ごとに構築する

追加／更新／削除ツールは、インストール済みスキーマのノードまたはエッジを1つ変更し、それ以外はそのままにします。これは、PuppyGraph の Web UI にある AI アシスタントと同様です。PuppyGraph は変更内容を自身の UI にのみ反映するため、MCP サーバーはインストール済みのスキーマを読み取り、要素を変更して検証し（列、型、キー）、スキーマ全体をアップロードします。その間にインストール済みのスキーマが変更された場合は処理を拒否し、要素に問題がある場合は何も変更しません。

グラフの確認

グラフは有効でも、内容が正しいとは限りません。誤った列での結合、逆向きのエッジ、または一意でないノード ID でも、エラーなくアップロードされます。puppygraph_check_edges は、各エッジタイプについてエッジ行数と、既存のソースノードおよびターゲットノードに到達する行数を数え、各ノードタイプの行数と一意な ID の数を比較します。これはすべての PuppyGraph 1.x で動作し、データを調べる権限は必要ありません。アップロード後、スキーマツールは新しいラベルが応答するまで数秒待機します。PuppyGraph はアップロード後の最初のクエリに対し、0 行を返すことがあるためです。

PuppyGraph に接続できない場合、ツールはエラーを返します。架空のデータを返すことはありません。

データの調査

puppygraph_sample_table、puppygraph_profile_column、puppygraph_table_row_count、puppygraph_check_join はソーステーブルを読み取るため、エージェントは列名だけでなく、データに基づいて ID とエッジを選べます。これらは PuppyGraph Web UI の AI アシスタントが使用するものと同じ調査機能であり、1.14 より新しい PuppyGraph リリースが必要です。それより古いバージョンでは error_type: "NOT_SUPPORTED" を返し、エージェントは列名と型を使って処理を続け、キーと結合が未検証であることを伝える必要があります。

• サンプル行、サンプル値、最小値／最大値は、エージェントのモデルとの会話に含まれます。
• PuppyGraph ユーザーには DATA:read 権限が必要です。
• 行レベルセキュリティが設定されたグラフで使用するカタログでは、フィルターを適用せずにテーブルを読み取るため、調査できるのは管理者のみです。
• PuppyGraph サーバーは、件数のみを返すように設定できます。その場合、puppygraph_sample_table は拒否され、その他の調査ツールは値を返さずに件数を返します。

これらのツールは読み取りのみを行うため、読み取り専用モードでも利用できます。

同じガイドは puppygraph_guide ツール、読み取り専用リソース puppygraph://guide、および短縮版としてサーバーの MCP instructions からも利用できます。puppygraph://schema は現在のグラフスキーマです。リソースや説明を参照しないクライアントもあるため、ツールの説明では puppygraph_guide も案内しています。

データの接続

• データベース（PostgreSQL、MySQL、SQL Server、Oracle など）：jdbc_uri、username、password_env を指定します。PuppyGraph には MySQL ドライバーが同梱されていないため、driver_url を渡してください（ツールは Maven Central にある公式コネクターを提示します）。MySQL 8 では通常、URI に ?allowPublicKeyRetrieval=true&useSSL=false も必要です。
• データレイクとデータウェアハウス（Iceberg、Delta Lake、Hive、Hudi、BigQuery、Snowflake key pair、Databricks など）：各フィールド名は PuppyGraph のカタログフォームと同じです。puppygraph_catalog_spec でタイプごとのフィールドを確認でき、puppygraph_create_catalog は接続前に options がそれらのフィールドと一致するか確認します。フォーム定義は PuppyGraph のソースから同梱されます。次のコマンドで再生成できます：node scripts/update-catalog-spec.mjs <puppygraph>/frontend/control/chat/catalogform/definition.json。
• CSV ファイルと Parquet ファイル：DuckDB ファイル内にこれらのファイルを参照するテーブルまたはビューを作成し、PuppyGraph コンテナーにマウントして、jdbc:duckdb:/path/in/container.duckdb を指定し、タイプ duckdb として登録します。S3 上のファイルには、Iceberg、Delta Lake、または Hive のカタログを使用してください。DuckDB の S3 設定はファイルに保存されないため、DuckDB 経由のクエリは失敗します。
• よくある接続エラーには hint が含まれ、該当する場合は suggested_jdbc_uri または suggested_driver_url も返されます。PuppyGraph の起動中、ツールは error_type: "STARTING" を返します。

クイックスタート

1. PuppyGraph を起動します（Docker）：

   docker run -d --name puppy --pull=always \
     -p 8081:8081 -p 8182:8182 -p 7687:7687 \
     -e PUPPYGRAPH_PASSWORD=puppygraph123 \
     --add-host=host.docker.internal:host-gateway \
     puppygraph/puppygraph:latest
   

2. MCP サーバーをクライアントに追加します（下記を参照）。PuppyGraph が localhost でデフォルトの認証情報を使用している場合、設定は不要です。

3. エージェントにデータからグラフを構築するよう依頼します。たとえば、「PuppyGraph を使って、jdbc:postgresql://db:5432/shop の Postgres に接続し、同じ決済カードを共有する顧客を見つけてください」や、スキーマがすでに読み込まれている場合は、「PuppyGraph のグラフには何がありますか？」と尋ねます。

   PuppyGraph はデータベースに直接接続するため、JDBC URI には PuppyGraph コンテナから到達可能なアドレスを指定する必要があります（たとえば、マシン上のデータベースには localhost ではなく host.docker.internal を使います。上記の --add-host フラグにより、Linux でもその名前を使えます）。エージェントがそれでも localhost を使うと、puppygraph_create_catalog は error_type: HOST_UNREACHABLE_FROM_PUPPYGRAPH、ヒント、および再試行用の suggested_jdbc_uri を返して失敗します。http://localhost:8081 のウェブ UI からデータを接続し、スキーマを構築することもできます（puppygraph / puppygraph123 でサインインしてください）。PuppyGraph のドキュメントを参照してください。

Node.js 20 以降が必要です。

クライアントの設定

Claude Code

claude mcp add puppygraph -- npx -y @puppygraph/mcp-server

リモートの PuppyGraph やその他の認証情報を使用する場合は、-e で環境変数を渡します。

claude mcp add puppygraph \
  -e PUPPYGRAPH_URL=bolt://puppygraph.example.com:7687 \
  -e PUPPYGRAPH_GREMLIN_URL=ws://puppygraph.example.com:8182/gremlin \
  -e PUPPYGRAPH_SCHEMA_URL=http://puppygraph.example.com:8081/schemajson \
  -e PUPPYGRAPH_PASSWORD=your-password \
  -e PUPPYGRAPH_GREMLIN_PASSWORD=your-password \
  -e PUPPYGRAPH_SCHEMA_PASSWORD=your-password \
  -- npx -y @puppygraph/mcp-server

すべてのプロジェクトで使用できるようにするには、--scope user を追加します。

Claude Desktop

claude_desktop_config.json を編集し（設定 → 開発者 → 設定を編集）、Claude Desktop を再起動します。

{
  "mcpServers": {
    "puppygraph": {
      "command": "npx",
      "args": ["-y", "@puppygraph/mcp-server"],
      "env": {
        "PUPPYGRAPH_URL": "bolt://localhost:7687"
      }
    }
  }
}

env ブロックは省略可能です。ここに環境変数を追加してください。

Cursor

サーバーを ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加します。

{
  "mcpServers": {
    "puppygraph": {
      "command": "npx",
      "args": ["-y", "@puppygraph/mcp-server"]
    }
  }
}

VS Code（GitHub Copilot）

サーバーを .vscode/mcp.json に追加します。

{
  "servers": {
    "puppygraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@puppygraph/mcp-server"]
    }
  }
}

その他の MCP クライアント

stdio MCP サーバーを起動できるクライアントであれば使用できます。コマンドは npx、引数は -y @puppygraph/mcp-server で、設定は環境変数に指定します。Windsurf、Cline などのクライアントでは、Claude Desktop と同じ mcpServers JSON 構造を使用します。

設定

すべての設定は環境変数で指定します。デフォルト値はローカルの PuppyGraph コンテナに対応しています。

変数	デフォルト	説明
PUPPYGRAPH_URL	bolt://localhost:7687	Cypher 用の Bolt エンドポイント
PUPPYGRAPH_USERNAME	puppygraph	Bolt のユーザー名
PUPPYGRAPH_PASSWORD	puppygraph123	Bolt のパスワード
PUPPYGRAPH_DATABASE	(空)	Bolt のデータベース名
PUPPYGRAPH_GREMLIN_URL	ws://localhost:8182/gremlin	Gremlin WebSocket エンドポイント
PUPPYGRAPH_GREMLIN_USERNAME	puppygraph	Gremlin のユーザー名
PUPPYGRAPH_GREMLIN_PASSWORD	puppygraph123	Gremlin のパスワード
PUPPYGRAPH_GREMLIN_TRAVERSAL_SOURCE	g	Gremlin のトラバーサルソース
PUPPYGRAPH_SCHEMA_URL	http://localhost:8081/schemajson	スキーマエンドポイント
PUPPYGRAPH_SCHEMA_USERNAME	puppygraph	スキーマエンドポイントのユーザー名
PUPPYGRAPH_SCHEMA_PASSWORD	puppygraph123	スキーマエンドポイントのパスワード。セットアップツールでも使用されます
PUPPYGRAPH_HTTP_URL	PUPPYGRAPH_SCHEMA_URL のオリジン	セットアップツールが使用する PuppyGraph HTTP API
PUPPYGRAPH_MCP_SECRET_ENV_ALLOWLIST	(空)	password_env / secret_env が読み取れる追加の変数名（データソースの認証情報を参照）
PUPPYGRAPH_READ_ONLY	false	書き込みクエリを拒否します（下記を参照）

PuppyGraph のパスワードを変更した場合は、3 つすべてのエンドポイントに設定してください（PUPPYGRAPH_PASSWORD、PUPPYGRAPH_GREMLIN_PASSWORD、PUPPYGRAPH_SCHEMA_PASSWORD）。

読み取り専用モード

デフォルトでは書き込みが許可されています。たとえば本番環境へのデプロイ時に、エージェントによるデータの変更を防ぐには、PUPPYGRAPH_READ_ONLY=true または --read-only フラグを使って読み取り専用モードを有効にします。

claude mcp add puppygraph -- npx -y @puppygraph/mcp-server --read-only

読み取り専用モードでは、puppygraph_query は、PuppyGraph に到達する前に、CREATE、MERGE、DELETE、SET、REMOVE、DROP、LOAD CSV、FOREACH を使う Cypher クエリと、addV、addE、mergeV、mergeE、property、drop、io、addVertex、addEdge、remove を使う Gremlin クエリを拒否します。エージェントには、対象の操作名を含む error_type: "READ_ONLY" のエラーが返されます。文字列やコメント内のキーワードは無視されます。クエリツールの説明と puppygraph_status（read_only: true）によって、エージェントはこのモードが有効であることを確認できます。

読み取り専用モードでは、puppygraph_create_catalog、puppygraph_upload_schema、およびスキーマの追加／更新／削除ツールはエージェントに提供されず（呼び出された場合も拒否されます）。その他のセットアップツールは読み取りのみを行うため、引き続き利用できます。

読み取り専用モードはエージェント向けのガードであり、アクセス制御ではありません。読み取り専用アクセスを強制するには、PuppyGraph のアクセス制御を使用し、書き込み権限のないユーザーとして接続してください。

データソースの認証情報

セットアップツールはデータソースのパスワードを返したり、ログに記録したりすることはありません。レスポンスでは認証情報のフィールドが ****** でマスクされ、エラーメッセージからは送信されたパスワードが除去されます。パスワードを会話に一切含めないようにするには、MCP サーバーの環境変数に設定し、エージェントには変数名のみを渡させてください（password_env、その他のシークレットには secret_env）。エージェントが変数名を選ぶため、サーバーの別のシークレットをデータベースに渡すのを防ぐには、次の変数のみ使用できるようにします。PUPPYGRAPH_SECRET_ で始まる名前、および PUPPYGRAPH_MCP_SECRET_ENV_ALLOWLIST に列挙した名前（カンマ区切りの完全一致）。それ以外の名前は拒否されます。

claude mcp add puppygraph -e PUPPYGRAPH_SECRET_PG_PASSWORD=... -- npx -y @puppygraph/mcp-server

次のように指示します。「ユーザー app として jdbc:postgresql://db:5432/shop 用の PuppyGraph カタログを作成し、パスワードには PUPPYGRAPH_SECRET_PG_PASSWORD を使用してください。」

スキーマの置き換え

puppygraph_upload_schema は、まずスキーマを検証し、次に PuppyGraph に対して、変更を加える前にマッピングされたすべてのテーブルとカラムを確認するよう依頼します。そのため、アップロードに失敗しても、インストール済みのスキーマはそのまま維持されます。すでにスキーマがインストールされている場合、エージェントが replace: true を渡さない限り、アップロードは拒否されます。拒否時には、インストール済みのバージョンとラベルが示されます。PuppyGraph は以前のバージョンをスキーマ履歴に保持します。

トラブルシューティング

• エージェントに puppygraph_status を呼び出すよう指示してください。サーバーが接続されているかどうか、接続されていない場合は原因が認証か接続かを確認できます。
• サーバーは stderr にログを出力します（MCP プロトコルを伝送する stdout には出力しません）。Claude Desktop はログを MCP のログファイルに書き込みます。
• PuppyGraph が別のホストや、クライアントから localhost として到達できないコンテナ内で実行されている場合は、3 つの URL 変数をクライアントが到達できるアドレスに設定してください。
• Gremlin の URL は ws:// または wss:// で始まる必要があります。
• Cypher と Gremlin は個別に接続します。一方が失敗しても、もう一方の言語は引き続き利用できます。

開発

git clone https://github.com/puppygraph/puppygraph-mcp-server.git
cd puppygraph-mcp-server
npm install        # also builds build/ through the prepare script
npm test           # unit and integration tests (mocked, no PuppyGraph needed)
npm run build
node build/index.js

クライアントでローカルのチェックアウトを使うには、npx -y @puppygraph/mcp-server を node /path/to/puppygraph-mcp-server/build/index.js に置き換えてください。

ライブテストでは、ビルド済みサーバーを実際の PuppyGraph に接続して実行します。

PUPPYGRAPH_LIVE_TEST=true npm run test:live

セットアップツールには独自のライブテストがあります。このテストではカタログを作成し、インストール済みのスキーマを置き換えるため、使い捨ての PuppyGraph に対してのみ実行してください。tests/live/fixtures/setup.sql を PuppyGraph から接続できる PostgreSQL データベースに読み込んでから、次を実行します。

PUPPYGRAPH_LIVE_SETUP_TEST=true \
PUPPYGRAPH_LIVE_JDBC_URI=jdbc:postgresql://<host>:5432/<db> \
PUPPYGRAPH_LIVE_JDBC_USER=<user> PUPPYGRAPH_LIVE_JDBC_PASSWORD=<password> \
npm run test:live

ユーザーに配布されるパッケージをテストするには、npm pack を実行して tarball をインストールするか、Verdaccio などのローカルレジストリに公開し、そのパッケージに対して npx -y @puppygraph/mcp-server を実行してください。

公開

メンテナーは npm に手動で公開します。RELEASING.md を参照してください。

ライセンス

Apache 2.0