@dockeryu/mysql-mcp 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# @dockeryu/mysql-mcp
+
+基于 [Model Context Protocol](https://modelcontextprotocol.io) 的 MySQL 数据库服务，让 AI 助手可以直接操作 MySQL。
+
+## 安装与运行
+
+```bash
+npx -y @dockeryu/mysql-mcp
+```
+
+作用域包公开发布后可用；若尚未发布到 npm，请用本地 `npm run build` 后通过 `node dist/index.js` 或 Cursor 里配置 `command` 为 `node`、`args` 指向本地 `dist/index.js`。
+
+## 配置
+
+通过环境变量配置数据库连接和操作权限。
+
+### 连接配置
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| `MYSQL_HOST` | `127.0.0.1` | 数据库地址 |
+| `MYSQL_PORT` | `3306` | 端口 |
+| `MYSQL_USER` | `root` | 用户名 |
+| `MYSQL_PASSWORD` | _(空)_ | 密码 |
+| `MYSQL_DATABASE` | _(无)_ | 默认数据库（可选）|
+
+### 操作权限
+
+危险操作默认禁止，需显式开启。
+
+| 环境变量 | 默认 | 说明 |
+|----------|------|------|
+| `MYSQL_ALLOW_INSERT` | `true` | 允许 INSERT |
+| `MYSQL_ALLOW_CREATE` | `true` | 允许 CREATE |
+| `MYSQL_ALLOW_UPDATE` | `false` | 允许 UPDATE |
+| `MYSQL_ALLOW_DELETE` | `false` | 允许 DELETE |
+| `MYSQL_ALLOW_DROP` | `false` | 允许 DROP |
+| `MYSQL_ALLOW_TRUNCATE` | `false` | 允许 TRUNCATE |
+
+## 在 Cursor / Claude Desktop 中使用
+
+编辑 MCP 配置文件（`mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@dockeryu/mysql-mcp"],
+      "env": {
+        "MYSQL_HOST": "127.0.0.1",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "root",
+        "MYSQL_PASSWORD": "your_password",
+        "MYSQL_DATABASE": "your_db",
+        "MYSQL_ALLOW_UPDATE": "true",
+        "MYSQL_ALLOW_DELETE": "true"
+      }
+    }
+  }
+}
+```
+
+## 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `query` | 执行 SELECT 查询 |
+| `execute` | 执行写操作（受权限控制） |
+| `list_databases` | 列出所有数据库 |
+| `list_tables` | 列出指定库的所有表 |
+| `describe_table` | 查看表结构 |
+
+## 本地开发
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+发布公开作用域包：`npm publish --access public`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const promise_1 = __importDefault(require("mysql2/promise"));
+const zod_1 = require("zod");
+const ConfigSchema = zod_1.z.object({
+    host: zod_1.z.string().default("127.0.0.1"),
+    port: zod_1.z.number().default(3306),
+    user: zod_1.z.string().default("root"),
+    password: zod_1.z.string().default(""),
+    database: zod_1.z.string().optional(),
+    allowUpdate: zod_1.z.boolean().default(false),
+    allowDelete: zod_1.z.boolean().default(false),
+    allowDrop: zod_1.z.boolean().default(false),
+    allowTruncate: zod_1.z.boolean().default(false),
+    allowCreate: zod_1.z.boolean().default(true),
+    allowInsert: zod_1.z.boolean().default(true),
+});
+let _config = null;
+function getConfig() {
+    if (!_config) {
+        _config = ConfigSchema.parse({
+            host: process.env.MYSQL_HOST,
+            port: process.env.MYSQL_PORT ? parseInt(process.env.MYSQL_PORT) : undefined,
+            user: process.env.MYSQL_USER,
+            password: process.env.MYSQL_PASSWORD,
+            database: process.env.MYSQL_DATABASE,
+            allowUpdate: process.env.MYSQL_ALLOW_UPDATE === "true",
+            allowDelete: process.env.MYSQL_ALLOW_DELETE === "true",
+            allowDrop: process.env.MYSQL_ALLOW_DROP === "true",
+            allowTruncate: process.env.MYSQL_ALLOW_TRUNCATE === "true",
+            allowCreate: process.env.MYSQL_ALLOW_CREATE !== "false",
+            allowInsert: process.env.MYSQL_ALLOW_INSERT !== "false",
+        });
+    }
+    return _config;
+}
+const DANGEROUS_PATTERNS = [
+    { regex: /^\s*UPDATE\s/i, key: "allowUpdate", label: "UPDATE" },
+    { regex: /^\s*DELETE\s/i, key: "allowDelete", label: "DELETE" },
+    { regex: /^\s*DROP\s/i, key: "allowDrop", label: "DROP" },
+    { regex: /^\s*TRUNCATE\s/i, key: "allowTruncate", label: "TRUNCATE" },
+    { regex: /^\s*INSERT\s/i, key: "allowInsert", label: "INSERT" },
+    { regex: /^\s*CREATE\s/i, key: "allowCreate", label: "CREATE" },
+];
+function checkPermission(sql) {
+    const cfg = getConfig();
+    for (const { regex, key, label } of DANGEROUS_PATTERNS) {
+        if (regex.test(sql) && !cfg[key]) {
+            throw new Error(`${label} 操作未被允许，请设置环境变量 MYSQL_ALLOW_${label}=true`);
+        }
+    }
+}
+let pool = null;
+function getPool() {
+    if (!pool) {
+        const { host, port, user, password, database } = getConfig();
+        pool = promise_1.default.createPool({
+            host, port, user, password, database,
+            waitForConnections: true,
+            connectionLimit: 10,
+        });
+    }
+    return pool;
+}
+async function executeQuery(sql, params = []) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [rows] = await getPool().execute(sql, params);
+    return rows;
+}
+const server = new index_js_1.Server({ name: "mysql-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "query",
+            description: "执行 SQL 查询（SELECT）",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sql: { type: "string", description: "SQL 查询语句" },
+                    params: { type: "array", description: "查询参数", items: {} },
+                },
+                required: ["sql"],
+            },
+        },
+        {
+            name: "execute",
+            description: "执行 SQL 写操作（INSERT/UPDATE/DELETE/CREATE 等）",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sql: { type: "string", description: "SQL 语句" },
+                    params: { type: "array", description: "参数列表", items: {} },
+                },
+                required: ["sql"],
+            },
+        },
+        {
+            name: "list_databases",
+            description: "列出所有数据库",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "list_tables",
+            description: "列出指定数据库的所有表",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    database: { type: "string", description: "数据库名（不填则用连接默认库）" },
+                },
+            },
+        },
+        {
+            name: "describe_table",
+            description: "查看表结构",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    table: { type: "string", description: "表名" },
+                    database: { type: "string", description: "数据库名（可选）" },
+                },
+                required: ["table"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        if (name === "query") {
+            const { sql, params = [] } = args;
+            result = await executeQuery(sql, params);
+        }
+        else if (name === "execute") {
+            const { sql, params = [] } = args;
+            checkPermission(sql);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const [res] = await getPool().execute(sql, params);
+            result = res;
+        }
+        else if (name === "list_databases") {
+            result = await executeQuery("SHOW DATABASES");
+        }
+        else if (name === "list_tables") {
+            const { database } = (args ?? {});
+            const sql = database
+                ? `SHOW TABLES FROM \`${database}\``
+                : "SHOW TABLES";
+            result = await executeQuery(sql);
+        }
+        else if (name === "describe_table") {
+            const { table, database } = args;
+            const fullTable = database ? `\`${database}\`.\`${table}\`` : `\`${table}\``;
+            result = await executeQuery(`DESCRIBE ${fullTable}`);
+        }
+        else {
+            throw new Error(`未知工具: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `错误: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("MySQL MCP Server 已启动\n");
+}
+main().catch((err) => {
+    process.stderr.write(`启动失败: ${err}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@dockeryu/mysql-mcp",
+  "version": "1.0.0",
+  "description": "MySQL MCP Server",
+  "main": "dist/index.js",
+  "bin": {
+    "mysql-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": ["mcp", "mysql", "modelcontextprotocol"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "mysql2": "^3.14.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "typescript": "^5.8.2"
+  }
+}