@contextflo/postgres-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,132 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { parse as parseConnectionString } from 'pg-connection-string';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { getTableContext, listTables } from './db/introspection.js';
+import { ADD_TABLE_CONTEXT_TOOL, runAddTableContextTool } from './tools/add-table-context.js';
+import { GET_TABLE_CONTEXT_TOOL, runGetTableContextTool } from './tools/get-table-context.js';
+import { LIST_TABLES_TOOL, runListTablesTool } from './tools/list-tables.js';
+import { QUERY_TOOL, runQueryTool } from './tools/query.js';
+const SCHEMA_PATH = 'schema';
+const RESOURCE_LIST_LIMIT = 500;
+export function createServer({ context, version, connectionString }) {
+    const server = new Server({ name: 'contextflo/postgres-mcp', version }, {
+        capabilities: { tools: {}, resources: {} },
+        // The curated preamble from .contextflo/context.md — business definitions, caveats,
+        // which tables to prefer — handed to the model once per session.
+        ...(context.contextFile.current.preamble ? { instructions: context.contextFile.current.preamble } : {}),
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            QUERY_TOOL,
+            LIST_TABLES_TOOL,
+            GET_TABLE_CONTEXT_TOOL,
+            ...(context.contextFile.writable ? [ADD_TABLE_CONTEXT_TOOL] : []),
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const args = request.params.arguments;
+        switch (request.params.name) {
+            case QUERY_TOOL.name:
+                return runQueryTool(context, args);
+            case LIST_TABLES_TOOL.name:
+                return runListTablesTool(context, args);
+            case GET_TABLE_CONTEXT_TOOL.name:
+                return runGetTableContextTool(context, args);
+            case ADD_TABLE_CONTEXT_TOOL.name:
+                if (!context.contextFile.writable)
+                    throw new Error(`Unknown tool: ${request.params.name}`);
+                return runAddTableContextTool(context, args);
+            default:
+                throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+    });
+    registerResources(server, context, connectionString);
+    return server;
+}
+/**
+ * The archived server exposed table schemas as `postgres://<host>/<table>/schema`
+ * resources and nothing else. Keeping those URIs means anything pinned to them still
+ * resolves after swapping the package.
+ *
+ * They only ever listed the public schema; tables elsewhere get a schema-qualified URI
+ * rather than being invisible. Note that most clients never fetch resources on their own,
+ * which is why schema discovery lives in the tools — this is compatibility, not the path
+ * we expect models to take.
+ */
+function registerResources(server, context, connectionString) {
+    const baseUrl = buildResourceBaseUrl(connectionString);
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const { tables } = await listTables(context.database, { limit: RESOURCE_LIST_LIMIT });
+        return {
+            resources: tables.map((table) => ({
+                uri: resourceUri(baseUrl, table.schema, table.name),
+                mimeType: 'application/json',
+                name: `"${table.fullyQualifiedName}" database schema`,
+            })),
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { schema, table } = parseResourceUri(request.params.uri);
+        const [described] = await getTableContext(context.database, [`${schema}.${table}`]);
+        if (!described) {
+            throw new Error(`Unknown resource: ${request.params.uri}`);
+        }
+        // Their payload was `[{ column_name, data_type }]`; keep those keys and append ours.
+        const columns = described.columns.map((column) => ({
+            column_name: column.name,
+            data_type: column.dataType,
+            is_nullable: column.isNullable,
+            description: column.description,
+        }));
+        return {
+            contents: [
+                {
+                    uri: request.params.uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(columns, null, 2),
+                },
+            ],
+        };
+    });
+}
+/**
+ * `postgres://user@host:port/database/`, built from the parsed pieces rather than
+ * `new URL(connectionString)`, which throws on `host=... dbname=...` strings and socket
+ * paths. The password is never included.
+ */
+function buildResourceBaseUrl(connectionString) {
+    const { host, port, database, user } = parseConnectionString(connectionString);
+    let url;
+    try {
+        // A socket directory is not a hostname; the URI only needs to be stable, not dialable.
+        url = new URL(`postgres://${host && !host.startsWith('/') ? host : 'localhost'}${port ? `:${port}` : ''}/`);
+    }
+    catch {
+        url = new URL('postgres://localhost/');
+    }
+    if (user)
+        url.username = encodeURIComponent(user);
+    // Always a database segment, so parseResourceUri can tell it from a schema. The
+    // trailing slash keeps `new URL(path, base)` from eating the last path segment.
+    url.pathname = `/${encodeURIComponent(database || 'postgres')}/`;
+    return url;
+}
+function resourceUri(baseUrl, schema, table) {
+    const path = schema === 'public' ? `${table}/${SCHEMA_PATH}` : `${schema}/${table}/${SCHEMA_PATH}`;
+    return new URL(path, baseUrl).href;
+}
+function parseResourceUri(uri) {
+    const parts = new URL(uri).pathname.split('/').filter(Boolean);
+    if (parts.pop() !== SCHEMA_PATH) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    const table = parts.pop();
+    if (!table) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    // Anything left is the schema; the database name at the front is dropped, matching the
+    // archived server's parsing, which only ever looked at the last two segments.
+    const schema = parts.length > 1 ? parts[parts.length - 1] : 'public';
+    return { schema: decodeURIComponent(schema), table: decodeURIComponent(table) };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/tools/add-table-context.d.ts

@@ -0,0 +1,28 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolContext } from './context.js';
+export declare const ADD_TABLE_CONTEXT_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            table: {
+                type: string;
+                description: string;
+            };
+            note: {
+                type: string;
+                description: string;
+            };
+            columns: {
+                type: string;
+                additionalProperties: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function runAddTableContextTool(context: ToolContext, args: Record<string, unknown> | undefined): Promise<CallToolResult>;

package/dist/tools/add-table-context.js

@@ -0,0 +1,105 @@
+import { getTableContext } from '../db/introspection.js';
+/**
+ * Lets the agent write down what it learned the hard way — `amount` is in cents, `status`
+ * also holds 'void' on pre-2022 rows, `deleted_at IS NULL` is required everywhere — so the
+ * next session starts knowing it instead of rediscovering it.
+ *
+ * The database stays read-only; this writes only the local context file. Notes are
+ * appended, never substituted for what a person wrote, and land in a file that lives in
+ * the repo, so a human reviews them in a diff like any other change.
+ */
+const MAX_NOTE_CHARS = 1_000;
+const MAX_COLUMNS_PER_CALL = 50;
+export const ADD_TABLE_CONTEXT_TOOL = {
+    name: 'add_table_context',
+    description: 'Record a durable fact about a table or its columns that you learned from working with the ' +
+        'data and that someone writing SQL against it later would otherwise get wrong: units ' +
+        '("amount is in cents"), undocumented values ("status also contains \'void\' for rows before ' +
+        '2022"), required filters ("exclude rows where deleted_at is set"), or which table is the ' +
+        'source of truth. The note is appended to the team\'s context file and shown by ' +
+        'get_table_context from then on. Do not record what the schema already says (types, ' +
+        'nullability, keys), one-off query results, or anything you have not verified against the data.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            table: {
+                type: 'string',
+                description: 'The table, ideally qualified as "schema.table".',
+            },
+            note: {
+                type: 'string',
+                description: 'Optional. One or two sentences about the table as a whole.',
+            },
+            columns: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'Optional. Column name → one or two sentences about that column.',
+            },
+        },
+        required: ['table'],
+    },
+};
+export async function runAddTableContextTool(context, args) {
+    const table = typeof args?.table === 'string' ? args.table.trim() : '';
+    const note = typeof args?.note === 'string' && args.note.trim() !== '' ? args.note.trim() : undefined;
+    const rawColumns = isStringRecord(args?.columns) ? args.columns : {};
+    const columnEntries = Object.entries(rawColumns).filter(([, value]) => value.trim() !== '');
+    if (table === '')
+        return toolError('The "table" argument is required.');
+    if (args?.columns !== undefined && !isStringRecord(args.columns)) {
+        return toolError('"columns" must be an object mapping column names to notes, e.g. {"amount": "In cents."}.');
+    }
+    if (!note && columnEntries.length === 0) {
+        return toolError('Nothing to add: pass a "note" for the table, "columns" notes, or both.');
+    }
+    if (columnEntries.length > MAX_COLUMNS_PER_CALL) {
+        return toolError(`At most ${MAX_COLUMNS_PER_CALL} column notes per call.`);
+    }
+    const tooLong = [note, ...columnEntries.map(([, value]) => value)].some((text) => text !== undefined && text.length > MAX_NOTE_CHARS);
+    if (tooLong) {
+        return toolError(`Keep each note under ${MAX_NOTE_CHARS} characters — a sentence or two.`);
+    }
+    // Only tables that exist and are readable, so a guessed name cannot become a heading.
+    const matches = await getTableContext(context.database, [table]);
+    if (matches.length === 0) {
+        return toolError(`No readable table named ${table}. Use list_tables to find the exact name.`);
+    }
+    if (matches.length > 1) {
+        return toolError(`"${table}" matches more than one table: ${matches.map((match) => match.fullyQualifiedName).join(', ')}. ` +
+            'Pass the schema-qualified name.');
+    }
+    const resolved = matches[0];
+    const actualColumns = new Map(resolved.columns.map((column) => [column.name.toLowerCase(), column.name]));
+    const unknown = columnEntries.filter(([name]) => !actualColumns.has(name.toLowerCase())).map(([name]) => name);
+    if (unknown.length > 0) {
+        return toolError(`${resolved.fullyQualifiedName} has no column ${unknown.join(', ')}. ` +
+            'Use get_table_context to see its columns.');
+    }
+    if (!context.contextFile.writable || context.contextFile.path === null) {
+        return toolError('Context writes are turned off on this server (--no-context-writes).');
+    }
+    const columns = Object.fromEntries(columnEntries.map(([name, value]) => [actualColumns.get(name.toLowerCase()), value]));
+    await context.contextFile.addNotes(resolved.fullyQualifiedName, { note, columns });
+    const added = [note && 'the table note', columnEntries.length > 0 && `${columnEntries.length} column note(s)`]
+        .filter(Boolean)
+        .join(' and ');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Added ${added} for ${resolved.fullyQualifiedName} to ${context.contextFile.path}.`,
+            },
+        ],
+        isError: false,
+    };
+}
+function isStringRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((item) => typeof item === 'string'));
+}
+function toolError(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+//# sourceMappingURL=add-table-context.js.map

package/dist/tools/add-table-context.js.map

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

package/dist/tools/context.d.ts

@@ -0,0 +1,12 @@
+import type { ContextStore } from '../context/store.js';
+import type { Database } from '../db/pool.js';
+import type { QueryLog } from '../log.js';
+/** Everything the tools share. Assembled once at startup in src/index.ts. */
+export interface ToolContext {
+    database: Database;
+    contextFile: ContextStore;
+    log: QueryLog;
+    maxRows: number;
+    /** Character budget for one query result, so a wide result cannot flood the model's context. */
+    maxOutputChars: number;
+}

package/dist/tools/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/tools/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":""}

package/dist/tools/get-table-context.d.ts

@@ -0,0 +1,20 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolContext } from './context.js';
+export declare const GET_TABLE_CONTEXT_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            tables: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function runGetTableContextTool(context: ToolContext, args: Record<string, unknown> | undefined): Promise<CallToolResult>;

package/dist/tools/get-table-context.js

@@ -0,0 +1,102 @@
+import { getTableContext } from '../db/introspection.js';
+import { notesForTable, preferCuratedDescription } from '../context/context-file.js';
+export const GET_TABLE_CONTEXT_TOOL = {
+    name: 'get_table_context',
+    description: 'Describe one or more tables: columns, types, nullability, primary keys, foreign key ' +
+        'targets, and any curated descriptions. Pass every candidate table at once rather than ' +
+        'calling repeatedly. Read this before writing SQL against a table you have not used yet.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            tables: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Table names, ideally qualified as "schema.table". An unqualified name resolves ' +
+                    'against any readable schema.',
+            },
+        },
+        required: ['tables'],
+    },
+};
+export async function runGetTableContextTool(context, args) {
+    const requested = Array.isArray(args?.tables)
+        ? args.tables.filter((name) => typeof name === 'string' && name.trim() !== '')
+        : [];
+    if (requested.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'The "tables" argument is required: an array of table names.' }],
+            isError: true,
+        };
+    }
+    const [tables, document] = await Promise.all([
+        getTableContext(context.database, requested),
+        context.contextFile.refresh(),
+    ]);
+    if (tables.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `None of these are readable tables: ${requested.join(', ')}. ` +
+                        'Use list_tables to see what exists — the name may be in a different schema, or the ' +
+                        'connected role may not have SELECT on it.',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const rendered = tables.map((table) => renderTable(document, table)).join('\n\n');
+    const missing = findMissing(requested, tables);
+    const notice = missing.length > 0 ? `\n\nNot found: ${missing.join(', ')}.` : '';
+    return { content: [{ type: 'text', text: rendered + notice }], isError: false };
+}
+function renderTable(document, table) {
+    const notes = notesForTable(document, table.fullyQualifiedName);
+    const description = preferCuratedDescription(notes?.description, table.description);
+    const heading = `## ${table.fullyQualifiedName} — ${table.kind}${formatRowCount(table.approximateRows)}`;
+    const lines = [heading];
+    if (description)
+        lines.push(description);
+    lines.push('');
+    for (const column of table.columns) {
+        lines.push(renderColumn(column, notes?.columns.get(column.name.toLowerCase())));
+    }
+    return lines.join('\n');
+}
+function renderColumn(column, curated) {
+    const facts = [column.dataType];
+    if (column.isPrimaryKey)
+        facts.push('primary key');
+    else if (!column.isNullable)
+        facts.push('not null');
+    if (column.references)
+        facts.push(`→ ${column.references}`);
+    if (column.enumValues?.length)
+        facts.push(formatEnumValues(column.enumValues));
+    if (column.defaultValue)
+        facts.push(`default ${column.defaultValue}`);
+    const description = preferCuratedDescription(curated, column.description);
+    return `- ${column.name} — ${facts.join(', ')}${description ? ` — ${description}` : ''}`;
+}
+/** The model otherwise guesses `'Active'` for a column whose values are `'active'`. */
+const MAX_ENUM_VALUES = 30;
+function formatEnumValues(values) {
+    const shown = values.slice(0, MAX_ENUM_VALUES).map((value) => `'${value}'`);
+    const more = values.length > MAX_ENUM_VALUES ? `, … ${values.length - MAX_ENUM_VALUES} more` : '';
+    return `one of ${shown.join(', ')}${more}`;
+}
+/** `reltuples` is a planner estimate, so say so rather than implying an exact count. */
+function formatRowCount(approximateRows) {
+    if (approximateRows === null || approximateRows <= 0)
+        return '';
+    return `, ~${approximateRows.toLocaleString('en-US')} rows`;
+}
+function findMissing(requested, found) {
+    const resolved = new Set();
+    for (const table of found) {
+        resolved.add(table.fullyQualifiedName.toLowerCase());
+        resolved.add(table.fullyQualifiedName.split('.').pop().toLowerCase());
+    }
+    return requested.filter((name) => !resolved.has(name.toLowerCase()));
+}
+//# sourceMappingURL=get-table-context.js.map

