@contextflo/postgres-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ContextFlo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @contextflo/postgres-mcp
+
+The analytics MCP server for Postgres. Read-only by construction, with schema context that makes answers correct.
+
+A drop-in replacement for the archived `@modelcontextprotocol/server-postgres`, which shipped with a
+[SQL injection vulnerability](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/)
+that let `COMMIT; DROP SCHEMA public CASCADE` walk straight out of its read-only transaction.
+
+```bash
+npx @contextflo/postgres-mcp postgresql://localhost/mydb
+```
+
+## Why this one
+
+**Read-only that holds up.** The archived server enforced read-only as a property of the SQL *string*. Here it is a
+property of the connection, the role, and the wire protocol: four independent layers, each of which stops that
+payload on its own. The exploit is a test case in this repo.
+
+**Answers that make sense.** A model that does not know `fct_orders_v2` is the table your team actually uses, or that
+`revenue` is gross rather than net, writes confident, wrong SQL. `.contextflo/context.md` is a markdown file you edit
+and this server hands to the model. No database, no index, no service.
+
+## Setup
+
+Add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@contextflo/postgres-mcp", "postgresql://localhost/mydb"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Claude Code, Cursor, Claude Desktop, VS Code</summary>
+
+**Claude Code**
+
+```bash
+claude mcp add postgres -- npx -y @contextflo/postgres-mcp postgresql://localhost/mydb
+```
+
+**Cursor** uses `.cursor/mcp.json`, same shape as above.
+
+**Claude Desktop** uses `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), same shape as above.
+
+**VS Code** uses `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@contextflo/postgres-mcp", "postgresql://localhost/mydb"]
+    }
+  }
+}
+```
+
+</details>
+
+Then generate a context file:
+
+```bash
+npx @contextflo/postgres-mcp init postgresql://localhost/mydb
+```
+
+That writes `.contextflo/context.md`, seeded from your `COMMENT ON` values, and prints the `CREATE ROLE` snippet for
+a read-only role. Editing the file is the point: the business definitions section is where the value is.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `query` | Runs one read-only statement: `SELECT`, `WITH ... SELECT`, `EXPLAIN`, or `SHOW`. |
+| `list_tables` | Lists readable tables with descriptions. `pattern` matches anywhere in the name or description. |
+| `get_table_context` | Describes tables: columns, types, keys, foreign key targets, enum values, curated descriptions. |
+| `add_table_context` | Lets the agent write down a gotcha it found (`amount` is in cents, `status` has an undocumented value) in the context file. |
+
+There is no separate search tool, and that is deliberate. `information_schema` and `pg_catalog` are ordinary tables,
+so anything more specific, like finding every column named like `%revenue%` or listing tables with no primary key,
+is a query the model can write itself:
+
+```sql
+SELECT table_schema, table_name, column_name
+FROM information_schema.columns
+WHERE column_name ILIKE '%revenue%';
+```
+
+Table schemas are also exposed as `postgres://<host>/<table>/schema` resources, matching the archived server, for
+anything pinned to those URIs. Most clients never fetch resources on their own, which is why discovery lives in the
+tools.
+
+## How read-only is enforced
+
+Four layers. Each one stops the archived server's exploit by itself.
+
+**1. Extended query protocol.** User SQL goes through `pg-cursor`, which always issues Parse/Bind/Execute, so
+Postgres itself rejects multi-statement input. The archived server called `client.query(sql)` with a bare string;
+node-postgres only prepares a statement when there are bind values, so that took the *simple* protocol path, where
+`;` separates statements. That is the whole bug.
+
+**2. Connection-level read-only.** `default_transaction_read_only=on` is set in the startup packet, and every
+statement runs inside an explicit `BEGIN READ ONLY` that always ends in `ROLLBACK`, never `COMMIT`. The rollback
+also undoes any `SET` made inside the transaction, so a statement cannot leave a pooled connection weakened for
+whoever gets it next.
+
+**3. A statement allowlist on the real Postgres parser.** [`libpg-query`](https://github.com/launchql/libpg-query-node)
+is the actual Postgres C parser compiled to WASM, not a JavaScript approximation of SQL. The whole parse tree is
+walked rather than just the top-level node, which is what catches a data-modifying CTE:
+
+```sql
+WITH x AS (INSERT INTO users VALUES (1) RETURNING *) SELECT * FROM x
+```
+
+That parses as a `SelectStmt`. A validator checking only the statement type runs it. Unknown node types fail closed.
+
+The same walk rejects built-in functions that act outside the transaction even inside a plain `SELECT`:
+`dblink` (a second connection, which is not read-only), `query_to_xml` (runs a SQL string the parser never sees),
+`pg_terminate_backend`, session-level advisory locks, `set_config`, and the server-filesystem functions.
+
+**4. A read-only database role.** The layers above are code, and code has bugs. A role that cannot write is enforced
+by Postgres regardless. `init` prints the snippet; this is the setup we recommend:
+
+```sql
+CREATE ROLE mcp_readonly LOGIN PASSWORD 'change-me';
+GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
+GRANT USAGE ON SCHEMA public TO mcp_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;
+```
+
+The server warns on startup if you connect as a superuser.
+
+**What this does not protect against.** The parser cannot see inside a user-defined function, so a volatile or
+`SECURITY DEFINER` function called from an allowed `SELECT` can do anything its body does, including open its own
+connection. The function denylist covers the built-in escapes, not yours. Layer 4 is what stops the rest, which is
+why the read-only role is the recommended setup rather than an optional extra. Read-only is also not
+confidentiality: anything the connected role can read, a model can read, so grant it only what you want an agent
+to see.
+
+## Migrating from `@modelcontextprotocol/server-postgres`
+
+Swap the package name. The tool is still called `query`, still takes `sql`, still returns JSON rows, and the
+connection string is still the first argument.
+
+Four deliberate differences:
+
+1. **Multi-statement SQL and `SET`/`RESET` are rejected** with a clear error. On the archived server these "worked",
+   and that was the vulnerability.
+2. **Results are capped** at 1000 rows and 50,000 characters by default, and single values over 2,000 characters are
+   shortened. Truncation is stated in the output, never silent. Rows come back one per line rather than
+   pretty-printed, which roughly halves their token cost; it is still a JSON array. Dates and timestamps are exactly
+   what Postgres sent, not re-rendered in the server's timezone.
+3. **Schema discovery is a tool, not just a resource.** Most clients do not auto-attach resources, which is why
+   models using the old server so often did not know the schema.
+4. **All non-system schemas are visible**, not only `public`, and column descriptions come through from
+   `COMMENT ON`.
+
+## Options
+
+```
+--max-rows <n>            Maximum rows returned per query (default: 1000)
+--max-output-chars <n>    Character budget for one query result (default: 50000)
+--statement-timeout <ms>  Server-side statement timeout (default: 30000)
+--context-file <path>     Curated schema context (default: .contextflo/context.md)
+--no-context-writes       Do not offer add_table_context; the context file is only read
+--log-file <path>         Query audit log (default: .contextflo/log.md once that directory exists)
+--no-log                  Never write a query log
+--http                    Serve over streamable HTTP instead of stdio
+--port <n>                HTTP port (default: 8080)
+--host <addr>             HTTP bind address (default: 127.0.0.1)
+```
+
+`DATABASE_URL` supplies the connection string if you do not pass one. `AUTH_TOKEN`, with `--http`, requires that
+value as a bearer token.
+
+**Connection poolers.** PgBouncer (and so the pooled connection strings from Supabase, Neon, and others) refuses
+the startup parameters this server normally sends. When that happens it reconnects without them and says so on
+stderr. Nothing is weakened: every statement still runs in `BEGIN READ ONLY` with its own statement timeout, and CI
+runs the read-only suite through PgBouncer in transaction mode.
+
+## The context file
+
+```markdown
+# Database context
+
+Revenue means gross, before refunds.
+"Active customer" means an order in the last 90 days.
+
+## Tables
+
+### public.orders
+One row per customer order. Source of truth for revenue, not `orders_legacy`.
+
+- revenue_usd: Gross revenue, before refunds. Net lives in `order_refunds`.
+- status: One of pending, paid, refunded.
+```
+
+Everything above `## Tables` is handed to the model: as server instructions, and again at the top of `list_tables`,
+because several clients never show the model server instructions. HTML comments are left out. Under `## Tables`, a
+`###` heading names a table, the prose beneath describes it, and `- column: meaning` lines describe columns (a dash
+separator works too). Your text wins over `COMMENT ON`. Edits take effect on the next tool call; no restart.
+
+A relative `--context-file` resolves against the directory the client starts the server in. Claude Desktop starts
+servers in `/`, so there it falls back to your home directory (`~/.contextflo/context.md`). For a file that lives in
+a repo, pass an absolute path. The server prints the path it is using on startup.
+
+**The agent adds to it.** When the model finds something the schema does not say (`amount` is in cents, `status`
+also holds `'void'` on old rows, every query needs `deleted_at IS NULL`), `add_table_context` appends it to this file,
+and every later session starts knowing it. Notes are only ever appended, never substituted for what you wrote, and
+only for tables and columns that exist. Treat them like any other change: keep the file in git and read the diff. A
+model can be wrong, and text inside your data can steer what it writes, so a note is a suggestion until someone has
+looked at it. `--no-context-writes` turns the tool off.
+
+`init` seeds this from existing comments, and only for columns that already have one. A file with a blank
+placeholder for all 4000 columns is a file nobody edits.
+
+Richer context generated from your code and docs, and shared across a team, is what
+[contextflo.com](https://contextflo.com) does.
+
+## Query log
+
+Once `.contextflo/` exists, every statement is appended to `.contextflo/log.md` with its outcome, row count, and
+duration. It is written for you, not fed back to the model. `--no-log` turns it off.
+
+## Docker
+
+```bash
+docker run -i --rm ghcr.io/contextflo/postgres-mcp postgresql://host.docker.internal/mydb
+```
+
+For a remote endpoint, see [`docker-compose.example.yml`](docker-compose.example.yml). Note what you are doing
+before you bind `0.0.0.0`: that is a live database connection on a port. Set `AUTH_TOKEN`, keep it inside a private
+network, and terminate TLS in front of it, because the token is plaintext on the wire otherwise. The server prints a
+warning when it is exposed without a token.
+
+On the default loopback bind, requests whose `Host` or `Origin` is not local are refused. That is what stops a web
+page from using DNS rebinding to reach a server on `127.0.0.1` through your browser.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+
+npm run db:up   # throwaway Postgres for the integration suite (needs Docker)
+TEST_DATABASE_URL=postgres://postgres:postgres@localhost:55432/postgres npm test
+npm run db:down
+```
+
+The integration suite deliberately bypasses the parser and drives the database directly, so it proves the wire and
+transaction layers rather than the validator. It skips without `TEST_DATABASE_URL` and is required to run in CI.
+
+## Security
+
+Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+export interface HttpConfig {
+    host: string;
+    port: number;
+    /** From the AUTH_TOKEN environment variable. Unset means no authentication. */
+    authToken: string | undefined;
+}
+export interface ServerConfig {
+    command: 'serve' | 'init';
+    connectionString: string;
+    maxRows: number;
+    maxOutputChars: number;
+    statementTimeoutMs: number;
+    /** Absolute. */
+    contextFile: string;
+    /** Whether the add_table_context tool is offered. */
+    contextWrites: boolean;
+    contextDirectory: string;
+    logFile: string | undefined;
+    logDisabled: boolean;
+    /** Undefined means stdio. */
+    http: HttpConfig | undefined;
+}
+export declare const DEFAULT_MAX_ROWS = 1000;
+/** About 12k tokens: room for a real answer, not enough to crowd out the conversation. */
+export declare const DEFAULT_MAX_OUTPUT_CHARS = 50000;
+export declare const DEFAULT_STATEMENT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_HTTP_PORT = 8080;
+/** Loopback by default: exposing a database to the network should take a deliberate flag. */
+export declare const DEFAULT_HTTP_HOST = "127.0.0.1";
+export declare class ConfigError extends Error {
+}
+/** Not a failure — `--help` is a successful invocation that prints and exits 0. */
+export declare class HelpRequested extends Error {
+    constructor();
+}
+export declare const USAGE = "postgres-mcp \u2014 the analytics MCP server for Postgres (read-only)\n\nUsage:\n  npx @contextflo/postgres-mcp <connection-string> [options]\n  npx @contextflo/postgres-mcp init <connection-string>\n\nThe connection string may also be supplied via the DATABASE_URL environment variable.\n\nCommands:\n  init                      Scan the schema and write .contextflo/context.md for you to edit\n\nOptions:\n  --max-rows <n>            Maximum rows returned per query (default: 1000)\n  --max-output-chars <n>    Character budget for one query result (default: 50000)\n  --statement-timeout <ms>  Server-side statement timeout in milliseconds (default: 30000)\n  --context-file <path>     Curated schema context served to the model (default: .contextflo/context.md)\n  --no-context-writes       Do not offer add_table_context; the context file is only read\n  --log-file <path>         Append a query audit log here (default: .contextflo/log.md once that directory exists)\n  --no-log                  Never write a query log\n  --http                    Serve over streamable HTTP instead of stdio\n  --port <n>                HTTP port (default: 8080)\n  --host <addr>             HTTP bind address (default: 127.0.0.1; use 0.0.0.0 to expose)\n  -h, --help                Show this message\n\nEnvironment:\n  DATABASE_URL              Connection string, if not given as an argument\n  AUTH_TOKEN                If set with --http, require this as a bearer token";
+/**
+ * The connection URL is the first positional argument, matching the archived
+ * `@modelcontextprotocol/server-postgres` so migrating is a package-name swap.
+ */
+export declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv, cwd?: string): ServerConfig;
+/**
+ * Relative paths resolve against the working directory — except when that is the
+ * filesystem root, which is where Claude Desktop and some other clients start servers.
+ * `/.contextflo/context.md` is never what anyone meant, so fall back to the home directory.
+ */
+export declare function resolveContextFile(path: string, cwd: string, home?: string): string;

package/dist/config.js

@@ -0,0 +1,159 @@
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { DEFAULT_CONTEXT_DIRECTORY, DEFAULT_CONTEXT_FILE } from './context/context-file.js';
+export const DEFAULT_MAX_ROWS = 1000;
+/** About 12k tokens: room for a real answer, not enough to crowd out the conversation. */
+export const DEFAULT_MAX_OUTPUT_CHARS = 50_000;
+export const DEFAULT_STATEMENT_TIMEOUT_MS = 30_000;
+export const DEFAULT_HTTP_PORT = 8080;
+/** Loopback by default: exposing a database to the network should take a deliberate flag. */
+export const DEFAULT_HTTP_HOST = '127.0.0.1';
+export class ConfigError extends Error {
+}
+/** Not a failure — `--help` is a successful invocation that prints and exits 0. */
+export class HelpRequested extends Error {
+    constructor() {
+        super(USAGE);
+    }
+}
+export const USAGE = `postgres-mcp — the analytics MCP server for Postgres (read-only)
+
+Usage:
+  npx @contextflo/postgres-mcp <connection-string> [options]
+  npx @contextflo/postgres-mcp init <connection-string>
+
+The connection string may also be supplied via the DATABASE_URL environment variable.
+
+Commands:
+  init                      Scan the schema and write ${DEFAULT_CONTEXT_FILE} for you to edit
+
+Options:
+  --max-rows <n>            Maximum rows returned per query (default: ${DEFAULT_MAX_ROWS})
+  --max-output-chars <n>    Character budget for one query result (default: ${DEFAULT_MAX_OUTPUT_CHARS})
+  --statement-timeout <ms>  Server-side statement timeout in milliseconds (default: ${DEFAULT_STATEMENT_TIMEOUT_MS})
+  --context-file <path>     Curated schema context served to the model (default: ${DEFAULT_CONTEXT_FILE})
+  --no-context-writes       Do not offer add_table_context; the context file is only read
+  --log-file <path>         Append a query audit log here (default: ${DEFAULT_CONTEXT_DIRECTORY}/log.md once that directory exists)
+  --no-log                  Never write a query log
+  --http                    Serve over streamable HTTP instead of stdio
+  --port <n>                HTTP port (default: ${DEFAULT_HTTP_PORT})
+  --host <addr>             HTTP bind address (default: ${DEFAULT_HTTP_HOST}; use 0.0.0.0 to expose)
+  -h, --help                Show this message
+
+Environment:
+  DATABASE_URL              Connection string, if not given as an argument
+  AUTH_TOKEN                If set with --http, require this as a bearer token`;
+/**
+ * The connection URL is the first positional argument, matching the archived
+ * `@modelcontextprotocol/server-postgres` so migrating is a package-name swap.
+ */
+export function parseArgs(argv, env = process.env, cwd = process.cwd()) {
+    let command = 'serve';
+    let connectionString;
+    let maxRows = DEFAULT_MAX_ROWS;
+    let maxOutputChars = DEFAULT_MAX_OUTPUT_CHARS;
+    let contextWrites = true;
+    let statementTimeoutMs = DEFAULT_STATEMENT_TIMEOUT_MS;
+    let contextFile = DEFAULT_CONTEXT_FILE;
+    let logFile;
+    let logDisabled = false;
+    let http = false;
+    let port = DEFAULT_HTTP_PORT;
+    let host = DEFAULT_HTTP_HOST;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        switch (arg) {
+            case 'init':
+                if (index !== 0)
+                    throw new ConfigError(`"init" must come first.\n\n${USAGE}`);
+                command = 'init';
+                break;
+            case '--max-rows':
+                maxRows = requirePositiveInteger(arg, argv[++index]);
+                break;
+            case '--max-output-chars':
+                maxOutputChars = requirePositiveInteger(arg, argv[++index]);
+                break;
+            case '--no-context-writes':
+                contextWrites = false;
+                break;
+            case '--statement-timeout':
+                statementTimeoutMs = requirePositiveInteger(arg, argv[++index]);
+                break;
+            case '--context-file':
+                contextFile = requireValue(arg, argv[++index]);
+                break;
+            case '--log-file':
+                logFile = requireValue(arg, argv[++index]);
+                break;
+            case '--no-log':
+                logDisabled = true;
+                break;
+            case '--http':
+                http = true;
+                break;
+            case '--port':
+                port = requirePositiveInteger(arg, argv[++index]);
+                break;
+            case '--host':
+                host = requireValue(arg, argv[++index]);
+                break;
+            case '-h':
+            case '--help':
+                throw new HelpRequested();
+            default:
+                if (arg.startsWith('-')) {
+                    throw new ConfigError(`Unknown option: ${arg}\n\n${USAGE}`);
+                }
+                if (connectionString !== undefined) {
+                    throw new ConfigError(`Unexpected argument: ${arg}\n\n${USAGE}`);
+                }
+                connectionString = arg;
+        }
+    }
+    connectionString ??= env.DATABASE_URL;
+    if (!connectionString) {
+        throw new ConfigError(`A Postgres connection string is required.\n\n${USAGE}`);
+    }
+    if (logFile && logDisabled) {
+        throw new ConfigError('--log-file and --no-log contradict each other.');
+    }
+    const resolvedContextFile = resolveContextFile(contextFile, cwd);
+    return {
+        command,
+        connectionString,
+        maxRows,
+        maxOutputChars,
+        statementTimeoutMs,
+        contextFile: resolvedContextFile,
+        contextWrites,
+        contextDirectory: dirname(resolvedContextFile),
+        logFile,
+        logDisabled,
+        http: http ? { host, port, authToken: env.AUTH_TOKEN || undefined } : undefined,
+    };
+}
+/**
+ * Relative paths resolve against the working directory — except when that is the
+ * filesystem root, which is where Claude Desktop and some other clients start servers.
+ * `/.contextflo/context.md` is never what anyone meant, so fall back to the home directory.
+ */
+export function resolveContextFile(path, cwd, home = homedir()) {
+    if (isAbsolute(path))
+        return path;
+    return resolve(cwd === '/' || /^[A-Za-z]:\\?$/.test(cwd) ? home : cwd, path);
+}
+function requireValue(flag, raw) {
+    if (!raw || raw.startsWith('-')) {
+        throw new ConfigError(`${flag} expects a value, received: ${raw ?? '(nothing)'}`);
+    }
+    return raw;
+}
+function requirePositiveInteger(flag, raw) {
+    const value = Number(raw);
+    if (!raw || !Number.isInteger(value) || value <= 0) {
+        throw new ConfigError(`${flag} expects a positive integer, received: ${raw ?? '(nothing)'}`);
+    }
+    return value;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/context/context-file.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `.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 declare const DEFAULT_CONTEXT_DIRECTORY = ".contextflo";
+export declare const DEFAULT_CONTEXT_FILE = ".contextflo/context.md";
+export interface TableNotes {
+    description?: string;
+    columns: Map<string, string>;
+}
+export interface ContextDocument {
+    /** Free text above `## Tables`: business definitions, caveats, which tables to prefer. */
+    preamble: string;
+    /** Keyed by lower-cased `schema.table`. */
+    tables: Map<string, TableNotes>;
+}
+export declare function emptyContextDocument(): ContextDocument;
+/** Returns null when the file does not exist — the server runs fine without one. */
+export declare function loadContextFile(path: string): Promise<ContextDocument | null>;
+export declare function parseContextFile(raw: string): ContextDocument;
+export declare function notesForTable(document: ContextDocument, fullyQualifiedName: string): TableNotes | 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 declare function preferCuratedDescription(curated: string | undefined, fromCatalog: string | null): string | null;
+export interface NewTableNotes {
+    /** Appended to the table's description. */
+    note?: string | undefined;
+    /** Column name → note, appended to that column's line or added as a new one. */
+    columns?: Record<string, string> | undefined;
+}
+/**
+ * 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 declare function addTableNotes(raw: string, fullyQualifiedName: string, notes: NewTableNotes): string;
+export declare const CONTEXT_FILE_HEADER = "# Database context\n\n<!--\npostgres-mcp reads this file and hands it to the model every session. It is the whole\ncontext layer \u2014 no database, no index, just this file.\n\nEverything above \"## Tables\" is passed through verbatim. Put the things your team\nargues about here: whether revenue is gross or net, what counts as an active customer,\nwhich table is the source of truth and which one nobody got around to dropping.\n\nUnder \"## Tables\", a \"###\" heading names a table, the prose beneath it describes the\ntable, and each \"- column \u2014 meaning\" line describes a column. Seeded from your\ndatabase's COMMENT ON values; anything you write wins over those.\n\nAdd a line for any column you like \u2014 only already-commented ones were seeded, to keep\nthis file small enough that you will actually edit it.\n\nThe agent can add notes here too, with the add_table_context tool, when it finds\nsomething about the data the next person would get wrong. It only ever appends, so\nreview those additions in a diff like any other change.\n-->\n\n## Business definitions\n\n_Replace this with the definitions a new analyst would get wrong on their first day._\n\n## Tables\n";