easy-pg-mcp 1.0.0 → 1.1.0

package/MANUAL.md

@@ -0,0 +1,120 @@
+# easy-pg-mcp Manual
+
+`easy-pg-mcp` 是一個用來操作 PostgreSQL 的 MCP server，提供查詢、寫入、批次執行、CSV 匯入，以及 schema / 權限檢查工具。
+
+## Overview
+
+適合用在：
+- PostgreSQL 資料查詢
+- 參數化寫入
+- `RETURNING` 型流程
+- 需要 CTE、複雜 join、聚合查詢的場景
+
+不適合用在：
+- 多語句 SQL
+- 直接字串拼接參數
+- 過度依賴隱式型別轉換
+
+## When to Consult This Manual
+
+如果你遇到以下情況，先看這份手冊：
+- 不確定 `pg_query`、`pg_execute`、`pg_batch_execute` 要怎麼用
+- SQL 被拒絕或回傳錯誤
+- 不確定 `$1, $2, ...` 參數要怎麼綁定
+- 不確定哪些 SQL 寫法是安全且允許的
+- 不確定應該先查 schema 還是直接執行
+
+## Modes
+
+- `readonly`: 只提供讀取相關工具
+- `readwrite`: 預設模式，允許一般讀寫，但不包含 DDL
+- `advanced`: 允許 schema / DDL 類工具
+
+## Tools
+
+- `pg_query`: 讀取資料
+- `pg_execute`: 執行單一寫入或變更 SQL
+- `pg_batch_execute`: 以多組參數批次執行同一段 SQL
+- `pg_import_csv`: 匯入 UTF-8 CSV
+- `pg_export_csv`: 匯出表格為 UTF-8 CSV
+- `pg_schema_execute`: 執行 schema / DDL 變更，僅 advanced 模式可用
+- `pg_list_pending_approvals`: 列出待審核命令
+- `pg_run_approved_command`: 執行已核准命令
+- `pg_cancel_approval`: 取消審核
+- `explain_query`: 檢查 query plan
+- `list_tables`, `list_views`, `describe_table`, `describe_index`, `list_triggers`
+- `get_current_privileges`
+
+## Execute Usage
+
+`pg_execute` 應使用 PostgreSQL placeholder：
+- `"$1", "$2", "$3"...`
+
+規則：
+- SQL 只描述結構
+- 值由 `params` 陣列提供
+- `$n` 與參數順序必須完全對應
+- 不要用 `?`
+- 不要把使用者輸入直接插入 SQL 字串
+
+`pg_batch_execute` 適合：
+- 同一個 SQL 搭配多組參數重複執行
+- 大量資料寫入
+
+參數寫法補充：
+- SQL 內使用 `$1`, `$2`, ... 代表參數位置
+- `params` 陣列的第 1 個值會綁定到 `$1`
+- `params` 陣列的第 2 個值會綁定到 `$2`
+- 依此類推，順序必須完全一致
+
+## SQL Algebra / Composition Rules
+
+PostgreSQL 查詢組裝可視為一個由上而下的代數式：
+
+1. 先定義中間結果：`WITH`
+2. 選擇欄位：`SELECT`
+3. 指定資料來源：`FROM`
+4. 關聯資料：`JOIN ... ON`
+5. 篩選資料：`WHERE`
+6. 聚合：`GROUP BY`
+7. 聚合後篩選：`HAVING`
+8. 排序：`ORDER BY`
+9. 限制筆數：`LIMIT` / `OFFSET`
+
+PostgreSQL 常用特性：
+- `RETURNING`：寫入後直接取回欄位
+- `::type`：明確型別轉換
+- CTE：提升複雜查詢可讀性
+- 參數化日期區間查詢：搭配 `$1`, `$2`
+
+值與型別的規則：
+- 值優先用參數
+- 型別轉換要明確
+- 時區與日期欄位要一致處理
+
+## Safety Rules
+
+- 不支援 multi-statement
+- 不要把使用者輸入直接嵌入 SQL
+- schema execute 不支援參數化
+- 某些 DDL 解析與授權限制需特別注意
+
+## Examples
+
+- 參數化查詢：
+  - `SELECT * FROM users WHERE id = $1`
+- 寫入後取回 id：
+  - `INSERT INTO users (name) VALUES ($1) RETURNING id`
+- CTE：
+  - `WITH recent_orders AS (...) SELECT * FROM recent_orders`
+- 聚合：
+  - `SELECT status, COUNT(*) FROM orders GROUP BY status`
+- 日期區間查詢：
+  - `SELECT * FROM logs WHERE created_at >= $1 AND created_at < $2`
+
+## Troubleshooting
+
+- 如果參數沒生效，先檢查 `$n` 與 `params` 順序
+- 如果欄位型別不對，補上 `::type`
+- 如果查詢太複雜，先改寫成 `WITH`
+- 如果執行失敗，先用 `describe_table` 確認 schema

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`
@@ -17,7 +17,7 @@ This project uses Node.js, TypeScript, the official MCP SDK, and [`pg`](https://
 
 ## Requirements
 
-- Node.js 18 or newer
+- Node.js 20 or newer
 - npm
 - A reachable PostgreSQL database
 
@@ -29,7 +29,7 @@ Run the server directly with `npx`:
 npx -y easy-pg-mcp
 ```
 
