postgres-mcp-safe 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandesh Poudel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# postgres-mcp-safe
 
-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.
+A drop-in replacement for the deprecated `@modelcontextprotocol/server-postgres`, but actually read-only.
+
+Lets AI tools (Claude, Cursor, Zed, ...) query a Postgres database, read its schema and explain queries. Swap the
+package name in your MCP config and keep everything else.
+
+> Status: pre-release. Not on npm or Docker Hub yet.
+
+## Migrating from server-postgres
+
+```diff
+ {
+   "mcpServers": {
+     "postgres": {
+       "command": "npx",
+-      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
++      "args": ["-y", "postgres-mcp-safe", "postgresql://localhost/mydb"]
+     }
+   }
+ }
+```
+
+Docker: `docker run -i --rm ghcr.io/poudel0/postgres-mcp-safe postgresql://host.docker.internal:5432/mydb`.
+Binaries for Linux, macOS and Windows are on the [releases page](https://github.com/Poudel0/postgres-mcp-safe/releases).
+
+**One catch:** if your URL logs in as a superuser (like Docker's default `postgres` user), every call is refused
+until you either [create a read-only role](#use-a-read-only-role-too) (recommended) or add `--allow-superuser`
+before the URL. A superuser can get around a read-only transaction, so we won't pretend otherwise.
+
+The old server's `query` tool and `postgres://.../<table>/schema` resources work the same. See
+[Differences](#differences-from-server-postgres) for the small, deliberate changes.
+
+## Why
+
+The old server's "read-only" mode can be broken with `COMMIT; DROP TABLE ...`
+([Datadog Security Labs, 2025-08-21](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/)).
+A fix was merged upstream but never published, and the package is deprecated with no official successor.
+
+## Flags
+
+Flags go **before** the URL.
+
+| Flag | Default | |
+|---|---|---|
+| `--timeout` | `30s` | Time limit per call. |
+| `--max-rows` | `1000` | Rows returned per call. Extra rows are cut off with a note. |
+| `--max-bytes` | `262144` | JSON bytes returned per call, and the max size of a single row. |
+| `--allow-explain-analyze` | off | Lets `explain` run `EXPLAIN ANALYZE`, which executes the query. |
+| `--allow-superuser` | off | Allows a superuser role, or a member of one. Read-only is then **not** guaranteed. |
+
+Limits can't be turned off; `0` is an error. The URL can also be a keyword DSN (`host=db dbname=app`), and the
+standard `PG*` environment variables (`PGPASSWORD`, ...) are read as libpq would.
+
+## Tools
+
+| Tool | Input | |
+|---|---|---|
+| `query` | `sql` | One read-only statement. Returns a JSON array of rows. |
+| `list_tables` | `schema?` | Tables and views with schema and type. |
+| `describe_table` | `table`, `schema?` (`public`) | Columns, constraints and indexes. |
+| `explain` | `sql`, `analyze?` | Query plan. `analyze` needs `--allow-explain-analyze`. |
+
+## How read-only is enforced
+
+Postgres enforces it, not a SQL parser. Every call:
+
+1. Opens a **fresh connection** (no session state survives a call) and starts a `READ ONLY` transaction.
+2. Sends your SQL as a single protocol-level *Parse* message. Postgres rejects more than one statement there, so
+   `COMMIT; ...` fails before anything runs.
+3. Runs it only if Postgres says it returns rows. `COMMIT`, `SET`, `DO`, `COPY`, `CALL`, `PREPARE` and friends are
+   rejected without running.
+4. Applies `statement_timeout`, a client deadline, and row and byte caps.
+5. Closes the connection, which ends the transaction.
+
+The [bypass suite](bypass_test.go) runs every known payload against a real database and checks a canary table after
+each one:
+
+| Payload | Result |
+|---|---|
+| `COMMIT; DROP SCHEMA public CASCADE;` | Rejected: multiple statements |
+| `COMMIT` / `SET TRANSACTION READ WRITE` / `DO $$...$$` / `CALL p()` | Rejected: returns no rows |
+| `COPY (SELECT 1) TO PROGRAM '...'` (as superuser) | Rejected: returns no rows |
+| `DELETE ... RETURNING *` / `WITH d AS (DELETE ...) SELECT ...` | Read-only transaction error |
+| `SELECT nextval('s')` | Read-only transaction error |
+| `SELECT set_config('transaction_read_only','off',true)` | Error |
+| `SELECT pg_sleep(600)`, even after `set_config('statement_timeout','0')` | Cancelled at `--timeout` |
+| `SELECT pg_advisory_lock(1)` | Released when the call ends |
+| `SELECT generate_series(1,10000000)` / `repeat('x', 10000000)` | Capped / rejected, memory stays bounded |
+| `explain` with `ANALYZE SELECT ...` | Syntax error: can't smuggle `ANALYZE` |
+
+Found a bypass? Open an issue. It becomes a test row before the fix.
+
+## Use a read-only role too
+
+This server makes each call read-only **at the transaction level**. Some things are out of a transaction's reach,
+and only the database role stops them:
+
+- `dblink_exec(...)` opens a *separate* session that isn't read-only.
+- `pg_terminate_backend(...)` kills other connections.
+- A superuser can read server files (`pg_read_file`, `pg_ls_dir`): read-only stops writes, not reads.
+- A superuser can **write** server files with `lo_export`, even inside a read-only transaction.
+
+So connect as a role that can only read:
+
+```sql
+CREATE ROLE mcp_ro LOGIN PASSWORD '...';
+GRANT pg_read_all_data TO mcp_ro;                     -- PG 14+; or GRANT SELECT on what it needs
+ALTER ROLE mcp_ro SET default_transaction_read_only = on;
+```
+
+Because of the last two, the server refuses superuser roles (and members of them) unless you pass `--allow-superuser`.
+
+## Differences from server-postgres
+
+1. Errors in a tool call come back as a tool result with `isError: true` and the Postgres message and SQLSTATE, so
+   the model can fix its SQL. The old server sent a JSON-RPC error.
+2. `resources/read` only shows columns of the `public` table, in column order. The old one mixed in columns from
+   same-named tables in other schemas.
+3. Percent-encoded table names in resource URIs are decoded (the old server never matched them).
+4. Values are what Postgres prints, typed where it's clear: booleans, numbers (including `bigint` and `numeric`)
+   and `json` are JSON values; everything else is a string such as `"2026-01-02 03:04:05+00"`, `"\\x0102"` or
+   `"{x,y}"`. `NaN` is `"NaN"` (the old server gave `null`).
+5. Statements that return no rows (`SET`, `DO`, `COPY`, ...) are rejected. The old server ran them and returned `[]`.
+
+## Development
+
+```sh
+docker run -d --name pg-mcp-test -e POSTGRES_PASSWORD=postgres -p 127.0.0.1:5434:5432 postgres:17-alpine
+export DATABASE_URL='postgresql://postgres:postgres@127.0.0.1:5434/postgres?sslmode=disable'
+make test     # all tests, including the bypass suite
+make golden   # re-record the old server's output (needs npx)
+```
+
+`DATABASE_URL` must be a superuser: the fixture resets the `public` schema and creates the `mcp_ro` role. Use a
+throwaway database.

package/bin/postgres-mcp-safe.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+
+// Runs the Go binary from the platform package npm picked via optionalDependencies.
+const { spawn } = require("node:child_process");
+
+const pkg = `postgres-mcp-safe-${process.platform}-${process.arch}`;
+const exe = process.platform === "win32" ? "postgres-mcp-safe.exe" : "postgres-mcp-safe";
+
+let bin;
+try {
+  bin = require.resolve(`${pkg}/bin/${exe}`);
+} catch {
+  console.error(
+    `postgres-mcp-safe: no binary for ${process.platform}-${process.arch} (${pkg} is not installed).\n` +
+      "Supported: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64. " +
+      "If you installed with --no-optional, reinstall without it.",
+  );
+  process.exit(1);
+}
+
+const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => child.kill(sig));
+}
+child.on("error", (err) => {
+  console.error(`postgres-mcp-safe: ${err.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "postgres-mcp-safe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Drop-in replacement for @modelcontextprotocol/server-postgres that is actually read-only.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgres",
+    "postgresql",
+    "read-only",
+    "server-postgres"
+  ],
+  "homepage": "https://github.com/Poudel0/postgres-mcp-safe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Poudel0/postgres-mcp-safe.git"
+  },
+  "license": "MIT",
+  "mcpName": "io.github.Poudel0/postgres-mcp-safe",
+  "bin": {
+    "postgres-mcp-safe": "bin/postgres-mcp-safe.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "postgres-mcp-safe-linux-arm64": "0.1.1",
+    "postgres-mcp-safe-linux-x64": "0.1.1",
+    "postgres-mcp-safe-darwin-x64": "0.1.1",
+    "postgres-mcp-safe-darwin-arm64": "0.1.1",
+    "postgres-mcp-safe-win32-x64": "0.1.1"
+  }
+}