@dexical30/mcp-server-mysql 0.0.0-stage → 2.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Ben Borla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# MCP Server for MySQL
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **This is a fork of [benborla/mcp-server-mysql](https://github.com/benborla/mcp-server-mysql)**, published as `@dexical30/mcp-server-mysql`.
+> It adds [1Password secret reference support](#1password-secret-references) for `MYSQL_PASS`.
+> All credit for the original project goes to Ben Borla and its contributors.
+
+[![MCP Toplist](https://mcptoplist.com/badge/glama%2Fbenborla%2Fmcp-server-mysql.svg)](https://mcptoplist.com/server/glama%2Fbenborla%2Fmcp-server-mysql)
+
+[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/benborla/mcp-server-mysql)](https://archestra.ai/mcp-catalog/benborla__mcp-server-mysql)
+
+## Sponsor — Bloome
+
+[![Bloome](assets/bloome.png)](https://bloome.im/login?ref=2x7GfeSw)
+
+Using mcp-server-mysql to let your AI query MySQL? [**Bloome**](https://bloome.im/login?ref=2x7GfeSw) brings that to your whole team — an AI-agent IM platform where AI agents are members of the chat. Connect your MCP tools and have agents inspect schemas, run queries, and answer data questions for everyone in one thread. Zero local setup, runs in the cloud, on web and mobile.
+
+---
+
+MCP server that gives Claude and other LLMs access to MySQL — inspect schemas, run queries, and optionally write data, all through the Model Context Protocol.
+
+## Key Features
+
+- **Read-only by default** — write operations opt-in via env flags
+- **Claude Code integration** — optimized for Anthropic's Claude Code CLI
+- **SSH tunnel support** — built-in support for remote databases
+- **Multi-DB mode** — query across multiple databases without reconnecting
+- **Schema-specific permissions** — per-database read/write control
+- **PII redaction** — automatic masking of sensitive data in results
+- **Remote mode** — HTTP transport with bearer token auth
+- **SSL/TLS support** — encrypted connections with mTLS option
+
+## Requirements
+
+- Node.js v20+
+- MySQL 5.7+ (8.0+ recommended)
+- MySQL user with appropriate privileges
+
+## Quick Install
+
+**Claude Code (simplest):**
+
+```bash
+claude mcp add mcp_server_mysql \
+  -e MYSQL_HOST="127.0.0.1" \
+  -e MYSQL_PORT="3306" \
+  -e MYSQL_USER="root" \
+  -e MYSQL_PASS="your_password" \
+  -e MYSQL_DB="your_database" \
+  -- npx @dexical30/mcp-server-mysql
+```
+
+**Claude Desktop / other clients:**
+
+```json
+{
+  "mcpServers": {
+    "mcp_server_mysql": {
+      "command": "npx",
+      "args": ["-y", "@dexical30/mcp-server-mysql"],
+      "env": {
+        "MYSQL_HOST": "127.0.0.1",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "root",
+        "MYSQL_PASS": "your_password",
+        "MYSQL_DB": "your_database"
+      }
+    }
+  }
+}
+```
+
+All write operations are disabled by default. Enable with `ALLOW_INSERT_OPERATION=true`, `ALLOW_UPDATE_OPERATION=true`, `ALLOW_DELETE_OPERATION=true`.
+
+## 1Password Secret References
+
+Set `MYSQL_PASS` to a [1Password secret reference](https://developer.1password.com/docs/cli/secret-reference-syntax/) instead of a plaintext password:
+
+```json
+"env": {
+  "MYSQL_PASS": "op://Private/MySQL Dev/password"
+}
+```
+
+When `MYSQL_PASS` starts with `op://`, the server runs `op read` itself at startup and keeps the password only in memory. The plaintext never enters the process environment, so it does not show up in `ps eww` or in your MCP client config.
+
+Requirements:
+
+- [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) installed
+- 1Password desktop app → **Settings → Developer → Integrate with 1Password CLI** enabled (approve with Touch ID on startup)
+- If your MCP client can't find `op` on its `PATH` (common for GUI apps), set `MYSQL_OP_PATH`, e.g. `/opt/homebrew/bin/op`
+
+Do **not** wrap the server in `op run`: it would inject the plaintext password into the environment, which is exactly what this avoids.
+
+## Documentation
+
+- [Installation Guide](docs/INSTALLATION.md) — Smithery, Cursor, Codex, Claude Code, local repo, remote mode
+- [Configuration & Environment Variables](docs/CONFIGURATION.md) — all env vars, advanced config
+- [Multi-DB Mode](README-MULTI-DB.md) — querying multiple databases
+- [PII Redaction](docs/PII-REDACTION.md) — automatic data masking
+- [Testing](docs/TESTING.md) — test setup and running
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common issues and fixes
+- [Changelog](CHANGELOG.md)
+
+## Tools & Resources
+
+**Tool: `mysql_query`**
+Execute SQL queries. Read-only by default. Write operations enabled per flag.
+
+**Resources: `mysql://tables`**
+Lists all tables and column metadata for the connected database.
+
+## Contributing
+
+PRs welcome at [github.com/benborla/mcp-server-mysql](https://github.com/benborla/mcp-server-mysql).
+
+```bash
+git clone https://github.com/benborla/mcp-server-mysql.git
+pnpm install
+pnpm run build
+pnpm test
+```
+
+[![Contributors](https://contrib.rocks/image?repo=benborla/mcp-server-mysql)](https://github.com/benborla/mcp-server-mysql/graphs/contributors)
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/evals.js

@@ -0,0 +1,32 @@
+import { openai } from "@ai-sdk/openai";
+import { grade } from "mcp-evals";
+const mysqlQueryToolEval = {
+    name: 'mysql_query Tool Evaluation',
+    description: 'Evaluates the MySQL query execution functionality',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Please execute the following SQL query and return the results: SELECT * FROM employees WHERE status='ACTIVE';");
+        return JSON.parse(result);
+    }
+};
+const mysqlQueryGenerationEval = {
+    name: 'mysql_query Tool Generation Evaluation',
+    description: 'Evaluates the MySQL query tool for correct SQL generation and execution',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Use the mysql_query tool to select all rows from the 'users' table where isActive = 1. Provide the SQL query in the correct format.");
+        return JSON.parse(result);
+    }
+};
+const mysqlQueryColumnsEval = {
+    name: 'mysql_query Columns Evaluation',
+    description: 'Evaluates the mysql_query tool for column selection',
+    run: async () => {
+        const result = await grade(openai("gpt-4"), "Please provide a SQL query to retrieve the id, name, and email columns for all records in the users table.");
+        return JSON.parse(result);
+    }
+};
+const config = {
+    model: openai("gpt-4"),
+    evals: [mysqlQueryToolEval, mysqlQueryGenerationEval, mysqlQueryColumnsEval]
+};
+export default config;
+export const evals = [mysqlQueryToolEval, mysqlQueryGenerationEval, mysqlQueryColumnsEval];

package/dist/index.js

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { log } from "./src/utils/index.js";
+import { ALLOW_DELETE_OPERATION, ALLOW_DDL_OPERATION, ALLOW_INSERT_OPERATION, ALLOW_UPDATE_OPERATION, SCHEMA_DELETE_PERMISSIONS, SCHEMA_DDL_PERMISSIONS, SCHEMA_INSERT_PERMISSIONS, SCHEMA_UPDATE_PERMISSIONS, isMultiDbMode, mcpConfig as config, MCP_VERSION as version, IS_REMOTE_MCP, REMOTE_SECRET_KEY, PORT, ENABLE_PII_REDACTION, PII_EXTRA_COLUMNS, PII_EXTRA_COLUMN_PATTERNS, } from "./src/config/index.js";
+import { isPIIColumn, DEFAULT_PII_COLUMNS } from "./src/security/redact.js";
+import { safeExit, getPool, executeQuery, executeReadOnlyQuery, poolPromise, } from "./src/db/index.js";
+import express from "express";
+import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
+log("info", `Starting MySQL MCP server v${version}...`);
+const toolVersion = `MySQL MCP Server [v${process.env.npm_package_version}]`;
+let toolDescription = `[${toolVersion}] Run SQL queries against MySQL database`;
+if (isMultiDbMode) {
+    toolDescription += " (Multi-DB mode enabled)";
+}
+if (ALLOW_INSERT_OPERATION ||
+    ALLOW_UPDATE_OPERATION ||
+    ALLOW_DELETE_OPERATION ||
+    ALLOW_DDL_OPERATION) {
+    toolDescription += " with support for:";
+    if (ALLOW_INSERT_OPERATION) {
+        toolDescription += " INSERT,";
+    }
+    if (ALLOW_UPDATE_OPERATION) {
+        toolDescription += " UPDATE,";
+    }
+    if (ALLOW_DELETE_OPERATION) {
+        toolDescription += " DELETE,";
+    }
+    if (ALLOW_DDL_OPERATION) {
+        toolDescription += " DDL,";
+    }
+    toolDescription = toolDescription.replace(/,$/, "") + " and READ operations";
+    if (Object.keys(SCHEMA_INSERT_PERMISSIONS).length > 0 ||
+        Object.keys(SCHEMA_UPDATE_PERMISSIONS).length > 0 ||
+        Object.keys(SCHEMA_DELETE_PERMISSIONS).length > 0 ||
+        Object.keys(SCHEMA_DDL_PERMISSIONS).length > 0) {
+        toolDescription += " (Schema-specific permissions enabled)";
+    }
+}
+else {
+    toolDescription += " (READ-ONLY)";
+}
+const isReadOnly = !(ALLOW_INSERT_OPERATION ||
+    ALLOW_UPDATE_OPERATION ||
+    ALLOW_DELETE_OPERATION ||
+    ALLOW_DDL_OPERATION);
+log("info", "MySQL Configuration:", JSON.stringify({
+    ...(process.env.MYSQL_SOCKET_PATH
+        ? {
+            socketPath: process.env.MYSQL_SOCKET_PATH,
+            connectionType: "Unix Socket",
+        }
+        : {
+            host: process.env.MYSQL_HOST || "127.0.0.1",
+            port: process.env.MYSQL_PORT || "3306",
+            connectionType: "TCP/IP",
+        }),
+    user: config.mysql.user,
+    password: config.mysql.password ? "******" : "not set",
+    database: config.mysql.database || "MULTI_DB_MODE",
+    ssl: process.env.MYSQL_SSL === "true" ? "enabled" : "disabled",
+    sslCA: process.env.MYSQL_SSL_CA || "not set",
+    sslCert: process.env.MYSQL_SSL_CERT || "not set",
+    sslKey: process.env.MYSQL_SSL_KEY || "not set",
+    multiDbMode: isMultiDbMode ? "enabled" : "disabled",
+}, null, 2));
+export const configSchema = z.object({
+    debug: z.boolean().default(false).describe("Enable debug logging"),
+});
+export default function createMcpServer({ sessionId, config, }) {
+    const server = new Server({
+        name: "MySQL MCP Server",
+        version: process.env.npm_package_version || "1.0.0",
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {
+                mysql_query: {
+                    description: toolDescription,
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            sql: {
+                                type: "string",
+                                description: "The SQL query to execute",
+                            },
+                        },
+                        required: ["sql"],
+                    },
+                    annotations: {
+                        readOnlyHint: isReadOnly,
+                        idempotentHint: isReadOnly,
+                        destructiveHint: !isReadOnly,
+                        openWorldHint: false,
+                        title: "MySQL Query",
+                    },
+                },
+            },
+        },
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        try {
+            log("info", "Handling ListResourcesRequest");
+            const connectionInfo = process.env.MYSQL_SOCKET_PATH
+                ? `socket: ${process.env.MYSQL_SOCKET_PATH}`
+                : `host: ${process.env.MYSQL_HOST || "localhost"}, port: ${process.env.MYSQL_PORT || 3306}`;
+            log("info", `Connection info: ${connectionInfo}`);
+            const tablesQuery = `
+      SELECT
+        table_name as name,
+        table_schema as \`database\`,
+        table_comment as description,
+        table_rows as rowCount,
+        data_length as dataSize,
+        index_length as indexSize,
+        create_time as createTime,
+        update_time as updateTime
+      FROM
+        information_schema.tables
+      WHERE
+        table_schema NOT IN ('information_schema', 'mysql', 'performance_schema', 'sys')
+      ORDER BY
+        table_schema, table_name
+    `;
+            const queryResult = (await executeReadOnlyQuery(tablesQuery));
+            const tables = JSON.parse(queryResult.content[0].text);
+            log("info", `Found ${tables.length} tables`);
+            const resources = tables.map((table) => ({
+                uri: `mysql://tables/${table.name}`,
+                name: table.name,
+                title: `${table.database}.${table.name}`,
+                description: table.description ||
+                    `Table ${table.name} in database ${table.database}`,
+                mimeType: "application/json",
+            }));
+            resources.push({
+                uri: "mysql://tables",
+                name: "Tables",
+                title: "MySQL Tables",
+                description: "List of all MySQL tables",
+                mimeType: "application/json",
+            });
+            return { resources };
+        }
+        catch (error) {
+            log("error", "Error in ListResourcesRequest handler:", error);
+            throw error;
+        }
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        try {
+            log("info", "Handling ReadResourceRequest:", request.params.uri);
+            const uriParts = request.params.uri.split("/");
+            const tableName = uriParts.pop();
+            const dbName = uriParts.length > 0 ? uriParts.pop() : null;
+            if (!tableName) {
+                throw new Error(`Invalid resource URI: ${request.params.uri}`);
+            }
+            let columnsQuery = "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = ?";
+            let queryParams = [tableName];
+            if (dbName) {
+                columnsQuery += " AND table_schema = ?";
+                queryParams.push(dbName);
+            }
+            const results = (await executeQuery(columnsQuery, queryParams));
+            const piiColumnList = [...DEFAULT_PII_COLUMNS, ...PII_EXTRA_COLUMNS];
+            const filtered = ENABLE_PII_REDACTION
+                ? results.filter((col) => !isPIIColumn(col.column_name, piiColumnList, PII_EXTRA_COLUMN_PATTERNS))
+                : results;
+            if (ENABLE_PII_REDACTION && filtered.length !== results.length) {
+                log("info", `[redact] hid ${results.length - filtered.length} PII column(s) from schema for table "${tableName}"`);
+            }
+            return {
+                contents: [
+                    {
+                        uri: request.params.uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(filtered, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            log("error", "Error in ReadResourceRequest handler:", error);
+            throw error;
+        }
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        try {
+            log("info", "Handling CallToolRequest:", request.params.name);
+            if (request.params.name !== "mysql_query") {
+                throw new Error(`Unknown tool: ${request.params.name}`);
+            }
+            const sql = request.params.arguments?.sql;
+            return await executeReadOnlyQuery(sql);
+        }
+        catch (err) {
+            const error = err;
+            log("error", "Error in CallToolRequest handler:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: ${error.message}`
+                    }],
+                isError: true
+            };
+        }
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        log("info", "Handling ListToolsRequest");
+        const toolsResponse = {
+            tools: [
+                {
+                    name: "mysql_query",
+                    description: toolDescription,
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            sql: {
+                                type: "string",
+                                description: "The SQL query to execute",
+                            },
+                        },
+                        required: ["sql"],
+                    },
+                    annotations: {
+                        readOnlyHint: isReadOnly,
+                        idempotentHint: isReadOnly,
+                        destructiveHint: !isReadOnly,
+                        openWorldHint: false,
+                        title: "MySQL Query",
+                    },
+                },
+            ],
+        };
+        log("info", "ListToolsRequest response:", JSON.stringify(toolsResponse, null, 2));
+        return toolsResponse;
+    });
+    (async () => {
+        try {
+            log("info", "Attempting to test database connection...");
+            const pool = await getPool();
+            const connection = await pool.getConnection();
+            log("info", "Database connection test successful");
+            connection.release();
+        }
+        catch (error) {
+            log("error", "Fatal error during server startup:", error);
+            safeExit(1);
+        }
+    })();
+    const shutdown = async (signal) => {
+        log("error", `Received ${signal}. Shutting down...`);
+        try {
+            if (poolPromise) {
+                const pool = await poolPromise;
+                await pool.end();
+            }
+        }
+        catch (err) {
+            log("error", "Error closing pool:", err);
+            throw err;
+        }
+    };
+    process.on("SIGINT", async () => {
+        try {
+            await shutdown("SIGINT");
+            process.exit(0);
+        }
+        catch (err) {
+            log("error", "Error during SIGINT shutdown:", err);
+            safeExit(1);
+        }
+    });
+    process.on("SIGTERM", async () => {
+        try {
+            await shutdown("SIGTERM");
+            process.exit(0);
+        }
+        catch (err) {
+            log("error", "Error during SIGTERM shutdown:", err);
+            safeExit(1);
+        }
+    });
+    process.on("uncaughtException", (error) => {
+        log("error", "Uncaught exception:", error);
+        safeExit(1);
+    });
+    process.on("unhandledRejection", (reason, promise) => {
+        log("error", "Unhandled rejection at:", promise, "reason:", reason);
+        safeExit(1);
+    });
+    return server;
+}
+const isMainModule = () => {
+    if (typeof require !== 'undefined' && require.main === module) {
+        return true;
+    }
+    if (typeof import.meta !== 'undefined' && import.meta.url && process.argv[1]) {
+        const currentModulePath = fileURLToPath(import.meta.url);
+        const mainScriptPath = realpathSync(process.argv[1]);
+        return currentModulePath === mainScriptPath;
+    }
+    return false;
+};
+if (isMainModule()) {
+    log("info", "Running in standalone mode");
+    (async () => {
+        try {
+            const mcpServer = createMcpServer({ config: { debug: false } });
+            if (IS_REMOTE_MCP && REMOTE_SECRET_KEY?.length) {
+                const app = express();
+                app.use(express.json());
+                app.post("/mcp", async (req, res) => {
+                    if (!req.get("Authorization") ||
+                        !req.get("Authorization")?.startsWith("Bearer ") ||
+                        !req.get("Authorization")?.endsWith(REMOTE_SECRET_KEY)) {
+                        console.error("Missing or invalid Authorization header");
+                        res.status(401).json({
+                            jsonrpc: "2.0",
+                            error: {
+                                code: -32603,
+                                message: "Missing or invalid Authorization header",
+                            },
+                            id: null,
+                        });
+                        return;
+                    }
+                    try {
+                        const server = createMcpServer({ config: { debug: false } });
+                        const transport = new StreamableHTTPServerTransport({
+                            sessionIdGenerator: undefined,
+                        });
+                        res.on("close", () => {
+                            log("info", "Request closed");
+                            transport.close();
+                            server.close();
+                        });
+                        await server.connect(transport);
+                        await transport.handleRequest(req, res, req.body);
+                    }
+                    catch (error) {
+                        log("error", "Error handling MCP request:", error);
+                        if (!res.headersSent) {
+                            res.status(500).json({
+                                jsonrpc: "2.0",
+                                error: {
+                                    code: -32603,
+                                    message: error.message,
+                                },
+                                id: null,
+                            });
+                        }
+                    }
+                });
+                app.get("/mcp", async (req, res) => {
+                    console.log("Received GET MCP request");
+                    res.writeHead(405).end(JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: {
+                            code: -32000,
+                            message: "Method not allowed.",
+                        },
+                        id: null,
+                    }));
+                });
+                app.delete("/mcp", async (req, res) => {
+                    console.log("Received DELETE MCP request");
+                    res.writeHead(405).end(JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: {
+                            code: -32000,
+                            message: "Method not allowed.",
+                        },
+                        id: null,
+                    }));
+                });
+                app.listen(PORT, (error) => {
+                    if (error) {
+                        console.error("Failed to start server:", error);
+                        process.exit(1);
+                    }
+                    console.log(`MCP Stateless Streamable HTTP Server listening on port ${PORT}`);
+                });
+            }
+            else {
+                const transport = new StdioServerTransport();
+                await mcpServer.connect(transport);
+                log("info", "Server started and listening on stdio");
+            }
+        }
+        catch (error) {
+            log("error", "Server error:", error);
+            safeExit(1);
+        }
+    })();
+}