@yawlabs/postgres-mcp 0.6.19 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,138 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.20] - 2026-06-04
+
+### Fixed
+- `wrapToolHandler` now distinguishes a handler that returned a non-`ApiResponse`
+  value (null, a primitive, a raw object) from a handler that returned
+  `{ok: false}`. The former surfaces `"Error: tool handler returned a malformed
+  result (missing ok)"`; the latter still surfaces `"Error: <error>"`. A
+  misbehaving handler no longer collapses into the generic `Unknown error` path.
+  `wrapToolHandler` is also now exported from `mcp-wrapper.ts` and covered by
+  a dedicated unit test (`mcp-wrapper.test.ts`), so the production mapping is
+  exercised without standing up `index.ts` and the stdio transport.
+- `index.ts` resolves `package.json` by walking up from the emitted module path
+  rather than via a hard-coded `"../package.json"`. A non-trivial `tsc` emit
+  layout (e.g. `dist/src/index.js`) used to crash startup with an unresolvable
+  require. Verified against the current `outDir: "dist"` layout; future layout
+  changes don't need an `index.ts` patch.
+- Shutdown is now idempotent. SIGINT, SIGTERM, and `stdin.end` can all fire
+  near-simultaneously when a client closes the connection while the shell also
+  sends a signal. An `exiting` flag short-circuits the second and third so
+  `shutdown()` and `process.exit()` don't race.
+- `index.ts` no longer fakes a `version` string when `__VERSION__` is unset
+  (which only happens on a plain `tsc` build, not the esbuild bundled output).
+  The new `readPackageVersion()` throws a clear error if it can't find
+  `package.json` rather than silently emitting a malformed banner.
+
+### Security
+- `paramValue` (used by `pg_query`, `pg_readonly`, `pg_explain` for positional
+  parameters) now uses `.finite()` on the number member, so `NaN`, `Infinity`,
+  and `-Infinity` are rejected at the MCP boundary. Without `.finite()`, pg
+  serializes the JS number to the literal string `'NaN'` / `'Infinity'`, which
+  the server happily accepts on a text column and rejects opaquely on a numeric
+  one. Now the request is rejected before it ever hits the database.
+- `identSchema` dropped its redundant `.max(63)` so the byte-length `.refine`
+  is the sole length guard. A 64-ASCII-char string now surfaces the tailored
+  "exceeds PostgreSQL's 63-byte NAMEDATALEN limit" message instead of Zod's
+  generic "at most 63 character(s)" -- agents that read the message act on it
+  correctly.
+
+### Added
+- `pg_explain` rejects pre-wrapped `EXPLAIN ...` SQL with a clear hint. An LLM
+  that calls the tool with `sql: "EXPLAIN ANALYZE SELECT ..."` no longer
+  becomes the double-`EXPLAIN` syntax error from the server; the handler
+  short-circuits with "the `sql` parameter should be the query to explain, not
+  an EXPLAIN statement." Also re-applies Zod defaults (`analyze`, `format`,
+  `using`) on the direct-call path so unit tests that bypass Zod still hit
+  the documented behavior.
+- `pg_explain` hypothetical_indexes pre-flight rejects over-qualified
+  `schema.table.extra` table names, not just pre-quoted / over-63-byte ones.
+  An `a.b.c` form previously rendered as `"a"."b"."c"` and surfaced a
+  confusing planner error; now it's rejected with a clear message.
+- `pg_describe_table` populates `_warnings` even when the `kind` sub-query
+  returned zero rows (not just when it errored). The `?? "table"` default
+  would otherwise silently mislabel a relation that was dropped between the
+  `columns` and `kind` fetches.
+- `pg_health` warns when the version sub-query returned zero rows (rather
+  than silently emitting `version: undefined`). Symmetric with the other
+  four sub-queries.
+- Per-tool `inputSchema parses a type-correct sample input` test in
+  `tools.test.ts`. Catches drift between the schema's declared shape and
+  the keys the handler destructures at runtime. Uses public Zod 4
+  constructors (`instanceof z.ZodString`, etc.) -- the `_def` introspection
+  path is brittle across Zod majors.
+
+### Docs
+- `pg_query` description now leads with "Postgres itself is the primary
+  safety gate" and presents `ALLOW_WRITES=1` as a secondary belt-and-braces.
+  Pre-0.6.20 the order implied `ALLOW_WRITES` was the primary control, which
+  is the opposite of the recommended posture (a least-privileged role in
+  `DATABASE_URL`).
+- `getPool()` env-var snapshot comment now leads with which two values
+  (`getMaxRows`, `isWritesAllowed`) are intentionally re-read per request,
+  with rationale, instead of burying the re-read list at the end of a
+  paragraph about the snapshot.
+
+### Infrastructure
+- `release.sh` accepts `REQUIRE_MATRIX=1`. When set, the existing "WSL Ubuntu
+  not detected" warning becomes a hard `fail`; default behavior is unchanged
+  (warn-only so contributors without WSL can still tag). The matrix remains
+  a local-only pre-tag gate; this is just an opt-in fail-fast.
+- `package.json` `package-lock.json` and `server.json` all bumped to 0.6.20.
+
+## [0.6.19] - 2026-06-02
+
+Release-flow hardening; no library behavior changes shipped in this version.
+
+### Fixed
+- `release.sh` refuses to push when origin already has `v<version>` pointing
+  at a different commit (rewound tag elsewhere, parallel release race) --
+  previously `git push --follow-tags` silently skipped the stale tag and the
+  GitHub release linked the wrong commit. Compares tag-object SHAs so resume
+  runs don't false-abort.
+- README "Add to Yaw MCP" badge points at the https forwarder so it renders
+  as a link on github.com (raw `yaw://` hrefs are stripped).
+
+### Added
+- `SKIP_LINT=1` escape hatch in `release.sh` for hosts where the npm
+  run-script wrapper segfaults on exit-cleanup (MINGW64-ARM64).
+- `wrapToolHandler` extracted from `index.ts` for testability, with unit
+  coverage of the MCP result wrapper and the connect-failure path (expanded
+  further in 0.6.20).
+
+## [0.6.18] - 2026-05-28
+
+### Changed
+- Release publishing consolidated into `release.sh`: the MCP Registry publish
+  moved into the script and `release.yml` (plus the non-release CI workflows)
+  was dropped. The script hands off to CI when a CI publish path exists and
+  publishes from the workstation otherwise.
+
+### Fixed
+- `release.sh` syncs `server.json` unconditionally, not only inside the bump
+  branch, so a resume run no longer asks mcp-publisher to re-publish the
+  previous version (400 duplicate-version).
+- `release.sh` falls back to the gh CLI session token when
+  `MCP_REGISTRY_TOKEN` is unset.
+- The release confirmation prompt is tty-gated so non-interactive runs don't
+  hang on `read`.
+
+### Docs
+- README install badge swapped to the "Add to Yaw MCP" deep link; `npx`
+  spawn examples pinned to `@latest` for auto-update.
+
+## [0.6.17] - 2026-05-19
+
+### Added
+- `release.sh` accepts an optional pre-release commit message as a second
+  argument: runs the pre-commit checklist, commits tracked changes, then
+  proceeds with the release.
+- Post-publish smoke script (`scripts/post-publish-smoke.sh`) wired into the
+  release flow -- exercises the published tarball via a real `npx` install
+  instead of trusting `npm view` registry metadata.
+
 ## [0.6.16] - 2026-05-18
 
 ### Tests

