easy-pg-mcp 1.0.0

package/build/csvTools.js

@@ -0,0 +1,97 @@
+import { config } from './config.js';
+import { readCsvFile, writeCsvFile } from './csv.js';
+import * as db from './db.js';
+import { writeBatchExecuteLog } from './logs.js';
+import { assertExecuteAllowed, assertTablesAllowed } from './sqlPolicy.js';
+export async function importCsv(tableName, filePath, transaction) {
+    assertTablesAllowed([tableName]);
+    const csv = await readCsvFile(filePath);
+    const escapedColumns = csv.headers.map((header) => db.escapeIdentifier(header)).join(', ');
+    const placeholders = csv.headers.map((_, index) => `$${index + 1}`).join(', ');
+    const sql = `INSERT INTO ${db.escapeIdentifier(tableName)} (${escapedColumns}) VALUES (${placeholders})`;
+    assertExecuteAllowed(sql);
+    try {
+        const summary = await db.batchExecute(sql, csv.rows, {
+            batchSize: config.batchMaxSize,
+            transaction,
+        });
+        const logPath = await writeBatchExecuteLog({
+            tool: 'pg_import_csv',
+            success: true,
+            tableName,
+            filePath,
+            headers: csv.headers,
+            sql,
+            summary,
+        });
+        return {
+            tableName,
+            filePath,
+            importedRows: summary.totalRows,
+            batches: summary.batches,
+            batchSize: summary.batchSize,
+            transaction: summary.transaction,
+            affectedRows: summary.affectedRows,
+            changedRows: summary.changedRows,
+            logPath,
+        };
+    }
+    catch (error) {
+        if (error instanceof db.BatchExecuteError) {
+            const logPath = await writeBatchExecuteLog({
+                tool: 'pg_import_csv',
+                success: false,
+                tableName,
+                filePath,
+                headers: csv.headers,
+                sql,
+                summary: error.summary,
+                error: error.message,
+            });
+            throw new Error(`CSV import failed: ${error.message}. Detailed log: ${logPath}`);
+        }
+        throw error;
+    }
+}
+export async function exportCsv(tableName, filePath) {
+    assertTablesAllowed([tableName]);
+    const { schema, name } = splitTableName(tableName);
+    const columns = await db.query(`
+    SELECT column_name
+    FROM information_schema.columns
+    WHERE table_schema = COALESCE($1, current_schema())
+      AND table_name = $2
+    ORDER BY ordinal_position
+  `, [schema, name]);
+    const headers = Array.isArray(columns)
+        ? columns
+            .map((column) => column.column_name)
+            .filter((field) => typeof field === 'string')
+        : [];
+    const rows = await db.query(`SELECT * FROM ${db.escapeIdentifier(tableName)}`);
+    const rowObjects = Array.isArray(rows) ? rows : [];
+    const exportHeaders = headers.length > 0 ? headers : collectExportHeaders(rowObjects);
+    await writeCsvFile(filePath, exportHeaders, rowObjects);
+    return {
+        tableName,
+        filePath,
+        exportedRows: rowObjects.length,
+        columns: exportHeaders.length,
+    };
+}
+function collectExportHeaders(rows) {
+    const headers = new Set();
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            headers.add(key);
+        }
+    }
+    return [...headers];
+}
+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/build/db.js

