easy-mysql-mcp 1.1.1 → 1.2.0

package/MANUAL.md

@@ -0,0 +1,120 @@
+# easy-mysql-mcp Manual
+
+`easy-mysql-mcp` 是一個用來操作 MySQL 的 MCP server，提供查詢、寫入、批次執行、CSV 匯入，以及 schema / 權限檢查工具。
+
+## Overview
+
+適合用在：
+- 讀取資料
+- 新增、更新、刪除資料
+- 批次執行 SQL
+- CSV 匯入與匯出
+- 需要查看 schema、index、trigger、權限與 query plan 的場景
+
+不適合用在：
+- 多語句 SQL
+- 未驗證字串直接拼接 SQL
+- 繞過 denylist / allowlist / policy hook
+
+## When to Consult This Manual
+
+如果你遇到以下情況，先看這份手冊：
+- 不確定 `mysql_query`、`mysql_execute`、`mysql_batch_execute` 要怎麼用
+- SQL 被拒絕或回傳錯誤
+- 不確定 `?` 參數要怎麼綁定
+- 不確定哪些 SQL 寫法是安全且允許的
+- 不確定應該先查 schema 還是直接執行
+
+## Modes
+
+- `readonly`: 只提供讀取相關工具
+- `readwrite`: 預設模式，允許一般讀寫，但不包含 DDL
+- `advanced`: 允許 schema / DDL 類工具
+
+## Tools
+
+- `mysql_query`: 讀取資料
+- `mysql_execute`: 執行單一寫入或變更 SQL
+- `mysql_batch_execute`: 以多組參數批次執行同一段 SQL
+- `mysql_import_csv`: 匯入 UTF-8 CSV
+- `mysql_export_csv`: 匯出表格為 UTF-8 CSV
+- `mysql_schema_execute`: 執行 schema / DDL 變更，僅 advanced 模式可用
+- `mysql_list_pending_approvals`: 列出待審核命令
+- `mysql_run_approved_command`: 執行已核准命令
+- `mysql_cancel_approval`: 取消審核
+- `explain_query`: 檢查 query plan
+- `list_tables`, `list_views`, `describe_table`, `describe_index`, `list_triggers`
+- `get_current_privileges`
+
+## Execute Usage
+
+`mysql_execute` 只應使用單一 SQL 指令。適合：
+- `INSERT`
+- `UPDATE`
+- `DELETE`
+
+`mysql_batch_execute` 適合：
+- 同一個 SQL 搭配多組參數重複執行
+- 大量資料寫入
+
+不要這樣用：
+- 多語句連寫
+- 把使用者輸入直接拼到 SQL 字串裡
+
+參數寫法以 `mysql2` 的 binding 方式為準：
+- 位置型參數使用 `?`
+- 批次執行時，`paramsList` 裡每一組參數都會依序對應 SQL 中的 `?`
+- 建議不要手動拼接字串值，改用參數綁定
+
+## SQL Algebra / Composition Rules
+
+MySQL 查詢可視為一個由上而下組裝的代數式：
+
+1. 先決定資料來源：`FROM`
+2. 再加條件：`WHERE`
+3. 需要關聯時使用 `JOIN ... ON`
+4. 有聚合時使用 `GROUP BY`
+5. 聚合後條件放在 `HAVING`
+6. 排序使用 `ORDER BY`
+7. 最後限制筆數：`LIMIT` / `OFFSET`
+
+常見正確組合：
+- 單表查詢：`SELECT ... FROM ... WHERE ...`
+- 聚合查詢：`SELECT ... COUNT(*) ... GROUP BY ... HAVING ...`
+- 多表查詢：`SELECT ... FROM a JOIN b ON ... WHERE ...`
+
+值與欄位的規則：
+- 欄位名稱必要時用反引號包住
+- 字串值使用單引號
+- 數值不要加引號
+- 日期與時間要用正確的 SQL 字面值
+- 不要把未驗證內容直接串進條件式
+
+## Safety Rules
+
+- 不支援 multi-statement
+- 不支援 `SELECT ... INTO`
+- 不支援 locking reads
+- 不支援 `CREATE TABLE ... AS SELECT`
+- 寫入前先確認 schema
+- deny tables 的優先級高於 allow tables
+
+## Examples
+
+- 查詢單一使用者：
+  - `SELECT id, name FROM users WHERE id = ?`
+- 聚合統計：
+  - `SELECT status, COUNT(*) FROM orders GROUP BY status`
+- join 查詢：
+  - `SELECT o.id, u.name FROM orders o JOIN users u ON o.user_id = u.id`
+- 更新資料：
+  - `UPDATE users SET name = ? WHERE id = ?`
+- 分頁查詢：
+  - `SELECT * FROM posts ORDER BY created_at DESC LIMIT 20 OFFSET 0`
+
+## Troubleshooting
+
+- 查不到欄位時，先用 `describe_table`
+- SQL 被拒絕時，先檢查是否是多語句或受限語法
+- 結果不如預期時，先確認 `WHERE` 與 `JOIN ON`
+- 效能不好時，先看 `explain_query`

