easy-mysql-mcp 1.1.0 → 1.1.2

package/README.md

@@ -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` |
@@ -157,6 +157,7 @@ MYSQL_DATABASE = "YOUR DB NAME"
 | --- | --- |
 | `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 +174,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 +240,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 +272,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 +344,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

@@ -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` 每個內部分批最多處理的參數組數 |
@@ -157,6 +157,7 @@ MYSQL_DATABASE = "YOUR DB NAME"
 | --- | --- |
 | `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 +174,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 +240,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 +272,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 +344,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

@@ -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, 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.0.3',
+    version: '1.1.2',
     description: `MySQL Database: ${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}`,
 });
 // --- Register Tools ---
@@ -66,6 +66,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.0",
+  "version": "1.1.2",
   "description": "High performance MySQL MCP Server using mysql2",
   "main": "build/index.js",
   "type": "module",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "mysql2": "^3.22.3",
+    "mysql2": "^3.22.4",
     "node-sql-parser": "^5.4.0",
     "zod": "^4.4.3"
   },