@@ -0,0 +1,206 @@
+import { Pool } from 'pg';
+export class BatchExecuteError extends Error {
+    summary;
+    constructor(message, summary) {
+        super(message);
+        this.summary = summary;
+        this.name = 'BatchExecuteError';
+    }
+}
+const { PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, PG_DATABASE, PG_CONNECTION_LIMIT, PG_IDLE_TIMEOUT, PG_ENABLE_KEEP_ALIVE, PG_KEEP_ALIVE_INITIAL_DELAY, PG_SSL, PG_CONNECTION_STRING, } = process.env;
+if (!PG_CONNECTION_STRING && (!PG_HOST || !PG_USER || !PG_DATABASE)) {
+    console.error('Missing required environment variables for PostgreSQL connection.');
+    process.exit(1);
+}
+export const pool = new Pool({
+    connectionString: PG_CONNECTION_STRING,
+    host: PG_CONNECTION_STRING ? undefined : PG_HOST,
+    port: PG_CONNECTION_STRING ? undefined : (PG_PORT ? parseInt(PG_PORT, 10) : 5432),
+    user: PG_CONNECTION_STRING ? undefined : PG_USER,
+    password: PG_CONNECTION_STRING ? undefined : PG_PASSWORD,
+    database: PG_CONNECTION_STRING ? undefined : PG_DATABASE,
+    max: PG_CONNECTION_LIMIT ? parseInt(PG_CONNECTION_LIMIT, 10) : 10,
+    idleTimeoutMillis: PG_IDLE_TIMEOUT ? parseInt(PG_IDLE_TIMEOUT, 10) : 30000,
+    keepAlive: PG_ENABLE_KEEP_ALIVE !== 'false',
+    keepAliveInitialDelayMillis: PG_KEEP_ALIVE_INITIAL_DELAY ? parseInt(PG_KEEP_ALIVE_INITIAL_DELAY, 10) : 0,
+    ssl: parseSslConfig(PG_SSL),
+});
+export async function query(sql, params) {
+    const result = await pool.query(sql, params);
+    return result.rows;
+}
+export async function execute(sql, params) {
+    const result = await pool.query(sql, params);
+    return toExecutionResult(result);
+}
+export async function batchExecute(sql, paramsList, options) {
+    const batches = chunk(paramsList, options.batchSize);
+    const summary = {
+        totalRows: paramsList.length,
+        batchSize: options.batchSize,
+        batches: batches.length,
+        transaction: options.transaction,
+        affectedRows: 0,
+        changedRows: 0,
+        results: [],
+    };
+    const client = await pool.connect();
+    let currentScope = createBatchScope();
+    let failedRow = null;
+    try {
+        if (options.transaction === 'all') {
+            await client.query('BEGIN');
+        }
+        for (let batchIndex = 0; batchIndex < batches.length; batchIndex += 1) {
+            const batch = batches[batchIndex];
+            if (options.transaction === 'batch') {
+                await client.query('BEGIN');
+                currentScope = createBatchScope();
+            }
+            for (let rowIndex = 0; rowIndex < batch.length; rowIndex += 1) {
+                if (options.transaction === 'each') {
+                    await client.query('BEGIN');
+                    currentScope = createBatchScope();
+                }
+                const globalRow = batchIndex * options.batchSize + rowIndex;
+                const rowResult = await executeBatchRow(client, sql, batch[rowIndex], batchIndex, globalRow);
+                if (options.transaction === 'none') {
+                    pushCommittedResults(summary, {
+                        results: [{ ...rowResult.rowResult, committed: true }],
+                        affectedRows: rowResult.executionResult.affectedRows,
+                        changedRows: rowResult.executionResult.changedRows,
+                    });
+                    continue;
+                }
+                currentScope.results.push(rowResult.rowResult);
+                currentScope.affectedRows += rowResult.executionResult.affectedRows;
+                currentScope.changedRows += rowResult.executionResult.changedRows;
+                if (options.transaction === 'each') {
+                    await client.query('COMMIT');
+                    pushCommittedResults(summary, currentScope);
+                    currentScope = createBatchScope();
+                }
+            }
+            if (options.transaction === 'batch') {
+                await client.query('COMMIT');
+                pushCommittedResults(summary, currentScope);
+                currentScope = createBatchScope();
+            }
+        }
+        if (options.transaction === 'all') {
+            await client.query('COMMIT');
+            pushCommittedResults(summary, currentScope);
+        }
+        return summary;
+    }
+    catch (error) {
+        if (error instanceof BatchRowError) {
+            failedRow = error.rowResult;
+            error = error.cause;
+        }
+        if (options.transaction !== 'none') {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                // Preserve the original batch execution error.
+            }
+        }
+        if (currentScope.results.length > 0) {
+            pushRolledBackResults(summary, currentScope);
+        }
+        if (failedRow) {
+            summary.results.push(failedRow);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new BatchExecuteError(message, summary);
+    }
+    finally {
+        client.release();
+    }
+}
+export function escapeIdentifier(identifier) {
+    return identifier
+        .split('.')
+        .map((part) => `"${part.replace(/"/g, '""')}"`)
+        .join('.');
+}
+function parseSslConfig(value) {
+    if (!value || value.toLowerCase() === 'false') {
+        return undefined;
+    }
+    if (value.toLowerCase() === 'true') {
+        return true;
+    }
+    if (value.toLowerCase() === 'no-verify') {
+        return { rejectUnauthorized: false };
+    }
+    return undefined;
+}
+class BatchRowError extends Error {
+    rowResult;
+    constructor(rowResult, cause) {
+        super(rowResult.error ?? 'Batch row execution failed.');
+        this.rowResult = rowResult;
+        this.name = 'BatchRowError';
+        this.cause = cause;
+    }
+}
+async function executeBatchRow(client, sql, params, batchIndex, globalRow) {
+    try {
+        const result = await client.query(sql, params);
+        const executionResult = toExecutionResult(result);
+        return {
+            rowResult: {
+                batch: batchIndex + 1,
+                row: globalRow + 1,
+                success: true,
+                params,
+                result: executionResult,
+            },
+            executionResult,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new BatchRowError({
+            batch: batchIndex + 1,
+            row: globalRow + 1,
+            success: false,
+            params,
+            committed: false,
+            error: message,
+        }, error);
+    }
+}
+function toExecutionResult(result) {
+    return {
+        command: result.command,
+        affectedRows: result.rowCount ?? 0,
+        changedRows: result.command === 'UPDATE' ? result.rowCount ?? 0 : 0,
+        rowCount: result.rowCount ?? 0,
+        rows: result.rows,
+    };
+}
+function chunk(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}
+function createBatchScope() {
+    return {
+        results: [],
+        affectedRows: 0,
+        changedRows: 0,
+    };
+}
+function pushCommittedResults(summary, scope) {
+    summary.results.push(...scope.results.map((row) => ({ ...row, committed: true })));
+    summary.affectedRows += scope.affectedRows;
+    summary.changedRows += scope.changedRows;
+}
+function pushRolledBackResults(summary, scope) {
+    summary.results.push(...scope.results.map((row) => ({ ...row, committed: false })));
+}

package/build/index.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { isPolicyHookEnabled, isReadOnlyMode } from './config.js';
+import { cleanupOldLogs } from './logs.js';
+import { cancelApproval, listPendingApprovals, runApprovedCommand } from './approvalStore.js';
+import { describeIndex, describeTable, explainQuery, getCurrentPrivileges, listTables, listTriggers, listViews, pgBatchExecute, pgExecute, pgExportCsv, pgImportCsv, pgQuery, } from './toolHandlers.js';
+const { PG_HOST, PG_PORT, PG_DATABASE, } = process.env;
+// Initialize MCP Server/mcp
+const server = new McpServer({
+    name: 'easy-pg-mcp',
+    version: '1.0.0',
+    description: `PostgreSQL Database: ${PG_HOST}:${PG_PORT ?? 5432}/${PG_DATABASE}`,
+});
+// --- Register Tools ---
+const transactionModeSchema = z.enum(['all', 'batch', 'each', 'none']);
+server.registerTool('pg_query', {
+    description: 'Execute a read-only SQL query (e.g., SELECT). Use this for data retrieval.',
+    inputSchema: z.object({
+        sql: z.string().describe('The PostgreSQL query to execute.'),
+    }),
+}, async ({ sql }) => {
+    const results = await pgQuery(sql);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+if (!isReadOnlyMode()) {
+    server.registerTool('pg_execute', {
+        description: 'Execute a data modification SQL statement (e.g., INSERT, UPDATE, DELETE). Use node-postgres placeholders: $1, $2, ... for params.',
+        inputSchema: z.object({
+            sql: z.string().describe('The PostgreSQL statement to execute. Use $1, $2, ... placeholders instead of ?.'),
+            params: z.array(z.any()).optional().describe('Optional parameters for the statement, bound to $1, $2, ... in order.'),
+        }),
+    }, async ({ sql, params }) => {
+        const result = await pgExecute(sql, params);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('pg_batch_execute', {
+        description: 'Execute one data modification SQL statement repeatedly with multiple parameter sets. Use node-postgres placeholders: $1, $2, ... for params.',
+        inputSchema: z.object({
+            sql: z.string().describe('The parameterized PostgreSQL statement to execute for each params entry. Use $1, $2, ... placeholders instead of ?.'),
+            paramsList: z.array(z.array(z.any())).min(1).describe('A list of parameter arrays. Each item is bound to $1, $2, ... for the same SQL statement.'),
+            transaction: transactionModeSchema.optional().default('all').describe('Transaction scope: all, batch, each, or none.'),
+        }),
+    }, async ({ sql, paramsList, transaction }) => {
+        const result = await pgBatchExecute(sql, paramsList, transaction);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('pg_import_csv', {
+        description: 'Import a UTF-8 CSV file into a table using the header row as column names.',
+        inputSchema: z.object({
+            tableName: z.string().min(1).describe('The target table name.'),
+            filePath: z.string().min(1).describe('Path to a UTF-8 CSV file. The first row must contain column names.'),
+            transaction: transactionModeSchema.optional().default('all').describe('Transaction scope: all, batch, each, or none.'),
+        }),
+    }, async ({ tableName, filePath, transaction }) => {
+        const result = await pgImportCsv(tableName, filePath, transaction);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+if (isPolicyHookEnabled()) {
+    server.registerTool('pg_run_approved_command', {
+        description: 'Run a pending command after the host has obtained user approval.',
+        inputSchema: z.object({
+            approvalId: z.string().min(1).describe('The approval id returned by an approval_required response.'),
+        }),
+    }, async ({ approvalId }) => {
+        const result = await runApprovedCommand(approvalId);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('pg_list_pending_approvals', {
+        description: 'List pending commands waiting for approval.',
+        inputSchema: z.object({}),
+    }, async () => {
+        const result = listPendingApprovals();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('pg_cancel_approval', {
+        description: 'Cancel a pending approval request.',
+        inputSchema: z.object({
+            approvalId: z.string().min(1).describe('The approval id to cancel.'),
+        }),
+    }, async ({ approvalId }) => {
+        const result = cancelApproval(approvalId);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ cancelled: true, approval: result }, null, 2) }],
+        };
+    });
+}
+server.registerTool('pg_export_csv', {
+    description: 'Export all rows from a table to a UTF-8 CSV file.',
+    inputSchema: z.object({
+        tableName: z.string().min(1).describe('The source table name.'),
+        filePath: z.string().min(1).describe('Path where the UTF-8 CSV file should be written.'),
+    }),
+}, async ({ tableName, filePath }) => {
+    const result = await pgExportCsv(tableName, filePath);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.registerTool('explain_query', {
+    description: 'Run EXPLAIN on a SQL query to analyze its execution plan and performance.',
+    inputSchema: z.object({
+        sql: z.string().describe('The SQL query to explain.'),
+    }),
+}, async ({ sql }) => {
+    const results = await explainQuery(sql);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('list_tables', {
+    description: 'List all base tables in the current database with row counts and comments.',
+    inputSchema: z.object({}),
+}, async () => {
+    const filteredResults = await listTables();
+    return {
+        content: [{ type: 'text', text: JSON.stringify(filteredResults, null, 2) }],
+    };
+});
+server.registerTool('list_views', {
+    description: 'List all views in the current database.',
+    inputSchema: z.object({}),
+}, async () => {
+    const filteredResults = await listViews();
+    return {
+        content: [{ type: 'text', text: JSON.stringify(filteredResults, null, 2) }],
+    };
+});
+server.registerTool('describe_table', {
+    description: 'Show the schema/structure of one or more specific tables.',
+    inputSchema: z.object({
+        tables: z.array(z.string()).describe('The names of the tables to describe.'),
+    }),
+}, async ({ tables }) => {
+    const results = await describeTable(tables);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('describe_index', {
+    description: 'Show indexes for a specific table.',
+    inputSchema: z.object({
+        table: z.string().describe('The name of the table to show indexes for.'),
+    }),
+}, async ({ table }) => {
+    const results = await describeIndex(table);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+});
+server.registerTool('list_triggers', {
+    description: 'List all triggers in the current database.',
+    inputSchema: z.object({}),
+}, async () => {
+    const filteredResults = await listTriggers();
+    return {
+        content: [{ type: 'text', text: JSON.stringify(filteredResults, null, 2) }],
+    };
+});
+server.registerTool('get_current_privileges', {
+    description: 'Check the permissions and grants of the current database user. Useful for debugging access issues.',
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await getCurrentPrivileges();
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2)
+            }],
+    };
+});
+// Start server
+async function main() {
+    await cleanupOldLogs();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('PostgreSQL MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/build/logs.js

@@ -0,0 +1,28 @@
+import { mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { config } from './config.js';
+const LOG_RETENTION_DAYS = 7;
+const LOG_RETENTION_MS = LOG_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+const logsDirectory = path.resolve(config.logPath);
+export async function cleanupOldLogs(now = Date.now()) {
+    await mkdir(logsDirectory, { recursive: true });
+    const entries = await readdir(logsDirectory);
+    await Promise.all(entries.map(async (entry) => {
+        if (!entry.endsWith('.log')) {
+            return;
+        }
+        const filePath = path.join(logsDirectory, entry);
+        const fileStat = await stat(filePath);
+        if (now - fileStat.mtimeMs > LOG_RETENTION_MS) {
+            await unlink(filePath);
+        }
+    }));
+}
+export async function writeBatchExecuteLog(payload) {
+    await mkdir(logsDirectory, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const randomSuffix = Math.random().toString(36).slice(2, 10);
+    const filePath = path.join(logsDirectory, `pg_batch_execute-${timestamp}-${randomSuffix}.log`);
+    await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    return filePath;
+}

package/build/policyHook.js

@@ -0,0 +1,66 @@
+import { config } from './config.js';
+import { createPendingApproval } from './approvalStore.js';
+export function isApprovalRequiredResponse(value) {
+    return typeof value === 'object'
+        && value !== null
+        && value.status === 'approval_required';
+}
+export async function runWithPolicy(context, command) {
+    if (!config.policyHookUrl) {
+        return command();
+    }
+    const decision = await callPolicyHook(context);
+    if (decision.status === 'accept') {
+        return command();
+    }
+    if (decision.status === 'reject') {
+        throw new Error(decision.message ?? 'Command rejected by PG_POLICY_HOOK.');
+    }
+    const pendingApproval = createPendingApproval({
+        functionName: context.functionName,
+        statementType: context.statementType,
+        tableNames: context.tableNames,
+        message: decision.message,
+        summary: context.summary,
+        command,
+    });
+    return {
+        status: 'approval_required',
+        approvalId: pendingApproval.approvalId,
+        message: pendingApproval.message,
+        expiresAt: pendingApproval.expiresAt,
+        functionName: context.functionName,
+        statementType: context.statementType,
+        tableNames: context.tableNames,
+        summary: pendingApproval.summary,
+    };
+}
+async function callPolicyHook(context) {
+    if (!config.policyHookUrl) {
+        return { status: 'accept' };
+    }
+    const response = await fetch(config.policyHookUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            functionName: context.functionName,
+            sql: context.sql ?? null,
+            statementType: context.statementType,
+            tableNames: context.tableNames,
+            paramsPreview: context.paramsPreview ?? null,
+            metadata: {
+                database: process.env.PG_DATABASE,
+                mode: config.mode,
+                timestamp: new Date().toISOString(),
+            },
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`PG_POLICY_HOOK returned HTTP ${response.status}.`);
+    }
+    const body = await response.json();
+    if (body.status !== 'accept' && body.status !== 'reject' && body.status !== 'approval_required') {
+        throw new Error('PG_POLICY_HOOK returned an invalid status.');
+    }
+    return body;
+}