@contextflo/postgres-mcp 0.1.0

package/dist/context/context-file.js

@@ -0,0 +1,248 @@
+import { readFile } from 'node:fs/promises';
+/**
+ * `.contextflo/context.md` — the whole context layer.
+ *
+ * No database, no embeddings, no index: a markdown file a human edits and this server
+ * hands to the model. The catalog can say a column is `numeric(12,2)` named `revenue`;
+ * only a person can say it is gross rather than net, or that `fct_orders_v2` is the one
+ * the team actually uses.
+ *
+ * Parsing is deliberately forgiving. This file's job is to be edited by hand, so anything
+ * it does not recognise is left alone rather than treated as an error — a file that
+ * rejects your notes is a file you stop updating.
+ */
+export const DEFAULT_CONTEXT_DIRECTORY = '.contextflo';
+export const DEFAULT_CONTEXT_FILE = `${DEFAULT_CONTEXT_DIRECTORY}/context.md`;
+/** Everything above this heading is passed to the model verbatim. */
+const TABLES_HEADING = /^##\s+tables\s*$/i;
+const TABLE_HEADING = /^###\s+(.+?)\s*$/;
+/** `- \`col\` — meaning`, `- col: meaning`, `- col - meaning`. */
+const COLUMN_LINE = /^[-*]\s+`?([A-Za-z_][\w$]*)`?\s*(?:[—–:-])\s*(.+)$/;
+export function emptyContextDocument() {
+    return { preamble: '', tables: new Map() };
+}
+/** Returns null when the file does not exist — the server runs fine without one. */
+export async function loadContextFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    return parseContextFile(raw);
+}
+export function parseContextFile(raw) {
+    const document = emptyContextDocument();
+    const lines = raw.split(/\r?\n/);
+    let index = 0;
+    const preamble = [];
+    while (index < lines.length && !TABLES_HEADING.test(lines[index])) {
+        preamble.push(lines[index]);
+        index++;
+    }
+    // HTML comments are notes to the human editing the file (init writes one), not to the model.
+    document.preamble = preamble.join('\n').replace(/<!--[\s\S]*?-->/g, '').replace(/\n{3,}/g, '\n\n').trim();
+    index++; // step past "## Tables"
+    let current;
+    let descriptionLines = [];
+    const flush = () => {
+        if (current) {
+            const description = descriptionLines.join(' ').trim();
+            if (description)
+                current.description = description;
+        }
+        descriptionLines = [];
+    };
+    for (; index < lines.length; index++) {
+        const line = lines[index];
+        const heading = TABLE_HEADING.exec(line);
+        if (heading) {
+            flush();
+            current = { columns: new Map() };
+            document.tables.set(heading[1].trim().toLowerCase(), current);
+            continue;
+        }
+        if (!current)
+            continue;
+        const column = COLUMN_LINE.exec(line);
+        if (column) {
+            flush();
+            current.columns.set(column[1].toLowerCase(), column[2].trim());
+            continue;
+        }
+        // Prose between the heading and the first bullet is the table's description.
+        if (current.columns.size === 0 && line.trim() !== '' && !line.startsWith('#')) {
+            descriptionLines.push(line.trim());
+        }
+    }
+    flush();
+    return document;
+}
+export function notesForTable(document, fullyQualifiedName) {
+    const notes = document.tables.get(fullyQualifiedName.toLowerCase());
+    if (notes)
+        return notes;
+    // Tolerate an unqualified heading like "### orders" for a single-schema database.
+    const bare = fullyQualifiedName.split('.').pop();
+    return bare ? document.tables.get(bare.toLowerCase()) : undefined;
+}
+/**
+ * The curated file wins over the database comment. `init` seeds the file from comments,
+ * so the two agree until somebody edits — and an edit is exactly the signal to prefer it.
+ */
+export function preferCuratedDescription(curated, fromCatalog) {
+    return curated ?? fromCatalog;
+}
+/**
+ * Adds notes to the file's text, touching nothing else — the file belongs to the humans
+ * editing it, so formatting, comments, and ordering all survive.
+ *
+ * Append-only by design. A note never replaces what is there: when the table or column
+ * already has a description, the note is added after it. Anything an agent writes can be
+ * reviewed in a diff and deleted, and nothing a person wrote is ever lost to it.
+ *
+ * `fullyQualifiedName` is the resolved `schema.table`. An existing section headed with
+ * the bare table name is reused rather than duplicated.
+ */
+export function addTableNotes(raw, fullyQualifiedName, notes) {
+    const lines = (raw.trim() === '' ? CONTEXT_FILE_HEADER : raw).replace(/\r\n/g, '\n').split('\n');
+    if (!lines.some((line) => TABLES_HEADING.test(line))) {
+        trimTrailingBlankLines(lines);
+        lines.push('', '## Tables', '');
+    }
+    // A leading bullet would make the parser read the note as a column line.
+    const tableNote = notes.note ? singleLine(notes.note).replace(/^[-*]\s+/, '') : undefined;
+    const columnNotes = Object.entries(notes.columns ?? {})
+        .map(([column, note]) => [column, singleLine(note)])
+        .filter(([, note]) => note !== '');
+    const section = findTableSection(lines, fullyQualifiedName);
+    if (!section) {
+        trimTrailingBlankLines(lines);
+        lines.push('', `### ${fullyQualifiedName}`);
+        if (tableNote)
+            lines.push(tableNote);
+        if (columnNotes.length > 0) {
+            lines.push('');
+            for (const [column, note] of columnNotes)
+                lines.push(`- ${column} — ${note}`);
+        }
+        return `${lines.join('\n')}\n`;
+    }
+    let end = section.end;
+    for (const [column, note] of columnNotes) {
+        const existing = findColumnLine(lines, section.start, end, column);
+        if (existing !== -1) {
+            lines[existing] = appendSentence(lines[existing], note);
+            continue;
+        }
+        // After the section's last column line; or, for the first one, after the prose with a
+        // blank line between, which is how the parser tells a description from a column list.
+        const lastColumn = findLastColumnLine(lines, section.start, end);
+        const inserted = lastColumn === -1 ? ['', `- ${column} — ${note}`] : [`- ${column} — ${note}`];
+        const at = lastColumn === -1 ? lastContentLine(lines, section.start, end) + 1 : lastColumn + 1;
+        lines.splice(at, 0, ...inserted);
+        end += inserted.length;
+    }
+    if (tableNote && !sectionText(lines, section.start, end).includes(tableNote)) {
+        // The parser reads prose between the heading and the first column line as the
+        // description, so the note goes at the end of that prose.
+        const firstColumn = findFirstColumnLine(lines, section.start, end);
+        const proseEnd = lastContentLine(lines, section.start, firstColumn === -1 ? end : firstColumn);
+        lines.splice(proseEnd + 1, 0, tableNote);
+    }
+    return `${lines.join('\n').replace(/\n*$/, '')}\n`;
+}
+/** Section bounds as [start, end): `start` is the heading line. */
+function findTableSection(lines, fullyQualifiedName) {
+    const tablesAt = lines.findIndex((line) => TABLES_HEADING.test(line));
+    const wanted = fullyQualifiedName.toLowerCase();
+    const bare = wanted.split('.').pop();
+    const headings = lines
+        .map((line, index) => ({ index, name: TABLE_HEADING.exec(line)?.[1]?.trim().toLowerCase() }))
+        .filter((heading) => heading.index > tablesAt && heading.name !== undefined);
+    const match = headings.find((heading) => heading.name === wanted) ?? headings.find((heading) => heading.name === bare);
+    if (!match)
+        return undefined;
+    let end = match.index + 1;
+    while (end < lines.length && !/^#{1,3}\s/.test(lines[end]))
+        end++;
+    return { start: match.index, end };
+}
+function findColumnLine(lines, start, end, column) {
+    for (let index = start + 1; index < end; index++) {
+        if (COLUMN_LINE.exec(lines[index])?.[1]?.toLowerCase() === column.toLowerCase())
+            return index;
+    }
+    return -1;
+}
+function findFirstColumnLine(lines, start, end) {
+    for (let index = start + 1; index < end; index++) {
+        if (COLUMN_LINE.test(lines[index]))
+            return index;
+    }
+    return -1;
+}
+function findLastColumnLine(lines, start, end) {
+    for (let index = end - 1; index > start; index--) {
+        if (COLUMN_LINE.test(lines[index]))
+            return index;
+    }
+    return -1;
+}
+/** The last non-blank line in (start, end), or `start` itself when there is none. */
+function lastContentLine(lines, start, end) {
+    for (let index = end - 1; index > start; index--) {
+        if (lines[index].trim() !== '')
+            return index;
+    }
+    return start;
+}
+function sectionText(lines, start, end) {
+    return lines.slice(start, end).join('\n');
+}
+function appendSentence(line, note) {
+    if (line.includes(note))
+        return line;
+    const trimmed = line.trimEnd();
+    return /[.!?]$/.test(trimmed) ? `${trimmed} ${note}` : `${trimmed}. ${note}`;
+}
+/** A note is one line: a newline would end the column line or split the description. */
+function singleLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function trimTrailingBlankLines(lines) {
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '')
+        lines.pop();
+}
+export const CONTEXT_FILE_HEADER = `# Database context
+
+<!--
+postgres-mcp reads this file and hands it to the model every session. It is the whole
+context layer — no database, no index, just this file.
+
+Everything above "## Tables" is passed through verbatim. Put the things your team
+argues about here: whether revenue is gross or net, what counts as an active customer,
+which table is the source of truth and which one nobody got around to dropping.
+
+Under "## Tables", a "###" heading names a table, the prose beneath it describes the
+table, and each "- column — meaning" line describes a column. Seeded from your
+database's COMMENT ON values; anything you write wins over those.
+
+Add a line for any column you like — only already-commented ones were seeded, to keep
+this file small enough that you will actually edit it.
+
+The agent can add notes here too, with the add_table_context tool, when it finds
+something about the data the next person would get wrong. It only ever appends, so
+review those additions in a diff like any other change.
+-->
+
+## Business definitions
+
+_Replace this with the definitions a new analyst would get wrong on their first day._
+
+## Tables
+`;
+//# sourceMappingURL=context-file.js.map

