easy-pg-mcp 1.0.0 → 1.0.1

package/README.md

@@ -8,7 +8,7 @@ This project uses Node.js, TypeScript, the official MCP SDK, and [`pg`](https://
 
 - PostgreSQL connection pooling powered by node-postgres
 - Read-only query tool for data retrieval
-- Execute tool for data modification statements
+- Execute tools for data modification and optional advanced schema changes
 - Batch execution and CSV import/export helpers
 - Schema discovery tools for tables, views, indexes, and triggers
 - Query plan inspection with `EXPLAIN`
@@ -53,7 +53,7 @@ npm run build
 | `PG_KEEP_ALIVE_INITIAL_DELAY` | No | `0` | Initial TCP keep-alive delay in milliseconds |
 | `PG_SSL` | No | - | Set `true` to enable SSL, or `no-verify` to disable certificate verification |
 | `PG_READ_ONLY` | No | `false` | When `true`, write tools are not registered |
-| `PG_MCP_MODE` | No | `readwrite` | Use `readonly` to disable write execution |
+| `PG_MCP_MODE` | No | `readwrite` | Use `readonly` to disable write execution, or `advanced` to enable schema execution |
 | `PG_MCP_ALLOW_TABLES` | No | - | Comma-separated table allowlist, such as `users,orders` |
 | `PG_MCP_DENY_TABLES` | No | - | Comma-separated table denylist, such as `payments,secrets` |
 | `PG_BATCH_MAX_SIZE` | No | `100` | Maximum number of parameter sets per internal batch for `pg_batch_execute` |
@@ -117,6 +117,7 @@ PG_DATABASE = "YOUR DB NAME"
 | --- | --- |
 | `pg_query` | Execute a read-only SQL query, such as `SELECT` |
 | `pg_execute` | Execute a data modification statement, such as `INSERT`, `UPDATE`, or `DELETE` |
+| `pg_schema_execute` | Execute advanced schema statements, such as table, view, index, trigger, or function DDL. Only registered when `PG_MCP_MODE=advanced` |
 | `pg_batch_execute` | Execute one data modification statement repeatedly with multiple parameter sets |
 | `pg_import_csv` | Import a UTF-8 CSV file into a table using the header row as column names |
 | `pg_export_csv` | Export all rows from a table to a UTF-8 CSV file |
@@ -131,7 +132,9 @@ PG_DATABASE = "YOUR DB NAME"
 | `pg_list_pending_approvals` | List pending approval requests, only registered when `PG_POLICY_HOOK` is set |
 | `pg_cancel_approval` | Cancel a pending approval request, only registered when `PG_POLICY_HOOK` is set |
 
-When `PG_READ_ONLY=true` or `PG_MCP_MODE=readonly`, `pg_execute`, `pg_batch_execute`, and `pg_import_csv` are not registered.
+When `PG_READ_ONLY=true` or `PG_MCP_MODE=readonly`, `pg_execute`, `pg_schema_execute`, `pg_batch_execute`, and `pg_import_csv` are not registered.
+
+When `PG_MCP_MODE=advanced`, `pg_schema_execute` is registered and can run approved single-statement DDL for tables, views, indexes, triggers, and functions.
 
 ## Parameter Syntax
 
@@ -177,6 +180,7 @@ Detailed per-row execution results are written to a timestamped `.log` file unde
 - `pg_query` allows only single-statement `SELECT`, `SHOW`, and `EXPLAIN` queries.
 - `explain_query` accepts only a single `SELECT` statement and runs `EXPLAIN` for it.
 - `pg_execute` allows only single-statement `INSERT`, `UPDATE`, and `DELETE` statements when write mode is enabled.
+- `pg_schema_execute` is only available when `PG_MCP_MODE=advanced`. It allows single-statement DDL for `CREATE` / `ALTER` / `DROP` table, view, index, trigger, and function operations, plus `TRUNCATE`.
 - `pg_batch_execute` and `pg_import_csv` use the same write policy as `pg_execute`.
 - `pg_export_csv` checks table policy before exporting table data.
 - Multi-statement SQL is rejected.
@@ -186,6 +190,8 @@ Detailed per-row execution results are written to a timestamped `.log` file unde
 
 Table policy matching is best-effort and based on SQL parsing. PostgreSQL grants remain the final security boundary.
 
+Some PostgreSQL DDL cannot always be mapped back to a table by static parsing, such as `DROP INDEX` or `DROP FUNCTION`. Use PostgreSQL grants and `PG_POLICY_HOOK` for stricter control in advanced mode.
+
 ## Policy Hook and Approvals
 
 When `PG_POLICY_HOOK` is configured, the server posts each tool action to the hook after built-in policy checks pass and before the command runs. The hook must return one of:

package/README.zh-TW.md

@@ -8,7 +8,7 @@
 
 - 使用 node-postgres 的 PostgreSQL connection pool
 - 唯讀查詢工具
-- INSERT / UPDATE / DELETE 執行工具
+- INSERT / UPDATE / DELETE 執行工具，以及可選的進階 schema 修改工具
 - 批次執行與 CSV 匯入 / 匯出
 - 資料表、view、index、trigger 結構查詢
 - `EXPLAIN` 查詢計畫分析
@@ -53,7 +53,7 @@ npm run build
 | `PG_KEEP_ALIVE_INITIAL_DELAY` | 否 | `0` | keep-alive 初始延遲，單位毫秒 |
 | `PG_SSL` | 否 | - | 設為 `true` 啟用 SSL，或 `no-verify` 關閉憑證驗證 |
 | `PG_READ_ONLY` | 否 | `false` | 設為 `true` 時不註冊寫入工具 |
-| `PG_MCP_MODE` | 否 | `readwrite` | 設為 `readonly` 可停用寫入工具 |
+| `PG_MCP_MODE` | 否 | `readwrite` | 設為 `readonly` 可停用寫入工具；設為 `advanced` 可啟用 schema 執行工具 |
 | `PG_MCP_ALLOW_TABLES` | 否 | - | table allowlist，例如 `users,orders` |
 | `PG_MCP_DENY_TABLES` | 否 | - | table denylist，例如 `payments,secrets` |
 | `PG_BATCH_MAX_SIZE` | 否 | `100` | `pg_batch_execute` 每批最大參數組數 |
@@ -117,6 +117,7 @@ PG_DATABASE = "YOUR DB NAME"
 | --- | --- |
 | `pg_query` | 執行唯讀 SQL，例如 `SELECT` |
 | `pg_execute` | 執行資料修改 SQL，例如 `INSERT`、`UPDATE`、`DELETE` |
+| `pg_schema_execute` | 執行進階 schema SQL，例如 table、view、index、trigger、function DDL。僅在 `PG_MCP_MODE=advanced` 時註冊 |
 | `pg_batch_execute` | 使用多組參數重複執行同一個資料修改 SQL |
 | `pg_import_csv` | 依 CSV header 將 UTF-8 CSV 匯入資料表 |
 | `pg_export_csv` | 將資料表匯出成 UTF-8 CSV |
@@ -131,7 +132,9 @@ PG_DATABASE = "YOUR DB NAME"
 | `pg_list_pending_approvals` | 列出 pending approvals，僅在 `PG_POLICY_HOOK` 設定時註冊 |
 | `pg_cancel_approval` | 取消 pending approval，僅在 `PG_POLICY_HOOK` 設定時註冊 |
 
-當 `PG_READ_ONLY=true` 或 `PG_MCP_MODE=readonly` 時，`pg_execute`、`pg_batch_execute`、`pg_import_csv` 不會被註冊。
+當 `PG_READ_ONLY=true` 或 `PG_MCP_MODE=readonly` 時，`pg_execute`、`pg_schema_execute`、`pg_batch_execute`、`pg_import_csv` 不會被註冊。
+
+當 `PG_MCP_MODE=advanced` 時，會註冊 `pg_schema_execute`，可執行通過 policy 的單一 statement DDL，用於修改 tables、views、indexes、triggers、functions。
 
 ## 參數語法
 
@@ -177,6 +180,7 @@ node-postgres 使用 `$1`、`$2`、`$3` 這種 positional placeholders。不要
 - `pg_query` 只允許單一 statement 的 `SELECT`、`SHOW`、`EXPLAIN`。
 - `explain_query` 只接受單一 `SELECT`，並在前方加上 `EXPLAIN` 執行。
 - `pg_execute` 在 write mode 下只允許單一 statement 的 `INSERT`、`UPDATE`、`DELETE`。
+- `pg_schema_execute` 僅在 `PG_MCP_MODE=advanced` 時可用，允許單一 statement 的 table、view、index、trigger、function `CREATE` / `ALTER` / `DROP` DDL，以及 `TRUNCATE`。
 - `pg_batch_execute` 與 `pg_import_csv` 使用和 `pg_execute` 相同的寫入規則。
 - `pg_export_csv` 會先檢查 table policy。
 - 禁止 multi-statement SQL。
@@ -186,6 +190,8 @@ node-postgres 使用 `$1`、`$2`、`$3` 這種 positional placeholders。不要
 
 Table policy 是根據 SQL parser 的 best-effort 檢查；PostgreSQL grants 仍然是最後的安全邊界。
 
+部分 PostgreSQL DDL 無法永遠透過靜態解析對應回 table，例如 `DROP INDEX` 或 `DROP FUNCTION`。在 advanced mode 下若需要更嚴格控管，建議搭配 PostgreSQL grants 與 `PG_POLICY_HOOK`。
+
 ## Policy Hook 與 Approval
 
 設定 `PG_POLICY_HOOK` 後，server 會在內建 policy 檢查通過、但命令實際執行前，將每次工具操作 POST 到外部 hook。Hook 必須回傳以下其中一種結果：

package/build/config.js

@@ -27,6 +27,9 @@ function resolveMode() {
     if (readOnly || explicitMode === 'readonly' || explicitMode === 'read-only') {
         return 'readonly';
     }
+    if (explicitMode === 'advanced') {
+        return 'advanced';
+    }
     return 'readwrite';
 }
 export const config = {
@@ -41,6 +44,9 @@ export const config = {
 export function isReadOnlyMode() {
     return config.mode === 'readonly';
 }
+export function isAdvancedMode() {
+    return config.mode === 'advanced';
+}
 export function isPolicyHookEnabled() {
     return Boolean(config.policyHookUrl);
 }

package/build/index.js

@@ -2,15 +2,15 @@
 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 { isAdvancedMode, 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';
+import { describeIndex, describeTable, explainQuery, getCurrentPrivileges, listTables, listTriggers, listViews, pgBatchExecute, pgExecute, pgExportCsv, pgImportCsv, pgSchemaExecute, 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',
+    version: '1.0.1',
     description: `PostgreSQL Database: ${PG_HOST}:${PG_PORT ?? 5432}/${PG_DATABASE}`,
 });
 // --- Register Tools ---
@@ -66,6 +66,19 @@ if (!isReadOnlyMode()) {
         };
     });
 }