package/dist/tools/get-table-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-table-context.js","sourceRoot":"","sources":["../../src/tools/get-table-context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAyC,MAAM,wBAAwB,CAAA;AAC/F,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAwB,MAAM,4BAA4B,CAAA;AAG1G,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,mBAAmB;IACzB,WAAW,EACT,sFAAsF;QACtF,wFAAwF;QACxF,yFAAyF;IAC3F,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EACT,iFAAiF;oBACjF,8BAA8B;aACjC;SACF;QACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;KACrB;CACF,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAoB,EACpB,IAAyC;IAEzC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;QAC3C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAC9F,CAAC,CAAC,EAAE,CAAA;IAEN,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,6DAA6D,EAAE,CAAC;YAChG,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IAED,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC3C,eAAe,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC;QAC5C,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE;KAC9B,CAAC,CAAA;IAEF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,sCAAsC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;wBAC9D,qFAAqF;wBACrF,2CAA2C;iBAC9C;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACjF,MAAM,OAAO,GAAG,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IAE9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAEhF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AACjF,CAAC;AAED,SAAS,WAAW,CAAC,QAAyB,EAAE,KAAmB;IACjE,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAC/D,MAAM,WAAW,GAAG,wBAAwB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;IAEnF,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,kBAAkB,MAAM,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAA;IACxG,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,CAAA;IAEvB,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAExC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAA;IACjF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED,SAAS,YAAY,CAAC,MAAqB,EAAE,OAA2B;IACtE,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAE/B,IAAI,MAAM,CAAC,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;SAC7C,IAAI,CAAC,MAAM,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAEnD,IAAI,MAAM,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC,CAAA;IAC3D,IAAI,MAAM,CAAC,UAAU,EAAE,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAA;IAC9E,IAAI,MAAM,CAAC,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,YAAY,EAAE,CAAC,CAAA;IAErE,MAAM,WAAW,GAAG,wBAAwB,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;IAEzE,OAAO,KAAK,MAAM,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC1F,CAAC;AAED,uFAAuF;AACvF,MAAM,eAAe,GAAG,EAAE,CAAA;AAE1B,SAAS,gBAAgB,CAAC,MAAgB;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAA;IAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,MAAM,GAAG,eAAe,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;IACjG,OAAO,UAAU,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAA;AAC5C,CAAC;AAED,wFAAwF;AACxF,SAAS,cAAc,CAAC,eAA8B;IACpD,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,IAAI,CAAC;QAAE,OAAO,EAAE,CAAA;IAC/D,OAAO,MAAM,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,OAAO,CAAA;AAC7D,CAAC;AAED,SAAS,WAAW,CAAC,SAAmB,EAAE,KAAqB;IAC7D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;IAClC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,WAAW,EAAE,CAAC,CAAA;QACpD,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC,WAAW,EAAE,CAAC,CAAA;IACxE,CAAC;IAED,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;AACtE,CAAC"}

