databridge-kit

databridge-kit

databridge-kit は、エージェント（またはターミナル）と、設定された 1 つの PostgreSQL データベースをつなぐ小さなブリッジです。1 つの SQL ステートメントを実行でき、見慣れないデータベースを調べる際に頻繁に確認する 7 つの項目、つまりテーブル、ビュー、スキーマ、トリガー、インデックス、シーケンス、ストアドプロシージャの一覧を返します。

このツールセットは、設定で定義されたデータベースツールボックスの、ドキュメント化済みのビルド済み Postgres ツールセットに準じています。ツールは固定されており、接続文字列の接続先がデータベースになります。データベースドライバーは同梱されていません。ステートメントは psql コマンドラインクライアントを通じて実行されるため、最新の情報を取得するには、利用するマシンの PATH に psql が必要です。psql がない場合や、接続文字列がない場合でも、サーバーは起動してツールの一覧を表示します。ただし、呼び出し自体は問題を報告します。

インストール

npx @reneturcios/databridge-kit list-tables postgres://user@localhost:5432/mydb

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/databridge-kit

コンテナはデフォルトで MCP サーバーを起動します（以下を参照）。CLI として使うには、CLI の引数を渡します。

CLI

# Run one SQL statement; rows print as JSON
databridge-kit execute-sql postgres://alice@localhost/shop "SELECT id, name FROM products ORDER BY id"

# Inspection commands; each prints its rows as JSON
databridge-kit list-tables postgres://alice@localhost/shop
databridge-kit list-views postgres://alice@localhost/shop
databridge-kit list-schemas postgres://alice@localhost/shop
databridge-kit list-triggers postgres://alice@localhost/shop
databridge-kit list-indexes postgres://alice@localhost/shop
databridge-kit list-sequences postgres://alice@localhost/shop
databridge-kit list-stored-procedures postgres://alice@localhost/shop

# Start the MCP server (connection string optional, see below)
databridge-kit mcp postgres://alice@localhost/shop

databridge-kit --version

終了コード：成功時は 0、ステートメント、接続文字列、または psql 自体でエラーが発生した場合は 1（どれに問題があるかはエラーに示されます）、使い方に誤りがある場合は 2 です。

接続文字列は通常の PostgreSQL URL です。postgres:// または postgresql:// を使い、ホスト、任意のポート（デフォルトは 5432）、パスから取得するデータベース名、任意のユーザー名とパスワードをユーザー情報に指定します。mcp コマンドでは、接続文字列をコマンドラインで省略し、代わりに DATABRIDGE_DATABASE_URL 環境変数から指定できます（通常の DATABASE_URL も使用できます）。

ステートメントと調査の仕組み

execute_sql は、呼び出しごとに 1 つのステートメントのみを受け付けます。文字列リテラルやコメント内のセミコロンはステートメントの区切りとは見なされませんが、2 つ目の実際のステートメントがあると、データベースに送られる前に拒否されます。ステートメントの種類に制限はありません。これは汎用ブリッジであるため、アクセスできる呼び出し元は読み取りだけでなく書き込みもできます。その用途が想定されているデータベースにのみ接続してください。

各調査ツールは、固定されたカタログクエリを 1 つ実行します。

ツール	読み取るカタログ
list_tables	information_schema.tables（ベーステーブル）
list_views	information_schema.views
list_schemas	information_schema.schemata
list_triggers	information_schema.triggers
list_indexes	pg_indexes
list_sequences	information_schema.sequences
list_stored_procedure	information_schema.routines

ステートメントは psql -v ON_ERROR_STOP=1 --csv -c <sql> として実行され、CSV 出力は行オブジェクトにパースされます。値は psql が出力した文字列として返されます。

MCP サーバー

1 つのバイナリで両方の用途に対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/databridge-kit mcp postgres://alice@localhost/shop

MCP クライアントの設定：

{
  "mcpServers": {
    "databridge-kit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/databridge-kit", "mcp"],
      "env": { "DATABRIDGE_DATABASE_URL": "postgres://alice@localhost/shop" }
    }
  }
}

ツール

ツール	入力	戻り値
execute_sql	sql（文字列、必須）— 1 つの SQL ステートメント	列名をキーとするオブジェクトの JSON 配列として、結果の行を返します。
list_tables	—	設定された接続先にあるベーステーブルを説明する行を返します。
list_views	—	設定された接続先にあるビューを説明する行を返します。
list_schemas	—	設定された接続先にあるスキーマを説明する行を返します。
list_triggers	—	設定された接続先にあるトリガーを説明する行を返します。
list_indexes	—	設定された接続先にあるインデックスを説明する行を返します。
list_sequences	—	設定された接続先にあるシーケンスを説明する行を返します。
list_stored_procedure	—	設定された接続先にあるストアドプロシージャ（ルーチン）を説明する行を返します。

接続がない場合、psql がない場合、複数のステートメントを含む execute_sql の場合、データベースエラーの場合は、すべてツールエラーとして返されます。架空の行が返されることはありません。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live database
npm run dev     # run the CLI from source via tsx

コアロジックは、テストスイートから操作できる、差し替え可能なエグゼキューターインターフェースの背後にあります。接続文字列のパース、単一ステートメントのチェック、処理の委譲、エラーの伝播、各調査ツールの正確なカタログ SQL を、すべてフェイクエグゼキューターを使ってテストしています。

ライセンス

MIT — LICENSE を参照してください。