@contextflo/postgres-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ConfigError, HelpRequested, parseArgs } from './config.js';
+import { parse as parseConnectionString } from 'pg-connection-string';
+import { ContextFileExists, readOnlyRoleSnippet, runInit } from './context/init.js';
+import { ContextStore } from './context/store.js';
+import { Database } from './db/pool.js';
+import { startHttpServer } from './http.js';
+import { QueryLog } from './log.js';
+import { ensureParserReady } from './safety/validate.js';
+import { createServer } from './server.js';
+// stdout carries MCP protocol frames on a stdio transport, so every diagnostic in this
+// package goes to stderr. A stray console.log corrupts the stream. The exceptions are
+// --help and `init`, neither of which starts a transport.
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+async function main() {
+    const config = readConfig();
+    // The WASM parser must be loaded before any query is validated.
+    await ensureParserReady();
+    const database = await Database.connect({
+        connectionString: config.connectionString,
+        statementTimeoutMs: config.statementTimeoutMs,
+    });
+    try {
+        if (config.command === 'init') {
+            await initialiseContextFile(database, config);
+            return;
+        }
+        await serve(database, config);
+    }
+    catch (error) {
+        await database.close().catch(() => { });
+        throw error;
+    }
+}
+function readConfig() {
+    try {
+        return parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        if (error instanceof HelpRequested) {
+            // Safe on stdout: no transport is running yet, and this process exits immediately.
+            console.log(error.message);
+            process.exit(0);
+        }
+        if (error instanceof ConfigError) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        throw error;
+    }
+}
+async function initialiseContextFile(database, config) {
+    let result;
+    try {
+        result = await runInit(database, config.contextFile);
+    }
+    catch (error) {
+        if (error instanceof ContextFileExists) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        throw error;
+    }
+    const databaseName = parseConnectionString(config.connectionString).database || 'postgres';
+    console.log(`Wrote ${result.path}`);
+    console.log(`  ${result.tableCount} tables across ${result.schemas.length} schema(s); ` +
+        `${result.seededColumnCount} column descriptions seeded from COMMENT ON.`);
+    if (result.truncated) {
+        console.log('  Note: only the first 1000 tables were included.');
+    }
+    console.log('\nEdit it — the business definitions section is where the value is.\n');
+    console.log('Recommended: connect as a role that cannot write, so read-only holds even if this');
+    console.log('server has a bug.\n');
+    console.log(readOnlyRoleSnippet(databaseName, result.schemas));
+    await database.close();
+}
+async function serve(database, config) {
+    await database.warnOnWeakSetup();
+    const contextFile = await ContextStore.open(config.contextFile, { writable: config.contextWrites });
+    const contextDocument = contextFile.current;
+    if (contextDocument.tables.size === 0 && !contextDocument.preamble) {
+        console.error(`[postgres-mcp] no context file at ${config.contextFile}. Run \`postgres-mcp init <url>\` to ` +
+            'generate one, or pass --context-file with an absolute path — the model does better when it ' +
+            'knows what your tables mean.');
+    }
+    else {
+        console.error(`[postgres-mcp] context from ${config.contextFile}`);
+    }
+    const log = await QueryLog.resolve({
+        explicitPath: config.logFile,
+        disabled: config.logDisabled,
+        contextDirectory: config.contextDirectory,
+    });
+    if (log.isEnabled) {
+        console.error(`[postgres-mcp] logging queries to ${log.filePath}`);
+    }
+    const toolContext = {
+        database,
+        contextFile,
+        log,
+        maxRows: config.maxRows,
+        maxOutputChars: config.maxOutputChars,
+    };
+    const buildServer = () => createServer({ context: toolContext, version, connectionString: config.connectionString });
+    const shutdown = async () => {
+        await log.flush().catch(() => { });
+        await database.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+    if (config.http) {
+        await startHttpServer({ config: config.http, createMcpServer: buildServer });
+        return;
+    }
+    await buildServer().connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    console.error(`[postgres-mcp] ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/log.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `.contextflo/log.md` — an audit trail of every statement the agent ran, in a file a
+ * human reads. Nothing here is served back to the model.
+ *
+ * Off unless asked for: enabled by `--log-file`, or automatically once `.contextflo/`
+ * exists, since creating that directory with `init` is the opt-in. A database tool that
+ * writes files into your project uninvited is a bad neighbour.
+ */
+export declare const DEFAULT_LOG_FILE = ".contextflo/log.md";
+export type QueryOutcome = 'ok' | 'rejected' | 'error';
+export interface QueryLogEntry {
+    sql: string;
+    outcome: QueryOutcome;
+    rowCount?: number | undefined;
+    durationMs?: number | undefined;
+    /** Rejection reason or database error, for the non-ok outcomes. */
+    message?: string | undefined;
+}
+export declare class QueryLog {
+    private readonly path;
+    /** Appends are chained so concurrent tool calls cannot interleave mid-entry. */
+    private pending;
+    private warned;
+    private constructor();
+    static disabled(): QueryLog;
+    static enabled(path: string): QueryLog;
+    /**
+     * Resolves whether to log at all: an explicit path wins, otherwise log only if the
+     * context directory is already there.
+     */
+    static resolve(options: {
+        explicitPath?: string | undefined;
+        disabled: boolean;
+        contextDirectory: string;
+    }): Promise<QueryLog>;
+    get isEnabled(): boolean;
+    get filePath(): string | null;
+    /**
+     * Never rejects. A failed write must not turn a successful query into a failed tool
+     * call, so problems are reported once to stderr and then swallowed.
+     */
+    record(entry: QueryLogEntry): void;
+    /** Waits for queued writes — used on shutdown so the last entry is not lost. */
+    flush(): Promise<void>;
+    private write;
+}

package/dist/log.js

@@ -0,0 +1,100 @@
+import { appendFile, mkdir, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { DEFAULT_CONTEXT_DIRECTORY } from './context/context-file.js';
+/**
+ * `.contextflo/log.md` — an audit trail of every statement the agent ran, in a file a
+ * human reads. Nothing here is served back to the model.
+ *
+ * Off unless asked for: enabled by `--log-file`, or automatically once `.contextflo/`
+ * exists, since creating that directory with `init` is the opt-in. A database tool that
+ * writes files into your project uninvited is a bad neighbour.
+ */
+export const DEFAULT_LOG_FILE = `${DEFAULT_CONTEXT_DIRECTORY}/log.md`;
+const FILE_HEADER = `# postgres-mcp query log
+
+Every statement this server ran, newest last. Written for you, not for the model.
+`;
+export class QueryLog {
+    path;
+    /** Appends are chained so concurrent tool calls cannot interleave mid-entry. */
+    pending = Promise.resolve();
+    warned = false;
+    constructor(path) {
+        this.path = path;
+    }
+    static disabled() {
+        return new QueryLog(null);
+    }
+    static enabled(path) {
+        return new QueryLog(path);
+    }
+    /**
+     * Resolves whether to log at all: an explicit path wins, otherwise log only if the
+     * context directory is already there.
+     */
+    static async resolve(options) {
+        if (options.disabled)
+            return QueryLog.disabled();
+        if (options.explicitPath)
+            return QueryLog.enabled(options.explicitPath);
+        try {
+            const info = await stat(options.contextDirectory);
+            if (info.isDirectory())
+                return QueryLog.enabled(`${options.contextDirectory}/log.md`);
+        }
+        catch {
+            // No context directory — nothing was opted into.
+        }
+        return QueryLog.disabled();
+    }
+    get isEnabled() {
+        return this.path !== null;
+    }
+    get filePath() {
+        return this.path;
+    }
+    /**
+     * Never rejects. A failed write must not turn a successful query into a failed tool
+     * call, so problems are reported once to stderr and then swallowed.
+     */
+    record(entry) {
+        if (this.path === null)
+            return;
+        this.pending = this.pending
+            .then(() => this.write(this.path, entry))
+            .catch((error) => {
+            if (this.warned)
+                return;
+            this.warned = true;
+            console.error(`[postgres-mcp] could not write the query log at ${this.path}: ` +
+                `${error instanceof Error ? error.message : String(error)}. Continuing without it.`);
+        });
+    }
+    /** Waits for queued writes — used on shutdown so the last entry is not lost. */
+    async flush() {
+        await this.pending;
+    }
+    async write(path, entry) {
+        let isNew = false;
+        try {
+            await stat(path);
+        }
+        catch {
+            isNew = true;
+            await mkdir(dirname(path), { recursive: true });
+        }
+        await appendFile(path, (isNew ? FILE_HEADER : '') + formatEntry(entry), 'utf8');
+    }
+}
+function formatEntry(entry) {
+    const parts = [new Date().toISOString(), entry.outcome];
+    if (entry.rowCount !== undefined)
+        parts.push(`${entry.rowCount} rows`);
+    if (entry.durationMs !== undefined)
+        parts.push(`${entry.durationMs}ms`);
+    const heading = `\n## ${parts.join(' · ')}\n\n`;
+    const sql = '```sql\n' + entry.sql.trim() + '\n```\n';
+    const message = entry.message ? `\n> ${entry.message.replace(/\n/g, '\n> ')}\n` : '';
+    return heading + sql + message;
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"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"}

package/dist/safety/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Stable rejection codes. These are asserted on by the adversarial test suite and
+ * surfaced to the model in tool errors, so treat them as part of the public contract.
+ */
+export type SafetyCode = 'PARSE_ERROR' | 'EMPTY_STATEMENT' | 'MULTIPLE_STATEMENTS' | 'STATEMENT_NOT_ALLOWED' | 'SELECT_INTO' | 'LOCKING_CLAUSE' | 'FUNCTION_NOT_ALLOWED';
+export declare class SafetyError extends Error {
+    readonly code: SafetyCode;
+    constructor(code: SafetyCode, message: string);
+}
+/** Falls back to de-camel-casing the node name so unknown types still read sensibly. */
+export declare function describeStatement(nodeName: string): string;

package/dist/safety/errors.js

@@ -0,0 +1,65 @@
+export class SafetyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SafetyError';
+        this.code = code;
+    }
+}
+/**
+ * Parse-tree node names are not what a user typed. Map the common ones back to SQL
+ * keywords so the rejection message is actionable rather than an implementation detail.
+ */
+const STATEMENT_KEYWORDS = {
+    InsertStmt: 'INSERT',
+    UpdateStmt: 'UPDATE',
+    DeleteStmt: 'DELETE',
+    MergeStmt: 'MERGE',
+    TruncateStmt: 'TRUNCATE',
+    CopyStmt: 'COPY',
+    DropStmt: 'DROP',
+    CreateStmt: 'CREATE TABLE',
+    CreateTableAsStmt: 'CREATE TABLE AS',
+    CreateFunctionStmt: 'CREATE FUNCTION',
+    CreateRoleStmt: 'CREATE ROLE',
+    AlterTableStmt: 'ALTER TABLE',
+    AlterRoleStmt: 'ALTER ROLE',
+    GrantStmt: 'GRANT/REVOKE',
+    GrantRoleStmt: 'GRANT/REVOKE ROLE',
+    DoStmt: 'DO',
+    CallStmt: 'CALL',
+    TransactionStmt: 'BEGIN/COMMIT/ROLLBACK',
+    VariableSetStmt: 'SET/RESET',
+    DeclareCursorStmt: 'DECLARE CURSOR',
+    FetchStmt: 'FETCH/MOVE',
+    ClosePortalStmt: 'CLOSE',
+    PrepareStmt: 'PREPARE',
+    ExecuteStmt: 'EXECUTE',
+    DeallocateStmt: 'DEALLOCATE',
+    LockStmt: 'LOCK',
+    NotifyStmt: 'NOTIFY',
+    ListenStmt: 'LISTEN',
+    UnlistenStmt: 'UNLISTEN',
+    VacuumStmt: 'VACUUM/ANALYZE',
+    ReindexStmt: 'REINDEX',
+    ClusterStmt: 'CLUSTER',
+    RefreshMatViewStmt: 'REFRESH MATERIALIZED VIEW',
+    IndexStmt: 'CREATE INDEX',
+    ViewStmt: 'CREATE VIEW',
+    RuleStmt: 'CREATE RULE',
+    CreatedbStmt: 'CREATE DATABASE',
+    DropdbStmt: 'DROP DATABASE',
+    CreateSchemaStmt: 'CREATE SCHEMA',
+    CreateTrigStmt: 'CREATE TRIGGER',
+    CreateExtensionStmt: 'CREATE EXTENSION',
+    AlterSystemStmt: 'ALTER SYSTEM',
+    CheckPointStmt: 'CHECKPOINT',
+};
+/** Falls back to de-camel-casing the node name so unknown types still read sensibly. */
+export function describeStatement(nodeName) {
+    const known = STATEMENT_KEYWORDS[nodeName];
+    if (known)
+        return known;
+    return nodeName.replace(/Stmt$/, '').replace(/([a-z])([A-Z])/g, '$1 $2').toUpperCase();
+}
+//# sourceMappingURL=errors.js.map

