@yawlabs/postgres-mcp 0.1.1 → 0.3.1

package/README.md

@@ -75,16 +75,41 @@ Read-only is the default. If you want the agent to be able to `INSERT`, `UPDATE`
 
 Prefer scoping this to dev/test databases — for production, leave writes off and use migration tools out-of-band.
 
+## What can an agent do with this?
+
+Once connected, the agent picks tools automatically based on what you ask. A few real examples:
+
+- **"Describe the users table"** -> `pg_describe_table` -> returns columns, PK, FKs, indexes.
+- **"Which tables have a `user_id` column?"** -> `pg_search_columns` with pattern `user_id` -> one call instead of iterating every table.
+- **"This query is slow, why?"** -> `pg_explain` with `analyze: true` -> returns the plan with actual row counts and timing.
+- **"What's the slowest query we run?"** -> `pg_top_queries` -> returns the top N from `pg_stat_statements` with mean/total/min/max times.
+- **"Why is my app hanging?"** -> `pg_inspect_locks` -> returns blocked PIDs and the queries holding their locks; follow up with `pg_kill` (with `ALLOW_WRITES=1`) to cancel the blocker.
+- **"Do we have any unused indexes?"** -> `pg_unused_indexes` -> returns non-unique, non-primary indexes with zero or low scan counts + their size.
+- **"Is `pgvector` installed?"** -> `pg_list_extensions` -> yes/no with version.
+
 ## Tools
 
 | Tool | Description |
 |------|-------------|
 | `pg_query` | Run a SQL query. Read-only by default; writes require `ALLOW_WRITES=1`. Supports parameterized queries via `params`. |
 | `pg_list_schemas` | List non-system schemas. |
-| `pg_list_tables` | List tables (and optionally views) in a schema with estimated row counts. |
+| `pg_list_tables` | List tables (and optionally views) in a schema with estimated row counts. Paginated via `limit`/`offset`. |
 | `pg_describe_table` | Columns, primary key, foreign keys, and indexes for a table. |
+| `pg_list_views` | List views and materialized views in a schema, including their SQL definitions. |
+| `pg_list_functions` | List functions, procedures, and aggregates in a schema with signatures and return types. |
+| `pg_list_extensions` | List installed extensions (pgvector, postgis, pg_stat_statements, etc.) with versions. |
+| `pg_search_columns` | Find columns by name pattern across all user schemas. Case-insensitive, supports SQL LIKE wildcards. |
 | `pg_explain` | `EXPLAIN` or `EXPLAIN ANALYZE` for a SQL statement. Text or JSON output. |
 | `pg_health` | Server version, database size, connection count, active queries, table count. |
+| `pg_top_queries` | Top N queries by total/mean execution time. Requires the `pg_stat_statements` extension. |
+| `pg_seq_scan_tables` | Tables with heavy sequential scans — missing-index candidates. |
+| `pg_unused_indexes` | Non-unique, non-primary indexes with low scan counts — drop candidates. |
+| `pg_inspect_locks` | Who is blocking whom right now (blocked PID, blocker PID, lock type, queries). |
+| `pg_list_roles` | Database roles with login/superuser/createdb flags and group memberships. |
+| `pg_table_privileges` | Who has SELECT/INSERT/UPDATE/DELETE/etc. on a table or whole schema. |
+| `pg_table_bloat` | Tables with high dead-tuple ratios — VACUUM candidates. |
+| `pg_replication_status` | Replication slots, connected replicas, and current WAL position. |
+| `pg_kill` | Cancel a running query or terminate a backend connection. Requires `ALLOW_WRITES=1`. |
 
 ## Configuration
 