+if (isAdvancedMode()) {
+    server.registerTool('pg_schema_execute', {
+        description: 'Execute an advanced PostgreSQL schema statement such as CREATE/ALTER/DROP table, view, index, trigger, or function. Requires PG_MCP_MODE=advanced.',
+        inputSchema: z.object({
+            sql: z.string().describe('The single PostgreSQL schema statement to execute. Parameters are not supported for schema execution.'),
+        }),
+    }, async ({ sql }) => {
+        const result = await pgSchemaExecute(sql);
+        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.',

package/build/sqlPolicy.js

@@ -1,11 +1,29 @@
 import { createRequire } from 'node:module';
-import { config, isReadOnlyMode, normalizeTableName } from './config.js';
+import { config, isAdvancedMode, 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']);
+const advancedTypes = new Set([
+    'alter_function',
+    'alter_index',
+    'alter_table',
+    'alter_trigger',
+    'alter_view',
+    'create_function',
+    'create_index',
+    'create_table',
+    'create_trigger',
+    'create_view',
+    'drop_function',
+    'drop_index',
+    'drop_table',
+    'drop_trigger',
+    'drop_view',
+    'truncate',
+]);
 export class SqlPolicyError extends Error {
     constructor(message) {
         super(message);
@@ -23,7 +41,7 @@ export function assertReadQueryAllowed(sql) {
 export function analyzeSql(sql) {
     const parsed = parseSingleStatement(sql);
     return {
-        statementType: parsed.type,
+        statementType: parsed.statementType,
         tableNames: parsed.tables,
     };
 }
@@ -45,6 +63,23 @@ export function assertExecuteAllowed(sql) {
     }
     assertTablePolicy(parsed.tables);
 }
+export function assertSchemaExecuteAllowed(sql) {
+    if (isReadOnlyMode()) {
+        throw new SqlPolicyError('SQL rejected: schema execution is disabled because PG_READ_ONLY=true or PG_MCP_MODE=readonly.');
+    }
+    if (!isAdvancedMode()) {
+        throw new SqlPolicyError('SQL rejected: pg_schema_execute requires PG_MCP_MODE=advanced.');
+    }
+    const parsed = parseSingleStatement(sql, { allowAdvancedFallback: true });
+    if (!advancedTypes.has(parsed.statementType)) {
+        throw new SqlPolicyError(`SQL rejected: pg_schema_execute only allows advanced schema statements. Received ${parsed.statementType.toUpperCase()}.`);
+    }
+    assertTablePolicy(parsed.tables);
+    return {
+        statementType: parsed.statementType,
+        tableNames: parsed.tables,
+    };
+}
 export function assertTablesAllowed(tables) {
     assertTablePolicy(tables.map((table) => normalizeTableName(table)));
 }
@@ -60,12 +95,18 @@ export function isTableAllowed(table) {
         throw error;
     }
 }
-function parseSingleStatement(sql) {
+function parseSingleStatement(sql, options) {
     let parsed;
     try {
         parsed = parser.parse(sql, parserOptions);
     }
     catch (error) {
+        if (options?.allowAdvancedFallback) {
+            const fallback = parseAdvancedFallback(sql);
+            if (fallback) {
+                return fallback;
+            }
+        }
         const message = error instanceof Error ? error.message : String(error);
         throw new SqlPolicyError(`SQL rejected: unable to parse statement as PostgreSQL SQL. ${message}`);
     }
@@ -77,19 +118,62 @@ function parseSingleStatement(sql) {
         return {
             ast: ast[0],
             type: getStatementType(ast[0]),
+            statementType: getDetailedStatementType(ast[0]),
             tables: getVisitedTables(parsed, ast[0]),
         };
     }
     return {
         ast,
         type: getStatementType(ast),
+        statementType: getDetailedStatementType(ast),
         tables: getVisitedTables(parsed, ast),
     };
 }
+function parseAdvancedFallback(sql) {
+    const trimmed = sql.trim();
+    const statement = trimmed.endsWith(';') ? trimmed.slice(0, -1).trim() : trimmed;
+    if (statement.includes(';')) {
+        throw new SqlPolicyError('SQL rejected: multiple statements are not allowed.');
+    }
+    const dropTriggerMatch = /^drop\s+trigger\s+(?:if\s+exists\s+)?(?<trigger>"[^"]+"|[a-zA-Z_][\w$]*)\s+on\s+(?:only\s+)?(?<table>"[^"]+"|[a-zA-Z_][\w$]*(?:\."[^"]+"|\.[a-zA-Z_][\w$]*)?)(?:\s+(?:cascade|restrict))?$/iu.exec(statement);
+    if (dropTriggerMatch?.groups?.table) {
+        return {
+            ast: null,
+            type: 'drop',
+            statementType: 'drop_trigger',
+            tables: [normalizeTableName(dropTriggerMatch.groups.table)],
+        };
+    }
+    const dropFunctionMatch = /^drop\s+function\s+(?:if\s+exists\s+)?(?<function>"[^"]+"|[a-zA-Z_][\w$]*(?:\."[^"]+"|\.[a-zA-Z_][\w$]*)?)\s*\([^)]*\)(?:\s+(?:cascade|restrict))?$/iu.exec(statement);
+    if (dropFunctionMatch) {
+        return {
+            ast: null,
+            type: 'drop',
+            statementType: 'drop_function',
+            tables: [],
+        };
+    }
+    return null;
+}
 function getStatementType(ast) {
     const type = typeof ast?.type === 'string' ? ast.type.toLowerCase() : 'unknown';
     return type === 'desc' ? 'describe' : type;
 }
+function getDetailedStatementType(ast) {
+    const type = getStatementType(ast);
+    if (type === 'truncate') {
+        return 'truncate';
+    }
+    const keyword = typeof ast?.keyword === 'string' ? ast.keyword.toLowerCase() : undefined;
+    const constraintType = typeof ast?.constraint_type === 'string' ? ast.constraint_type.toLowerCase() : undefined;
+    if (type === 'create' && constraintType === 'trigger') {
+        return 'create_trigger';
+    }
+    if ((type === 'create' || type === 'alter' || type === 'drop') && keyword) {
+        return `${type}_${keyword.replace(/\s+/g, '_')}`;
+    }
+    return type;
+}
 function assertNoUnsafeReadOptions(ast) {
     if (Array.isArray(ast)) {
         for (const statement of ast) {
@@ -175,12 +259,45 @@ function collectTablesFromAst(ast) {
         return [];
     }
     switch (ast.type) {
+        case 'alter':
+            return normalizeAstTableList(ast.table);
+        case 'create':
+            return collectCreateTables(ast);
         case 'desc':
         case 'describe':
             return typeof ast.table === 'string' ? [ast.table] : [];
+        case 'drop':
+            return normalizeAstTableList(ast.name);
         case 'explain':
             return collectTablesFromAst(ast.expr);
+        case 'truncate':
+            return normalizeAstTableList(ast.name);
         default:
             return [];
     }
 }
+function collectCreateTables(ast) {
+    const tables = normalizeAstTableList(ast.table);
+    if (ast.keyword === 'view') {
+        tables.push(...normalizeAstTableList(ast.view));
+    }
+    return tables;
+}
+function normalizeAstTableList(value) {
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => normalizeAstTableList(item));
+    }
+    if (typeof value === 'string') {
+        return [value];
+    }
+    if (typeof value.table === 'string') {
+        return [value.db ? `${value.db}.${value.table}` : value.table];
+    }
+    if (typeof value.view === 'string') {
+        return [value.db ? `${value.db}.${value.view}` : value.view];
+    }
+    return [];
+}

package/build/toolHandlers.js

@@ -3,7 +3,7 @@ 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';
+import { analyzeSql, assertExecuteAllowed, assertExplainQueryAllowed, assertReadQueryAllowed, assertSchemaExecuteAllowed, assertTablesAllowed, isTableAllowed, } from './sqlPolicy.js';
 export async function pgQuery(sql) {
     assertReadQueryAllowed(sql);
     const analysis = analyzeSql(sql);
@@ -26,6 +26,16 @@ export async function pgExecute(sql, params) {
         summary: { sql, paramsPreview: params ?? null },
     }, () => db.execute(sql, params));
 }
+export async function pgSchemaExecute(sql) {
+    const analysis = assertSchemaExecuteAllowed(sql);
+    return runWithPolicy({
+        functionName: 'pg_schema_execute',
+        sql,
+        statementType: analysis.statementType,
+        tableNames: analysis.tableNames,
+        summary: { sql },
+    }, () => db.execute(sql));
+}
 export async function pgBatchExecute(sql, paramsList, transaction) {
     assertExecuteAllowed(sql);
     const analysis = analyzeSql(sql);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-pg-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "High performance PostgreSQL MCP Server using node-postgres",
   "main": "build/index.js",
   "type": "module",