pgport

pgport

pgport を使うと、エージェントも、ターミナルを使うあなたも、データベースを変更できないまま PostgreSQL データベースに質問できます。接続文字列を受け取り、読み取り専用クエリを 1 つ実行して、行を返します。単一のプレーンな SELECT 文または WITH ... SELECT 文でないものは、プロセスの外に送信される前に拒否されます。また、実行される文は明示的な読み取り専用トランザクション内で実行されます。

データベースドライバーは同梱されていません。内部では pgport が psql コマンドラインクライアントを呼び出すため、実際の応答を得るには、マシンの PATH に psql が必要です。psql がない場合や、接続文字列がない場合でも、サーバーは起動してツールを一覧表示します。ただし、クエリ自体は問題を報告します。

インストール

npx @reneturcios/pgport query postgres://user@localhost:5432/mydb "SELECT 1"

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

docker run -i ghcr.io/cloudcorprecords/pgport

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

CLI

# Run one read-only query; rows print as JSON
pgport query postgres://alice@localhost/shop "SELECT id, name FROM products ORDER BY id"

# See what tables exist and which columns each one has
pgport schemas postgres://alice@localhost/shop

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

pgport --version

終了コード：成功時は 0、クエリ、接続文字列、または psql 自体が失敗した場合（どれが原因かはエラーに表示されます）は 1、使用方法に関するエラーの場合は 2 です。

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

読み取り専用ガード

クエリが受け付けられるのは、次の条件をすべて満たす場合のみです。

• 先頭の空白とコメントを取り除いた後、最初のキーワードが SELECT または WITH であること。
• 単一の文であること。セミコロンの後に空白以外の文字が続くと、処理は拒否されます。
• 文字列リテラルの外に、INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、TRUNCATE、GRANT、REVOKE、COPY、VACUUM のいずれも、単語全体として含まれていないこと。一重引用符で囲まれたリテラルは走査前に空白に置き換えられるため、SELECT 'delete me' は問題なく実行できます。一方、update という名前の列は実行できません。ガードは、変わった名前の列を許可するより、言いくるめられないことを優先します。

受け付けられたクエリは、BEGIN TRANSACTION READ ONLY; <sql>; COMMIT; として psql -v ON_ERROR_STOP=1 --csv 経由で実行され、CSV 出力は行オブジェクトに解析されます。値は psql が出力した文字列として返されます。

MCP サーバー

1 つの実行ファイルで、どちらの使い方にも対応します。mcp サブコマンドは stdio MCP サーバーを起動します。

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

MCP クライアントの設定：

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

ツール

ツール	入力	返される内容
query	sql（文字列、必須）— 読み取り専用の SQL 文 1 つ	結果の行を、列名をキーとするオブジェクトの JSON 配列として返します。ガード違反、接続の未設定、psql の未設定、データベースエラーは、いずれもツールエラーとして返されます。架空の行が返されることはありません。

サーバーは、MCP レイヤーでは意図的にスキーマについて何も把握しません。たとえば SELECT table_name FROM information_schema.tables のようにデータベース自体に問い合わせるか、information_schema.columns の行をテーブルごとの列リストにまとめる CLI の schemas コマンドを使ってください。

開発

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

コアロジックは、差し替え可能なエグゼキューターインターフェースの背後にあります。テストスイートはこのインターフェースを使い、接続文字列の解析、ガード、クエリの受け渡し、エラーの伝播、スキーマのグループ化をすべてフェイクエグゼキューターで検証します。

ライセンス

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