pg-admin-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,609 @@
-# Temporary Holding Version
+# pg-admin-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server, stdio transport, that gives an AI agent full
+PostgreSQL access: connect, browse the catalog, read and paginate rows, run arbitrary SQL, bulk
+insert/update/delete, DDL, snapshot and diff schemas, plan migrations, administer roles/grants/extensions/
+sessions/maintenance, and back up or restore with `pg_dump`/`pg_restore`. 18 tools, 3 read-only resources.
+
+Every connection profile is **read-only by default**. Writes, DDL, admin operations, `EXPLAIN ANALYZE`,
+backup and restore are each a separate opt-in flag, set per profile via environment variables — nothing is
+unlocked implicitly. Every destructive operation (bulk update/delete, guarded raw SQL, restore, role drop,
+`pg_terminate_backend`, `REINDEX`, …) goes through a dry-run/confirm protocol: the first call previews the
+change and returns a token, the second call must hand that exact token back to commit it.
+
+**What it is not.** This server never elevates privileges — it only restricts. It runs as whatever
+PostgreSQL role the connection string authenticates as; capability flags gate which of *that role's own*
+privileges the server is willing to exercise, they do not grant new ones. A read-only transaction is not a
+sandbox either: it won't stop `COPY … TO PROGRAM`, `lo_export()`, or advisory locks, so the documented
+production posture is a role that is itself read-only at the database level
+(`ALTER ROLE … SET default_transaction_read_only = on`, no `pg_write_server_files`).
+
+Two ways to run it: **`npx -y pg-admin-mcp`** (primary — runs on your machine, needs Node.js >= 20.12)
+or the **Docker image** (alternative — carries its own pinned PostgreSQL client tools; see
+[Docker packaging](docs/design.md#docker-packaging) in the design doc).
+
+## Quick start (npx)
+
+1. **Copy the per-project template** from [`examples/per-project/`](examples/per-project/) into your
+   project root: `.mcp.json` (committed — profiles, environment classes, capability flags) and
+   `.env.example` (copy to `.env`, gitignored — the `PG_<ALIAS>_URL` lines with passwords).
+   ```bash
+   cp .env.example .env    # then fill in the URLs
+   mkdir -p pg-workspace   # exports, backups, snapshots land here
+   ```
+   `.mcp.json` launches `npx -y pg-admin-mcp` with `PG_MCP_ENV_FILE: ".env"`; the server reads that
+   file itself, and any key also set in `.mcp.json` wins over `.env`. On native Windows use
+   `"command": "cmd", "args": ["/c", "npx", "-y", "pg-admin-mcp"]`.
+2. **Start `claude` from the project root** — `.env` and `pg-workspace` are relative paths resolved
+   against the directory the client was launched from.
+3. **Verify** by calling `postgres_connection_status`. It reports `runtime: "host"`, reachability, the
+   server version, your role's privileges, and the client tool versions.
+
+Host-mode notes:
+
+- **The database host is plain `localhost`** for a database on your machine — the server is not in a
+  container, so no `host.docker.internal`.
+- **Only `postgres_backup`/`postgres_restore` need the PostgreSQL client tools** (`pg_dump`,
+  `pg_restore`); the other 16 tools need nothing beyond Node. Install a client matching your server's
+  major — Windows `winget install PostgreSQL.PostgreSQL.17`, Debian/Ubuntu
+  `sudo apt install postgresql-client`, macOS `brew install libpq` — and, if it is not on `PATH`, set
+  `PG_MCP_PG_BIN_DIR` in `.env` (Windows: `C:\Program Files\PostgreSQL\17\bin`).
+- `bunx pg-admin-mcp` should work too — untested.
+
+## Quick start (Docker, alternative)
+
+1. **Pull the image** (client binaries are pinned to a PostgreSQL major; use the tag matching your
+   server — `linux/amd64` only):
+   ```bash
+   docker pull mrrainx/pg-admin-mcp:pg17
+   ```
+   `manifest unknown` means no release has been cut yet — see [Status](#status) for how to tell, and
+   [Building the image locally](#building-the-image-locally) for the interim path.
+2. **Create your env file:**
+   ```bash
+   cp .env.example .env
+   ```
+   Edit `.env`: set `PG_MCP_PROFILES`, and for each alias a `PG_<ALIAS>_URL` plus whichever
+   `PG_<ALIAS>_ALLOW_*` flags you want on. See [Configuration](#configuration) and [Networking](#networking)
+   for the connection host — `localhost` will not reach your host machine from inside the container.
+3. **Create the workspace** the container writes files into (exports, backups, snapshots):
+   ```bash
+   mkdir -p pg-workspace
+   ```
+4. **Register it in your MCP client** — see [Connecting a client](#connecting-a-client) for the exact form
+   for Claude Code, Claude Desktop, Codex CLI, Cursor and VS Code.
+5. **Verify** by calling `postgres_connection_status` from the client. It reports `runtime: "container"`,
+   reachability, the server version, your role's privileges, and the `pg_dump`/`pg_restore`/`psql` client
+   versions — everything needed to confirm the server actually reached your database.
+
+## Using it from several projects
+
+Run **one server process per project**, not one shared server for every project on the machine. The
+profile/capability model (`PG_MCP_PROFILES`, `PG_<ALIAS>_URL`, `PG_<ALIAS>_ALLOW_*`) is scoped to the
+process, not to the caller — it assumes the process belongs to a single client. A server shared
+across projects would let one project's agent name another project's profile alias and reach its
+database, `prod` included. One process per project, launched from that project's own config, keeps
+each project's agent limited to the profiles that project itself defines.
+
+**With npx (primary)** this is what [Quick start (npx)](#quick-start-npx) already sets up: the client
+spawns a fresh `npx -y pg-admin-mcp` per session from the project's own `.mcp.json` + `.env`. The
+template is [`examples/per-project/`](examples/per-project/).
+
+**With Docker (alternative)** it is one container per project, launched by a small Compose file.
+Pull the image once — the same image is reused across every project (see [Quick start (Docker, alternative)](#quick-start-docker-alternative)
+if this returns `manifest unknown`):
+
+```bash
+docker pull mrrainx/pg-admin-mcp:pg17
+```
+
+Each project then carries three small committed files plus a gitignored `.env`:
+
+```
+myproject/
+  .mcp.json      # committed — identical in every project, never edited
+  pg_mcp.yml     # committed — this project's profiles and environments, no passwords
+  .env           # gitignored — passwords only
+  pg-workspace/  # gitignored — where exports, dumps and snapshots land
+```
+
+`pg_mcp.yml` is a Docker Compose file. The server itself has no config-file format — it only reads
+environment variables — so Compose here is nothing more than a launcher that sets those variables and
+interpolates the passwords in from `.env`:
+
+```yaml
+services:
+  pg-mcp:
+    image: mrrainx/pg-admin-mcp:pg17
+    stdin_open: true
+    extra_hosts: ["host.docker.internal:host-gateway"]  # harmless on Docker Desktop, required on Linux
+    volumes: ["./pg-workspace:/workspace"]
+    environment:
+      PG_MCP_PROFILES: dev,prod
+      PG_MCP_DEFAULT_PROFILE: dev
+
+      # development: writes and DDL allowed
+      PG_DEV_URL: postgres://app:${DEV_PASSWORD}@host.docker.internal:5432/myproject
+      PG_DEV_ENV: development
+      PG_DEV_ALLOW_WRITE: "true"
+      PG_DEV_ALLOW_DDL: "true"
+
+      # production: no ALLOW_* keys, so it stays read-only
+      PG_PROD_URL: postgres://readonly:${PROD_PASSWORD}@prod.internal:5432/myproject
+      PG_PROD_ENV: production
+```
+
+`.mcp.json` — commit this byte-identical across every project, never edit it:
+
+```json
+{
+  "mcpServers": {
+    "pg": {
+      "command": "docker",
+      "args": [
+        "compose", "-f", "${CLAUDE_PROJECT_DIR:-.}/pg_mcp.yml",
+        "run", "--rm", "-T", "pg-mcp"
+      ]
+    }
+  }
+}
+```
+
+**`-T`, never `-t`** — the Compose spelling of the same rule as `docker run`: a TTY echoes stdin back
+onto stdout and corrupts the JSON-RPC frame stream this server relies on.
+
+**The launch directory is load-bearing.** Verified against Claude Code 2.1.220: `CLAUDE_PROJECT_DIR` is
+not set at the point `.mcp.json` is substituted, so `${CLAUDE_PROJECT_DIR:-.}` always takes its `.`
+fallback, which resolves against the spawned server's CWD — the directory `claude` was launched from,
+not the directory `.mcp.json` lives in and not `$HOME`. The dangerous case is not the obvious failure
+(launching from a directory with no `pg_mcp.yml` — Compose exits, no server); it's launching from a
+*parent* directory that happens to hold its **own** `pg_mcp.yml` (a monorepo root, or any other project
+set up this same way): Compose silently loads that file instead, and the session connects to a
+different project's databases, `prod` profile included, with no error at all. Always start `claude`
+from the project root that holds this `pg_mcp.yml`.
+
+Add to the project's `.gitignore`:
+
+```
+.env
+pg-workspace/
+```
+
+The full template — copy-ready files, adding a third profile, the networking table, and how to confirm
+it worked — lives in [`examples/per-project-docker/`](examples/per-project-docker/); start there rather than
+retyping any of the above.
+
+## The 18 tools
+
+All tool names are prefixed `postgres_`. "Capability flag" is the `PG_<ALIAS>_ALLOW_*` env var that must be
+`true` on the profile for that tool (or that part of it) to work; a blank cell means no flag is needed.
+
+**Discovery** — always available, read-only:
+
+| Tool | What it does | Capability flag |
+|---|---|---|
+| `postgres_connection_status` | Resolved config, reachability, server version, current-role privileges, and `pg_dump`/`pg_restore`/`psql` client versions for one profile. | — |
+| `postgres_list_objects` | Paginated listing of schemas, tables, views, materialized views, sequences, functions, enum types, and extensions in scope for a profile. | — |
+| `postgres_describe_object` | Full detail for one object: columns, PK/FK (both directions), unique/check constraints, indexes (incl. partial), triggers, RLS policies. | — |
+| `postgres_get_schema` | Structured live snapshot of a database or a filtered scope (schemas/kinds/name pattern); `detail:"summary"` or full. | — |
+
+**Read:**
+
+| Tool | What it does | Capability flag |
+|---|---|---|
+| `postgres_select` | Structured, parameterized, paginated (keyset) read of one table or view — the primary way to fetch row data. | — |
+| `postgres_explain` | `EXPLAIN` a statement (TEXT/JSON/XML/YAML, costs/buffers/verbose/settings). `analyze:true` actually executes the statement. | `ALLOW_EXPLAIN_ANALYZE` (only for `analyze:true`) |
+| `postgres_export` | Streams a table selection or a `SELECT` to a CSV/JSON/JSONL file under `/workspace`, batched via a server-side cursor — never buffers the full result. | — |
+
+**Write** (the escape hatch plus the batch mutation tools, all destructive-annotated):
+
+| Tool | What it does | Capability flag |
+|---|---|---|
+| `postgres_execute_sql` | Arbitrary parameterized SQL — reads always work; `INSERT`/`UPDATE`/`DELETE`/`MERGE` need `ALLOW_WRITE`, `CREATE`/`ALTER`/`DROP`/`TRUNCATE` additionally need `ALLOW_DDL`, `GRANT`/`REVOKE` need `ALLOW_ADMIN`. Mutating statements go through dry-run/confirm. | `ALLOW_WRITE` / `ALLOW_DDL` / `ALLOW_ADMIN` (statement-dependent) |
+| `postgres_insert_batch` | Bulk `INSERT` — set-based `INSERT … SELECT * FROM unnest()`, switching to a bulk strategy above a row threshold. Confirmed on row count alone (no pre-existing rows to checksum). | `ALLOW_WRITE` |
+| `postgres_update_batch` | Filtered bulk `UPDATE`. `where` is a structured, parameterized filter and is mandatory — an empty filter is refused before any SQL reaches the server. Dry-run/confirm. | `ALLOW_WRITE` |
+| `postgres_delete_batch` | Filtered bulk `DELETE`, same mandatory-`where` rule as update. Dry-run/confirm. | `ALLOW_WRITE` |
+| `postgres_copy` | High-throughput whole-table (or column-subset) transfer via PostgreSQL's `COPY` protocol, streamed to/from a file. Export direction is read-only; import direction needs write and goes through dry-run/confirm. | `ALLOW_WRITE` (import direction only) |
+
+**Schema:**
+
+| Tool | What it does | Capability flag |
+|---|---|---|
+| `postgres_schema_snapshot` | Captures a normalized, byte-stable schema snapshot (tables, views, sequences, functions, enums, extensions) and writes it to a workspace JSON file. | — |
+| `postgres_schema_diff` | Structural diff between two snapshots, each independently `kind:"live"` (fresh capture) or `kind:"file"` (a `postgres_schema_snapshot` output). | — |
+| `postgres_prepare_migration` | Diffs two snapshots and returns an ordered, dependency-safe, risk-annotated SQL plan. **Emits SQL only — never executes it.** | — |
+
+**Admin:**
+
+| Tool | What it does | Capability flag |
+|---|---|---|
+| `postgres_admin` | Widest blast radius in the server. Six sub-operations selected by `op`: `roles_*` (create/alter/drop a role), `grants_*` (GRANT/REVOKE), `extensions_*` (CREATE/DROP EXTENSION — installing runs arbitrary SQL as superuser), `sessions_*` (cancel/terminate a backend), `maintenance_*` (VACUUM/ANALYZE/REINDEX), `stats_*` (table/index/activity stats). Mutating sub-ops go through dry-run/confirm. `grants_get`, `extensions_list`, and `stats_*` are read-only and need no flag; everything else needs admin. | `ALLOW_ADMIN` (all sub-ops except `grants_get` / `extensions_list` / `stats_*`) |
+
+**Backup:**
+
+| Tool | What it does | Capability flag |
+|---|---|---|
+| `postgres_backup` | Runs `pg_dump` into a workspace file — whole database (default), or named schemas/tables. Formats: custom (default), directory, tar, plain. Not wrapped in dry-run/confirm (it only reads the database and writes a file); gated by the capability plus the workspace path rules. | `ALLOW_BACKUP` |
+| `postgres_restore` | **The most destructive tool in this server.** `mode:"inspect"` (default) lists archive contents via `pg_restore --list`, touching no database. `mode:"restore"` runs `pg_restore` and can overwrite, or with `clean:true` drop-and-recreate, every object in the archive — no undo, not wrapped in a transaction guard, refused without an explicit `confirm:true`. | `ALLOW_RESTORE` |
+
+## The 3 resources
+
+Same read-only catalog listings the discovery tools use, exposed as MCP resources:
+
+| URI | Returns |
+|---|---|
+| `postgres://<profile>/schemas` | Every schema in scope for the profile. |
+| `postgres://<profile>/schema/<schema>` | Every object in one schema. |
+| `postgres://<profile>/table/<schema>/<table>` | Full detail for one table-like relation. |
+
+## Safety model
+
+**Read-only by default.** A profile with no `ALLOW_*` flags set can only discover, `SELECT`, `EXPLAIN`
+(without `ANALYZE`), export, and diff schemas. Every other capability is a separate, explicit,
+per-profile opt-in:
+
+| Flag | Unlocks |
+|---|---|
+| `PG_<ALIAS>_ALLOW_WRITE` | `INSERT`/`UPDATE`/`DELETE`/`MERGE` via `postgres_execute_sql`; `postgres_insert_batch` / `update_batch` / `delete_batch`; `postgres_copy` import direction |
+| `PG_<ALIAS>_ALLOW_DDL` | `CREATE`/`ALTER`/`DROP`/`TRUNCATE` via `postgres_execute_sql` |
+| `PG_<ALIAS>_ALLOW_ADMIN` | `postgres_admin`'s mutating sub-ops (roles, grants, extensions, sessions, maintenance) and `GRANT`/`REVOKE` via `postgres_execute_sql` |
+| `PG_<ALIAS>_ALLOW_EXPLAIN_ANALYZE` | `postgres_explain` with `analyze:true` (this actually executes the statement) |
+| `PG_<ALIAS>_ALLOW_BACKUP` | `postgres_backup` |
+| `PG_<ALIAS>_ALLOW_RESTORE` | `postgres_restore` |
+
+All six default to `false`.
+
+**Dry-run/confirm protocol.** Every mutating tool shares one parameter fragment:
+
+```ts
+{ profile?: string,
+  confirm?: boolean,                                  // default false = dry run
+  expect?: { sqlHash: string, rowCount: number, keyChecksum?: string },
+  allowRowDrift?: number }                             // default 0
+```
+
+Concrete example, `postgres_delete_batch`:
+
+**Call 1 — dry run** (`confirm` omitted). The server resolves identifiers, builds parameterized SQL, checks
+the `where` guard, runs the delete inside a transaction, captures the row count and a checksum of the
+affected primary keys, then rolls back:
+
+```json
+{ "profile": "dev", "table": "customers", "where": { "region": { "eq": "closed" } } }
+```
+→
+```json
+{ "rowCount": 42, "expect": { "sqlHash": "a1b2…", "rowCount": 42, "keyChecksum": "9f3e…" } }
+```
+
+**Call 2 — confirm.** Hand the `expect` object straight back with `confirm: true`. The server recomputes
+`sqlHash` from the incoming arguments — a mismatch is `GUARD_HASH_MISMATCH` — re-checks the row count and
+(if supplied) the key checksum inside the committing transaction, and only then commits:
+
+```json
+{ "profile": "dev", "table": "customers", "where": { "region": { "eq": "closed" } },
+  "confirm": true, "expect": { "sqlHash": "a1b2…", "rowCount": 42, "keyChecksum": "9f3e…" } }
+```
+
+A concurrent change between the two calls that alters the row count or the key set beyond `allowRowDrift`
+aborts the commit with `GUARD_ROW_DRIFT` instead of silently widening the blast radius.
+
+**`envClass: production` makes `expect` (including `keyChecksum`) mandatory and forces `allowRowDrift = 0`.**
+`development` accepts a bare `confirm: true`. `envClass` comes from `PG_<ALIAS>_ENV`; an unset or
+unrecognized value defaults to `production` — the safest failure mode.
+
+**Honest limitation.** `keyChecksum` is an MD5 over the sorted *primary keys* of the affected rows, so it
+proves *which* rows a statement touches, never their contents. A row whose non-key columns changed between
+the dry run and the confirm — leaving the primary-key set and the row count identical — is undetectable by
+either check. What `keyChecksum` does catch, that `rowCount` alone does not, is *substitution*: one matching
+row disappearing while a different one starts matching keeps the count identical while changing the key set.
+
+## Configuration
+
+`.env.example` is the full, commented contract — copy it to `.env` and fill it in. The tables below are
+what exists, not the full detail.
+
+**Global:**
+
+| Var | Default |
+|---|---|
+| `PG_MCP_PROFILES` | **required** — csv of profile aliases |
+| `PG_MCP_DEFAULT_PROFILE` | first entry |
+| `PG_MCP_ALLOWED_DIRS` | `/workspace` in the image; empty on a bare host run disables file tools. Comma-separated (Windows `D:\…` paths are fine); a relative entry resolves against the launch directory |
+| `PG_MCP_ENV_FILE` | unset — path to a dotenv file the server loads at startup (relative = launch directory); keys already in the environment win; unreadable file = exit 1 |
+| `PG_MCP_AUDIT_PATH` | unset — audit logging disabled |
+| `PG_MCP_AUDIT_PARAMS` | `false` — redact statement params in the audit log |
+| `PG_MCP_LOG_LEVEL` | `warn` — stderr only, never stdout |
+| `PG_MCP_MAX_ROWS` / `PG_MCP_MAX_BYTES` | `500` / `262144` |
+| `PG_MCP_CONNECT_TIMEOUT_MS` | `10000` — pool checkout timeout; exceeding it is `PROFILE_UNREACHABLE` |
+| `PG_MCP_MAX_IMPORT_BYTES` | `536870912` (512 MiB) — `postgres_copy` import source cap |
+| `PG_MCP_MAX_SNAPSHOT_BYTES` | `67108864` (64 MiB) — snapshot JSON read cap (a real memory bound) |
+| `PG_MCP_MAX_ARCHIVE_BYTES` | `21474836480` (20 GiB) — `pg_dump` archive cap for `postgres_restore` |
+| `PG_MCP_IN_CONTAINER` | set to `1` by the Dockerfile — **never set this yourself** |
+| `PG_MCP_HOST_REWRITE` | unset — opt-in rewrite of loopback hosts, see [Networking](#networking) |
+| `PG_MCP_WORKSPACE_HOST_PATH` | unset — cosmetic host-side path shown in responses |
+| `PG_MCP_PG_BIN_DIR` / `PG_MCP_PG_MAJOR` | resolved from `PATH` / the image's build arg — on a host without the client on `PATH`, e.g. `C:\Program Files\PostgreSQL\17\bin` |
+
+**Per profile** (alias uppercased, non-alphanumerics → `_`, prefixed `PG_<ALIAS>_`):
+
+| Var | Default |
+|---|---|
+| `URL` | **required** — percent-encode special characters in the password |
+| `ENV` | `production` (`development` \| `staging` \| `production`) |
+| `ALLOW_WRITE` / `ALLOW_DDL` / `ALLOW_ADMIN` / `ALLOW_EXPLAIN_ANALYZE` / `ALLOW_BACKUP` / `ALLOW_RESTORE` | all `false` |
+| `STATEMENT_TIMEOUT_MS` / `LOCK_TIMEOUT_MS` / `IDLE_TX_TIMEOUT_MS` | `30000` / `5000` / `60000` |
+| `POOL_MAX` | `4` |
+| `SCHEMAS` | unset — csv allowlist, unset = all non-system schemas |
+| `ALLOWED_DIRS` / `MAX_ROWS` | inherit global |
+| `SSL_MODE` / `SSL_ROOT_CERT` | unset |
+| `EXPORT_TIMEOUT_MAX_MS` | `600000` (10 min) — ceiling for `postgres_export` / `postgres_copy`'s per-call `timeoutMs` |
+| `BACKUP_TIMEOUT_MAX_MS` | `3600000` (1 hour) — ceiling for the `pg_dump`/`pg_restore` child process, deliberately separate from `STATEMENT_TIMEOUT_MS` |
+
+A broken profile does not stop the server at startup — other profiles stay usable, and
+`postgres_connection_status` reports the breakage for the affected alias.
+
+## Connecting a client
+
+Every client below takes the same stdio `command`/`args` shape. **npx (primary):** `"command": "npx"`,
+`"args": ["-y", "pg-admin-mcp"]` plus an `env` block — the per-project `.mcp.json` in
+[`examples/per-project/`](examples/per-project/) is the complete Claude Code form. On native Windows,
+`npx` is a `.cmd` shim that most clients cannot spawn directly: use `"command": "cmd"`,
+`"args": ["/c", "npx", "-y", "pg-admin-mcp"]`. Clients launched outside a project (Claude Desktop) have
+no meaningful launch directory, so give `PG_MCP_ENV_FILE` and `PG_MCP_ALLOWED_DIRS` absolute paths there.
+
+The Docker forms (alternative) follow.
+
+### Claude Code
+
+Verified against Claude Code 2.1.220 (`claude mcp add --help`). Stdio is the default transport, so it does
+not need to be specified:
+
+```bash
+claude mcp add pg-admin-mcp -- docker run --rm -i --init \
+  --add-host=host.docker.internal:host-gateway \
+  --env-file /absolute/path/to/.env \
+  -v /absolute/path/to/pg-workspace:/workspace \
+  mrrainx/pg-admin-mcp:pg17
+```
+
+This writes an entry shaped like this into Claude Code's config (`~/.claude.json`, under `mcpServers`):
+
+```json
+{
+  "mcpServers": {
+    "pg-admin-mcp": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i", "--init",
+        "--add-host=host.docker.internal:host-gateway",
+        "--env-file", "/absolute/path/to/.env",
+        "-v", "/absolute/path/to/pg-workspace:/workspace",
+        "mrrainx/pg-admin-mcp:pg17"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+Use absolute paths for `--env-file` and the volume mount — relative paths are resolved against wherever
+the client process's cwd happens to be, not this repo.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` directly:
+
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pg-admin-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i", "--init",
+        "--add-host=host.docker.internal:host-gateway",
+        "--env-file", "/absolute/path/to/.env",
+        "-v", "/absolute/path/to/pg-workspace:/workspace",
+        "mrrainx/pg-admin-mcp:pg17"
+      ]
+    }
+  }
+}
+```
+
+Check your Claude Desktop version's docs for this exact key set — not verified locally against Claude
+Desktop, only against the standard stdio-server JSON shape.
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.pg-admin-mcp]
+command = "docker"
+args = [
+  "run", "--rm", "-i", "--init",
+  "--add-host=host.docker.internal:host-gateway",
+  "--env-file", "/absolute/path/to/.env",
+  "-v", "/absolute/path/to/pg-workspace:/workspace",
+  "mrrainx/pg-admin-mcp:pg17",
+]
+```
+
+Not verified locally against the Codex CLI — this is the standard `[mcp_servers.<name>]` stdio form; check
+`codex --help` / the Codex docs for your installed version before relying on it.
+
+### Cursor / VS Code
+
+Both use the same `command`/`args` stdio shape as Claude Desktop, in a project-local file:
+
+- Cursor: `.cursor/mcp.json`, top-level key `mcpServers`
+- VS Code: `.vscode/mcp.json`, top-level key `servers`
+
+```json
+{
+  "pg-admin-mcp": {
+    "command": "docker",
+    "args": [
+      "run", "--rm", "-i", "--init",
+      "--add-host=host.docker.internal:host-gateway",
+      "--env-file", "/absolute/path/to/.env",
+      "-v", "/absolute/path/to/pg-workspace:/workspace",
+      "mrrainx/pg-admin-mcp:pg17"
+    ]
+  }
+}
+```
+
+Not verified locally against Cursor or VS Code — check each editor's MCP docs for the current top-level
+key and file location before relying on it.
+
+## Networking
+
+**npx / host mode:** the server is an ordinary process on your machine, so URL hosts mean what they
+mean there — `localhost` for a local database (or a container's published port), the hostname for a
+remote one. Nothing below applies.
+
+**Docker:** the DB's location relative to the container decides the URL host and any extra `docker run` flags:
+
+| DB location | Extra run flags | URL host |
+|---|---|---|
+| Host machine, Docker Desktop (Windows/macOS) | none | `host.docker.internal` |
+| Host machine, Linux | `--add-host=host.docker.internal:host-gateway` | `host.docker.internal` |
+| Another container | `--network <shared_network>` | that container's service name |
+
+`localhost` inside the container **is the container** — not your host. The server does not silently rewrite
+a loopback host to something that might work, because that could connect the agent to a different database
+than the one it thinks it named. Instead it fails fast with `PROFILE_UNREACHABLE`, reported both from
+`postgres_connection_status` before any connection attempt and from the error path on a runtime
+`ECONNREFUSED`/`ENOTFOUND`. Opt-in rewrite is available via `PG_MCP_HOST_REWRITE=host.docker.internal`
+(applied only to loopback hosts, always reported in the response) if you want the old silent behavior.
+
+## The `/workspace` volume
+
+One mounted volume, `-v <HOST>/pg-workspace:/workspace`. Every tool that writes a file —
+`postgres_export`, `postgres_backup`, `postgres_schema_snapshot`, `postgres_copy` (export direction),
+and the audit log (`PG_MCP_AUDIT_PATH`) — writes inside it, and nothing outside `PG_MCP_ALLOWED_DIRS` is
+reachable at all.
+
+**Path rule:** a relative path resolves against the profile's first allowed directory (so `dumps/x.dump`
+means `/workspace/dumps/x.dump`); an absolute path is normalized and its parent directory must still land
+inside an allowed directory. Files are written as `<name>.partial` and renamed on success, so a killed
+`pg_dump`/export never leaves a plausible-looking truncated file under the real name.
+
+**Linux ownership note.** The container always runs as uid `10001` (never root — see the `Dockerfile`).
+On Docker Desktop (Windows/macOS) the bind-mount boundary maps every uid to full access, so this is
+cosmetic. **On native Linux it is not cosmetic — it is a real `EACCES` risk.** `./pg-workspace` ends up
+owned by whichever uid created it first: your own, if you ran `mkdir -p pg-workspace` first (Quick
+start step 3); `root:root` at mode `0755`, if you skipped that and let the Docker daemon auto-create
+the missing bind-mount source. Either way, uid `10001` is neither the owner nor (normally) in the
+owning group, and the default `0755` grants no write to anyone else — so the very first
+`postgres_export`/`postgres_backup`/`postgres_schema_snapshot` call fails with `EACCES` writing into a
+directory that, from the host side, looks perfectly normal and owned by you. The fix is the same one
+that solves the ownership question above — run the container as your own uid/gid instead of `10001`:
+
+```bash
+docker run --rm -i --init --user "$(id -u):$(id -g)" \
+  --add-host=host.docker.internal:host-gateway \
+  --env-file /absolute/path/to/.env \
+  -v /absolute/path/to/pg-workspace:/workspace \
+  mrrainx/pg-admin-mcp:pg17
+```
+
+For the Compose form (`pg_mcp.yml`, see [Using it from several projects](#using-it-from-several-projects)),
+the equivalent is a `user:` key on the `pg-mcp` service — plain `$UID`/`$GID` are bash builtins and are
+**not** exported to `docker compose` by default, so export them under different names first:
+
+```bash
+export DOCKER_UID="$(id -u)" DOCKER_GID="$(id -g)"
+docker compose -f pg_mcp.yml run --rm -T pg-mcp
+```
+
+```yaml
+services:
+  pg-mcp:
+    image: mrrainx/pg-admin-mcp:pg17
+    user: "${DOCKER_UID:-10001}:${DOCKER_GID:-10001}"
+    # ... rest unchanged
+```
+
+Not applied by default in [`examples/per-project-docker/pg_mcp.yml`](examples/per-project-docker/pg_mcp.yml) — the
+key is a no-op on Docker Desktop and would need every Linux user to remember to export
+`DOCKER_UID`/`DOCKER_GID` first, so it stays opt-in text here rather than a template default that fails
+open to `10001:10001` for anyone who forgets.
+
+## Troubleshooting
+
+- **`PROFILE_UNREACHABLE` pointing at `localhost`.** You configured `PG_<ALIAS>_URL` with `localhost` or
+  `127.0.0.1` — inside the container that's the container itself. See [Networking](#networking).
+- **A password with `#` gets silently truncated.** Docker's `--env-file` does no quote stripping and no
+  interpolation — a value is taken literally from the first `=` to end of line, and a `#` anywhere starts a
+  comment. Percent-encode special characters in the connection URL (`p@ss#1` → `p%40ss%231`).
+- **Never pass `-t` to `docker run`.** A TTY echoes input back onto stdout and corrupts the JSON-RPC frame
+  stream this server relies on. Use `-i` only.
+- **`BINARY_MISSING`.** `postgres_backup`/`postgres_restore` need `pg_dump`/`pg_restore` on `PATH` (or
+  `PG_MCP_PG_BIN_DIR`). Resolution is lazy — the other 16 tools work with no client binaries installed at
+  all; this error only ever comes from the two backup/restore tools. In host mode install a client
+  matching your server's major (Windows `winget install PostgreSQL.PostgreSQL.17`, Debian/Ubuntu
+  `sudo apt install postgresql-client`, macOS `brew install libpq`) and point `PG_MCP_PG_BIN_DIR` at its
+  `bin` if it is not on `PATH` (Windows: `C:\Program Files\PostgreSQL\17\bin`).
+- **npx server exits immediately with `PG_MCP_ENV_FILE points to …`.** The `.env` it names does not
+  exist at that path. A relative path resolves against the directory the client was launched from —
+  start `claude` from the project root, or make the path absolute.
+- **`pg_dump`/`pg_restore` major-version mismatch.** Archives are forward-only: a client older than the
+  server it dumped from refuses to run, and an archive produced by a newer `pg_dump` cannot be restored by
+  an older `pg_restore`. Use the image tag matching your PostgreSQL major (`:pg17`, `:pg16`, …) —
+  `postgres_restore` checks this before spawning anything and names the required tag in the refusal.
+
+## Known limitations
+
+- `postgres_restore` only accepts single-file archives (`pg_dump --format=custom` or `--format=tar`).
+  **Directory-format archives are not supported** — they cannot be identity-checked as one file.
+- `postgres_restore` cannot restore **plain-format (SQL text) dumps** — those aren't `pg_restore` archives;
+  feed them to `psql` instead.
+- `keyChecksum` in the dry-run/confirm protocol pins *which* rows a statement touches (by primary key), not
+  their contents — see [Safety model](#safety-model) for the exact case it does and doesn't catch.
+
+## Development
+
+Package manager is **pnpm** — never npm.
+
+```bash
+pnpm install
+pnpm check          # lint + typecheck + unit tests + build + stdio smoke check
+pnpm test           # unit tests only (no Docker)
+pnpm test:int       # integration tests against a real postgres:17 via testcontainers (needs Docker)
+RUN_CONTAINER_SMOKE=1 pnpm test:smoke   # builds the image and drives it over stdio (needs Docker)
+```
+
+Three Vitest projects: `unit` needs nothing but Node; `integration` needs Docker (testcontainers starts
+`postgres:17` on a random port); `smoke` needs Docker and is opt-in (`RUN_CONTAINER_SMOKE=1`, ~300s) because
+it builds the image from scratch. **The suite runs on the host, never inside the MCP image** — testing
+in-image would need Docker-in-Docker for testcontainers for no gain.
+
+### Building the image locally
+
+The published image comes from Docker Hub (see [Quick start (Docker, alternative)](#quick-start-docker-alternative)) — build locally only when
+testing a change before it ships. Client binaries are pinned to a PostgreSQL major; pass the `PG_MAJOR`
+matching your server and tag accordingly:
+
+```bash
+docker build --build-arg PG_MAJOR=17 -t pg-admin-mcp:pg17 .
+```
+
+See [docs/releasing.md](docs/releasing.md) for how a tagged commit turns this into the published
+`mrrainx/pg-admin-mcp:pg17`/`:pg16` images (`linux/amd64` only).
+
+## Status
+
+Personal project, version `0.1.0`. Distributed on npm as `pg-admin-mcp` (`npx -y pg-admin-mcp`) — if
+`npx` reports `404 Not Found`, no npm release has been cut yet; until then run it from a clone
+(`pnpm install && pnpm build`, then `node /absolute/path/to/dist/index.js` as the client `command`). Docker images are
+built and pushed to Docker Hub as `mrrainx/pg-admin-mcp` (`:pg17`, `:pg16`, `linux/amd64` only) by the
+release workflow described in [docs/releasing.md](docs/releasing.md), triggered by pushing a `v*` tag —
+if no such tag has been pushed yet, `docker pull` returns `manifest unknown` and
+[Building the image locally](#building-the-image-locally) is the only way to get the image. No license
+file yet.