@@ -96,8 +121,43 @@ All env vars are read from the MCP server's environment:
 | `ALLOW_WRITES` | unset | Set to `1` or `true` to allow DML/DDL via `pg_query` and `pg_explain` ANALYZE of writes. |
 | `POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-statement timeout. |
 | `POSTGRES_MAX_ROWS` | `1000` | Cap on rows returned by `pg_query`. |
+| `POSTGRES_POOL_MAX` | `5` | Max pool connections. Set to `1` for single-threaded backends (pglite-socket, PgBouncer transaction mode). |
+| `POSTGRES_SSL_REJECT_UNAUTHORIZED` | unset | Set to `false` to skip TLS cert verification (for managed DBs using private-CA certs). Connection is still encrypted. |
+
+### Connecting to managed Postgres (Supabase, Neon, RDS, etc.)
+
+Most managed databases require TLS but serve certs signed by a private CA that Node's default trust store doesn't recognize. The symptom is one of:
+
+- `self signed certificate in certificate chain`
+- `unable to get local issuer certificate`
+- `unable to verify the first certificate`
+
+To allow the connection while keeping traffic encrypted, add `POSTGRES_SSL_REJECT_UNAUTHORIZED=false` to the `env` block:
+
+```json
+"env": {
+  "DATABASE_URL": "postgres://user:pass@host:5432/db?sslmode=require",
+  "POSTGRES_SSL_REJECT_UNAUTHORIZED": "false"
+}
+```
+
+This disables certificate chain verification only -- the TCP connection is still TLS-encrypted end-to-end. For production setups where you can install the CA, prefer putting the cert in the Node trust store (`NODE_EXTRA_CA_CERTS`) over disabling verification globally.
+
+## Troubleshooting
+
+**`DATABASE_URL is not set`** — Your MCP client is launching the server without the env var. On Windows especially, env vars set in bash / PowerShell profiles are not inherited by MCP servers launched via `cmd`. Put `DATABASE_URL` directly in the `env` block of `.mcp.json`.
+
+**`password authentication failed`** — Check the username, password, and that the user has `CONNECT` privilege on the database. URL-encode special characters in the password (`@` → `%40`, `#` → `%23`, `/` → `%2F`).
+
+**`SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string`** — The password in your connection string is empty or became `null` after URL decoding. Re-check your connection string.
+
+**`canceling statement due to statement timeout`** — A single query exceeded `POSTGRES_STATEMENT_TIMEOUT_MS` (default 30s). Increase it, narrow the query with `WHERE`, or add an index. This is working as designed -- the timeout exists so a runaway query cannot hang the agent.
+
+**`Write blocked: this server is in read-only mode`** — You asked the agent to write but `ALLOW_WRITES` is not set. Add `ALLOW_WRITES=1` to the `env` block of `.mcp.json` and restart your MCP client. Only do this for dev/test DBs.
+
+**Connection pool exhaustion with PgBouncer transaction mode or pglite-socket** — These backends don't support concurrent queries on a single connection. Set `POSTGRES_POOL_MAX=1` in the env block.
 
-SSL is handled by the `pg` driver based on the connection string — use `?sslmode=require` (or equivalent) in `DATABASE_URL` for cloud-hosted databases.
+**First query is slow, subsequent queries are fast** — Expected. The pg driver lazily establishes the first connection; subsequent queries reuse the pool.
 
 ## License
 

package/dist/index.js

@@ -35271,13 +35271,25 @@ function isWritesAllowed() {
   const v = process.env.ALLOW_WRITES;
   return v === "1" || v === "true";
 }