package/dist/context/context-file.js.map

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

package/dist/context/init.d.ts

@@ -0,0 +1,14 @@
+import type { Database } from '../db/pool.js';
+export interface InitResult {
+    path: string;
+    tableCount: number;
+    seededColumnCount: number;
+    truncated: boolean;
+    schemas: string[];
+}
+export declare class ContextFileExists extends Error {
+    constructor(path: string);
+}
+export declare function runInit(database: Database, contextFile: string): Promise<InitResult>;
+/** The setup that makes read-only true regardless of any bug in this server. */
+export declare function readOnlyRoleSnippet(databaseName: string, schemas: string[]): string;

package/dist/context/init.js

@@ -0,0 +1,71 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { getTableContext, listTables } from '../db/introspection.js';
+import { CONTEXT_FILE_HEADER } from './context-file.js';
+/**
+ * `init` — scan the schema and write a context file worth editing.
+ *
+ * The temptation is to emit a placeholder line for every column of every table. On a
+ * real warehouse that is thousands of blank lines, and a file nobody edits is a file
+ * that does nothing. So: every table gets a heading, but only columns that already carry
+ * a COMMENT are seeded. The file stays proportional to what is already documented, and
+ * adding a line for an undocumented column is one line of typing.
+ */
+const MAX_TABLES = 1000;
+export class ContextFileExists extends Error {
+    constructor(path) {
+        super(`${path} already exists. Delete it to regenerate, or pass --context-file to write elsewhere — ` +
+            'refusing to overwrite notes you may have written by hand.');
+    }
+}
+export async function runInit(database, contextFile) {
+    const { tables, totalMatches } = await listTables(database, { limit: MAX_TABLES });
+    const described = await getTableContext(database, tables.map((table) => table.fullyQualifiedName));
+    const markdown = renderContextFile(described);
+    await mkdir(dirname(contextFile), { recursive: true });
+    // 'wx' fails if the file exists, so a hand-edited context file is never clobbered.
+    try {
+        await writeFile(contextFile, markdown, { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new ContextFileExists(contextFile);
+        throw error;
+    }
+    return {
+        path: contextFile,
+        tableCount: described.length,
+        seededColumnCount: described.reduce((total, table) => total + table.columns.filter((column) => column.description).length, 0),
+        truncated: totalMatches > tables.length,
+        schemas: [...new Set(described.map((table) => table.fullyQualifiedName.split('.')[0]))].sort(),
+    };
+}
+function renderContextFile(tables) {
+    const sections = tables.map((table) => {
+        const lines = [`### ${table.fullyQualifiedName}`];
+        lines.push(table.description ?? '');
+        const documented = table.columns.filter((column) => column.description);
+        if (documented.length > 0) {
+            lines.push('');
+            for (const column of documented) {
+                lines.push(`- ${column.name} — ${column.description}`);
+            }
+        }
+        return lines.join('\n');
+    });
+    return `${CONTEXT_FILE_HEADER}\n${sections.join('\n\n')}\n`;
+}
+/** The setup that makes read-only true regardless of any bug in this server. */
+export function readOnlyRoleSnippet(databaseName, schemas) {
+    const grants = schemas
+        .flatMap((schema) => [
+        `GRANT USAGE ON SCHEMA ${schema} TO mcp_readonly;`,
+        `GRANT SELECT ON ALL TABLES IN SCHEMA ${schema} TO mcp_readonly;`,
+        `ALTER DEFAULT PRIVILEGES IN SCHEMA ${schema} GRANT SELECT ON TABLES TO mcp_readonly;`,
+    ])
+        .join('\n');
+    return `CREATE ROLE mcp_readonly LOGIN PASSWORD 'change-me';
+GRANT CONNECT ON DATABASE ${databaseName} TO mcp_readonly;
+${grants}`;
+}
+//# sourceMappingURL=init.js.map

package/dist/context/init.js.map

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

package/dist/context/store.d.ts

@@ -0,0 +1,34 @@
+import { type ContextDocument, type NewTableNotes } from './context-file.js';
+/**
+ * The context file as the tools see it: re-read whenever it changes on disk, so an edit
+ * someone makes mid-session — or a note the agent just added — shows up on the next tool
+ * call without restarting the server.
+ *
+ * Only the preamble is fixed at startup, because MCP delivers server instructions once,
+ * at initialisation.
+ */
+export declare class ContextStore {
+    readonly path: string | null;
+    /** False when context writes were turned off, or there is no file to write to. */
+    readonly writable: boolean;
+    private document;
+    private loadedMtimeMs;
+    /** Writes are chained so two notes added at once cannot clobber each other. */
+    private pendingWrite;
+    private constructor();
+    static open(path: string, options: {
+        writable: boolean;
+    }): Promise<ContextStore>;
+    /** A fixed document with no file behind it. */
+    static inMemory(document?: ContextDocument): ContextStore;
+    /** The document as last loaded. */
+    get current(): ContextDocument;
+    /**
+     * Re-reads the file if it changed since the last load; returns the current document.
+     * `force` skips the mtime check, for after our own writes: two writes inside one clock
+     * tick can leave the mtime unchanged.
+     */
+    refresh(force?: boolean): Promise<ContextDocument>;
+    /** Appends notes to the file, creating it if needed. See {@link addTableNotes}. */
+    addNotes(fullyQualifiedName: string, notes: NewTableNotes): Promise<void>;
+}

package/dist/context/store.js

@@ -0,0 +1,87 @@
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { addTableNotes, emptyContextDocument, parseContextFile, } from './context-file.js';
+/**
+ * The context file as the tools see it: re-read whenever it changes on disk, so an edit
+ * someone makes mid-session — or a note the agent just added — shows up on the next tool
+ * call without restarting the server.
+ *
+ * Only the preamble is fixed at startup, because MCP delivers server instructions once,
+ * at initialisation.
+ */
+export class ContextStore {
+    path;
+    /** False when context writes were turned off, or there is no file to write to. */
+    writable;
+    document;
+    loadedMtimeMs;
+    /** Writes are chained so two notes added at once cannot clobber each other. */
+    pendingWrite = Promise.resolve();
+    constructor(path, writable, document, mtimeMs) {
+        this.path = path;
+        this.writable = writable;
+        this.document = document;
+        this.loadedMtimeMs = mtimeMs;
+    }
+    static async open(path, options) {
+        const store = new ContextStore(path, options.writable, emptyContextDocument(), null);
+        await store.refresh();
+        return store;
+    }
+    /** A fixed document with no file behind it. */
+    static inMemory(document = emptyContextDocument()) {
+        return new ContextStore(null, false, document, null);
+    }
+    /** The document as last loaded. */
+    get current() {
+        return this.document;
+    }
+    /**
+     * Re-reads the file if it changed since the last load; returns the current document.
+     * `force` skips the mtime check, for after our own writes: two writes inside one clock
+     * tick can leave the mtime unchanged.
+     */
+    async refresh(force = false) {
+        if (this.path === null)
+            return this.document;
+        let mtimeMs;
+        try {
+            mtimeMs = (await stat(this.path)).mtimeMs;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            mtimeMs = null;
+        }
+        if (!force && mtimeMs === this.loadedMtimeMs)
+            return this.document;
+        this.document = mtimeMs === null ? emptyContextDocument() : parseContextFile(await readFile(this.path, 'utf8'));
+        this.loadedMtimeMs = mtimeMs;
+        return this.document;
+    }
+    /** Appends notes to the file, creating it if needed. See {@link addTableNotes}. */
+    async addNotes(fullyQualifiedName, notes) {
+        const path = this.path;
+        if (path === null || !this.writable)
+            throw new Error('Context writes are disabled on this server.');
+        const write = this.pendingWrite.then(async () => {
+            let raw = '';
+            try {
+                raw = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            await mkdir(dirname(path), { recursive: true });
+            // Write-then-rename, so an editor or a crash never sees a half-written file.
+            const temporary = `${path}.${process.pid}.tmp`;
+            await writeFile(temporary, addTableNotes(raw, fullyQualifiedName, notes), 'utf8');
+            await rename(temporary, path);
+            await this.refresh(true);
+        });
+        this.pendingWrite = write.catch(() => { });
+        await write;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/context/store.js.map

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

package/dist/db/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Turns Postgres driver errors into messages a model can act on, without echoing more of
+ * the database's internals than the caller already knew.
+ *
+ * Ported from the ContextFlo connector's `executeQuery` error handling and extended with
+ * the cases this server's safety layers produce.
+ */
+export declare function describeQueryError(error: unknown): string;
+export declare function describeConnectionError(error: unknown): string;

package/dist/db/errors.js

@@ -0,0 +1,58 @@
+/**
+ * Turns Postgres driver errors into messages a model can act on, without echoing more of
+ * the database's internals than the caller already knew.
+ *
+ * Ported from the ContextFlo connector's `executeQuery` error handling and extended with
+ * the cases this server's safety layers produce.
+ */
+/** Postgres SQLSTATE 25006 — attempted a write inside a read-only transaction. */
+const READ_ONLY_TRANSACTION = '25006';
+export function describeQueryError(error) {
+    const pgError = error;
+    const message = pgError?.message ?? 'Unknown database error';
+    if (pgError?.code === READ_ONLY_TRANSACTION) {
+        return `Rejected by the database: this connection is read-only. (${message})`;
+    }
+    // Postgres refuses multi-statement input over the extended query protocol. Reaching
+    // this means the parser-level check was bypassed — the wire protocol caught it anyway.
+    if (message.includes('cannot insert multiple commands into a prepared statement')) {
+        return 'Only one statement per call is allowed. Send each statement as a separate query call.';
+    }
+    if (message.includes('canceling statement due to statement timeout')) {
+        return 'Query exceeded the statement timeout. Narrow the query, or raise the limit with --statement-timeout.';
+    }
+    if (message.includes('syntax error')) {
+        const position = pgError?.position ? ` (at position ${pgError.position})` : '';
+        return `SQL syntax error: ${message}${position}`;
+    }
+    if (message.includes('does not exist')) {
+        return `Object not found: ${message}`;
+    }
+    if (message.includes('permission denied')) {
+        return `Permission denied: ${message}`;
+    }
+    return message;
+}
+export function describeConnectionError(error) {
+    const message = error?.message ?? 'Unknown connection error';
+    if (message.includes('ECONNREFUSED')) {
+        return 'Connection refused. Check that the Postgres server is running and the host/port are correct.';
+    }
+    if (message.includes('ENOTFOUND')) {
+        return 'Host not found. Check the hostname or IP address in the connection string.';
+    }
+    if (message.includes('password authentication failed')) {
+        return 'Authentication failed. Check the username and password in the connection string.';
+    }
+    if (message.includes('database') && message.includes('does not exist')) {
+        return 'Database does not exist. Check the database name in the connection string.';
+    }
+    if (message.includes('SSL') || message.includes('ssl')) {
+        return `SSL connection error: ${message}. Try adding ?sslmode=require to the connection string.`;
+    }
+    if (message.includes('timeout')) {
+        return 'Connection timed out. Check network connectivity to the database host.';
+    }
+    return message;
+}
+//# sourceMappingURL=errors.js.map

package/dist/db/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/db/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,kFAAkF;AAClF,MAAM,qBAAqB,GAAG,OAAO,CAAA;AAErC,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,MAAM,OAAO,GAAG,KAAoB,CAAA;IACpC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,wBAAwB,CAAA;IAE5D,IAAI,OAAO,EAAE,IAAI,KAAK,qBAAqB,EAAE,CAAC;QAC5C,OAAO,4DAA4D,OAAO,GAAG,CAAA;IAC/E,CAAC;IAED,oFAAoF;IACpF,uFAAuF;IACvF,IAAI,OAAO,CAAC,QAAQ,CAAC,2DAA2D,CAAC,EAAE,CAAC;QAClF,OAAO,uFAAuF,CAAA;IAChG,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,8CAA8C,CAAC,EAAE,CAAC;QACrE,OAAO,sGAAsG,CAAA;IAC/G,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,iBAAiB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;QAC9E,OAAO,qBAAqB,OAAO,GAAG,QAAQ,EAAE,CAAA;IAClD,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACvC,OAAO,qBAAqB,OAAO,EAAE,CAAA;IACvC,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC1C,OAAO,sBAAsB,OAAO,EAAE,CAAA;IACxC,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,MAAM,OAAO,GAAI,KAAqB,EAAE,OAAO,IAAI,0BAA0B,CAAA;IAE7E,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,OAAO,8FAA8F,CAAA;IACvG,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,OAAO,4EAA4E,CAAA;IACrF,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,gCAAgC,CAAC,EAAE,CAAC;QACvD,OAAO,kFAAkF,CAAA;IAC3F,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACvE,OAAO,4EAA4E,CAAA;IACrF,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO,yBAAyB,OAAO,yDAAyD,CAAA;IAClG,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,wEAAwE,CAAA;IACjF,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/db/introspection.d.ts

@@ -0,0 +1,55 @@
+import type { Database } from './pool.js';
+export interface TableSummary {
+    schema: string;
+    name: string;
+    /** `schema.name`, the identifier every other tool accepts. */
+    fullyQualifiedName: string;
+    kind: string;
+    description: string | null;
+}
+export interface ListTablesResult {
+    tables: TableSummary[];
+    /** Total matches before the limit was applied, so truncation can be stated rather than hidden. */
+    totalMatches: number;
+}
+export interface ColumnContext {
+    name: string;
+    dataType: string;
+    isNullable: boolean;
+    defaultValue: string | null;
+    description: string | null;
+    isPrimaryKey: boolean;
+    /** `schema.table.column` this column references, when it is a foreign key. */
+    references: string | null;
+    /** Labels in sort order, when the column's type is an enum. */
+    enumValues: string[] | null;
+}
+export interface TableContext {
+    fullyQualifiedName: string;
+    kind: string;
+    description: string | null;
+    /** Planner estimate from `reltuples`, not an exact count — cheap on large tables. */
+    approximateRows: number | null;
+    columns: ColumnContext[];
+}
+/**
+ * Lists tables, optionally narrowed by a case-insensitive substring.
+ *
+ * The pattern matches anywhere in the table name, the qualified name, or the table's
+ * comment — the comment included because a table named `fct_orders` may be the one
+ * someone means by "revenue", and a name-only match would report nothing and send the
+ * model away empty-handed.
+ */
+export declare function listTables(database: Database, options: {
+    pattern?: string | undefined;
+    schema?: string | undefined;
+    limit: number;
+}): Promise<ListTablesResult>;
+/**
+ * Describes several tables in one round trip — the model usually has two or three
+ * candidates after a search and should not need a call each to choose between them.
+ *
+ * Names are matched case-insensitively, and an unqualified name resolves against any
+ * visible schema, because a model that read `orders` in a list will ask for `orders`.
+ */
+export declare function getTableContext(database: Database, fullyQualifiedNames: string[]): Promise<TableContext[]>;