AGE-MCP-Server

AGE MCP サーバー

PostgreSQL 内の Apache AGE グラフをクエリする MCP サーバーです。

バージョン 0.3.0 では、読み取り専用操作をセキュアなデフォルトにし、非同期接続プーリング、安全な Cypher パラメーター、上限付きカーソルページネーションを追加し、すべてのツールから MCP の構造化コンテンツを返すようになりました。

要件

• Python 3.13 以降
• Apache AGE 拡張機能がインストールされ、読み込まれている PostgreSQL
• MCP クライアントが必要とするグラフと操作に制限されたデータベースロール

対象データベースで AGE を有効にします。

CREATE EXTENSION IF NOT EXISTS age CASCADE;

インストール

uv を使用する場合：

uv init your_project
cd your_project
uv add age_mcp_server

Python 仮想環境を使用する場合：

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install age_mcp_server

Homebrew を使用する場合：

brew install rioriost/tap/age_mcp_server

MCP クライアントの設定

データベースのパスワードをコマンドライン引数に含めないでください。PG_CONNECTION_STRING を通じて接続文字列を渡し、PGPASSWORD や保護された PostgreSQL パスワードファイルなど、libpq の認証情報メカニズムを使用してください。

{
  "mcpServers": {
    "age_manager": {
      "command": "age_mcp_server",
      "env": {
        "PG_CONNECTION_STRING": "host=db.example port=5432 dbname=postgres user=age_reader sslmode=require",
        "PGPASSWORD": "replace-with-a-secret"
      }
    }
  }
}

PGPASSWORD が含まれている場合は、MCP クライアントの設定をシークレットとして扱ってください。PostgreSQL パスワードファイルまたはクライアントのシークレットストアを使用することをおすすめします。

必要に応じて、接続文字列を明示的に指定することもできます。

age_mcp_server --pg-con-str "host=db.example dbname=postgres user=age_reader sslmode=require"

Azure Database for PostgreSQL で Microsoft Entra 認証を行うには、最初に Azure CLI でサインインし、その後トークン取得を有効にします。

age_mcp_server \
  --pg-con-str "host=server.postgres.database.azure.com dbname=postgres user=identity sslmode=require" \
  --azure-identity

ツール

読み取り専用モードがデフォルトです。

ツール	用途
read-age-cypher	検証済みのパラメーター化された読み取り専用 Cypher クエリを実行し、ページネーションします
list-age-graphs	Apache AGE のグラフを一覧表示します
get-age-schema	件数、方向、サンプリングしたプロパティ型を調べます

書き込みツールは、サーバーの起動時に --allow-write を指定した場合のみ公開され、受け付けられます。

ツール	用途
write-age-cypher	変更を伴う句を含む Cypher を実行します
create-age-graph	グラフを作成します
drop-age-graph	グラフを完全に削除します

age_mcp_server --allow-write

書き込みモードには、権限を必要最小限に絞った別のデータベースロールを使用してください。このフラグを有効にしても、設定されたロールにすでに付与されていない PostgreSQL 権限が付与されることはありません。

安全性の上限

• Cypher、グラフ名、戻り値のエイリアス、グラフ管理の引数は、安全に引用符で囲むかパラメーター化してから PostgreSQL に渡されます。
• 読み取りツールは PostgreSQL の読み取り専用トランザクション内で実行されます。
• CALL は副作用があるものと見なされ、書き込みモードが必要です。
• 読み取りページの行数は最大 50 行です。不透明な HMAC 認証カーソルはグラフ、クエリ、パラメーターに紐付けられ、オフセットの上限は 100,000 です。
• Cypher の $parameters は、プレースホルダー名が JSON パラメーターオブジェクトと完全に一致する場合のみ受け付けられます。オブジェクトの上限は 100,000 バイトで、準備済みステートメントを通じて AGE に渡されます。
• 書き込みクエリは最後まで実行され、結果行の代わりに影響を受けた行数を返します。
• ステートメントはデフォルトで 30 秒後にタイムアウトします。
• クエリの長さは 100,000 文字までで、各クエリ分岐に明示的な RETURN 句が 1 つ含まれている必要があります。
• 生のデータベースエラー、クエリ内容、接続認証情報が MCP クライアントに返されることも、通常のログに書き込まれることもありません。

必要に応じてタイムアウトを変更します。

age_mcp_server --statement-timeout-ms 60000

タイムアウトは 1 ミリ秒以上 1 時間以下である必要があります。

非同期接続プールを調整するか、新しく開かれるプール接続ごとに AGE ライブラリを読み込みます。

age_mcp_server --pool-min-size 2 --pool-max-size 8 --load-age

プールは 1 <= min <= max <= 64 を満たす必要があります。RETURN * は引き続きサポートされません。Apache AGE の SQL 結果型を宣言できるように、戻り値を明示的に列挙してください。

パラメーターとページネーションを使用するツール入力の例：

{
  "graph_name": "people",
  "query": "MATCH (n:Person) WHERE n.age >= $minimum RETURN n.name AS name ORDER BY name",
  "parameters": {"minimum": 18},
  "page_size": 25
}

次のページを取得するには、返された nextCursor を cursor として渡します。

OpenTelemetry

オプションのエクスポーター依存関係をインストールし、OTLP エクスポートを有効にします。

python3 -m pip install "age_mcp_server[telemetry]"
age_mcp_server --enable-telemetry --otel-service-name age-production

エクスポーターは、標準の OTEL_EXPORTER_OTLP_* 環境変数に従います。 トレースとメトリクスには、操作のレイテンシー、件数、失敗が記録されます。接続の詳細、Cypher テキスト、パラメーター値、生のデータベースエラーは除外されます。

開発

すべての開発用依存関係をインストールし、リリースゲートを実行します。

make sync
make check

make check は Ruff、カバレッジ 80% のゲート、Bandit、ロックされた依存関係の監査、パッケージのビルドを実行します。テストスイートには、Apache AGE を実際に使用する統合テストが含まれます。

AGE_TEST_CONNECTION_STRING="host=127.0.0.1 dbname=postgres user=postgres password=postgres" \
  make integration

CI では、公式の Apache AGE PostgreSQL コンテナーを使用してこのテストを実行します。完了したセキュリティレビューと機能レビューについては、0.3.0 のレビューをご覧ください。

ライセンス

MIT