+function getSslConfig() {
+  const raw = process.env.POSTGRES_SSL_REJECT_UNAUTHORIZED;
+  if (raw === void 0) return void 0;
+  if (raw === "0" || raw === "false") return { rejectUnauthorized: false };
+  if (raw === "1" || raw === "true") return { rejectUnauthorized: true };
+  return void 0;
+}
 function getPool() {
   if (pool) return pool;
+  const ssl = getSslConfig();
   pool = new esm_default.Pool({
     connectionString: getDatabaseUrl(),
     statement_timeout: getStatementTimeoutMs(),
     max: getPoolMax(),
-    idleTimeoutMillis: 1e4
+    // MCP sessions can have minutes-long gaps between tool calls. A short
+    // idleTimeout forces a reconnect on every tool call. 60s keeps the pool
+    // warm without holding connections indefinitely.
+    idleTimeoutMillis: 6e4,
+    ...ssl ? { ssl } : {}
   });
   pool.on("error", (err) => {
     console.error(`[postgres-mcp] pool error: ${err.message}`);
@@ -35364,11 +35376,275 @@ async function shutdown() {
   }
 }
 
+// src/tools/admin.ts
+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 \u2014 it's the fastest way to identify a long-held transaction holding a lock.",
+    annotations: {
+      title: "Inspect blocking locks",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      limit: external_exports3.number().int().min(1).max(100).default(50).describe("Max blocked/blocker pairs (default 50).")
+    }),
+    handler: async (input) => {
+      const { limit } = input;
+      return runInternal(
+        `SELECT
+           blocked.pid AS blocked_pid,
+           blocked.usename AS blocked_user,
+           blocked.query AS blocked_query,
+           EXTRACT(EPOCH FROM (now() - blocked.query_start))::numeric(10, 2)::float8 AS blocked_duration_seconds,
+           blocking.pid AS blocking_pid,
+           blocking.usename AS blocking_user,
+           blocking.query AS blocking_query,
+           blocking.state AS blocking_state,
+           EXTRACT(EPOCH FROM (now() - blocking.query_start))::numeric(10, 2)::float8 AS blocking_duration_seconds,
+           CASE
+             WHEN bl.relation IS NOT NULL
+               THEN (SELECT n.nspname || '.' || c.relname
+                     FROM pg_catalog.pg_class c
+                     JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+                     WHERE c.oid = bl.relation)
+             ELSE NULL
+           END AS relation,
+           bl.locktype AS lock_type
+         FROM pg_catalog.pg_locks bl
+         JOIN pg_catalog.pg_stat_activity blocked ON blocked.pid = bl.pid
+         JOIN LATERAL unnest(pg_blocking_pids(bl.pid)) AS bpid(pid) ON TRUE
+         JOIN pg_catalog.pg_stat_activity blocking ON blocking.pid = bpid.pid
+         WHERE NOT bl.granted
+         ORDER BY blocked.query_start NULLS LAST
+         LIMIT $1`,
+        [limit]
+      );
+    }
+  },
+  {
+    name: "pg_list_roles",
+    description: "List database roles (users and groups) with their login/superuser/createdb/createrole attributes and inherited role memberships. Use this to answer 'who has access to this database?' without needing to read `pg_authid` directly.",
+    annotations: {
+      title: "List roles",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      includeSystem: external_exports3.boolean().default(false).describe("If true, include built-in `pg_*` roles (pg_read_all_data, pg_monitor, etc.).")
+    }),
+    handler: async (input) => {
+      const { includeSystem } = input;
+      const filter = includeSystem ? "" : "WHERE NOT starts_with(r.rolname, 'pg_')";
+      return runInternal(
+        // Cast member_of to text[] so node-pg parses it into a JS array.
+        // Without the cast, it comes back as the postgres text form `{a,b}`.
+        `SELECT
+           r.rolname AS name,
+           r.rolcanlogin AS can_login,
+           r.rolsuper AS superuser,
+           r.rolcreatedb AS createdb,
+           r.rolcreaterole AS createrole,
+           r.rolreplication AS replication,
+           r.rolbypassrls AS bypass_rls,
+           COALESCE(
+             (SELECT array_agg(g.rolname::text ORDER BY g.rolname)
+              FROM pg_catalog.pg_auth_members m
+              JOIN pg_catalog.pg_roles g ON g.oid = m.roleid
+              WHERE m.member = r.oid),
+             ARRAY[]::text[]
+           ) AS member_of
+         FROM pg_catalog.pg_roles r
+         ${filter}
+         ORDER BY r.rolname`
+      );
+    }
+  },
+  {
+    name: "pg_table_privileges",
+    description: "Show which roles have which privileges (SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER) on a table or on all tables in a schema. Use this to answer 'who can write to this table?' or to audit schema-wide access before a migration.",
+    annotations: {
+      title: "Show table privileges",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      schema: external_exports3.string().min(1).max(63).default("public").describe("Schema name (defaults to 'public')."),
+      table: external_exports3.string().min(1).max(63).optional().describe("Table name. Omit to list privileges for all tables in the schema.")
+    }),
+    handler: async (input) => {
+      const { schema, table } = input;
+      const tableFilter = table ? "AND table_name = $2" : "";
+      const params = [schema];
+      if (table) params.push(table);
+      return runInternal(
+        `SELECT
+           table_name AS "table",
+           grantee,
+           privilege_type,
+           is_grantable::boolean AS is_grantable
+         FROM information_schema.table_privileges
+         WHERE table_schema = $1
+           ${tableFilter}
+         ORDER BY table_name, grantee, privilege_type`,
+        params
+      );
+    }
+  },
+  {
+    name: "pg_kill",
+    description: "Cancel a running query (SIGINT-equivalent) or terminate a backend connection (SIGTERM-equivalent) by PID. Find the PID via `pg_health` active_queries or `pg_inspect_locks`. Requires ALLOW_WRITES=1 since this changes database session state. The role in DATABASE_URL must have permission \u2014 cancelling another user's query needs the `pg_signal_backend` role or superuser. Cancel is graceful; terminate is forceful.",
+    annotations: {
+      title: "Cancel or terminate a backend",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      pid: external_exports3.number().int().min(1).describe("Backend PID to signal."),
+      mode: external_exports3.enum(["cancel", "terminate"]).default("cancel").describe("`cancel` aborts the current query; `terminate` closes the connection entirely.")
+    }),
+    handler: async (input) => {
+      const { pid, mode } = input;
+      if (!isWritesAllowed()) {
+        return {
+          ok: false,
+          error: "pg_kill requires ALLOW_WRITES=1 because cancelling or terminating a backend changes session state. Set ALLOW_WRITES=1 in the MCP server env."
+        };
+      }
+      const fn = mode === "terminate" ? "pg_terminate_backend" : "pg_cancel_backend";
+      const result = await runInternal(`SELECT ${fn}($1) AS signaled`, [pid]);
+      if (!result.ok) return result;
+      const signaled = result.data?.[0]?.signaled === true;
+      return {
+        ok: true,
+        data: {
+          pid,
+          mode,
+          signaled,
+          note: signaled ? `Sent ${mode === "terminate" ? "SIGTERM" : "SIGINT"} to backend ${pid}.` : `Signal returned false \u2014 PID ${pid} may not exist, may already be gone, or the current role lacks permission.`
+        }
+      };
+    }
+  },
+  {
+    name: "pg_replication_status",
+    description: "Replication overview: configured replication slots, connected replicas (from `pg_stat_replication`), and current WAL position. Use on primary to spot lagging or disconnected replicas, on replicas to see upstream status. Returns empty arrays on a standalone (non-replicated) database rather than erroring.",
+    annotations: {
+      title: "Replication status",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({}),
+    handler: async () => {
+      const [slotsRes, replicasRes, walRes] = await Promise.all([
+        runInternal(
+          `SELECT
+             slot_name, slot_type, active,
+             restart_lsn::text AS restart_lsn,
+             confirmed_flush_lsn::text AS confirmed_flush_lsn,
+             wal_status, database, plugin
+           FROM pg_catalog.pg_replication_slots
+           ORDER BY slot_name`
+        ),
+        runInternal(
+          `SELECT
+             application_name,
+             client_addr::text AS client_addr,
+             state,
+             sync_state,
+             EXTRACT(EPOCH FROM write_lag)::numeric(10, 2)::float8 AS write_lag_seconds,
+             EXTRACT(EPOCH FROM flush_lag)::numeric(10, 2)::float8 AS flush_lag_seconds,
+             EXTRACT(EPOCH FROM replay_lag)::numeric(10, 2)::float8 AS replay_lag_seconds
+           FROM pg_catalog.pg_stat_replication
+           ORDER BY application_name`
+        ),
+        runInternal(
+          `SELECT
+             pg_is_in_recovery() AS is_in_recovery,
+             CASE
+               WHEN pg_is_in_recovery() THEN pg_last_wal_receive_lsn()::text
+               ELSE pg_current_wal_lsn()::text
+             END AS wal_position`
+        )
+      ]);
+      if (!slotsRes.ok) return slotsRes;
+      if (!replicasRes.ok) return replicasRes;
+      if (!walRes.ok) return walRes;
+      return {
+        ok: true,
+        data: {
+          is_replica: walRes.data?.[0]?.is_in_recovery ?? false,
+          wal_position: walRes.data?.[0]?.wal_position ?? null,
+          slots: slotsRes.data ?? [],
+          replicas: replicasRes.data ?? []
+        }
+      };
+    }
+  },
+  {
+    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 \u2014 uses `pg_stat_user_tables`, no extensions required.",
+    annotations: {
+      title: "Estimate table bloat",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      schema: external_exports3.string().min(1).max(63).optional().describe("Limit to one schema. If omitted, all user schemas are included."),
+      minDeadRatio: external_exports3.number().min(0).max(1).default(0.1).describe("Minimum dead/live ratio to include (default 0.1 = 10%)."),
+      limit: external_exports3.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
+    }),
+    handler: async (input) => {
+      const { schema, minDeadRatio, limit } = input;
+      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);
+      return runInternal(
+        `SELECT
+           schemaname AS schema,
+           relname AS "table",
+           n_live_tup::text AS live_tuples,
+           n_dead_tup::text AS dead_tuples,
+           CASE
+             WHEN n_live_tup = 0 THEN 0
+             ELSE (n_dead_tup::float8 / GREATEST(n_live_tup, 1))::numeric(6, 3)::float8
+           END AS dead_ratio,
+           pg_size_pretty(pg_total_relation_size(relid)) AS size_pretty,
+           pg_total_relation_size(relid)::text AS size_bytes,
+           last_vacuum::text AS last_vacuum,
+           last_autovacuum::text AS last_autovacuum,
+           last_analyze::text AS last_analyze
+         FROM pg_catalog.pg_stat_user_tables
+         WHERE (n_dead_tup::float8 / GREATEST(n_live_tup, 1)) >= $1
+           ${schemaFilter}
+         ORDER BY n_dead_tup DESC
+         LIMIT $2`,
+        params
+      );
+    }
+  }
+];
+
 // src/tools/explain.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)])