package/dist/safety/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/safety/errors.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAY;IAEzB,YAAY,IAAgB,EAAE,OAAe;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,kBAAkB,GAA2B;IACjD,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE,QAAQ;IACpB,SAAS,EAAE,OAAO;IAClB,YAAY,EAAE,UAAU;IACxB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,cAAc;IAC1B,iBAAiB,EAAE,iBAAiB;IACpC,kBAAkB,EAAE,iBAAiB;IACrC,cAAc,EAAE,aAAa;IAC7B,cAAc,EAAE,aAAa;IAC7B,aAAa,EAAE,YAAY;IAC3B,SAAS,EAAE,cAAc;IACzB,aAAa,EAAE,mBAAmB;IAClC,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,MAAM;IAChB,eAAe,EAAE,uBAAuB;IACxC,eAAe,EAAE,WAAW;IAC5B,iBAAiB,EAAE,gBAAgB;IACnC,SAAS,EAAE,YAAY;IACvB,eAAe,EAAE,OAAO;IACxB,WAAW,EAAE,SAAS;IACtB,WAAW,EAAE,SAAS;IACtB,cAAc,EAAE,YAAY;IAC5B,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE,QAAQ;IACpB,YAAY,EAAE,UAAU;IACxB,UAAU,EAAE,gBAAgB;IAC5B,WAAW,EAAE,SAAS;IACtB,WAAW,EAAE,SAAS;IACtB,kBAAkB,EAAE,2BAA2B;IAC/C,SAAS,EAAE,cAAc;IACzB,QAAQ,EAAE,aAAa;IACvB,QAAQ,EAAE,aAAa;IACvB,YAAY,EAAE,iBAAiB;IAC/B,UAAU,EAAE,eAAe;IAC3B,gBAAgB,EAAE,eAAe;IACjC,cAAc,EAAE,gBAAgB;IAChC,mBAAmB,EAAE,kBAAkB;IACvC,eAAe,EAAE,cAAc;IAC/B,cAAc,EAAE,YAAY;CAC7B,CAAA;AAED,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAA;IAC1C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAA;IACvB,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAA;AACxF,CAAC"}