-For local development:
+For local development after cloning the repository:
 
 ```bash
 cd easy-pg-mcp
@@ -39,6 +39,8 @@ npm run build
 
 ## Configuration
 
+Configure the server with environment variables. You can provide them through your MCP client configuration or by creating a local `.env` file.
+
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
 | `PG_CONNECTION_STRING` | No | - | PostgreSQL connection string. When set, host/user/password/database fields are optional |
@@ -53,7 +55,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` |
@@ -73,9 +75,27 @@ PG_PASSWORD=your_password
 PG_DATABASE=your_database
 ```
 
-## MCP Client Examples
+## Usage
+
+Configure your MCP client to launch the package through `npx`.
+
+For local development, build the TypeScript source first:
+
+```bash
+npm run build
+```
 
-Claude Desktop:
+Start the MCP server:
+
+```bash
+npm start
+```
+
+The server communicates over stdio and is normally launched by an MCP client rather than run manually.
+
+If you are unsure how a tool should be used, or an operation fails, call `pg_manual` first. It returns the built-in manual with safe usage rules, placeholder guidance, and SQL composition notes.
+
+## Claude Desktop Example
 
 ```json
 {
@@ -95,7 +115,9 @@ Claude Desktop:
 }
 ```
 
-Codex `config.toml`:
+Restart Claude Desktop after updating the configuration.
+
+## Codex config.toml Example
 
 ```toml
 [mcp_servers.easy-pg-mcp]
@@ -111,12 +133,36 @@ PG_PASSWORD = "YOUR PASSWORD"
 PG_DATABASE = "YOUR DB NAME"
 ```
 
+## OpenCode opencode.jsonc Example
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "easy-pg-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "easy-pg-mcp"],
+      "enabled": true,
+      "environment": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "YOUR USERNAME",
+        "PG_PASSWORD": "YOUR PASSWORD",
+        "PG_DATABASE": "YOUR DB NAME"
+      }
+    }
+  }
+}
+```
+
 ## Available Tools
 
 | Tool | Description |
 | --- | --- |
+| `pg_manual` | Return the built-in manual. Use this first when you are unsure how to use PostgreSQL tools or need help diagnosing an operation error |
 | `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 +177,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 +225,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 +235,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` 查詢計畫分析
@@ -17,7 +17,7 @@
 
 ## 需求
 
-- Node.js 18 以上
+- Node.js 20 以上
 - npm
 - 可連線的 PostgreSQL 資料庫
 
@@ -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` 每批最大參數組數 |
@@ -113,10 +113,14 @@ PG_DATABASE = "YOUR DB NAME"
 
 ## 可用工具
 
+如果你不確定某個工具該怎麼用，或操作失敗，請先呼叫 `pg_manual`。它會回傳內建手冊，包含安全使用規則、placeholder 指引，以及 SQL 組合方式。
+
 | 工具 | 說明 |
 | --- | --- |
+| `pg_manual` | 回傳內建手冊。當你不確定如何使用 PostgreSQL 工具，或需要排查操作錯誤時，請先查這個工具 |
 | `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 +135,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 +183,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 +193,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

@@ -1,20 +1,29 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 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}`,
 });
+const manualText = readFileSync(fileURLToPath(new URL('../MANUAL.md', import.meta.url)), 'utf8');
 // --- Register Tools ---
 const transactionModeSchema = z.enum(['all', 'batch', 'each', 'none']);
+server.registerTool('pg_manual', {
+    description: 'Return the PostgreSQL MCP manual. Use this first when you are unsure how to use pg_query, pg_execute, pg_batch_execute, or when an operation fails and you need the safe usage rules, placeholder rules, or SQL composition guidance.',
+    inputSchema: z.object({}),
+}, async () => ({
+    content: [{ type: 'text', text: manualText }],
+}));
 server.registerTool('pg_query', {
     description: 'Execute a read-only SQL query (e.g., SELECT). Use this for data retrieval.',
     inputSchema: z.object({
@@ -66,6 +75,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.1.0",
   "description": "High performance PostgreSQL MCP Server using node-postgres",
   "main": "build/index.js",
   "type": "module",
@@ -9,10 +9,12 @@
   },
   "files": [
     "build",
-    "README.md"
+    "README.md",
+    "README.zh-TW.md",
+    "MANUAL.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "mcp",
@@ -41,8 +43,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "@types/pg": "^8.15.6",
+    "@types/node": "^25.9.3",
+    "@types/pg": "^8.20.0",
     "typescript": "^6.0.3"
   },
   "repository": {