package/README.md

@@ -16,7 +16,7 @@ This project uses Node.js, TypeScript, the official MCP SDK, and `mysql2/promise
 
 ## Requirements
 
-- Node.js 18 or newer
+- Node.js 20 or newer
 - npm
 - A reachable MySQL-compatible database
 
@@ -55,7 +55,7 @@ Configure the server with environment variables. You can provide them through yo
 | `MYSQL_ENABLE_KEEP_ALIVE` | No | `true` | Whether TCP keep-alive is enabled |
 | `MYSQL_KEEP_ALIVE_INITIAL_DELAY` | No | `0` | Initial TCP keep-alive delay in milliseconds |
 | `MYSQL_READ_ONLY` | No | `false` | When `true`, enables read-only mode and does not register `mysql_execute` |
-| `MYSQL_MCP_MODE` | No | `readwrite` | MCP policy mode. Use `readonly` to disable write execution |
+| `MYSQL_MCP_MODE` | No | `readwrite` | MCP policy mode. Use `readonly` to disable write execution or `advanced` to enable schema modification tools |
 | `MYSQL_MCP_ALLOW_TABLES` | No | - | Comma-separated table allowlist, such as `users,orders` |
 | `MYSQL_MCP_DENY_TABLES` | No | - | Comma-separated table denylist, such as `payments,secrets` |
 | `MYSQL_BATCH_MAX_SIZE` | No | `100` | Maximum number of parameter sets per internal batch for `mysql_batch_execute` |
@@ -91,6 +91,8 @@ 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 `mysql_manual` first. It returns the built-in manual with safe usage rules, parameter binding guidance, and SQL composition notes.
+
 ## Claude Desktop Example
 
 ```json
@@ -155,8 +157,10 @@ MYSQL_DATABASE = "YOUR DB NAME"
 
 | Tool | Description |
 | --- | --- |
+| `mysql_manual` | Return the built-in manual. Use this first when you are unsure how to use MySQL tools or need help diagnosing an operation error |
 | `mysql_query` | Execute a SQL query intended for data retrieval, such as `SELECT` |
 | `mysql_execute` | Execute a data modification statement, such as `INSERT`, `UPDATE`, or `DELETE` |
+| `mysql_schema_execute` | Execute schema modification statements in advanced mode, such as `CREATE TABLE`, `ALTER TABLE`, `CREATE VIEW`, `CREATE TRIGGER`, and `CREATE INDEX` |
 | `mysql_batch_execute` | Execute one data modification statement repeatedly with multiple parameter sets |
 | `mysql_import_csv` | Import a UTF-8 CSV file into a table using the header row as column names |
 | `mysql_export_csv` | Export all rows from a table to a UTF-8 CSV file |
@@ -173,6 +177,8 @@ MYSQL_DATABASE = "YOUR DB NAME"
 
 When `MYSQL_READ_ONLY=true` or `MYSQL_MCP_MODE=readonly`, the `mysql_execute`, `mysql_batch_execute`, and `mysql_import_csv` tools are not registered.
 
+When `MYSQL_MCP_MODE=advanced`, `mysql_schema_execute` is registered. Existing write tools remain available because advanced mode includes read/write behavior.
+
 ### Batch Execute
 
 `mysql_batch_execute` runs the same parameterized write statement with multiple parameter arrays. It is useful for bulk inserts or repeated updates without enabling multi-statement SQL.