package/README.md

@@ -246,6 +246,12 @@ DATABASE_URL='postgres://user:pass@host:5432/db' POSTGRES_MCP_INTEGRATION=1 npm
 
 The integration suite assumes a disposable database -- it creates and drops a `test_fixture` schema. Don't point it at anything you care about.
 
+To also run the destructive tests (REVOKE / restricted-role path), add `POSTGRES_MCP_DESTRUCTIVE_TESTS=1`. Only safe on a disposable cluster:
+
+```bash
+DATABASE_URL='postgres://user:pass@host:5432/db' POSTGRES_MCP_INTEGRATION=1 POSTGRES_MCP_DESTRUCTIVE_TESTS=1 npm run test:integration
+```
+
 ### Windows: integration tests via WSL2
 
 Native Postgres on Windows ARM64 is fragile (UCRT runtime gaps, missing ARM64 builds). The reliable path is a disposable Ubuntu under WSL2 with the integration suite running inside WSL (WSL2's NAT blocks the Windows host from reaching :5432, so don't try to run the tests from PowerShell):

package/dist/index.js

@@ -36354,6 +36354,17 @@ function wrapToolHandler(handler) {
   return async (input) => {
     try {
       const result = await handler(input);
+      if (result === null || typeof result !== "object" || !("ok" in result)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error: tool handler returned a malformed result (missing ok)"
+            }
+          ],
+          isError: true
+        };
+      }
       const response = result;
       if (!response.ok) {
         return {
@@ -36366,7 +36377,11 @@ function wrapToolHandler(handler) {
           isError: true
         };
       }
-      const text = JSON.stringify(response.data ?? { success: true }, null, 2);
+      const text = JSON.stringify(
+        response.data ?? { success: true },
+        (_k, v) => typeof v === "bigint" ? v.toString() : v,
+        2
+      );
       return {
         content: [{ type: "text", text }]
       };
@@ -36382,7 +36397,14 @@ function wrapToolHandler(handler) {
 
 // src/tools/params.ts
 var paramValue = external_exports.lazy(
-  () => external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null(), external_exports.array(paramValue), external_exports.record(external_exports.string(), paramValue)])
+  () => external_exports.union([
+    external_exports.string(),
+    external_exports.number().finite(),
+    external_exports.boolean(),
+    external_exports.null(),
+    external_exports.array(paramValue),
+    external_exports.record(external_exports.string(), paramValue)
+  ])
 );
 var MAX_PARAM_DEPTH = 32;
 function isWithinDepth(value, maxDepth) {
@@ -36403,7 +36425,7 @@ function isWithinDepth(value, maxDepth) {
 var paramsArray = external_exports.array(paramValue).refine((arr) => arr.every((v) => isWithinDepth(v, MAX_PARAM_DEPTH)), {
   message: `Parameter value exceeds maximum nesting depth of ${MAX_PARAM_DEPTH}`
 });
-var identSchema = external_exports.string().min(1).max(63).refine((v) => Buffer.byteLength(v, "utf8") <= 63, {
+var identSchema = external_exports.string().min(1).refine((v) => Buffer.byteLength(v, "utf8") <= 63, {
   message: "Identifier exceeds PostgreSQL's 63-byte NAMEDATALEN limit (multi-byte characters count as multiple bytes)."
 });
 
@@ -36411,7 +36433,7 @@ var identSchema = external_exports.string().min(1).max(63).refine((v) => Buffer.
 var adminTools = [
   {
     name: "pg_inspect_locks",
-    description: "Show current lock contention: which sessions are blocked and who is blocking them. Returns blocked PID, blocking PID, lock types, relation being contested, and the queries involved. Use this first when a tool call hangs or the app feels stuck - it's the fastest way to identify a long-held transaction holding a lock. Row shape: one row per (blocked_pid, blocking_pid) pair. A session waiting on multiple blockers appears on multiple rows -- group/deduplicate by `blocked_pid` if you want a per-blocked-session count.",
+    description: "Show current lock contention: which sessions are blocked and who is blocking them. Returns blocked PID, blocking PID, lock types, relation being contested, and the queries involved. Use this first when a tool call hangs or the app feels stuck - it's the fastest way to identify a long-held transaction holding a lock. Row shape: one row per (blocked_pid, blocking_pid) pair. A session waiting on multiple blockers appears on multiple rows -- group/deduplicate by `blocked_pid` if you want a per-blocked-session count. Caveat on `relation`: for non-relation waits (transactionid/virtualxid, where the wait is on the blocker's xid rather than a table) `relation` is a best-effort hint -- an alphabetical guess among the blocker's held write-intent locks -- not authoritative. Use the blocked/blocking query text to disambiguate which table is actually contested.",
     annotations: {
       title: "Inspect blocking locks",
       readOnlyHint: true,
@@ -36547,7 +36569,7 @@ var adminTools = [
            table_name AS "table",
            grantee,
            privilege_type,
-           is_grantable::boolean AS is_grantable
+           (is_grantable = 'YES') AS is_grantable
          FROM information_schema.table_privileges
          WHERE table_schema = $1
            ${tableFilter}
@@ -36669,7 +36691,7 @@ var adminTools = [
   },
   {
     name: "pg_advisor",
-    description: "Rolled-up DBA lint pass. One call returns three categories of findings:\n- sequence_exhaustion: SERIAL / BIGSERIAL / IDENTITY sequences whose `last_value` is above `seqExhaustionThreshold` of `max_value`. The classic incident class.\n- tables_without_primary_key: user tables with no PK. Bloat candidates and a sign of design drift; some replication setups also need PKs.\n- public_tables_without_rls: tables in `public` (or any schema in `rlsSchemas`) with row-level security disabled. Useful as a security baseline check.\nUse this as the 'what should I be looking at?' starting point, then drill into `pg_unused_indexes`, `pg_table_bloat`, `pg_seq_scan_tables` for the perf side.",
+    description: "Rolled-up DBA lint pass. One call returns three categories of findings:\n- sequence_exhaustion: SERIAL / BIGSERIAL / IDENTITY sequences whose `last_value` is above `seqExhaustionThreshold` of `max_value`. The classic incident class.\n- tables_without_primary_key: user tables (plain and partitioned) with no PK defined. Bloat candidates and a sign of design drift; some replication setups also need PKs. Foreign tables are excluded -- PostgreSQL forbids declaring PKs on foreign tables.\n- public_tables_without_rls: tables in `public` (or any schema in `rlsSchemas`) with row-level security disabled. Useful as a security baseline check.\nUse this as the 'what should I be looking at?' starting point, then drill into `pg_unused_indexes`, `pg_table_bloat`, `pg_seq_scan_tables` for the perf side.",
     annotations: {
       title: "Database advisor (DBA lints)",
       readOnlyHint: true,
@@ -36692,6 +36714,11 @@ var adminTools = [
             // Divide in `numeric`, not `float8`: BIGINT sequences past 2^53 lose
             // precision in float8, and the danger zone (>= threshold) is exactly
             // where the reported pct_used must stay accurate.
+            // Filter vs display precision differ on purpose: the WHERE clause
+            // tests the full-precision ratio while the SELECT rounds pct_used
+            // to numeric(6,4) for display. So a displayed 0.5000 may correspond
+            // to a true ratio slightly above the threshold -- the filter is
+            // correct, the display is rounded.
             `SELECT
                schemaname AS schema,
                sequencename AS sequence,
@@ -36717,6 +36744,10 @@ var adminTools = [
             // Partition children (relkind='r') inherit the parent's PK as an
             // indisprimary index on the child, so the NOT EXISTS clause keeps
             // already filtering them out.
+            //
+            // Foreign tables (relkind='f') are excluded: PostgreSQL forbids
+            // PRIMARY KEY (and UNIQUE) constraints on foreign tables entirely,
+            // so they would always appear here with no possible remediation.
             `SELECT
                n.nspname AS schema,
                c.relname AS "table"
@@ -36765,7 +36796,7 @@ var adminTools = [
   },
   {
     name: "pg_table_bloat",
-    description: "Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM. Cheap - uses `pg_stat_user_tables`, no extensions required.",
+    description: "Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM.\n\nThree methods are available via the `method` parameter:\n- `estimate` (default): reads pg_stat_user_tables -- fast, no extensions, ANALYZE-driven approximations. Use this first.\n- `approx`: uses pgstattuple_approx() -- fast sampling pass, more accurate than estimates, requires the pgstattuple extension.\n- `exact`: uses pgstattuple() -- full table scan, exact counts, slow on large tables, requires the pgstattuple extension. Always pass `schema` with method='exact' -- scanning all user tables in one statement will hit statement_timeout on non-trivial databases.\nInstall pgstattuple with `CREATE EXTENSION pgstattuple` (requires superuser).",
     annotations: {
       title: "Estimate table bloat",
       readOnlyHint: true,
@@ -36776,13 +36807,60 @@ var adminTools = [
     inputSchema: external_exports.object({
       schema: identSchema.optional().describe("Limit to one schema. If omitted, all user schemas are included."),
       minDeadRatio: external_exports.number().min(0).max(1).default(0.1).describe("Minimum dead-tuple fraction to include - dead / (live + dead). Default 0.1 = 10%."),
-      limit: external_exports.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
+      limit: external_exports.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50)."),
+      method: external_exports.enum(["estimate", "approx", "exact"]).default("estimate").describe(
+        "Bloat measurement method. 'estimate' (default) uses pg_stat_user_tables (fast, no extensions). 'approx' uses pgstattuple_approx() (fast sampling, more accurate). 'exact' uses pgstattuple() (full scan, exact but slow). Both 'approx' and 'exact' require the pgstattuple extension."
+      )
     }),
     handler: async (input) => {
-      const { schema, minDeadRatio, limit } = input;
+      const {
+        schema,
+        minDeadRatio,
+        limit,
+        method: rawMethod
+      } = input;
+      const method = rawMethod ?? "estimate";
       const schemaFilter = schema ? "AND schemaname = $3" : "AND schemaname NOT IN ('pg_catalog', 'information_schema') AND schemaname NOT LIKE 'pg_%'";
       const params = [minDeadRatio, limit];
       if (schema) params.push(schema);
+      if (method !== "estimate") {
+        const check2 = await runInternal(
+          `SELECT EXISTS (
+             SELECT 1 FROM pg_catalog.pg_extension WHERE extname = 'pgstattuple'
+           ) AS installed`
+        );
+        if (!check2.ok) return check2;
+        if (!check2.data?.[0]?.installed) {
+          return {
+            ok: false,
+            error: `pgstattuple extension is not installed. Install with \`CREATE EXTENSION pgstattuple;\` (requires superuser), then retry with method='${method}'.`
+          };
+        }
+        const fn = method === "approx" ? "pgstattuple_approx" : "pgstattuple";
+        const liveTuplesCol = method === "approx" ? "approx_tuple_count" : "tuple_count";
+        return runInternal(
+          `SELECT
+             s.schemaname AS schema,
+             s.relname AS "table",
+             (p.${liveTuplesCol})::text AS live_tuples,
+             p.dead_tuple_count::text AS dead_tuples,
+             (p.dead_tuple_count::float8 / NULLIF(p.${liveTuplesCol} + p.dead_tuple_count, 0))::numeric(6, 3)::float8 AS dead_ratio,
+             pg_size_pretty(pg_total_relation_size(s.relid)) AS size_pretty,
+             pg_total_relation_size(s.relid)::text AS size_bytes,
+             s.last_vacuum::text AS last_vacuum,
+             s.last_autovacuum::text AS last_autovacuum,
+             s.last_analyze::text AS last_analyze
+           FROM pg_catalog.pg_stat_user_tables s
+           JOIN pg_catalog.pg_class c ON c.oid = s.relid AND c.relkind IN ('r', 'm')
+           CROSS JOIN LATERAL ${fn}(s.relid::regclass) p
+           WHERE (p.${liveTuplesCol} + p.dead_tuple_count) > 0
+             AND (p.dead_tuple_count::float8 / NULLIF(p.${liveTuplesCol} + p.dead_tuple_count, 0)) >= $1
+             ${schemaFilter}
+           ORDER BY p.dead_tuple_count DESC
+           LIMIT $2`,
+          params
+        );
+      }
       return runInternal(
         // dead_ratio = dead / (live + dead): bounded [0, 1]. A 100%-dead table
         // (live=0, dead>0) correctly reports 1.0 instead of 0. Tables with both
@@ -36828,10 +36906,14 @@ function quoteQualifiedTable(name) {
   return name.split(".").map((p) => quoteIdent(p)).join(".");
 }
 function validateHypoIndex(idx) {
-  for (const piece of idx.table.split(".")) {
-    if (piece.includes('"')) {
-      return `Hypothetical index table ${JSON.stringify(idx.table)} contains a double-quote; pass plain identifier names without pre-quoting.`;
-    }
+  if (idx.table.includes('"')) {
+    return `Hypothetical index table ${JSON.stringify(idx.table)} contains a double-quote; pass plain identifier names without pre-quoting.`;
+  }
+  const pieces = idx.table.split(".");
+  if (pieces.length > 2) {
+    return `Hypothetical index table ${JSON.stringify(idx.table)} is over-qualified; use only \`schema.table\` or \`table\`.`;
+  }
+  for (const piece of pieces) {
     if (Buffer.byteLength(piece, "utf8") > 63) {
       return `Hypothetical index table piece ${JSON.stringify(piece)} exceeds PostgreSQL's 63-byte NAMEDATALEN limit (multi-byte characters count as multiple bytes).`;
     }
@@ -36889,7 +36971,15 @@ var explainTools = [
       )
     }),
     handler: async (input) => {
-      const { sql, analyze, format, params, hypothetical_indexes } = input;
+      const {
+        sql,
+        analyze: rawAnalyze,
+        format: rawFormat,
+        params,
+        hypothetical_indexes
+      } = input;
+      const analyze = rawAnalyze ?? false;
+      const format = rawFormat ?? "text";
       if (/^\s*EXPLAIN\b/i.test(sql)) {
         return {
           ok: false,
@@ -36929,6 +37019,9 @@ var explainTools = [
       }
       if (format === "text") {
         const lines = rows.map((r) => String(r["QUERY PLAN"] ?? ""));
+        if (result.data.truncated) {
+          lines.push(`... [plan truncated at ${rows.length} lines; raise POSTGRES_MAX_ROWS to see the full plan]`);
+        }
         return { ok: true, data: { plan: lines.join("\n") } };
       }
       const jsonPlan = rows[0]?.["QUERY PLAN"];
@@ -37000,6 +37093,9 @@ var healthTools = [
         ]);
         if (!versionRes.ok) return versionRes;
         const warnings = [];
+        if (versionRes.data?.[0]?.version === void 0) {
+          warnings.push(`version unavailable despite successful query`);
+        }
         if (!sizeRes.ok) warnings.push(`database fetch failed: ${sizeRes.error}`);
         if (!connsRes.ok) warnings.push(`connections fetch failed: ${connsRes.error}`);
         if (!activeRes.ok) warnings.push(`active_queries fetch failed: ${activeRes.error}`);
@@ -37044,7 +37140,7 @@ var queryTools = [
   },
   {
     name: "pg_query",
-    description: "Run a SQL query against the configured PostgreSQL database. Writes are gated by the role in `DATABASE_URL` first and `ALLOW_WRITES` second: a role created with `GRANT pg_read_all_data` makes writes server-rejected regardless of `ALLOW_WRITES`, and is the recommended way to scope agent access. `ALLOW_WRITES=1` is a secondary belt-and-braces gate - useful for managed databases where creating a second role is awkward. For read-only access where you want the guarantee in the tool name, prefer `pg_readonly`. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Dates and UUIDs can be passed as ISO strings. Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
+    description: "Run a SQL query against the configured PostgreSQL database. Postgres itself is the primary safety gate: the role in `DATABASE_URL` enforces what queries can succeed. The recommended posture is a least-privileged role (e.g. one granted `pg_read_all_data`), which makes writes server-rejected regardless of any env var. `ALLOW_WRITES=1` is a secondary belt-and-braces gate - it lifts the in-server `BEGIN READ ONLY` wrapper, but it cannot grant privileges the role lacks. Useful for managed databases where creating a second role is awkward. For read-only access where you want the guarantee in the tool name, prefer `pg_readonly`. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Dates and UUIDs can be passed as ISO strings. Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
     annotations: {
       title: "Run SQL query",
       readOnlyHint: false,
@@ -37095,7 +37191,7 @@ var schemaTools = [
   },
   {
     name: "pg_list_tables",
-    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; approximate - 0 until ANALYZE runs). Paginate via `limit`/`offset` on very large schemas.",
+    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; null = no ANALYZE yet on PG 14+; 0 may mean empty or unanalyzed on PG <= 13). Paginate via `limit`/`offset` on very large schemas.",
     annotations: {
       title: "List tables in a schema",
       readOnlyHint: true,
@@ -37123,7 +37219,7 @@ var schemaTools = [
              WHEN 'p' THEN 'partitioned_table'
              ELSE c.relkind::text
            END AS type,
-           c.reltuples::bigint AS estimated_rows
+           NULLIF(round(c.reltuples), -1)::float8 AS estimated_rows
          FROM pg_catalog.pg_class c
          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
          WHERE n.nspname = $1
@@ -37204,6 +37300,10 @@ var schemaTools = [
         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
         JOIN pg_catalog.pg_class cl ON cl.oid = con.confrelid
         JOIN pg_catalog.pg_namespace fn ON fn.oid = cl.relnamespace
+        -- Pairing local conkey[i] to foreign confkey[i] by ordinality relies on
+        -- the postgres invariant that conkey[i] references confkey[i]. unnest
+        -- WITH ORDINALITY preserves array order; reordering or dropping
+        -- WITH ORDINALITY would silently mispair composite-FK columns.
         JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS u(attnum, attposition) ON TRUE
         JOIN pg_catalog.pg_attribute att ON att.attrelid = con.conrelid AND att.attnum = u.attnum
         JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS fu(attnum, attposition) ON fu.attposition = u.attposition
@@ -37258,6 +37358,10 @@ var schemaTools = [
         JOIN pg_catalog.pg_namespace srcn ON srcn.oid = src.relnamespace
         JOIN pg_catalog.pg_class ref ON ref.oid = con.confrelid
         JOIN pg_catalog.pg_namespace refn ON refn.oid = ref.relnamespace
+        -- Pairing local conkey[i] to foreign confkey[i] by ordinality relies on
+        -- the postgres invariant that conkey[i] references confkey[i]. unnest
+        -- WITH ORDINALITY preserves array order; reordering or dropping
+        -- WITH ORDINALITY would silently mispair composite-FK columns.
         JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS u(attnum, attposition) ON TRUE
         JOIN pg_catalog.pg_attribute srcatt ON srcatt.attrelid = con.conrelid AND srcatt.attnum = u.attnum
         JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS fu(attnum, attposition) ON fu.attposition = u.attposition
@@ -37318,6 +37422,7 @@ var schemaTools = [
         const kind = kindRes.ok ? kindRes.data?.[0]?.kind ?? "table" : "table";
         const warnings = [];
         if (!kindRes.ok) warnings.push(`kind fetch failed, reported as "table": ${kindRes.error}`);
+        else if ((kindRes.data?.length ?? 0) === 0) warnings.push(`kind unavailable, reported as "table"`);
         if (!pk.ok) warnings.push(`primary_key fetch failed: ${pk.error}`);
         if (!fks.ok) warnings.push(`foreign_keys fetch failed: ${fks.error}`);
         if (!idxs.ok) warnings.push(`indexes fetch failed: ${idxs.error}`);
@@ -37486,7 +37591,7 @@ var schemaTools = [
 var statsTools = [
   {
     name: "pg_top_queries",
-    description: "Top N queries by total or mean execution time. Requires the `pg_stat_statements` extension to be installed and enabled (most managed Postgres providers have it on by default). Returns normalized query text (constants replaced with `?`), call count, total/mean/min/max time in ms, rows returned, and cache hit ratio. Use this to find slow queries worth optimizing.",
+    description: "Top N queries by total or mean execution time. Requires the `pg_stat_statements` extension to be installed and enabled (most managed Postgres providers have it on by default). Returns normalized query text (constants replaced with `?`), call count, total/mean/min/max time in ms, rows returned, and cache hit ratio. Use this to find slow queries worth optimizing. On pg_stat_statements >= 1.10 (Postgres 15+), also returns `io_read_time_ms` and `io_write_time_ms` to separate IO-bound from CPU-bound queries (null when track_io_timing = off or the query did no measurable IO -- enable track_io_timing in postgresql.conf to get non-null values).",
     annotations: {
       title: "Top queries by execution time",
       readOnlyHint: true,
@@ -37516,6 +37621,11 @@ var statsTools = [
       const meanCol = useExecSuffix ? "mean_exec_time" : "mean_time";
       const minCol = useExecSuffix ? "min_exec_time" : "min_time";
       const maxCol = useExecSuffix ? "max_exec_time" : "max_time";
+      const hasIoTiming = compareVersions(extVersion, "1.10") >= 0;
+      const hasSharedBlkCols = compareVersions(extVersion, "1.11") >= 0;
+      const ioTimingCols = hasIoTiming ? `,
+           NULLIF(${hasSharedBlkCols ? "shared_blk_read_time" : "blk_read_time"}, 0)::numeric(18, 2)::float8 AS io_read_time_ms,
+           NULLIF(${hasSharedBlkCols ? "shared_blk_write_time" : "blk_write_time"}, 0)::numeric(18, 2)::float8 AS io_write_time_ms` : "";
       const orderCol = orderBy === "total_time" ? totalCol : orderBy === "mean_time" ? meanCol : "pg_stat_statements.calls";
       return runInternal(
         // bigint counters (calls, rows) come back as `.text` for lossless
@@ -37534,7 +37644,7 @@ var statsTools = [
              WHEN (shared_blks_hit + shared_blks_read) > 0
              THEN (shared_blks_hit::float8 / (shared_blks_hit + shared_blks_read) * 100)::numeric(5, 2)::float8
              ELSE NULL
-           END AS hit_percent
+           END AS hit_percent${ioTimingCols}
          FROM pg_stat_statements
          ORDER BY ${orderCol} DESC NULLS LAST
          LIMIT $1`,
@@ -37641,7 +37751,7 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.6.19" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.7.0" : await readPackageVersion();
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -37662,10 +37772,18 @@ for (const tool of allTools) {
   );
 }
 var transport = new StdioServerTransport();
-await server.connect(transport);
-var writesNote = isWritesAllowed() ? "writes ENABLED" : "read-only";
-console.error(`@yawlabs/postgres-mcp v${version2} ready (${allTools.length} tools, ${writesNote})`);
+server.connect(transport).then(() => {
+  const writesNote = isWritesAllowed() ? "writes ENABLED" : "read-only";
+  console.error(`@yawlabs/postgres-mcp v${version2} ready (${allTools.length} tools, ${writesNote})`);
+}).catch((err) => {
+  process.stderr.write(`postgres-mcp: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});
+var exiting = false;
 var cleanup = async () => {
+  if (exiting) return;
+  exiting = true;
   try {
     await shutdown();
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/postgres-mcp",
-  "version": "0.6.19",
+  "version": "0.7.0",
   "mcpName": "io.github.YawLabs/postgres-mcp",
   "description": "PostgreSQL MCP server - query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "@types/pg": "^8.20.0",
     "esbuild": "^0.28.0",
     "pg": "^8.14.0",
+    "postject": "^1.0.0-alpha.6",
     "typescript": "^6.0.3",
     "zod": "^4.3.6"
   },