package/dist/tools/list-tables.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolContext } from './context.js';
+export declare const DEFAULT_LIST_LIMIT = 100;
+export declare const LIST_TABLES_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            pattern: {
+                type: string;
+                description: string;
+            };
+            schema: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function runListTablesTool(context: ToolContext, args: Record<string, unknown> | undefined): Promise<CallToolResult>;

package/dist/tools/list-tables.js

@@ -0,0 +1,78 @@
+import { listTables } from '../db/introspection.js';
+import { notesForTable, preferCuratedDescription } from '../context/context-file.js';
+export const DEFAULT_LIST_LIMIT = 100;
+const MAX_LIST_LIMIT = 500;
+export const LIST_TABLES_TOOL = {
+    name: 'list_tables',
+    description: 'List the tables, views, and materialized views this connection can read, with their ' +
+        'descriptions. Call this first when you need to know what data exists — do not guess ' +
+        'table names. Pass `pattern` to narrow by a word appearing anywhere in the table name ' +
+        'or its description; call it again with a different word to try a synonym. For anything ' +
+        'more specific — searching column names, types, or comments — query information_schema ' +
+        'and pg_catalog directly with the query tool, they are ordinary tables.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'Optional. Case-insensitive substring matched anywhere in the table name, the ' +
+                    'qualified schema.table name, or the table description. Omit to list everything.',
+            },
+            schema: {
+                type: 'string',
+                description: 'Optional. Restrict to one schema, e.g. "analytics".',
+            },
+            limit: {
+                type: 'integer',
+                description: `Optional. Maximum tables to return (default ${DEFAULT_LIST_LIMIT}, max ${MAX_LIST_LIMIT}).`,
+            },
+        },
+    },
+};
+export async function runListTablesTool(context, args) {
+    const pattern = optionalString(args?.pattern);
+    const schema = optionalString(args?.schema);
+    const limit = Math.min(Math.max(Number(args?.limit) || DEFAULT_LIST_LIMIT, 1), MAX_LIST_LIMIT);
+    const [result, document] = await Promise.all([
+        listTables(context.database, { pattern, schema, limit }),
+        context.contextFile.refresh(),
+    ]);
+    // Several clients never show the model the server's instructions, so the team's
+    // business definitions also ride along with the tool the model is told to call first.
+    const preamble = document.preamble ? `Business context from the team:\n\n${document.preamble}\n\n---\n\n` : '';
+    if (result.tables.length === 0) {
+        return {
+            content: [{ type: 'text', text: preamble + describeEmptyResult(pattern, schema) }],
+            isError: false,
+        };
+    }
+    const lines = result.tables.map((table) => {
+        const curated = notesForTable(document, table.fullyQualifiedName)?.description;
+        const description = preferCuratedDescription(curated, table.description);
+        return `${table.fullyQualifiedName} — ${table.kind}${description ? ` — ${description}` : ''}`;
+    });
+    const header = result.totalMatches > result.tables.length
+        ? `Showing ${result.tables.length} of ${result.totalMatches} matching tables. ` +
+            'Narrow with `pattern` or `schema`, or raise `limit`.'
+        : `${result.tables.length} table${result.tables.length === 1 ? '' : 's'}.`;
+    return {
+        content: [{ type: 'text', text: `${preamble}${header}\n\n${lines.join('\n')}` }],
+        isError: false,
+    };
+}
+function describeEmptyResult(pattern, schema) {
+    if (!pattern && !schema) {
+        return ('No readable tables found. The connected role may not have SELECT on anything, or the ' +
+            'database may be empty.');
+    }
+    const filters = [pattern && `pattern "${pattern}"`, schema && `schema "${schema}"`]
+        .filter(Boolean)
+        .join(' and ');
+    return (`No tables matched ${filters}. Try a synonym, drop the filters to see everything, or search ` +
+        'column names directly, e.g. ' +
+        "SELECT table_schema, table_name, column_name FROM information_schema.columns WHERE column_name ILIKE '%term%'");
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+//# sourceMappingURL=list-tables.js.map

package/dist/tools/list-tables.js.map

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

package/dist/tools/query.d.ts

@@ -0,0 +1,22 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolContext } from './context.js';
+/**
+ * Name, argument, and result shape match the archived
+ * `@modelcontextprotocol/server-postgres` so existing prompts and configs keep working
+ * when someone swaps the package name.
+ */
+export declare const QUERY_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            sql: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function runQueryTool(context: ToolContext, args: Record<string, unknown> | undefined): Promise<CallToolResult>;