@@ -237,10 +243,12 @@ The server applies a lightweight SQL policy before executing user-provided SQL:
 - `mysql_query` allows only single-statement `SELECT`, `SHOW`, `DESCRIBE`, and `EXPLAIN` queries.
 - `explain_query` accepts only a single `SELECT` statement and runs `EXPLAIN` for it.
 - `mysql_execute` allows only single-statement `INSERT`, `UPDATE`, `DELETE`, and `REPLACE` statements when write mode is enabled.
+- `mysql_schema_execute` is only registered when `MYSQL_MCP_MODE=advanced`, and allows single-statement schema changes for tables, views, triggers, and indexes.
 - `mysql_batch_execute` uses the same SQL policy as `mysql_execute` and applies the statement repeatedly with parameter arrays.
 - `mysql_import_csv` uses table policy and the same batch execution path as `mysql_batch_execute`.
 - `mysql_export_csv` uses table policy before exporting table data.
 - Multi-statement SQL is rejected.
+- `CREATE TABLE ... AS SELECT` is rejected because it copies data while creating a table.
 - `SELECT ... INTO` and locking reads are rejected for read-query tools.
 - `MYSQL_MCP_DENY_TABLES` rejects matching tables before `MYSQL_MCP_ALLOW_TABLES` is evaluated.
 - If `MYSQL_MCP_ALLOW_TABLES` is set, every detected table must be included in the allowlist.
@@ -267,6 +275,23 @@ In this configuration, `users` and `orders` are allowed, `payments` is rejected,
 
 `MYSQL_POLICY_HOOK` cannot override built-in rejections. It can only decide what happens after a command has already passed local policy: `accept`, `reject`, or `approval_required`.
 
