easy-pg-mcp 1.0.0

package/build/sqlPolicy.js

@@ -0,0 +1,186 @@
+import { createRequire } from 'node:module';
+import { config, isReadOnlyMode, normalizeTableName } from './config.js';
+const require = createRequire(import.meta.url);
+const { Parser } = require('node-sql-parser/build/postgresql.js');
+const parser = new Parser();
+const parserOptions = { database: 'Postgresql' };
+const readQueryTypes = new Set(['select', 'show', 'explain']);
+const executeTypes = new Set(['insert', 'update', 'delete']);
+export class SqlPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SqlPolicyError';
+    }
+}
+export function assertReadQueryAllowed(sql) {
+    const parsed = parseSingleStatement(sql);
+    if (!readQueryTypes.has(parsed.type)) {
+        throw new SqlPolicyError(`SQL rejected: pg_query only allows SELECT, SHOW, and EXPLAIN statements. Received ${parsed.type.toUpperCase()}.`);
+    }
+    assertNoUnsafeReadOptions(parsed.ast);
+    assertTablePolicy(parsed.tables);
+}
+export function analyzeSql(sql) {
+    const parsed = parseSingleStatement(sql);
+    return {
+        statementType: parsed.type,
+        tableNames: parsed.tables,
+    };
+}
+export function assertExplainQueryAllowed(sql) {
+    const parsed = parseSingleStatement(sql);
+    if (parsed.type !== 'select') {
+        throw new SqlPolicyError(`SQL rejected: explain_query only accepts a SELECT statement. Received ${parsed.type.toUpperCase()}.`);
+    }
+    assertNoUnsafeReadOptions(parsed.ast);
+    assertTablePolicy(parsed.tables);
+}
+export function assertExecuteAllowed(sql) {
+    if (isReadOnlyMode()) {
+        throw new SqlPolicyError('SQL rejected: write execution is disabled because PG_READ_ONLY=true or PG_MCP_MODE=readonly.');
+    }
+    const parsed = parseSingleStatement(sql);
+    if (!executeTypes.has(parsed.type)) {
+        throw new SqlPolicyError(`SQL rejected: pg_execute only allows INSERT, UPDATE, and DELETE statements. Received ${parsed.type.toUpperCase()}.`);
+    }
+    assertTablePolicy(parsed.tables);
+}
+export function assertTablesAllowed(tables) {
+    assertTablePolicy(tables.map((table) => normalizeTableName(table)));
+}
+export function isTableAllowed(table) {
+    try {
+        assertTablesAllowed([table]);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof SqlPolicyError) {
+            return false;
+        }
+        throw error;
+    }
+}
+function parseSingleStatement(sql) {
+    let parsed;
+    try {
+        parsed = parser.parse(sql, parserOptions);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new SqlPolicyError(`SQL rejected: unable to parse statement as PostgreSQL SQL. ${message}`);
+    }
+    const ast = parsed.ast;
+    if (Array.isArray(ast)) {
+        if (ast.length !== 1) {
+            throw new SqlPolicyError('SQL rejected: multiple statements are not allowed.');
+        }
+        return {
+            ast: ast[0],
+            type: getStatementType(ast[0]),
+            tables: getVisitedTables(parsed, ast[0]),
+        };
+    }
+    return {
+        ast,
+        type: getStatementType(ast),
+        tables: getVisitedTables(parsed, ast),
+    };
+}
+function getStatementType(ast) {
+    const type = typeof ast?.type === 'string' ? ast.type.toLowerCase() : 'unknown';
+    return type === 'desc' ? 'describe' : type;
+}
+function assertNoUnsafeReadOptions(ast) {
+    if (Array.isArray(ast)) {
+        for (const statement of ast) {
+            assertNoUnsafeReadOptions(statement);
+        }
+        return;
+    }
+    if (ast?.type === 'select' && ast.into?.keyword) {
+        throw new SqlPolicyError('SQL rejected: SELECT ... INTO is not allowed.');
+    }
+    if (ast?.locking_read) {
+        throw new SqlPolicyError('SQL rejected: locking reads are not allowed in pg_query.');
+    }
+    if (Array.isArray(ast?.with)) {
+        for (const cte of ast.with) {
+            assertNoUnsafeReadOptions(cte?.stmt?.ast);
+        }
+    }
+    if (ast?.type === 'explain') {
+        assertNoUnsafeReadOptions(ast.expr);
+    }
+}
+function assertTablePolicy(tables) {
+    for (const table of tables) {
+        if (matchesTableList(table, config.denyTables)) {
+            throw new SqlPolicyError(`SQL rejected: table "${table}" is denied by PG_MCP_DENY_TABLES.`);
+        }
+        if (config.allowTables.length > 0 && !matchesTableList(table, config.allowTables)) {
+            throw new SqlPolicyError(`SQL rejected: table "${table}" is not included in PG_MCP_ALLOW_TABLES.`);
+        }
+    }
+}
+function matchesTableList(table, configuredTables) {
+    if (configuredTables.includes(table)) {
+        return true;
+    }
+    const tableOnly = table.split('.').at(-1);
+    return tableOnly ? configuredTables.includes(tableOnly) : false;
+}
+function getVisitedTables(parsed, ast) {
+    const cteNames = collectCteNames(ast);
+    const tables = new Set();
+    for (const tableRef of parsed.tableList) {
+        const table = normalizeTableRef(tableRef);
+        if (table && !cteNames.has(table)) {
+            tables.add(table);
+        }
+    }
+    for (const table of collectTablesFromAst(ast)) {
+        const normalized = normalizeTableName(table);
+        if (normalized && !cteNames.has(normalized)) {
+            tables.add(normalized);
+        }
+    }
+    return [...tables];
+}
+function normalizeTableRef(tableRef) {
+    const [, dbName, tableName] = tableRef.split('::');
+    if (!tableName || tableName === 'null') {
+        return null;
+    }
+    const normalizedTable = normalizeTableName(tableName);
+    if (dbName && dbName !== 'null') {
+        return `${normalizeTableName(dbName)}.${normalizedTable}`;
+    }
+    return normalizedTable;
+}
+function collectCteNames(ast) {
+    const names = new Set();
+    if (!Array.isArray(ast?.with)) {
+        return names;
+    }
+    for (const cte of ast.with) {
+        const value = cte?.name?.value;
+        if (typeof value === 'string') {
+            names.add(normalizeTableName(value));
+        }
+    }
+    return names;
+}
+function collectTablesFromAst(ast) {
+    if (!ast) {
+        return [];
+    }
+    switch (ast.type) {
+        case 'desc':
+        case 'describe':
+            return typeof ast.table === 'string' ? [ast.table] : [];
+        case 'explain':
+            return collectTablesFromAst(ast.expr);
+        default:
+            return [];
+    }
+}

