easy-mysql-mcp 1.1.2 → 1.2.2

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
 
@@ -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,6 +157,7 @@ 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` |

package/README.zh-TW.md

@@ -16,7 +16,7 @@
 
 ## 需求
 
-- Node.js 18 或更新版本
+- Node.js 20 或更新版本
 - npm
 - 可連線的 MySQL-compatible database
 
@@ -153,8 +153,11 @@ 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` |

package/build/index.js

@@ -1,4 +1,6 @@
 #!/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';
@@ -13,8 +15,15 @@ const server = new McpServer({
     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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-mysql-mcp",
-  "version": "1.1.2",
+  "version": "1.2.2",
   "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,13 +36,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "mysql2": "^3.22.4",
+    "mysql2": "^3.23.0",
     "node-sql-parser": "^5.4.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
   },
   "repository": {
     "type": "git",