+);
 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`.",
+    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).",
     annotations: {
       title: "Explain query plan",
       readOnlyHint: false,
@@ -35377,13 +35653,19 @@ var explainTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      sql: external_exports3.string().min(1).describe("The SQL statement to explain."),
+      sql: external_exports3.string().min(1).max(1e6).describe("The SQL statement to explain. Do NOT prefix with EXPLAIN."),
       analyze: external_exports3.boolean().default(false).describe("Run EXPLAIN ANALYZE (actually executes the query)."),
       format: external_exports3.enum(["text", "json"]).default("text").describe("Output format."),
-      params: external_exports3.array(external_exports3.union([external_exports3.string(), external_exports3.number(), external_exports3.boolean(), external_exports3.null()])).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, analyze, format, params } = input;
+      if (/^\s*EXPLAIN\b/i.test(sql)) {
+        return {
+          ok: false,
+          error: "The `sql` parameter should be the query to explain, not an EXPLAIN statement. Use the `analyze` and `format` parameters on this tool instead of prefixing the SQL."
+        };
+      }
       const flags = [];
       if (analyze) flags.push("ANALYZE");
       if (format === "json") flags.push("FORMAT JSON");
@@ -35414,8 +35696,11 @@ var healthTools = [
       idempotentHint: true,
       openWorldHint: true
     },
-    inputSchema: external_exports3.object({}),
-    handler: async () => {
+    inputSchema: external_exports3.object({
+      activeQueryLimit: external_exports3.number().int().min(1).max(100).default(10).describe("Max active queries to return (default 10, max 100).")
+    }),
+    handler: async (input) => {
+      const { activeQueryLimit } = input;
       const [versionRes, sizeRes, connsRes, activeRes, tableCountRes] = await Promise.all([
         runInternal(`SELECT version() AS version`),
         runInternal(
@@ -35446,7 +35731,8 @@ var healthTools = [
              AND state <> 'idle'
              AND pid <> pg_backend_pid()
            ORDER BY query_start ASC NULLS LAST
-           LIMIT 10`
+           LIMIT $1`,
+          [activeQueryLimit]
         ),
         runInternal(
           `SELECT count(*)::text AS count