package/build/toolHandlers.js

@@ -0,0 +1,249 @@
+import { config } from './config.js';
+import { exportCsv, importCsv } from './csvTools.js';
+import * as db from './db.js';
+import { writeBatchExecuteLog } from './logs.js';
+import { runWithPolicy } from './policyHook.js';
+import { analyzeSql, assertExecuteAllowed, assertExplainQueryAllowed, assertReadQueryAllowed, assertTablesAllowed, isTableAllowed, } from './sqlPolicy.js';
+export async function pgQuery(sql) {
+    assertReadQueryAllowed(sql);
+    const analysis = analyzeSql(sql);
+    return runWithPolicy({
+        functionName: 'pg_query',
+        sql,
+        statementType: analysis.statementType,
+        tableNames: analysis.tableNames,
+    }, () => db.query(sql));
+}
+export async function pgExecute(sql, params) {
+    assertExecuteAllowed(sql);
+    const analysis = analyzeSql(sql);
+    return runWithPolicy({
+        functionName: 'pg_execute',
+        sql,
+        statementType: analysis.statementType,
+        tableNames: analysis.tableNames,
+        paramsPreview: params ?? null,
+        summary: { sql, paramsPreview: params ?? null },
+    }, () => db.execute(sql, params));
+}
+export async function pgBatchExecute(sql, paramsList, transaction) {
+    assertExecuteAllowed(sql);
+    const analysis = analyzeSql(sql);
+    return runWithPolicy({
+        functionName: 'pg_batch_execute',
+        sql,
+        statementType: analysis.statementType,
+        tableNames: analysis.tableNames,
+        paramsPreview: { rows: paramsList.length, firstParams: paramsList[0] ?? null },
+        summary: { sql, rows: paramsList.length, transaction },
+    }, async () => {
+        const summary = await db.batchExecute(sql, paramsList, {
+            batchSize: config.batchMaxSize,
+            transaction,
+        });
+        const logPath = await writeBatchExecuteLog({
+            tool: 'pg_batch_execute',
+            success: true,
+            sql,
+            summary,
+        });
+        return {
+            totalRows: summary.totalRows,
+            batches: summary.batches,
+            batchSize: summary.batchSize,
+            transaction: summary.transaction,
+            affectedRows: summary.affectedRows,
+            changedRows: summary.changedRows,
+            logPath,
+        };
+    }).catch(async (error) => {
+        if (!(error instanceof db.BatchExecuteError)) {
+            throw error;
+        }
+        const logPath = await writeBatchExecuteLog({
+            tool: 'pg_batch_execute',
+            success: false,
+            sql,
+            summary: error.summary,
+            error: error.message,
+        });
+        throw new Error(`Batch execution failed: ${error.message}. Detailed log: ${logPath}`);
+    });
+}
+export async function pgImportCsv(tableName, filePath, transaction) {
+    assertTablesAllowed([tableName]);
+    return runWithPolicy({
+        functionName: 'pg_import_csv',
+        sql: null,
+        statementType: 'insert',
+        tableNames: [tableName],
+        paramsPreview: { filePath, transaction },
+        summary: { tableName, filePath, transaction },
+    }, () => importCsv(tableName, filePath, transaction));
+}
+export async function pgExportCsv(tableName, filePath) {
+    assertTablesAllowed([tableName]);
+    return runWithPolicy({
+        functionName: 'pg_export_csv',
+        sql: null,
+        statementType: 'export',
+        tableNames: [tableName],
+        paramsPreview: { filePath },
+        summary: { tableName, filePath },
+    }, () => exportCsv(tableName, filePath));
+}
+export async function explainQuery(sql) {
+    assertExplainQueryAllowed(sql);
+    const analysis = analyzeSql(sql);
+    return runWithPolicy({
+        functionName: 'explain_query',
+        sql,
+        statementType: 'explain',
+        tableNames: analysis.tableNames,
+    }, () => db.query(`EXPLAIN ${sql}`));
+}
+export async function listTables() {
+    return runWithPolicy({
+        functionName: 'list_tables',
+        sql: null,
+        statementType: 'schema',
+        tableNames: [],
+    }, async () => {
+        const results = await db.query(`
+      SELECT
+        table_name,
+        COALESCE(pg_class.reltuples::bigint, 0) AS table_rows,
+        obj_description(pg_class.oid, 'pg_class') AS table_comment
+      FROM information_schema.tables
+      LEFT JOIN pg_namespace
+        ON pg_namespace.nspname = information_schema.tables.table_schema
+      LEFT JOIN pg_class
+        ON pg_class.relname = information_schema.tables.table_name
+        AND pg_class.relnamespace = pg_namespace.oid
+      WHERE table_schema = current_schema()
+        AND table_type = 'BASE TABLE'
+      ORDER BY table_name
+    `);
+        return Array.isArray(results)
+            ? results.filter((row) => typeof row.table_name === 'string' && isTableAllowed(row.table_name))
+            : results;
+    });
+}
+export async function listViews() {
+    return runWithPolicy({
+        functionName: 'list_views',
+        sql: null,
+        statementType: 'schema',
+        tableNames: [],
+    }, async () => {
+        const results = await db.query(`
+      SELECT table_name, view_definition
+      FROM information_schema.views
+      WHERE table_schema = current_schema()
+      ORDER BY table_name
+    `);
+        return Array.isArray(results)
+            ? results.filter((row) => typeof row.table_name === 'string' && isTableAllowed(row.table_name))
+            : results;
+    });
+}
+export async function describeTable(tables) {
+    assertTablesAllowed(tables);
+    return runWithPolicy({
+        functionName: 'describe_table',
+        sql: null,
+        statementType: 'schema',
+        tableNames: tables,
+        summary: { tables },
+    }, async () => {
+        const results = {};
+        for (const table of tables) {
+            const { schema, name } = splitTableName(table);
+            results[table] = await db.query(`
+        SELECT
+          column_name,
+          data_type,
+          is_nullable,
+          column_default,
+          character_maximum_length,
+          numeric_precision,
+          numeric_scale
+        FROM information_schema.columns
+        WHERE table_schema = COALESCE($1, current_schema())
+          AND table_name = $2
+        ORDER BY ordinal_position
+      `, [schema, name]);
+        }
+        return results;
+    });
+}
+export async function describeIndex(table) {
+    assertTablesAllowed([table]);
+    return runWithPolicy({
+        functionName: 'describe_index',
+        sql: null,
+        statementType: 'schema',
+        tableNames: [table],
+        summary: { table },
+    }, () => {
+        const { schema, name } = splitTableName(table);
+        return db.query(`
+      SELECT
+        schemaname AS schema_name,
+        tablename AS table_name,
+        indexname AS index_name,
+        indexdef AS index_definition
+      FROM pg_indexes
+      WHERE schemaname = COALESCE($1, current_schema())
+        AND tablename = $2
+      ORDER BY indexname
+    `, [schema, name]);
+    });
+}
+export async function listTriggers() {
+    return runWithPolicy({
+        functionName: 'list_triggers',
+        sql: null,
+        statementType: 'schema',
+        tableNames: [],
+    }, async () => {
+        const results = await db.query(`
+      SELECT
+        trigger_name,
+        event_object_table AS table_name,
+        event_manipulation,
+        action_timing,
+        action_statement
+      FROM information_schema.triggers
+      WHERE trigger_schema = current_schema()
+      ORDER BY trigger_name, event_manipulation
+    `);
+        return Array.isArray(results)
+            ? results.filter((row) => typeof row.table_name === 'string' && isTableAllowed(row.table_name))
+            : results;
+    });
+}
+export async function getCurrentPrivileges() {
+    return runWithPolicy({
+        functionName: 'get_current_privileges',
+        sql: null,
+        statementType: 'privileges',
+        tableNames: [],
+    }, async () => {
+        const user = await db.query('SELECT current_user AS user');
+        const grants = await db.query(`
+      SELECT grantee, table_schema, table_name, privilege_type, is_grantable
+      FROM information_schema.role_table_grants
+      WHERE grantee = current_user
+      ORDER BY table_schema, table_name, privilege_type
+    `);
+        return { currentUser: user, grants };
+    });
+}
+function splitTableName(table) {
+    const parts = table.replace(/"/g, '').split('.');
+    if (parts.length > 1) {
+        return { schema: parts[0], name: parts.at(-1) ?? table };
+    }
+    return { schema: null, name: table.replace(/"/g, '') };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "easy-pg-mcp",
+  "version": "1.0.0",
+  "description": "High performance PostgreSQL MCP Server using node-postgres",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "easy-pg-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgresql",
+    "postgres",
+    "pg",
+    "node-postgres",
+    "claude"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "start": "node build/index.js",
+    "dev": "tsc --watch",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "node-sql-parser": "^5.4.0",
+    "pg": "^8.21.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/pg": "^8.15.6",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenkumi/easy-pg-mcp.git"
+  }
+}