@imrieul/mysql-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,686 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+function parseConnectionString(connStr) {
+  let url;
+  try {
+    url = new URL(connStr);
+  } catch {
+    throw new Error(`Invalid connection string: ${connStr}`);
+  }
+  if (url.protocol !== "mysql:") {
+    throw new Error(`Expected mysql:// protocol, got ${url.protocol}`);
+  }
+  const database = url.pathname.slice(1) || void 0;
+  return {
+    host: url.hostname,
+    port: url.port ? parseInt(url.port, 10) : 3306,
+    user: decodeURIComponent(url.username),
+    password: decodeURIComponent(url.password),
+    database
+  };
+}
+function parseEnvConfig(env) {
+  const host = env.MYSQL_HOST;
+  const user = env.MYSQL_USER;
+  const password = env.MYSQL_PASSWORD;
+  if (!host) throw new Error("Missing required environment variable: MYSQL_HOST");
+  if (!user) throw new Error("Missing required environment variable: MYSQL_USER");
+  if (!password) throw new Error("Missing required environment variable: MYSQL_PASSWORD");
+  return {
+    host,
+    port: env.MYSQL_PORT ? parseInt(env.MYSQL_PORT, 10) : 3306,
+    user,
+    password,
+    database: env.MYSQL_DATABASE || void 0
+  };
+}
+function parseArgs(argv) {
+  let connectionString;
+  let readonly = false;
+  for (const arg of argv) {
+    if (arg === "--readonly") {
+      readonly = true;
+    } else if (arg.startsWith("mysql://")) {
+      connectionString = arg;
+    }
+  }
+  return { connectionString, readonly };
+}
+function resolveConfig(argv, env = process.env) {
+  const args = parseArgs(argv);
+  const mysql2 = args.connectionString ? parseConnectionString(args.connectionString) : parseEnvConfig(env);
+  const readonly = args.readonly || env.MYSQL_READONLY === "true";
+  const maxRows = env.MYSQL_MAX_ROWS ? parseInt(env.MYSQL_MAX_ROWS, 10) : 100;
+  const queryTimeout = env.MYSQL_QUERY_TIMEOUT !== void 0 ? parseInt(env.MYSQL_QUERY_TIMEOUT, 10) : 3e4;
+  const ssl = env.MYSQL_SSL === "true";
+  return { mysql: mysql2, readonly, maxRows, queryTimeout, ssl };
+}
+
+// src/connection.ts
+import mysql from "mysql2/promise";
+function createConnectionManager(config, options) {
+  const poolOptions = {
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    database: config.database,
+    connectionLimit: 5,
+    waitForConnections: true
+  };
+  if (options?.ssl) {
+    poolOptions.ssl = { rejectUnauthorized: true };
+  }
+  const pool = mysql.createPool(poolOptions);
+  return {
+    getPool() {
+      return pool;
+    },
+    async close() {
+      await pool.end();
+    }
+  };
+}
+
+// src/query-runner.ts
+var QueryTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Query timeout after ${timeoutMs}ms`);
+    this.name = "QueryTimeoutError";
+  }
+};
+function withTimeout(promise, timeoutMs) {
+  if (timeoutMs <= 0) return promise;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new QueryTimeoutError(timeoutMs)), timeoutMs))
+  ]);
+}
+function createQueryRunner(pool, options) {
+  const { readonly, queryTimeout } = options;
+  return {
+    async query(sql) {
+      if (!readonly) {
+        return withTimeout(pool.query(sql), queryTimeout);
+      }
+      const conn = await pool.getConnection();
+      try {
+        await conn.query("SET SESSION TRANSACTION READ ONLY");
+        await conn.beginTransaction();
+        const result = await withTimeout(conn.query(sql), queryTimeout);
+        await conn.rollback();
+        return result;
+      } catch (error) {
+        try {
+          await conn.rollback();
+        } catch {
+        }
+        throw error;
+      } finally {
+        conn.release();
+      }
+    },
+    async withConnection(fn) {
+      const conn = await pool.getConnection();
+      try {
+        if (readonly) {
+          await conn.query("SET SESSION TRANSACTION READ ONLY");
+          await conn.beginTransaction();
+        }
+        const queryFn = (sql) => withTimeout(conn.query(sql), queryTimeout);
+        const result = await fn(queryFn);
+        if (readonly) {
+          await conn.rollback();
+        }
+        return result;
+      } catch (error) {
+        if (readonly) {
+          try {
+            await conn.rollback();
+          } catch {
+          }
+        }
+        throw error;
+      } finally {
+        conn.release();
+      }
+    }
+  };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/query.ts
+import { z } from "zod";
+
+// src/tools/error-hint.ts
+var HINTS = [
+  [/Table '.*' doesn't exist/i, "Hint: use list_tables to check available tables."],
+  [/Unknown column/i, "Hint: use describe_table to check column names."],
+  [/Unknown database/i, "Hint: use list_databases to check available databases."],
+  [/Access denied/i, "Hint: check database user permissions."],
+  [/ECONNREFUSED|ETIMEDOUT|ENOTFOUND/i, "Hint: check MYSQL_HOST and MYSQL_PORT settings."],
+  [/ER_PARSE_ERROR/i, "Hint: check SQL syntax."],
+  [/Query timeout/i, "Hint: increase MYSQL_QUERY_TIMEOUT or optimize the query."]
+];
+function formatError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = HINTS.find(([pattern]) => pattern.test(message));
+  return hint ? `Error: ${message}
+${hint[1]}` : `Error: ${message}`;
+}
+
+// src/tools/query.ts
+var queryToolName = "query";
+var queryToolConfig = {
+  title: "Query",
+  description: "Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN).",
+  inputSchema: {
+    sql: z.string().describe(
+      "The SQL query to execute. Only SELECT, SHOW, DESCRIBE, EXPLAIN, and WITH (CTE) statements are allowed."
+    )
+  }
+};
+var ALLOWED_PREFIXES = ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN", "WITH"];
+var LIMIT_PREFIXES = ["SELECT", "WITH"];
+function needsLimit(normalized) {
+  if (!LIMIT_PREFIXES.some((p) => normalized.startsWith(p))) return false;
+  return !/\bLIMIT\b/i.test(normalized);
+}
+function createQueryHandler(runner, maxRows) {
+  return async ({ sql }) => {
+    const normalized = sql.trim().toUpperCase();
+    const isAllowed = ALLOWED_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+    if (!isAllowed) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: 'Error: Only SELECT, SHOW, DESCRIBE, EXPLAIN queries are allowed. Use the "execute" tool for data modification.'
+          }
+        ]
+      };
+    }
+    try {
+      const finalSql = needsLimit(normalized) ? `${sql.trim()} LIMIT ${maxRows}` : sql;
+      const [rows] = await runner.query(finalSql);
+      const arr = rows;
+      if (arr.length === 0) {
+        return { content: [{ type: "text", text: "(empty)" }] };
+      }
+      const cols = Object.keys(arr[0]);
+      const data = arr.map((r) => cols.map((c) => r[c]));
+      return {
+        content: [{ type: "text", text: JSON.stringify({ columns: cols, rows: data }) }]
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/execute.ts
+import { z as z2 } from "zod";
+var executeToolName = "execute";
+var executeToolConfig = {
+  title: "Execute",
+  description: "Execute a data modification SQL statement (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.).",
+  inputSchema: {
+    sql: z2.string().describe('The SQL statement to execute. SELECT statements are not allowed here; use the "query" tool instead.')
+  }
+};
+function createExecuteHandler(runner, isReadonly) {
+  return async ({ sql }) => {
+    if (isReadonly) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: "Error: Server is in read-only mode. Data modification is not allowed."
+          }
+        ]
+      };
+    }
+    const normalized = sql.trim().toUpperCase();
+    if (normalized.startsWith("SELECT") || normalized.startsWith("WITH")) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: 'Error: Use the "query" tool for SELECT statements.'
+          }
+        ]
+      };
+    }
+    try {
+      const [result] = await runner.query(sql);
+      const r = result;
+      return {
+        content: [
+          { type: "text", text: `affectedRows: ${r.affectedRows}, changedRows: ${r.changedRows ?? 0}` }
+        ]
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/list-databases.ts
+var listDatabasesToolName = "list_databases";
+var listDatabasesToolConfig = {
+  title: "List Databases",
+  description: "List all databases on the MySQL server."
+};
+function createListDatabasesHandler(runner) {
+  return async () => {
+    try {
+      const [rows] = await runner.query("SHOW DATABASES");
+      const databases = rows.map((r) => Object.values(r)[0]);
+      return {
+        content: [{ type: "text", text: JSON.stringify(databases) }]
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/list-tables.ts
+import { z as z3 } from "zod";
+
+// src/tools/resolve-database.ts
+async function resolveDatabase(query, database) {
+  if (database) return database;
+  const [rows] = await query("SELECT DATABASE() AS db");
+  const db = rows[0]?.db;
+  return typeof db === "string" ? db : null;
+}
+
+// src/tools/sql-escape.ts
+function escapeStringValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "''");
+}
+function quoteStringValue(value) {
+  return `'${escapeStringValue(value)}'`;
+}
+
+// src/tools/list-tables.ts
+var listTablesToolName = "list_tables";
+var listTablesToolConfig = {
+  title: "List Tables",
+  description: "List all tables in the specified database (or the current database if not specified).",
+  inputSchema: {
+    database: z3.string().optional().describe("Database name. Uses the current database if omitted.")
+  }
+};
+function createListTablesHandler(runner) {
+  return async ({ database }) => {
+    try {
+      return await runner.withConnection(async (query) => {
+        const db = await resolveDatabase(query, database);
+        if (!db) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "Error: No database selected. Specify a database name or set MYSQL_DATABASE."
+              }
+            ]
+          };
+        }
+        const sql = `SELECT TABLE_NAME, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA = ${quoteStringValue(db)} ORDER BY TABLE_NAME`;
+        const [rows] = await query(sql);
+        const lines = rows.map((r) => {
+          const comment = r.TABLE_COMMENT;
+          return comment ? `${r.TABLE_NAME} -- ${comment}` : r.TABLE_NAME;
+        });
+        return {
+          content: [{ type: "text", text: lines.join("\n") }]
+        };
+      });
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/describe-table.ts
+import { z as z4 } from "zod";
+
+// src/tools/format-column.ts
+function formatColumn(col) {
+  let result = `${col.name} ${col.type}`;
+  if (!col.nullable) result += " NOT NULL";
+  if (col.key === "PRI") result += " PK";
+  else if (col.key === "UNI") result += " UNIQUE";
+  else if (col.key === "MUL") result += " INDEX";
+  if (col.defaultValue != null) result += ` DEFAULT ${col.defaultValue}`;
+  if (col.extra) result += ` ${col.extra}`;
+  if (col.comment) result += ` -- ${col.comment}`;
+  return result;
+}
+
+// src/tools/describe-table.ts
+var describeTableToolName = "describe_table";
+var describeTableToolConfig = {
+  title: "Describe Table",
+  description: "Show the schema/structure of a table, including column names, types, constraints, and comments.",
+  inputSchema: {
+    table: z4.string().describe("Table name to describe."),
+    database: z4.string().optional().describe("Database name. Uses the current database if omitted.")
+  }
+};
+function createDescribeTableHandler(runner) {
+  return async ({ table, database }) => {
+    try {
+      return await runner.withConnection(async (query) => {
+        const db = await resolveDatabase(query, database);
+        if (!db) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "Error: No database selected. Specify a database name or set MYSQL_DATABASE."
+              }
+            ]
+          };
+        }
+        const sql = `SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ${quoteStringValue(db)} AND TABLE_NAME = ${quoteStringValue(table)} ORDER BY ORDINAL_POSITION`;
+        const [rows] = await query(sql);
+        const typedRows = rows;
+        if (typedRows.length === 0) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Error: Table '${table}' doesn't exist in database '${db}'.
+Hint: use list_tables to check available tables.`
+              }
+            ]
+          };
+        }
+        const columns = typedRows.map(
+          (r) => formatColumn({
+            name: String(r.COLUMN_NAME),
+            type: String(r.COLUMN_TYPE),
+            nullable: r.IS_NULLABLE === "YES",
+            key: String(r.COLUMN_KEY ?? ""),
+            defaultValue: r.COLUMN_DEFAULT,
+            extra: String(r.EXTRA ?? ""),
+            comment: String(r.COLUMN_COMMENT ?? "")
+          })
+        );
+        return {
+          content: [{ type: "text", text: `${table}:
+${columns.join("\n")}` }]
+        };
+      });
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/describe-all-tables.ts
+import { z as z5 } from "zod";
+var describeAllTablesToolName = "describe_all_tables";
+var describeAllTablesToolConfig = {
+  title: "Describe All Tables",
+  description: "Show the schema of all tables at once. Much more efficient than calling describe_table for each table individually.",
+  inputSchema: {
+    database: z5.string().optional().describe("Database name. Uses the current database if omitted.")
+  }
+};
+function createDescribeAllTablesHandler(runner) {
+  return async ({ database }) => {
+    try {
+      return await runner.withConnection(async (query) => {
+        const db = await resolveDatabase(query, database);
+        if (!db) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "Error: No database selected. Specify a database name or set MYSQL_DATABASE."
+              }
+            ]
+          };
+        }
+        const sql = `SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ${quoteStringValue(db)} ORDER BY TABLE_NAME, ORDINAL_POSITION`;
+        const [rows] = await query(sql);
+        const typedRows = rows;
+        if (typedRows.length === 0) {
+          return { content: [{ type: "text", text: "(no tables)" }] };
+        }
+        const tableMap = /* @__PURE__ */ new Map();
+        for (const r of typedRows) {
+          const tableName = String(r.TABLE_NAME);
+          const line = formatColumn({
+            name: String(r.COLUMN_NAME),
+            type: String(r.COLUMN_TYPE),
+            nullable: r.IS_NULLABLE === "YES",
+            key: String(r.COLUMN_KEY ?? ""),
+            defaultValue: r.COLUMN_DEFAULT,
+            extra: String(r.EXTRA ?? ""),
+            comment: String(r.COLUMN_COMMENT ?? "")
+          });
+          if (!tableMap.has(tableName)) {
+            tableMap.set(tableName, []);
+          }
+          tableMap.get(tableName).push(line);
+        }
+        const parts = Array.from(tableMap.entries()).map(([table, lines]) => `${table}:
+${lines.join("\n")}`);
+        return {
+          content: [{ type: "text", text: parts.join("\n\n") }]
+        };
+      });
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/add-comment.ts
+import { z as z6 } from "zod";
+var addCommentToolName = "add_comment";
+var addCommentToolConfig = {
+  title: "Add Comment",
+  description: "Safely add a comment to a table or column. This tool only modifies comments \u2014 it cannot alter table structure, column types, or data.",
+  inputSchema: {
+    table: z6.string().describe("Table name."),
+    column: z6.string().optional().describe("Column name. If omitted, sets a table-level comment."),
+    comment: z6.string().describe("Comment text to set."),
+    database: z6.string().optional().describe("Database name. Uses the current database if omitted.")
+  }
+};
+function createAddCommentHandler(runner, isReadonly) {
+  return async ({
+    table,
+    column,
+    comment,
+    database
+  }) => {
+    if (isReadonly) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: "Error: Server is in read-only mode. Modifying comments is not allowed."
+          }
+        ]
+      };
+    }
+    try {
+      return await runner.withConnection(async (query) => {
+        const db = await resolveDatabase(query, database);
+        if (!db) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "Error: No database selected. Specify a database name or set MYSQL_DATABASE."
+              }
+            ]
+          };
+        }
+        const fullName = `\`${db}\`.\`${table}\``;
+        const escapedComment = escapeStringValue(comment);
+        if (!column) {
+          const sql = `ALTER TABLE ${fullName} COMMENT = '${escapedComment}'`;
+          await query(sql);
+          return {
+            content: [{ type: "text", text: `Table comment updated: ${table}` }]
+          };
+        }
+        const colSql = `SELECT COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, EXTRA FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ${quoteStringValue(db)} AND TABLE_NAME = ${quoteStringValue(table)} AND COLUMN_NAME = ${quoteStringValue(column)}`;
+        const [rows] = await query(colSql);
+        const colInfo = rows[0];
+        if (!colInfo) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Error: Column '${column}' doesn't exist in table '${table}'.
+Hint: use describe_table to check available columns.`
+              }
+            ]
+          };
+        }
+        let modifySql = `ALTER TABLE ${fullName} MODIFY COLUMN \`${column}\` ${colInfo.COLUMN_TYPE}`;
+        if (colInfo.IS_NULLABLE === "NO") modifySql += " NOT NULL";
+        if (colInfo.COLUMN_DEFAULT != null)
+          modifySql += ` DEFAULT '${escapeStringValue(String(colInfo.COLUMN_DEFAULT))}'`;
+        if (colInfo.EXTRA) modifySql += ` ${colInfo.EXTRA}`;
+        modifySql += ` COMMENT '${escapedComment}'`;
+        await query(modifySql);
+        return {
+          content: [{ type: "text", text: `Column comment updated: ${table}.${column}` }]
+        };
+      });
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: formatError(error) }]
+      };
+    }
+  };
+}
+
+// src/tools/index.ts
+function registerAllTools(server, runner, readonly, maxRows) {
+  server.tool(
+    queryToolName,
+    queryToolConfig.description,
+    queryToolConfig.inputSchema,
+    createQueryHandler(runner, maxRows)
+  );
+  server.tool(
+    executeToolName,
+    executeToolConfig.description,
+    executeToolConfig.inputSchema,
+    createExecuteHandler(runner, readonly)
+  );
+  server.tool(listDatabasesToolName, listDatabasesToolConfig.description, createListDatabasesHandler(runner));
+  server.tool(
+    listTablesToolName,
+    listTablesToolConfig.description,
+    listTablesToolConfig.inputSchema,
+    createListTablesHandler(runner)
+  );
+  server.tool(
+    describeTableToolName,
+    describeTableToolConfig.description,
+    describeTableToolConfig.inputSchema,
+    createDescribeTableHandler(runner)
+  );
+  server.tool(
+    describeAllTablesToolName,
+    describeAllTablesToolConfig.description,
+    describeAllTablesToolConfig.inputSchema,
+    createDescribeAllTablesHandler(runner)
+  );
+  server.tool(
+    addCommentToolName,
+    addCommentToolConfig.description,
+    addCommentToolConfig.inputSchema,
+    createAddCommentHandler(runner, readonly)
+  );
+}
+
+// src/server.ts
+function createMcpServer(runner, readonly, maxRows) {
+  const server = new McpServer({
+    name: "@imrieul/mysql-mcp-server",
+    version: "0.1.0"
+  });
+  registerAllTools(server, runner, readonly, maxRows);
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const config = resolveConfig(process.argv.slice(2));
+  const connectionManager = createConnectionManager(config.mysql, { ssl: config.ssl });
+  const runner = createQueryRunner(connectionManager.getPool(), {
+    readonly: config.readonly,
+    queryTimeout: config.queryTimeout
+  });
+  const server = createMcpServer(runner, config.readonly, config.maxRows);
+  const transport = new StdioServerTransport();
+  process.on("SIGINT", async () => {
+    await server.close();
+    await connectionManager.close();
+    process.exit(0);
+  });
+  process.on("SIGTERM", async () => {
+    await server.close();
+    await connectionManager.close();
+    process.exit(0);
+  });
+  console.error("MySQL MCP Server starting...");
+  console.error(`Readonly mode: ${config.readonly}`);
+  console.error(`Query timeout: ${config.queryTimeout}ms`);
+  console.error(`SSL: ${config.ssl}`);
+  await server.connect(transport);
+  console.error("MySQL MCP Server connected via stdio");
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map