@yawlabs/postgres-mcp 0.3.1 → 0.3.3

package/README.md

@@ -2,23 +2,38 @@
 
 [![npm version](https://img.shields.io/npm/v/@yawlabs/postgres-mcp)](https://www.npmjs.com/package/@yawlabs/postgres-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![CI](https://github.com/YawLabs/postgres-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/postgres-mcp/actions/workflows/ci.yml) [![Release](https://github.com/YawLabs/postgres-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/postgres-mcp/actions/workflows/release.yml)
 
 **Query a PostgreSQL database from Claude Code, Cursor, and any MCP client.** Read-only by default — writes opt in via a single env var — so an agent can't silently drop your tables.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
-## Why this one?
+## Backstory
+
+Anthropic's reference Postgres MCP server, `@modelcontextprotocol/server-postgres`, was [archived in May 2025](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/postgres) and [marked deprecated on npm](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres) in July 2025. Anthropic has not shipped a replacement. Despite the deprecation, the last published version (v0.6.2) is still pulled ~20,000 times per week — a lot of agents are pointed at an unmaintained package.
+
+That unmaintained package also has a known, [publicly documented stacked-query SQL injection](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) (Datadog Security Labs) that bypasses its `BEGIN READ ONLY` wrapper with input like `COMMIT; DROP SCHEMA public CASCADE;`. It has never been patched at npm.
+
+A handful of community forks have appeared, but each fills a narrow slice:
 
-The official Anthropic `@modelcontextprotocol/server-postgres` was [deprecated on npm](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres) in early 2026. This one picks up where it left off, with a few extras:
+- [`@zeddotdev/postgres-context-server`](https://www.npmjs.com/package/@zeddotdev/postgres-context-server) — Zed's fork, primarily a security patch on the original shape.
+- **Postgres MCP Pro** (Crystal DBA) — focused on index tuning and hypothetical-index / buffer-cache diagnostics.
+- **AWS Labs Postgres MCP** — tied to Aurora / RDS Data API + Secrets Manager.
+
+None of them position themselves as a general-purpose daily driver you'd hand to Claude Code or Cursor against an arbitrary Postgres: modern introspection, perf helpers, role/privilege awareness, and a write-safety posture out of the box. That's the gap `@yawlabs/postgres-mcp` fills.
+
+## Why this one?
 
-- **Read-only by default** — user SQL runs in a `BEGIN READ ONLY` transaction, so postgres itself (not string parsing) blocks writes. Opt in to writes with `ALLOW_WRITES=1`.
-- **Schema introspection built in** — `pg_list_schemas`, `pg_list_tables`, `pg_describe_table` return columns, primary keys, foreign keys, and indexes without you having to remember the `pg_catalog` joins.
-- **`EXPLAIN` as a first-class tool** — text or JSON format, with optional `ANALYZE`. ANALYZE for non-SELECT statements requires `ALLOW_WRITES=1` since it actually runs the query.
-- **Health snapshot** — `pg_health` returns version, db size, connection counts, and the 10 longest-running active queries in one call. Use it as a connection smoke-test and to catch runaway queries.
-- **Instant startup** — ships as a single bundled file with zero runtime dependencies. No multi-minute `node_modules` install on every npx cold start.
+- **Read-only by default** — user SQL runs in a `BEGIN READ ONLY` transaction, so postgres itself (not string parsing) blocks writes. Opt in with `ALLOW_WRITES=1`.
+- **Extended query protocol for all user SQL** — `pg_query` sends user input with `queryMode: 'extended'`, which restricts each request to a single statement. This closes the [stacked-query injection class](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) (`COMMIT; DROP SCHEMA x CASCADE;`) that defeated the reference server's `BEGIN READ ONLY` wrapper. Integration test asserts the rejection.
+- **Parameterized queries** — `pg_query` takes a `params` array for `$1`, `$2`, etc. No string-interpolated SQL in our code path.
+- **Written from scratch, actively maintained** — not a fork of the deprecated code. Unit + integration tests (`npm test`, `npm run test:integration`) run against a real Postgres; releases cut via `release.sh`.
+- **Schema introspection built in** — `pg_list_schemas`, `pg_list_tables`, `pg_describe_table` return columns, primary keys, foreign keys, and indexes without the agent having to remember `pg_catalog` joins.
+- **`EXPLAIN` as a first-class tool** — text or JSON format, with optional `ANALYZE`. ANALYZE for non-SELECT statements requires `ALLOW_WRITES=1` and always rolls back, so the plan is real but the write doesn't persist.
+- **Perf diagnostics the deprecated server never had** — `pg_top_queries` (from `pg_stat_statements`), `pg_seq_scan_tables`, `pg_unused_indexes`, `pg_table_bloat`, `pg_inspect_locks`, `pg_replication_status`. Answer "why is this slow?" in one tool call.
+- **Health snapshot** — `pg_health` returns version, db size, connection counts, and the 10 longest-running active queries in one call.
+- **Role and privilege awareness** — `pg_list_roles` and `pg_table_privileges` for the common "who can touch what?" questions.
+- **Instant startup** — ships as a single bundled file with zero runtime dependencies. No multi-minute `node_modules` install on every `npx` cold start.
 - **Result truncation** — large result sets are capped at `POSTGRES_MAX_ROWS` (default 1000) with a `truncated: true` flag, so a stray `SELECT * FROM events` doesn't blow out the model context.
-- **Parameterized queries** — `pg_query` accepts a `params` array for `$1`, `$2`, etc. No string-interpolated SQL.
 
 ## Quick start
 

package/dist/index.js

@@ -35324,7 +35324,7 @@ async function runReadOnly(sql, params = []) {
   const maxRows = getMaxRows();
   try {
     await client.query("BEGIN READ ONLY");
-    const result = await client.query(sql, params);
+    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
     await client.query("ROLLBACK");
     return { ok: true, data: toQueryResult(result, maxRows) };
   } catch (err) {
@@ -35348,7 +35348,7 @@ async function runReadWrite(sql, params = []) {
   const maxRows = getMaxRows();
   try {
     await client.query("BEGIN");
-    const result = await client.query(sql, params);
+    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
     await client.query("COMMIT");
     return { ok: true, data: toQueryResult(result, maxRows) };
   } catch (err) {
@@ -35361,6 +35361,30 @@ async function runReadWrite(sql, params = []) {
     client.release();
   }
 }
+async function runReadWriteRollback(sql, params = []) {
+  if (!isWritesAllowed()) {
+    return {
+      ok: false,
+      error: "Write blocked: ALLOW_WRITES is not set. Set ALLOW_WRITES=1 in the MCP server env to enable DML/DDL."
+    };
+  }
+  const client = await getPool().connect();
+  const maxRows = getMaxRows();
+  try {
+    await client.query("BEGIN");
+    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
+    await client.query("ROLLBACK");
+    return { ok: true, data: toQueryResult(result, maxRows) };
+  } catch (err) {
+    try {
+      await client.query("ROLLBACK");
+    } catch {
+    }
+    return { ok: false, error: formatPgError(err) };
+  } finally {
+    client.release();
+  }
+}
 async function runInternal(sql, params = []) {
   try {
     const result = await getPool().query(sql, params);
@@ -35637,14 +35661,16 @@ var adminTools = [
   }
 ];
 
-// src/tools/explain.ts
+// src/tools/params.ts
 var paramValue = external_exports3.lazy(
   () => external_exports3.union([external_exports3.string(), external_exports3.number(), external_exports3.boolean(), external_exports3.null(), external_exports3.array(paramValue), external_exports3.record(external_exports3.string(), paramValue)])
 );
+
+// src/tools/explain.ts
 var explainTools = [
   {
     name: "pg_explain",
-    description: "Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set `analyze: true` to run the query with EXPLAIN ANALYZE \u2014 for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Format is `text` (default) or `json`. Pass the raw SQL (not an EXPLAIN-prefixed statement).",
+    description: "Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set `analyze: true` to run the query with EXPLAIN ANALYZE \u2014 for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Writes executed during EXPLAIN ANALYZE are always rolled back, so you can inspect a plan for an INSERT/UPDATE/DELETE without persisting the mutation. Format is `text` (default) or `json`. Pass the raw SQL (not an EXPLAIN-prefixed statement).",
     annotations: {
       title: "Explain query plan",
       readOnlyHint: false,
@@ -35670,7 +35696,7 @@ var explainTools = [
       if (analyze) flags.push("ANALYZE");
       if (format === "json") flags.push("FORMAT JSON");
       const explainSql = flags.length > 0 ? `EXPLAIN (${flags.join(", ")}) ${sql}` : `EXPLAIN ${sql}`;
-      const result = analyze && isWritesAllowed() ? await runReadWrite(explainSql, params ?? []) : await runReadOnly(explainSql, params ?? []);
+      const result = analyze && isWritesAllowed() ? await runReadWriteRollback(explainSql, params ?? []) : await runReadOnly(explainSql, params ?? []);
       if (!result.ok) return result;
       const data = result.data;
       const rows = data?.rows ?? [];
@@ -35740,7 +35766,8 @@ var healthTools = [
            JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
            WHERE c.relkind IN ('r', 'p')
              AND n.nspname NOT IN ('pg_catalog', 'information_schema')
-             AND n.nspname NOT LIKE 'pg_toast%'`
+             AND n.nspname NOT LIKE 'pg_toast%'
+             AND n.nspname NOT LIKE 'pg_temp_%'`
         )
       ]);
       if (!versionRes.ok) return versionRes;
@@ -35760,9 +35787,6 @@ var healthTools = [
 ];
 
 // src/tools/query.ts
-var paramValue2 = external_exports3.lazy(
-  () => external_exports3.union([external_exports3.string(), external_exports3.number(), external_exports3.boolean(), external_exports3.null(), external_exports3.array(paramValue2), external_exports3.record(external_exports3.string(), paramValue2)])
-);
 var queryTools = [
   {
     name: "pg_query",
@@ -35777,7 +35801,7 @@ var queryTools = [
     },
     inputSchema: external_exports3.object({
       sql: external_exports3.string().min(1).max(1e6).describe("The SQL statement to execute. Hard cap of 1 MB."),
-      params: external_exports3.array(paramValue2).optional().describe("Positional parameters referenced as $1, $2, ... in the SQL.")
+      params: external_exports3.array(paramValue).optional().describe("Positional parameters referenced as $1, $2, ... in the SQL.")
     }),
     handler: async (input) => {
       const { sql, params } = input;
@@ -36192,9 +36216,8 @@ var statsTools = [
            n_live_tup::text AS live_tuples,
            seq_tup_read::text AS seq_tup_read,
            CASE
-             WHEN COALESCE(idx_scan, 0) = 0 AND seq_scan > 0 THEN NULL
-             WHEN COALESCE(idx_scan, 0) = 0 THEN 0
-             ELSE (seq_scan::numeric / NULLIF(idx_scan, 0))::numeric(10, 2)::float8
+             WHEN COALESCE(idx_scan, 0) = 0 THEN NULL
+             ELSE (seq_scan::numeric / idx_scan)::numeric(10, 2)::float8
            END AS ratio
          FROM pg_catalog.pg_stat_user_tables
          WHERE n_live_tup >= $1
@@ -36260,7 +36283,7 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.3.1" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.3.3" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -36322,4 +36345,7 @@ process.on("SIGINT", () => {
 process.on("SIGTERM", () => {
   void cleanup().finally(() => process.exit(0));
 });
+process.stdin.on("end", () => {
+  void cleanup().finally(() => process.exit(0));
+});
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/postgres-mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "PostgreSQL MCP server — query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
@@ -38,12 +38,11 @@
     "lint:fix": "biome check --write src/",
     "prepublishOnly": "npm run build"
   },
-  "dependencies": {},
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/node": "^25.6.0",
-    "@types/pg": "^8.11.10",
+    "@types/pg": "^8.20.0",
     "esbuild": "^0.28.0",
     "pg": "^8.13.0",
     "typescript": "^6.0.3",