@contextflo/postgres-mcp 0.1.0

package/dist/tools/query.js

@@ -0,0 +1,138 @@
+import { describeQueryError } from '../db/errors.js';
+import { SafetyError } from '../safety/errors.js';
+import { validateReadOnlySql } from '../safety/validate.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 const QUERY_TOOL = {
+    name: 'query',
+    description: 'Run a read-only SQL query against the Postgres database. Accepts a single SELECT ' +
+        '(including WITH ... SELECT), EXPLAIN, or SHOW statement. Writes, DDL, multiple ' +
+        'statements, and SET are rejected. information_schema and pg_catalog are readable, so ' +
+        'schema questions this server has no tool for can be answered with plain SQL.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sql: {
+                type: 'string',
+                description: 'A single read-only SQL statement.',
+            },
+        },
+        required: ['sql'],
+    },
+};
+export async function runQueryTool(context, args) {
+    const sql = args?.sql;
+    if (typeof sql !== 'string' || sql.trim() === '') {
+        return toolError('The "sql" argument is required and must be a non-empty string.');
+    }
+    try {
+        validateReadOnlySql(sql);
+    }
+    catch (error) {
+        if (error instanceof SafetyError) {
+            context.log.record({ sql, outcome: 'rejected', message: error.message });
+            return toolError(error.message);
+        }
+        throw error;
+    }
+    const startedAt = Date.now();
+    let result;
+    try {
+        result = await context.database.runReadOnly(sql, context.maxRows);
+    }
+    catch (error) {
+        const message = describeQueryError(error);
+        context.log.record({ sql, outcome: 'error', durationMs: Date.now() - startedAt, message });
+        return toolError(message);
+    }
+    context.log.record({
+        sql,
+        outcome: 'ok',
+        rowCount: result.rows.length,
+        durationMs: Date.now() - startedAt,
+    });
+    const rendered = renderRows(result.rows, context.maxOutputChars);
+    const content = [{ type: 'text', text: rendered.text }];
+    const notes = [];
+    if (rendered.shown < result.rows.length) {
+        notes.push(`Output truncated to ${rendered.shown} of ${result.rows.length} rows to stay under ` +
+            `${context.maxOutputChars.toLocaleString('en-US')} characters. Select fewer columns, add LIMIT, ` +
+            'or aggregate. --max-output-chars raises the budget.');
+    }
+    if (result.truncated) {
+        notes.push(`Results truncated to ${context.maxRows} rows. Add LIMIT/aggregation to narrow the query, ` +
+            'or start the server with --max-rows to raise the cap.');
+    }
+    if (rendered.cellsShortened) {
+        notes.push(`Values longer than ${MAX_CELL_CHARS.toLocaleString('en-US')} characters were shortened.`);
+    }
+    if (notes.length > 0)
+        content.push({ type: 'text', text: notes.join('\n') });
+    return { content, isError: false };
+}
+/**
+ * A JSON array with one row per line: still valid JSON for anything that parses it, but
+ * without the indentation that roughly doubled the token cost of every result.
+ *
+ * Rows are added until the character budget is spent — a `SELECT *` over a table with a
+ * wide jsonb column should not blow the model's context window on its first try.
+ */
+function renderRows(rows, maxChars) {
+    const state = { cellsShortened: false };
+    const lines = [];
+    let used = 2;
+    for (const row of rows) {
+        const line = JSON.stringify(toJsonSafe(row, state));
+        // Always show at least one row, even if it alone is over budget.
+        if (lines.length > 0 && used + line.length + 2 > maxChars)
+            break;
+        lines.push(line);
+        used += line.length + 2;
+    }
+    const text = lines.length === 0 ? '[]' : `[\n${lines.join(',\n')}\n]`;
+    return { text, shown: lines.length, cellsShortened: state.cellsShortened };
+}
+function toolError(message) {
+    // Returned as a tool error rather than thrown so the model sees it and can correct the
+    // query itself, instead of the client surfacing a protocol-level failure.
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** Bytes rendered as `{"type":"Buffer","data":[…]}` are unreadable and expensive in tokens. */
+const MAX_RENDERED_BYTES = 32;
+/** One long text or jsonb value should not crowd every other row out of the budget. */
+const MAX_CELL_CHARS = 2_000;
+function toJsonSafe(value, state, isRow = true) {
+    if (Buffer.isBuffer(value)) {
+        return renderBytes(value);
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (typeof value === 'string') {
+        return shorten(value, value, state);
+    }
+    if (isRow && value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJsonSafe(item, state, false)]));
+    }
+    if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
+        // An array or jsonb value is one cell: keep it structured when it fits, shorten its
+        // serialised form when it does not.
+        const serialised = JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? item.toString() : item);
+        return shorten(serialised, value, state);
+    }
+    return value;
+}
+function shorten(serialised, original, state) {
+    if (serialised.length <= MAX_CELL_CHARS)
+        return original;
+    state.cellsShortened = true;
+    return `${serialised.slice(0, MAX_CELL_CHARS)}… (${serialised.length.toLocaleString('en-US')} chars)`;
+}
+function renderBytes(value) {
+    const hex = value.subarray(0, MAX_RENDERED_BYTES).toString('hex');
+    return value.length > MAX_RENDERED_BYTES ? `\\x${hex}… (${value.length} bytes)` : `\\x${hex}`;
+}
+//# sourceMappingURL=query.js.map

package/dist/tools/query.js.map

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

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@contextflo/postgres-mcp",
+  "version": "0.1.0",
+  "description": "Read-only Postgres MCP server: a drop-in replacement for the archived @modelcontextprotocol/server-postgres, with schema context for correct answers.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgres",
+    "postgresql",
+    "mcp-server",
+    "read-only",
+    "claude",
+    "cursor",
+    "text-to-sql"
+  ],
+  "homepage": "https://github.com/contextflo/postgres-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contextflo/postgres-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/contextflo/postgres-mcp/issues"
+  },
+  "author": "ContextFlo (https://contextflo.com)",
+  "license": "MIT",
+  "mcpName": "io.github.contextflo/postgres-mcp",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "postgres-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "db:up": "docker compose -f docker-compose.test.yml up -d --wait",
+    "db:down": "docker compose -f docker-compose.test.yml down -v",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "libpg-query": "^17.7.4",
+    "pg": "^8.16.3",
+    "pg-connection-string": "^2.9.1",
+    "pg-cursor": "^2.15.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@types/pg": "^8.15.5",
+    "@types/pg-cursor": "^2.7.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}