@@ -35474,10 +35760,13 @@ 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",
-    description: "Run a SQL query against the configured PostgreSQL database. Read-only by default (query runs in a READ ONLY transaction). Set ALLOW_WRITES=1 in the MCP server env to enable DML/DDL. Use `params` for parameterized queries to avoid SQL injection. 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. Read-only by default (query runs in a READ ONLY transaction). Set ALLOW_WRITES=1 in the MCP server env to enable DML/DDL. 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,
@@ -35487,8 +35776,8 @@ var queryTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      sql: external_exports3.string().min(1).describe("The SQL statement to execute."),
-      params: external_exports3.array(external_exports3.union([external_exports3.string(), external_exports3.number(), external_exports3.boolean(), external_exports3.null()])).optional().describe("Positional parameters referenced as $1, $2, ... in the SQL.")
+      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.")
     }),
     handler: async (input) => {
       const { sql, params } = input;
@@ -35501,12 +35790,7 @@ var queryTools = [
 ];
 
 // src/tools/schemas.ts
-var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-function validateIdent(value, field) {
-  if (!IDENT_RE.test(value)) {
-    throw new Error(`Invalid ${field}: ${JSON.stringify(value)}. Must match ${IDENT_RE}.`);
-  }
-}
+var identSchema = external_exports3.string().min(1).max(63);
 var schemaTools = [
   {
     name: "pg_list_schemas",
@@ -35534,7 +35818,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.",
+    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; approximate \u2014 0 until ANALYZE runs). Paginate via `limit`/`offset` on very large schemas.",
     annotations: {
       title: "List tables in a schema",
       readOnlyHint: true,
@@ -35543,12 +35827,13 @@ var schemaTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      schema: external_exports3.string().default("public").describe("Schema name (defaults to 'public')."),
-      includeViews: external_exports3.boolean().default(false).describe("If true, include views and materialized views.")
+      schema: identSchema.default("public").describe("Schema name (defaults to 'public')."),
+      includeViews: external_exports3.boolean().default(false).describe("If true, include views and materialized views."),
+      limit: external_exports3.number().int().min(1).max(1e4).default(500).describe("Max rows to return (default 500, max 10000)."),
+      offset: external_exports3.number().int().min(0).default(0).describe("Rows to skip for pagination (default 0).")
     }),
     handler: async (input) => {
-      const { schema, includeViews } = input;
-      validateIdent(schema, "schema");
+      const { schema, includeViews, limit, offset } = input;
       const kinds = includeViews ? "('r', 'v', 'm', 'f', 'p')" : "('r', 'f', 'p')";
       return runInternal(
         `SELECT
@@ -35566,8 +35851,9 @@ var schemaTools = [
          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
          WHERE n.nspname = $1
            AND c.relkind IN ${kinds}
-         ORDER BY c.relname`,
-        [schema]
+         ORDER BY c.relname
+         LIMIT $2 OFFSET $3`,
+        [schema, limit, offset]
       );
     }
   },
@@ -35582,13 +35868,11 @@ var schemaTools = [
       openWorldHint: true
     },
     inputSchema: external_exports3.object({
-      schema: external_exports3.string().default("public").describe("Schema name (defaults to 'public')."),
-      table: external_exports3.string().describe("Table name.")
+      schema: identSchema.default("public").describe("Schema name (defaults to 'public')."),
+      table: identSchema.describe("Table name.")
     }),
     handler: async (input) => {
       const { schema, table } = input;
-      validateIdent(schema, "schema");
-      validateIdent(table, "table");
       const columnsQuery = `
         SELECT
           a.attname AS name,
@@ -35620,10 +35904,10 @@ var schemaTools = [
       const foreignKeysQuery = `
         SELECT
           con.conname AS constraint_name,
-          array_agg(att.attname ORDER BY u.attposition) AS columns,
+          array_agg(att.attname::text ORDER BY u.attposition) AS columns,
           cl.relname AS foreign_table,
           fn.nspname AS foreign_schema,
-          array_agg(fatt.attname ORDER BY u.attposition) AS foreign_columns
+          array_agg(fatt.attname::text ORDER BY u.attposition) AS foreign_columns
         FROM pg_catalog.pg_constraint con
         JOIN pg_catalog.pg_class c ON c.oid = con.conrelid
         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
@@ -35663,6 +35947,10 @@ var schemaTools = [
       if (!cols.data || cols.data.length === 0) {
         return { ok: false, error: `Table "${schema}"."${table}" not found.` };
       }
+      const warnings = [];
+      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}`);
       return {
         ok: true,
         data: {
@@ -35671,21 +35959,314 @@ var schemaTools = [
           columns: cols.data,
           primary_key: pk.ok ? (pk.data ?? []).map((r) => r.column_name) : [],
           foreign_keys: fks.ok ? fks.data : [],
-          indexes: idxs.ok ? idxs.data : []
+          indexes: idxs.ok ? idxs.data : [],
+          ...warnings.length > 0 ? { _warnings: warnings } : {}
         }
       };
     }
+  },
+  {
+    name: "pg_list_views",
+    description: "List views and materialized views in a schema with their SQL definitions. Use this over `pg_list_tables` with `includeViews: true` when you want the view body, not just names.",
+    annotations: {
+      title: "List views with definitions",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      schema: identSchema.default("public").describe("Schema name (defaults to 'public')."),
+      includeMaterialized: external_exports3.boolean().default(true).describe("If true, include materialized views.")
+    }),
+    handler: async (input) => {
+      const { schema, includeMaterialized } = input;
+      const kinds = includeMaterialized ? "('v', 'm')" : "('v')";
+      return runInternal(
+        `SELECT
+           c.relname AS name,
+           CASE c.relkind WHEN 'v' THEN 'view' WHEN 'm' THEN 'materialized_view' END AS type,
+           pg_catalog.pg_get_viewdef(c.oid, true) AS definition
+         FROM pg_catalog.pg_class c
+         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+         WHERE n.nspname = $1
+           AND c.relkind IN ${kinds}
+         ORDER BY c.relname`,
+        [schema]
+      );
+    }
+  },
+  {
+    name: "pg_list_functions",
+    description: "List functions, procedures, and aggregates in a schema. Returns name, arguments, return type, kind (function/procedure/aggregate/window), and implementation language.",
+    annotations: {
+      title: "List functions and procedures",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      schema: identSchema.default("public").describe("Schema name (defaults to 'public').")
+    }),
+    handler: async (input) => {
+      const { schema } = input;
+      return runInternal(
+        `SELECT
+           p.proname AS name,
+           pg_catalog.pg_get_function_arguments(p.oid) AS arguments,
+           pg_catalog.pg_get_function_result(p.oid) AS return_type,
+           CASE p.prokind
+             WHEN 'f' THEN 'function'
+             WHEN 'p' THEN 'procedure'
+             WHEN 'a' THEN 'aggregate'
+             WHEN 'w' THEN 'window'
+             ELSE p.prokind::text
+           END AS kind,
+           l.lanname AS language
+         FROM pg_catalog.pg_proc p
+         JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+         JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+         WHERE n.nspname = $1
+         ORDER BY p.proname, p.oid`,
+        [schema]
+      );
+    }
+  },
+  {
+    name: "pg_list_extensions",
+    description: "List installed PostgreSQL extensions. Returns name, version, schema, and description. Useful to check for pgvector, postgis, pg_stat_statements, uuid-ossp, etc. before writing queries that rely on them.",
+    annotations: {
+      title: "List installed extensions",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({}),
+    handler: async () => {
+      return runInternal(
+        `SELECT
+           e.extname AS name,
+           e.extversion AS version,
+           n.nspname AS schema,
+           d.description
+         FROM pg_catalog.pg_extension e
+         JOIN pg_catalog.pg_namespace n ON n.oid = e.extnamespace
+         LEFT JOIN pg_catalog.pg_description d ON d.objoid = e.oid AND d.classoid = 'pg_extension'::regclass
+         ORDER BY e.extname`
+      );
+    }
+  },
+  {
+    name: "pg_search_columns",
+    description: "Search for columns by name across all user schemas. Supports SQL LIKE patterns (`%` matches any substring, `_` matches one character). Case-insensitive. Use this instead of iterating `pg_describe_table` when the user asks 'which tables have X'.",
+    annotations: {
+      title: "Search columns by name",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      pattern: external_exports3.string().min(1).describe("LIKE pattern. Use '%' for wildcard: 'user_id', '%email%', 'created_%'."),
+      schema: identSchema.optional().describe("Limit to this schema. If omitted, searches all user schemas."),
+      limit: external_exports3.number().int().min(1).max(1e3).default(100).describe("Max rows to return (default 100).")
+    }),
+    handler: async (input) => {
+      const { pattern, schema, limit } = input;
+      const schemaFilter = schema ? "AND n.nspname = $3" : "AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'";
+      const params = [pattern, limit];
+      if (schema) params.push(schema);
+      return runInternal(
+        `SELECT
+           n.nspname AS schema,
+           c.relname AS "table",
+           a.attname AS "column",
+           pg_catalog.format_type(a.atttypid, a.atttypmod) AS type,
+           NOT a.attnotnull AS nullable
+         FROM pg_catalog.pg_attribute a
+         JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+         WHERE a.attname ILIKE $1
+           AND a.attnum > 0
+           AND NOT a.attisdropped
+           AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
+           ${schemaFilter}
+         ORDER BY n.nspname, c.relname, a.attnum
+         LIMIT $2`,
+        params
+      );
+    }
+  }
+];
+
+// src/tools/stats.ts
+var identSchema2 = external_exports3.string().min(1).max(63);
+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.",
+    annotations: {
+      title: "Top queries by execution time",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      orderBy: external_exports3.enum(["total_time", "mean_time", "calls"]).default("total_time").describe("Ranking: total_time (cumulative impact), mean_time (worst per-call), or calls (hottest)."),
+      limit: external_exports3.number().int().min(1).max(100).default(20).describe("Number of rows to return (default 20).")
+    }),
+    handler: async (input) => {
+      const { orderBy, limit } = input;
+      const check2 = await runInternal(
+        `SELECT EXISTS (
+           SELECT 1 FROM pg_catalog.pg_extension WHERE extname = 'pg_stat_statements'
+         ) AS installed`
+      );
+      if (!check2.ok) return check2;
+      if (!check2.data?.[0]?.installed) {
+        return {
+          ok: false,
+          error: "pg_stat_statements extension is not installed. Install it with `CREATE EXTENSION pg_stat_statements;` (may require superuser) and add `pg_stat_statements` to `shared_preload_libraries` in postgresql.conf, then restart."
+        };
+      }
+      const versionRes = await runInternal(
+        `SELECT extversion AS version FROM pg_catalog.pg_extension WHERE extname = 'pg_stat_statements'`
+      );
+      const extVersion = versionRes.ok ? versionRes.data?.[0]?.version ?? "0" : "0";
+      const useExecSuffix = compareVersions(extVersion, "1.8") >= 0;
+      const totalCol = useExecSuffix ? "total_exec_time" : "total_time";
+      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 orderCol = orderBy === "total_time" ? totalCol : orderBy === "mean_time" ? meanCol : "calls";
+      return runInternal(
+        `SELECT
+           query,
+           calls::text AS calls,
+           ${totalCol}::numeric(18, 2)::float8 AS total_time_ms,
+           ${meanCol}::numeric(18, 2)::float8 AS mean_time_ms,
+           ${minCol}::numeric(18, 2)::float8 AS min_time_ms,
+           ${maxCol}::numeric(18, 2)::float8 AS max_time_ms,
+           rows::text AS rows,
+           CASE
+             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
+         FROM pg_stat_statements
+         ORDER BY ${orderCol} DESC NULLS LAST
+         LIMIT $1`,
+        [limit]
+      );
+    }
+  },
+  {
+    name: "pg_seq_scan_tables",
+    description: "Tables with high sequential-scan counts relative to index scans \u2014 the first place to look for missing-index candidates. Returns seq_scans, idx_scans, live tuples, and the ratio. A high ratio on a large table usually means a query is reading the whole table where an index would suffice. Pair with `pg_top_queries` to find which query is doing it.",
+    annotations: {
+      title: "Find tables with heavy sequential scans",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      schema: identSchema2.optional().describe("Limit to one schema. If omitted, all user schemas are included."),
+      minSize: external_exports3.number().int().min(0).default(1e3).describe("Minimum live tuple count to include (default 1000, filters out tiny/empty tables)."),
+      limit: external_exports3.number().int().min(1).max(100).default(20).describe("Max rows to return (default 20).")
+    }),
+    handler: async (input) => {
+      const { schema, minSize, limit } = input;
+      const schemaFilter = schema ? "AND schemaname = $3" : "AND schemaname NOT IN ('pg_catalog', 'information_schema') AND schemaname NOT LIKE 'pg_%'";
+      const params = [minSize, limit];
+      if (schema) params.push(schema);
+      return runInternal(
+        `SELECT
+           schemaname AS schema,
+           relname AS "table",
+           seq_scan::text AS seq_scans,
+           COALESCE(idx_scan, 0)::text AS idx_scans,
+           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
+           END AS ratio
+         FROM pg_catalog.pg_stat_user_tables
+         WHERE n_live_tup >= $1
+           ${schemaFilter}
+         ORDER BY seq_scan DESC NULLS LAST
+         LIMIT $2`,
+        params
+      );
+    }
+  },
+  {
+    name: "pg_unused_indexes",
+    description: "Indexes that have never been scanned or have very low usage. Each unused index costs write amplification (every INSERT/UPDATE maintains it) and disk space. Excludes primary keys and unique constraints (which are load-bearing even with zero scans). Use this before adding new indexes \u2014 sometimes the fix is to drop a dead one.",
+    annotations: {
+      title: "Find unused indexes",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      schema: identSchema2.optional().describe("Limit to one schema. If omitted, all user schemas are included."),
+      maxScans: external_exports3.number().int().min(0).default(10).describe("Include indexes with scan count <= this (default 10). Use 0 for 'never scanned'."),
+      limit: external_exports3.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
+    }),
+    handler: async (input) => {
+      const { schema, maxScans, limit } = input;
+      const schemaFilter = schema ? "AND s.schemaname = $3" : "AND s.schemaname NOT IN ('pg_catalog', 'information_schema') AND s.schemaname NOT LIKE 'pg_%'";
+      const params = [maxScans, limit];
+      if (schema) params.push(schema);
+      return runInternal(
+        `SELECT
+           s.schemaname AS schema,
+           s.relname AS "table",
+           s.indexrelname AS "index",
+           s.idx_scan::text AS scans,
+           pg_size_pretty(pg_relation_size(s.indexrelid)) AS size_pretty,
+           pg_relation_size(s.indexrelid)::text AS size_bytes,
+           pg_catalog.pg_get_indexdef(s.indexrelid) AS definition
+         FROM pg_catalog.pg_stat_user_indexes s
+         JOIN pg_catalog.pg_index i ON i.indexrelid = s.indexrelid
+         WHERE s.idx_scan <= $1
+           AND NOT i.indisunique
+           AND NOT i.indisprimary
+           ${schemaFilter}
+         ORDER BY pg_relation_size(s.indexrelid) DESC
+         LIMIT $2`,
+        params
+      );
+    }
   }
 ];
+function compareVersions(a, b) {
+  const parse3 = (v) => v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const aa = parse3(a);
+  const bb = parse3(b);
+  const len = Math.max(aa.length, bb.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (aa[i] ?? 0) - (bb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
 
 // src/index.ts
-var version2 = true ? "0.1.1" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.3.1" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
   process.exit(0);
 }
-var allTools = [...queryTools, ...schemaTools, ...explainTools, ...healthTools];
+var allTools = [...queryTools, ...schemaTools, ...explainTools, ...healthTools, ...statsTools, ...adminTools];
 var server = new McpServer({
   name: "@yawlabs/postgres-mcp",
   version: version2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/postgres-mcp",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "description": "PostgreSQL MCP server — query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
@@ -31,8 +31,9 @@
     "build": "tsc && node build.mjs",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "test": "npm run build && node --test dist/**/*.test.js",
+    "test": "npm run build && node scripts/run-tests.mjs dist",
     "test:ci": "npm run test",
+    "test:integration": "npm run build && node scripts/run-tests.mjs dist --integration",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "prepublishOnly": "npm run build"