package/dist/safety/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Loads the WASM parser. Must be awaited once before {@link validateReadOnlySql}, which
+ * is synchronous so it can be used freely from anywhere.
+ */
+export declare function ensureParserReady(): Promise<void>;
+/**
+ * Throws {@link SafetyError} unless `sql` is a single read-only statement.
+ *
+ * Accepts: SELECT (including `WITH ... SELECT`, set operations, and subqueries), EXPLAIN
+ * over an otherwise-accepted statement, and SHOW.
+ */
+export declare function validateReadOnlySql(sql: string): void;

package/dist/safety/validate.js

@@ -0,0 +1,145 @@
+import { loadModule, parseSync } from 'libpg-query';
+import { SafetyError, describeStatement } from './errors.js';
+import { findFunctionNames, findStatementNodes } from './walk.js';
+/**
+ * Layer 3 of four: the statement allowlist, enforced with the real Postgres C parser
+ * (libpg-query, compiled to WASM) rather than a JavaScript SQL dialect approximation.
+ *
+ * The other three layers live outside this file and each stop the archived server's CVE
+ * on their own: the extended query protocol (src/db/pool.ts), the connection's
+ * `default_transaction_read_only` (src/db/pool.ts), and a read-only database role (the
+ * documented setup). This layer exists to turn "the database refused it" into a clear,
+ * early, actionable error — and to catch the cases the transaction alone would not,
+ * like `SELECT ... INTO`.
+ */
+/** Anything not in this set is rejected. Allowlist, so new node types fail closed. */
+const ALLOWED_STATEMENTS = new Set(['SelectStmt', 'ExplainStmt', 'VariableShowStmt']);
+let parserReady;
+/**
+ * Loads the WASM parser. Must be awaited once before {@link validateReadOnlySql}, which
+ * is synchronous so it can be used freely from anywhere.
+ */
+export function ensureParserReady() {
+    parserReady ??= loadModule();
+    return parserReady;
+}
+/**
+ * Throws {@link SafetyError} unless `sql` is a single read-only statement.
+ *
+ * Accepts: SELECT (including `WITH ... SELECT`, set operations, and subqueries), EXPLAIN
+ * over an otherwise-accepted statement, and SHOW.
+ */
+export function validateReadOnlySql(sql) {
+    if (sql.trim() === '') {
+        // libpg-query reports this as a parse error; EMPTY_STATEMENT is the clearer contract.
+        throw new SafetyError('EMPTY_STATEMENT', 'No SQL statement found. Provide a single SELECT, EXPLAIN, or SHOW.');
+    }
+    let parsed;
+    try {
+        parsed = parseSync(sql);
+    }
+    catch (error) {
+        throw new SafetyError('PARSE_ERROR', formatParseError(error));
+    }
+    const statements = parsed.stmts ?? [];
+    if (statements.length === 0 || !statements[0]?.stmt) {
+        throw new SafetyError('EMPTY_STATEMENT', 'No SQL statement found. Provide a single SELECT, EXPLAIN, or SHOW.');
+    }
+    if (statements.length > 1) {
+        // The wire protocol rejects this too (see src/db/pool.ts) — this is the friendly version.
+        throw new SafetyError('MULTIPLE_STATEMENTS', `Only one statement per call is allowed; received ${statements.length}. ` +
+            'Send each statement as a separate query call.');
+    }
+    for (const node of findStatementNodes(statements[0].stmt)) {
+        if (!ALLOWED_STATEMENTS.has(node.name)) {
+            throw new SafetyError('STATEMENT_NOT_ALLOWED', `This server is read-only; ${describeStatement(node.name)} is not allowed. ` +
+                'Only SELECT, EXPLAIN, and SHOW statements can run.');
+        }
+        if (node.name === 'SelectStmt') {
+            checkSelect(node.fields);
+        }
+    }
+    for (const name of findFunctionNames(statements[0].stmt)) {
+        if (isDeniedFunction(name)) {
+            throw new SafetyError('FUNCTION_NOT_ALLOWED', `This server is read-only; ${name}() is not allowed because it can act outside the ` +
+                'read-only transaction (another connection, the filesystem, other sessions, or a lock ' +
+                'that outlives the query).');
+        }
+    }
+}
+/**
+ * Functions a read-only SELECT can call that escape the read-only transaction. This is
+ * defence in depth, not a boundary: user-defined and SECURITY DEFINER functions can do
+ * the same things, and only a read-only role stops those. What it does is make the common
+ * built-in escapes fail with a clear message instead of depending on the role.
+ */
+const DENIED_FUNCTIONS = new Set([
+    // Run a SQL string the parser never sees.
+    'query_to_xml',
+    'query_to_xmlschema',
+    'query_to_xml_and_xmlschema',
+    'cursor_to_xml',
+    'cursor_to_xmlschema',
+    'ts_stat',
+    // Change settings; SET is rejected, so its function form is too.
+    'set_config',
+    // Act on other sessions or the server.
+    'pg_terminate_backend',
+    'pg_cancel_backend',
+    'pg_reload_conf',
+    'pg_rotate_logfile',
+    'pg_switch_wal',
+    'pg_promote',
+    'pg_create_restore_point',
+    'pg_notify',
+    // Session-level advisory locks survive the ROLLBACK and stay on the pooled connection.
+    'pg_advisory_lock',
+    'pg_advisory_lock_shared',
+    'pg_try_advisory_lock',
+    'pg_try_advisory_lock_shared',
+    // Server filesystem.
+    'pg_read_file',
+    'pg_read_binary_file',
+    'pg_stat_file',
+    'pg_file_write',
+    'pg_file_unlink',
+    'pg_file_rename',
+    'lo_import',
+    'lo_export',
+]);
+/** Families matched by prefix. */
+const DENIED_FUNCTION_PREFIXES = [
+    // dblink opens a new connection, which is not read-only, and runs SQL the parser never sees.
+    'dblink',
+    // Directory listings of the server's filesystem.
+    'pg_ls_',
+    // Replication slots and origins: creating, dropping, or consuming them changes server state.
+    'pg_create_logical_replication_slot',
+    'pg_create_physical_replication_slot',
+    'pg_drop_replication_slot',
+    'pg_logical_slot_',
+    'pg_replication_origin_',
+];
+function isDeniedFunction(name) {
+    return DENIED_FUNCTIONS.has(name) || DENIED_FUNCTION_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+function checkSelect(fields) {
+    if (fields.intoClause) {
+        // `SELECT ... INTO new_table` is a SelectStmt but creates a table.
+        throw new SafetyError('SELECT_INTO', 'SELECT ... INTO creates a table, which this read-only server does not allow. ' +
+            'Drop the INTO clause to return the rows instead.');
+    }
+    if (fields.lockingClause) {
+        // FOR UPDATE/SHARE takes row locks; the read-only transaction would reject it with a
+        // less obvious error, so name it here.
+        throw new SafetyError('LOCKING_CLAUSE', 'Row locking (FOR UPDATE / FOR SHARE) is not available on a read-only connection. ' +
+            'Remove the locking clause.');
+    }
+}
+function formatParseError(error) {
+    const details = error;
+    const message = details?.message ?? 'Could not parse SQL';
+    const position = details?.sqlDetails?.cursorPosition;
+    return position && position > 0 ? `${message} (at position ${position})` : message;
+}
+//# sourceMappingURL=validate.js.map

package/dist/safety/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/safety/validate.ts"],"names":[],"mappings":"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"}

package/dist/safety/walk.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Walking the whole parse tree — not just the top-level node — is the point of this file.
+ *
+ * `WITH x AS (INSERT INTO t VALUES (1) RETURNING *) SELECT * FROM x` parses to a
+ * SelectStmt at the top, with the InsertStmt buried at
+ * `SelectStmt.withClause.ctes[].CommonTableExpr.ctequery.InsertStmt`. A validator that
+ * only inspects the top-level statement type waves that through, and it writes.
+ */
+export interface StatementNode {
+    /** Parse-tree node name, e.g. `SelectStmt`. */
+    name: string;
+    /** The node's fields. */
+    fields: Record<string, unknown>;
+}
+/**
+ * Yields every statement node anywhere in the tree, in document order, including the
+ * root. Callers check membership against an allowlist so unfamiliar node types — from a
+ * future Postgres, say — fail closed instead of slipping through a denylist.
+ */
+export declare function findStatementNodes(node: unknown): Generator<StatementNode>;
+/**
+ * Yields the lower-cased, unqualified name of every function call anywhere in the tree —
+ * in the select list, FROM (`dblink(...) AS t`), WHERE, subqueries, CTEs. The schema
+ * qualifier is dropped so `pg_catalog.pg_read_file` and `pg_read_file` look the same.
+ */
+export declare function findFunctionNames(node: unknown): Generator<string>;

package/dist/safety/walk.js

@@ -0,0 +1,61 @@
+/**
+ * Walking the whole parse tree — not just the top-level node — is the point of this file.
+ *
+ * `WITH x AS (INSERT INTO t VALUES (1) RETURNING *) SELECT * FROM x` parses to a
+ * SelectStmt at the top, with the InsertStmt buried at
+ * `SelectStmt.withClause.ctes[].CommonTableExpr.ctequery.InsertStmt`. A validator that
+ * only inspects the top-level statement type waves that through, and it writes.
+ */
+/**
+ * Postgres parse trees wrap every node as `{ PascalCaseTypeName: { ...fields } }`, while
+ * plain fields are camelCase (`stmt`, `ctequery`, `withClause`). Requiring a leading
+ * capital keeps this from matching a field that merely ends in "Stmt".
+ */
+const STATEMENT_NODE_KEY = /^[A-Z][A-Za-z0-9]*Stmt$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Yields every statement node anywhere in the tree, in document order, including the
+ * root. Callers check membership against an allowlist so unfamiliar node types — from a
+ * future Postgres, say — fail closed instead of slipping through a denylist.
+ */
+export function* findStatementNodes(node) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            yield* findStatementNodes(item);
+        return;
+    }
+    if (!isRecord(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (STATEMENT_NODE_KEY.test(key) && isRecord(value)) {
+            yield { name: key, fields: value };
+        }
+        yield* findStatementNodes(value);
+    }
+}
+/**
+ * Yields the lower-cased, unqualified name of every function call anywhere in the tree —
+ * in the select list, FROM (`dblink(...) AS t`), WHERE, subqueries, CTEs. The schema
+ * qualifier is dropped so `pg_catalog.pg_read_file` and `pg_read_file` look the same.
+ */
+export function* findFunctionNames(node) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            yield* findFunctionNames(item);
+        return;
+    }
+    if (!isRecord(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'FuncCall' && isRecord(value) && Array.isArray(value.funcname)) {
+            const last = value.funcname[value.funcname.length - 1];
+            const name = last?.String?.sval;
+            if (typeof name === 'string')
+                yield name.toLowerCase();
+        }
+        yield* findFunctionNames(value);
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/safety/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../src/safety/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,yBAAyB,CAAA;AASpD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,SAAS,CAAC,CAAC,kBAAkB,CAAC,IAAa;IAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,KAAK,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAA;QACxD,OAAM;IACR,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAM;IAE3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;QACpC,CAAC;QACD,KAAK,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAClC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,SAAS,CAAC,CAAC,iBAAiB,CAAC,IAAa;IAC9C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,KAAK,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACvD,OAAM;IACR,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAM;IAE3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,GAAG,KAAK,UAAU,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAgD,CAAA;YACrG,MAAM,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAA;YAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,CAAC,WAAW,EAAE,CAAA;QACxD,CAAC;QACD,KAAK,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACjC,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ToolContext } from './tools/context.js';
+export interface ServerDeps {
+    context: ToolContext;
+    version: string;
+    /** Connection string, used only to build resource URIs. The password is stripped. */
+    connectionString: string;
+}
+export declare function createServer({ context, version, connectionString }: ServerDeps): Server;