+### Advanced Schema Mode
+
+Set `MYSQL_MCP_MODE=advanced` to enable `mysql_schema_execute` for schema changes. This is an explicit opt-in mode for database structure operations.
+
+Allowed schema statements:
+
+| Object | Statements |
+| --- | --- |
+| Tables | `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `RENAME TABLE` |
+| Views | `CREATE VIEW`, `CREATE OR REPLACE VIEW`, `DROP VIEW` |
+| Triggers | `CREATE TRIGGER`, `DROP TRIGGER` |
+| Indexes | `CREATE INDEX`, `DROP INDEX`, plus index changes through `ALTER TABLE` |
+
+The same table allow/deny policy applies to detected schema objects and referenced tables. `MYSQL_MCP_DENY_TABLES` still takes precedence over `MYSQL_MCP_ALLOW_TABLES`.
+
+Advanced mode still rejects multi-statement SQL, unsupported DDL object types, and `CREATE TABLE ... AS SELECT`.
+
 ## Policy Hook and Approvals
 
 When `MYSQL_POLICY_HOOK` is configured, the server posts each tool action to the hook after built-in policy checks pass and before the command runs.
@@ -322,9 +347,11 @@ This is an approval-friendly protocol. The server cannot verify that a human app
 - Use a dedicated MySQL user with the minimum permissions your assistant needs.
 - Prefer read-only database credentials if you only need inspection and reporting.
 - Use `MYSQL_READ_ONLY=true` or `MYSQL_MCP_MODE=readonly` to hide write execution from MCP clients.
+- Use `MYSQL_MCP_MODE=advanced` only when the assistant should be able to modify schema objects such as tables, views, triggers, and indexes.
 - Use `MYSQL_MCP_ALLOW_TABLES` and `MYSQL_MCP_DENY_TABLES` as MCP-level guardrails, not as a replacement for MySQL grants.
 - Use `MYSQL_POLICY_HOOK` when you need an external policy or approval workflow.
 - Be careful with `mysql_execute`, because it can modify data.
+- Be careful with `mysql_schema_execute`, because it can create, alter, or drop database structure.
 - Be careful with `mysql_import_csv`, because it can insert many rows.
 - Batch execution and CSV import logs include parameter values and per-row results. Treat files under `MYSQL_LOG_PATH` as sensitive.
 - CSV export writes table data to the local filesystem. Treat exported files as sensitive.

package/README.zh-TW.md

@@ -16,7 +16,7 @@
 
 ## 需求
 
-- Node.js 18 或更新版本
+- Node.js 20 或更新版本
 - npm
 - 可連線的 MySQL-compatible database
 
@@ -55,7 +55,7 @@ npm run build
 | `MYSQL_ENABLE_KEEP_ALIVE` | 否 | `true` | 是否啟用 TCP keep-alive |
 | `MYSQL_KEEP_ALIVE_INITIAL_DELAY` | 否 | `0` | TCP keep-alive 初始延遲，單位毫秒 |
 | `MYSQL_READ_ONLY` | 否 | `false` | 設為 `true` 時啟用唯讀模式，且不註冊 `mysql_execute` |
-| `MYSQL_MCP_MODE` | 否 | `readwrite` | MCP policy mode。使用 `readonly` 可停用寫入執行 |
+| `MYSQL_MCP_MODE` | 否 | `readwrite` | MCP policy mode。使用 `readonly` 可停用寫入執行，或使用 `advanced` 啟用結構修改工具 |
 | `MYSQL_MCP_ALLOW_TABLES` | 否 | - | table allowlist，逗號分隔，例如 `users,orders` |
 | `MYSQL_MCP_DENY_TABLES` | 否 | - | table denylist，逗號分隔，例如 `payments,secrets` |
 | `MYSQL_BATCH_MAX_SIZE` | 否 | `100` | `mysql_batch_execute` 每個內部分批最多處理的參數組數 |
@@ -153,10 +153,14 @@ MYSQL_DATABASE = "YOUR DB NAME"
 
 ## 可用工具
 
+如果你不確定某個工具該怎麼用，或操作失敗，請先呼叫 `mysql_manual`。它會回傳內建手冊，包含安全使用規則、參數綁定指引，以及 SQL 組合方式。
+
 | 工具 | 說明 |
 | --- | --- |
+| `mysql_manual` | 回傳內建手冊。當你不確定如何使用 MySQL 工具，或需要排查操作錯誤時，請先查這個工具 |
 | `mysql_query` | 執行用於資料讀取的 SQL query，例如 `SELECT` |
 | `mysql_execute` | 執行資料修改 statement，例如 `INSERT`、`UPDATE`、`DELETE` |
+| `mysql_schema_execute` | 在 advanced mode 執行 schema 修改 statement，例如 `CREATE TABLE`、`ALTER TABLE`、`CREATE VIEW`、`CREATE TRIGGER`、`CREATE INDEX` |
 | `mysql_batch_execute` | 使用多組參數重複執行同一個資料修改 statement |
 | `mysql_import_csv` | 使用 CSV header row 作為欄位名稱，將 UTF-8 CSV 匯入 table |
 | `mysql_export_csv` | 將 table 的所有 rows 匯出為 UTF-8 CSV |
@@ -173,6 +177,8 @@ MYSQL_DATABASE = "YOUR DB NAME"
 
 當 `MYSQL_READ_ONLY=true` 或 `MYSQL_MCP_MODE=readonly` 時，`mysql_execute`、`mysql_batch_execute`、`mysql_import_csv` 不會被註冊。
 
+當 `MYSQL_MCP_MODE=advanced` 時，會註冊 `mysql_schema_execute`。advanced mode 包含 read/write 行為，因此既有寫入工具仍會提供。
+
 ### Batch Execute
 
 `mysql_batch_execute` 會使用多組參數重複執行同一個 parameterized write statement。它適合 bulk insert 或 repeated update，而且不需要啟用 multi-statement SQL。
@@ -237,10 +243,12 @@ server 在執行使用者提供的 SQL 前，會套用輕量 SQL policy：
 - `mysql_query` 只允許單一 statement 的 `SELECT`、`SHOW`、`DESCRIBE`、`EXPLAIN` queries。
 - `explain_query` 只接受單一 `SELECT` statement，並對它執行 `EXPLAIN`。
 - `mysql_execute` 在 write mode 啟用時，只允許單一 statement 的 `INSERT`、`UPDATE`、`DELETE`、`REPLACE`。
+- `mysql_schema_execute` 只有在 `MYSQL_MCP_MODE=advanced` 時註冊，允許 tables、views、triggers、indexes 的單一 schema 修改 statement。
 - `mysql_batch_execute` 使用與 `mysql_execute` 相同的 SQL policy，並用多組參數重複執行。
 - `mysql_import_csv` 使用 table policy，並走與 `mysql_batch_execute` 相同的 batch execution path。
 - `mysql_export_csv` 會在匯出 table data 前套用 table policy。
 - multi-statement SQL 會被拒絕。
+- `CREATE TABLE ... AS SELECT` 會被拒絕，因為它會在建立 table 時複製資料。
 - read-query tools 會拒絕 `SELECT ... INTO` 與 locking reads。
 - `MYSQL_MCP_DENY_TABLES` 優先於 `MYSQL_MCP_ALLOW_TABLES`。
 - 如果設定 `MYSQL_MCP_ALLOW_TABLES`，每個偵測到的 table 都必須包含在 allowlist 中。
@@ -267,6 +275,23 @@ MYSQL_MCP_DENY_TABLES=payments
 
 `MYSQL_POLICY_HOOK` 不能覆蓋內建 policy 的拒絕結果。它只能在 command 已經通過本機 policy 後，決定接下來是 `accept`、`reject`，或 `approval_required`。
 
+### Advanced Schema Mode
+
+設定 `MYSQL_MCP_MODE=advanced` 可啟用 `mysql_schema_execute`，用於 schema changes。這是明確 opt-in 的資料庫結構操作模式。
+
+允許的 schema statements：
+
+| 物件 | Statements |
+| --- | --- |
+| Tables | `CREATE TABLE`、`ALTER TABLE`、`DROP TABLE`、`RENAME TABLE` |
+| Views | `CREATE VIEW`、`CREATE OR REPLACE VIEW`、`DROP VIEW` |
+| Triggers | `CREATE TRIGGER`、`DROP TRIGGER` |
+| Indexes | `CREATE INDEX`、`DROP INDEX`，以及透過 `ALTER TABLE` 修改 index |
+
+相同的 table allow/deny policy 會套用到偵測到的 schema objects 與 referenced tables。`MYSQL_MCP_DENY_TABLES` 仍然優先於 `MYSQL_MCP_ALLOW_TABLES`。
+
+Advanced mode 仍會拒絕 multi-statement SQL、不支援的 DDL object types，以及 `CREATE TABLE ... AS SELECT`。
+
 ## Policy Hook 與 Approval
 
 設定 `MYSQL_POLICY_HOOK` 後，server 會在內建 policy 通過後、command 真正執行前，將每個 tool action POST 到 hook。
@@ -322,9 +347,11 @@ Pending approvals 是 one-time use，並會在 `MYSQL_APPROVAL_TTL_SECONDS` 後
 - 使用 dedicated MySQL user，並只給 assistant 所需的最小權限。
 - 如果只需要 inspection/reporting，建議使用 read-only database credentials。
 - 使用 `MYSQL_READ_ONLY=true` 或 `MYSQL_MCP_MODE=readonly`，可以避免 write execution tools 暴露給 MCP clients。
+- 只有在 assistant 需要修改 tables、views、triggers、indexes 等 schema objects 時，才使用 `MYSQL_MCP_MODE=advanced`。
 - `MYSQL_MCP_ALLOW_TABLES` 與 `MYSQL_MCP_DENY_TABLES` 是 MCP 層 guardrails，不能取代 MySQL grants。
 - 需要外部 policy 或 approval workflow 時，可使用 `MYSQL_POLICY_HOOK`。
 - 請小心使用 `mysql_execute`，它可以修改資料。
+- 請小心使用 `mysql_schema_execute`，它可以建立、修改或刪除資料庫結構。
 - 請小心使用 `mysql_import_csv`，它可以插入大量資料。
 - batch execution 與 CSV import logs 會包含參數值與逐筆結果。請將 `MYSQL_LOG_PATH` 下的檔案視為敏感資料。
 - CSV export 會將 table data 寫到本機 filesystem。請將匯出檔視為敏感資料。

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, mysqlBatchExecute, mysqlExecute, mysqlExportCsv, mysqlImportCsv, mysqlQuery, } from './toolHandlers.js';
+import { describeIndex, describeTable, explainQuery, getCurrentPrivileges, listTables, listTriggers, listViews, mysqlBatchExecute, mysqlExecute, mysqlExportCsv, mysqlImportCsv, mysqlSchemaExecute, mysqlQuery, } from './toolHandlers.js';
 const { MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE, } = process.env;
 // Initialize MCP Server/mcp
 const server = new McpServer({
     name: 'easy-mysql-mcp',
-    version: '1.1.1',
+    version: '1.1.2',
     description: `MySQL Database: ${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_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('mysql_manual', {
+    description: 'Return the MySQL MCP manual. Use this first when you are unsure how to use mysql_query, mysql_execute, mysql_batch_execute, or when an operation fails and you need the safe usage rules, parameter rules, or SQL composition guidance.',
+    inputSchema: z.object({}),
+}, async () => ({
+    content: [{ type: 'text', text: manualText }],
+}));
 server.registerTool('mysql_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('mysql_schema_execute', {
+        description: 'Execute an advanced schema modification SQL statement, such as CREATE TABLE, ALTER TABLE, DROP VIEW, CREATE TRIGGER, or CREATE INDEX.',
+        inputSchema: z.object({
+            sql: z.string().describe('The single schema modification SQL statement to execute.'),
+        }),
+    }, async ({ sql }) => {
+        const result = await mysqlSchemaExecute(sql);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
 if (isPolicyHookEnabled()) {
     server.registerTool('mysql_run_approved_command', {
         description: 'Run a pending command after the host has obtained user approval.',

package/build/sqlPolicy.js

@@ -1,11 +1,14 @@
 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/mysql.js');
 const parser = new Parser();
 const parserOptions = { database: 'MySQL' };
 const readQueryTypes = new Set(['select', 'show', 'desc', 'describe', 'explain']);
 const executeTypes = new Set(['insert', 'update', 'delete', 'replace']);
+const schemaExecuteTypes = new Set(['create', 'alter', 'drop', 'rename']);
+const createSchemaKeywords = new Set(['table', 'view', 'trigger', 'index']);
+const dropSchemaKeywords = new Set(['table', 'view', 'trigger', 'index']);
 export class SqlPolicyError extends Error {
     constructor(message) {
         super(message);
@@ -45,6 +48,18 @@ export function assertExecuteAllowed(sql) {
     }
     assertTablePolicy(parsed.tables);
 }
+export function assertSchemaExecuteAllowed(sql) {
+    if (!isAdvancedMode()) {
+        throw new SqlPolicyError('SQL rejected: schema execution requires MYSQL_MCP_MODE=advanced.');
+    }
+    const parsed = parseSingleStatement(sql);
+    if (!schemaExecuteTypes.has(parsed.type)) {
+        throw new SqlPolicyError(`SQL rejected: mysql_schema_execute only allows CREATE, ALTER, DROP, and RENAME statements. Received ${parsed.type.toUpperCase()}.`);
+    }
+    assertSchemaAstAllowed(parsed.ast);
+    assertNoUnsafeReadOptions(parsed.ast);
+    assertTablePolicy(parsed.tables);
+}
 export function assertTablesAllowed(tables) {
     assertTablePolicy(tables.map((table) => normalizeTableName(table)));
 }
@@ -111,6 +126,39 @@ function assertNoUnsafeReadOptions(ast) {
     if (ast?.type === 'explain') {
         assertNoUnsafeReadOptions(ast.expr);
     }
+    if (ast?.type === 'create' && ast.keyword === 'view') {
+        assertNoUnsafeReadOptions(ast.select);
+    }
+}
+function assertSchemaAstAllowed(ast) {
+    switch (ast?.type) {
+        case 'create': {
+            const keyword = normalizeKeyword(ast.keyword);
+            if (!createSchemaKeywords.has(keyword)) {
+                throw new SqlPolicyError(`SQL rejected: mysql_schema_execute does not allow CREATE ${keyword.toUpperCase()}.`);
+            }
+            if (keyword === 'table' && ast.query_expr) {
+                throw new SqlPolicyError('SQL rejected: CREATE TABLE ... AS SELECT is not allowed by mysql_schema_execute.');
+            }
+            return;
+        }
+        case 'alter':
+            if (!ast.table) {
+                throw new SqlPolicyError('SQL rejected: mysql_schema_execute only allows ALTER TABLE statements.');
+            }
+            return;
+        case 'drop': {
+            const keyword = normalizeKeyword(ast.keyword);
+            if (!dropSchemaKeywords.has(keyword)) {
+                throw new SqlPolicyError(`SQL rejected: mysql_schema_execute does not allow DROP ${keyword.toUpperCase()}.`);
+            }
+            return;
+        }
+        case 'rename':
+            return;
+        default:
+            throw new SqlPolicyError(`SQL rejected: mysql_schema_execute does not allow ${String(ast?.type ?? 'unknown').toUpperCase()} statements.`);
+    }
 }
 function assertTablePolicy(tables) {
     for (const table of tables) {
@@ -175,6 +223,12 @@ function collectTablesFromAst(ast) {
         return [];
     }
     switch (ast.type) {
+        case 'create':
+            return collectCreateTablesFromAst(ast);
+        case 'drop':
+            return collectDropTablesFromAst(ast);
+        case 'rename':
+            return collectRenameTablesFromAst(ast);
         case 'desc':
         case 'describe':
             return typeof ast.table === 'string' ? [ast.table] : [];
@@ -184,3 +238,47 @@ function collectTablesFromAst(ast) {
             return [];
     }
 }
+function collectCreateTablesFromAst(ast) {
+    const tables = [
+        ...collectTableLikeNames(ast.table),
+        ...collectTableLikeNames(ast.view),
+        ...collectTableLikeNames(ast.trigger),
+        ...collectTableLikeNames(ast.like?.table),
+    ];
+    if (ast.keyword === 'view') {
+        tables.push(...collectTablesFromAst(ast.select));
+    }
+    return tables;
+}
+function collectDropTablesFromAst(ast) {
+    if (ast.keyword === 'index') {
+        return collectTableLikeNames(ast.table);
+    }
+    return collectTableLikeNames(ast.name);
+}
+function collectRenameTablesFromAst(ast) {
+    return collectTableLikeNames(ast.table);
+}
+function collectTableLikeNames(value) {
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => collectTableLikeNames(item));
+    }
+    if (typeof value === 'string') {
+        return [value];
+    }
+    if (typeof value === 'object') {
+        const objectName = value.table ?? value.view ?? value.trigger;
+        if (typeof objectName === 'string') {
+            return value.db || value.schema
+                ? [`${value.db ?? value.schema}.${objectName}`]
+                : [objectName];
+        }
+    }
+    return [];
+}
+function normalizeKeyword(keyword) {
+    return typeof keyword === 'string' ? keyword.toLowerCase() : 'unknown';
+}

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 mysqlQuery(sql) {
     assertReadQueryAllowed(sql);
     const analysis = analyzeSql(sql);
@@ -26,6 +26,17 @@ export async function mysqlExecute(sql, params) {
         summary: { sql, paramsPreview: params ?? null },
     }, () => db.execute(sql, params));
 }
+export async function mysqlSchemaExecute(sql) {
+    assertSchemaExecuteAllowed(sql);
+    const analysis = analyzeSql(sql);
+    return runWithPolicy({
+        functionName: 'mysql_schema_execute',
+        sql,
+        statementType: analysis.statementType,
+        tableNames: analysis.tableNames,
+        summary: { sql },
+    }, () => db.query(sql));
+}
 export async function mysqlBatchExecute(sql, paramsList, transaction) {
     assertExecuteAllowed(sql);
     const analysis = analyzeSql(sql);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-mysql-mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "High performance MySQL MCP Server using mysql2",
   "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",
@@ -34,12 +36,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "mysql2": "^3.22.4",
+    "mysql2": "^3.22.5",
     "node-sql-parser": "^5.4.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.3",
     "typescript": "^6.0.3"
   },
   "repository": {