@arvoretech/mysql-mcp 1.0.0

package/src/index.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { MySQLMCPServer } from "./server.js";
+
+async function main(): Promise<void> {
+  try {
+    const server = MySQLMCPServer.fromEnvironment();
+    server.setupGracefulShutdown();
+    await server.start();
+  } catch (error) {
+    console.error("Failed to start MySQL MCP Server:", error);
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  });
+}
+
+export { MySQLMCPServer } from "./server.js";
+export { MySQLConnection } from "./database.js";
+export { MySQLMCPTools } from "./tools.js";
+export * from "./types.js";

package/src/server.ts

@@ -0,0 +1,157 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { MySQLConnection } from "./database.js";
+import { MySQLMCPTools } from "./tools.js";
+import {
+  MySQLConfig,
+  MySQLConfigSchema,
+  ReadQueryParams,
+  DescribeTableParams,
+  ReadQueryParamsSchema,
+  DescribeTableParamsSchema,
+  MySQLMCPError,
+} from "./types.js";
+
+export class MySQLMCPServer {
+  private server: McpServer;
+  private db: MySQLConnection;
+  private tools: MySQLMCPTools;
+
+  constructor(config: MySQLConfig) {
+    this.server = new McpServer({
+      name: "mysql-mcp-server",
+      version: "1.0.0",
+    });
+
+    this.db = new MySQLConnection(config);
+    this.tools = new MySQLMCPTools(this.db);
+
+    this.setupTools();
+  }
+
+  static fromEnvironment(): MySQLMCPServer {
+    const config = MySQLConfigSchema.parse({
+      host: process.env.MYSQL_HOST || "localhost",
+      port: parseInt(process.env.MYSQL_PORT || "3306", 10),
+      user: process.env.MYSQL_USER || "root",
+      password: process.env.MYSQL_PASSWORD || "",
+      database: process.env.MYSQL_DATABASE || "test",
+      ssl: process.env.MYSQL_SSL === "true",
+      connectionTimeout: parseInt(
+        process.env.MYSQL_CONNECTION_TIMEOUT || "30000",
+        10
+      ),
+    });
+
+    return new MySQLMCPServer(config);
+  }
+
+  private setupTools(): void {
+    this.server.registerTool(
+      "read_query",
+      {
+        title: "Execute Read Query",
+        description: "Execute a SELECT query on the MySQL database",
+        inputSchema: { query: ReadQueryParamsSchema.shape.query },
+      },
+      async (params) => {
+        return this.tools.readQuery(params as ReadQueryParams);
+      }
+    );
+
+    this.server.registerTool(
+      "list_tables",
+      {
+        title: "List Tables",
+        description: "List all tables in the current database",
+        inputSchema: {},
+      },
+      async () => {
+        return this.tools.listTables();
+      }
+    );
+
+    this.server.registerTool(
+      "describe_table",
+      {
+        title: "Describe Table",
+        description:
+          "Get the structure and schema information of a specific table",
+        inputSchema: { tableName: DescribeTableParamsSchema.shape.tableName },
+      },
+      async (params) => {
+        return this.tools.describeTable(params as DescribeTableParams);
+      }
+    );
+
+    this.server.registerTool(
+      "show_databases",
+      {
+        title: "Show Databases",
+        description: "List all available databases on the MySQL server",
+        inputSchema: {},
+      },
+      async () => {
+        return this.tools.showDatabases();
+      }
+    );
+  }
+
+  async start(): Promise<void> {
+    try {
+      await this.db.connect();
+
+      const isConnected = await this.db.testConnection();
+      if (!isConnected) {
+        throw new MySQLMCPError(
+          "Database connection test failed",
+          "CONNECTION_TEST_FAILED"
+        );
+      }
+
+      const transport = new StdioServerTransport();
+      await this.server.connect(transport);
+
+      console.error("MySQL MCP Server started successfully");
+    } catch (error) {
+      console.error(
+        "Failed to start MySQL MCP Server:",
+        error instanceof Error ? error.message : error
+      );
+      await this.cleanup();
+      process.exit(1);
+    }
+  }
+
+  async cleanup(): Promise<void> {
+    try {
+      await this.db.disconnect();
+    } catch (error) {
+      console.error(
+        "Error during cleanup:",
+        error instanceof Error ? error.message : error
+      );
+    }
+  }
+
+  setupGracefulShutdown(): void {
+    const shutdown = async (signal: string): Promise<void> => {
+      console.error(`Received ${signal}, shutting down gracefully...`);
+      await this.cleanup();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("uncaughtException", async (error) => {
+      console.error("Uncaught exception:", error);
+      await this.cleanup();
+      process.exit(1);
+    });
+    process.on("unhandledRejection", async (reason) => {
+      console.error("Unhandled rejection:", reason);
+      await this.cleanup();
+      process.exit(1);
+    });
+  }
+}

package/src/tools.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MySQLMCPTools } from "./tools.js";
+import { MySQLConnection } from "./database.js";
+import { MySQLMCPError } from "./types.js";
+
+vi.mock("./database.js", () => ({
+  MySQLConnection: vi.fn(),
+}));
+
+describe("MySQLMCPTools", () => {
+  let tools: MySQLMCPTools;
+  let mockDb: {
+    executeQuery: ReturnType<typeof vi.fn>;
+    listTables: ReturnType<typeof vi.fn>;
+    describeTable: ReturnType<typeof vi.fn>;
+    showDatabases: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = {
+      executeQuery: vi.fn(),
+      listTables: vi.fn(),
+      describeTable: vi.fn(),
+      showDatabases: vi.fn(),
+    };
+    tools = new MySQLMCPTools(mockDb as unknown as MySQLConnection);
+  });
+
+  describe("readQuery", () => {
+    it("should execute query and return formatted result", async () => {
+      mockDb.executeQuery.mockResolvedValue({
+        data: [
+          { id: 1, name: "John" },
+          { id: 2, name: "Jane" },
+        ],
+        rowCount: 2,
+        executionTime: 15,
+      });
+
+      const result = await tools.readQuery({ query: "SELECT * FROM users" });
+
+      expect(result.content).toHaveLength(1);
+      expect(result.content[0].type).toBe("text");
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.query).toBe("SELECT * FROM users");
+      expect(parsed.rowCount).toBe(2);
+      expect(parsed.executionTime).toBe("15ms");
+      expect(parsed.data).toHaveLength(2);
+    });
+
+    it("should return error result when query fails", async () => {
+      mockDb.executeQuery.mockRejectedValue(
+        new MySQLMCPError("Syntax error", "ER_PARSE_ERROR", "42000")
+      );
+
+      const result = await tools.readQuery({ query: "SELECT * FROM invalid" });
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error).toContain("MySQL Error");
+      expect(parsed.query).toBe("SELECT * FROM invalid");
+    });
+
+    it("should handle unexpected errors", async () => {
+      mockDb.executeQuery.mockRejectedValue(new Error("Unexpected error"));
+
+      const result = await tools.readQuery({ query: "SELECT * FROM users" });
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error).toContain("Unexpected error");
+    });
+
+    it("should handle empty result sets", async () => {
+      mockDb.executeQuery.mockResolvedValue({
+        data: [],
+        rowCount: 0,
+        executionTime: 5,
+      });
+
+      const result = await tools.readQuery({
+        query: "SELECT * FROM empty_table",
+      });
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.rowCount).toBe(0);
+      expect(parsed.data).toEqual([]);
+    });
+  });
+
+  describe("listTables", () => {
+    it("should return list of tables", async () => {
+      mockDb.listTables.mockResolvedValue([
+        {
+          TABLE_NAME: "users",
+          TABLE_TYPE: "BASE TABLE",
+          TABLE_SCHEMA: "testdb",
+        },
+        {
+          TABLE_NAME: "posts",
+          TABLE_TYPE: "BASE TABLE",
+          TABLE_SCHEMA: "testdb",
+        },
+        { TABLE_NAME: "user_view", TABLE_TYPE: "VIEW", TABLE_SCHEMA: "testdb" },
+      ]);
+
+      const result = await tools.listTables();
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.tableCount).toBe(3);
+      expect(parsed.tables).toHaveLength(3);
+      expect(parsed.tables[0].name).toBe("users");
+      expect(parsed.tables[0].type).toBe("BASE TABLE");
+      expect(parsed.tables[0].schema).toBe("testdb");
+    });
+
+    it("should handle empty table list", async () => {
+      mockDb.listTables.mockResolvedValue([]);
+
+      const result = await tools.listTables();
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.tableCount).toBe(0);
+      expect(parsed.tables).toEqual([]);
+    });
+
+    it("should return error result when listing fails", async () => {
+      mockDb.listTables.mockRejectedValue(
+        new MySQLMCPError("Access denied", "ER_ACCESS_DENIED")
+      );
+
+      const result = await tools.listTables();
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error).toContain("MySQL Error");
+    });
+  });
+
+  describe("describeTable", () => {
+    it("should return table structure", async () => {
+      mockDb.describeTable.mockResolvedValue([
+        {
+          COLUMN_NAME: "id",
+          DATA_TYPE: "int",
+          IS_NULLABLE: "NO",
+          COLUMN_DEFAULT: null,
+          COLUMN_KEY: "PRI",
+          EXTRA: "auto_increment",
+          COLUMN_COMMENT: "Primary key",
+        },
+        {
+          COLUMN_NAME: "email",
+          DATA_TYPE: "varchar",
+          IS_NULLABLE: "NO",
+          COLUMN_DEFAULT: null,
+          COLUMN_KEY: "UNI",
+          EXTRA: "",
+          COLUMN_COMMENT: "User email",
+        },
+        {
+          COLUMN_NAME: "created_at",
+          DATA_TYPE: "timestamp",
+          IS_NULLABLE: "YES",
+          COLUMN_DEFAULT: "CURRENT_TIMESTAMP",
+          COLUMN_KEY: "",
+          EXTRA: "DEFAULT_GENERATED",
+          COLUMN_COMMENT: "",
+        },
+      ]);
+
+      const result = await tools.describeTable({ tableName: "users" });
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.tableName).toBe("users");
+      expect(parsed.columnCount).toBe(3);
+      expect(parsed.columns).toHaveLength(3);
+      expect(parsed.columns[0].name).toBe("id");
+      expect(parsed.columns[0].type).toBe("int");
+      expect(parsed.columns[0].nullable).toBe(false);
+      expect(parsed.columns[0].key).toBe("PRI");
+      expect(parsed.columns[1].nullable).toBe(false);
+      expect(parsed.columns[2].nullable).toBe(true);
+    });
+
+    it("should return error result when table not found", async () => {
+      mockDb.describeTable.mockRejectedValue(
+        new MySQLMCPError("Table doesn't exist", "ER_NO_SUCH_TABLE")
+      );
+
+      const result = await tools.describeTable({ tableName: "non_existent" });
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error).toContain("MySQL Error");
+      expect(parsed.tableName).toBe("non_existent");
+    });
+  });
+
+  describe("showDatabases", () => {
+    it("should return list of databases", async () => {
+      mockDb.showDatabases.mockResolvedValue([
+        { Database: "information_schema" },
+        { Database: "testdb" },
+        { Database: "production" },
+      ]);
+
+      const result = await tools.showDatabases();
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.databaseCount).toBe(3);
+      expect(parsed.databases).toEqual([
+        "information_schema",
+        "testdb",
+        "production",
+      ]);
+    });
+
+    it("should return error result when listing databases fails", async () => {
+      mockDb.showDatabases.mockRejectedValue(
+        new MySQLMCPError("Access denied", "ER_ACCESS_DENIED")
+      );
+
+      const result = await tools.showDatabases();
+
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.error).toContain("MySQL Error");
+    });
+  });
+});

package/src/tools.ts

@@ -0,0 +1,212 @@
+import { MySQLConnection } from "./database.js";
+import {
+  ReadQueryParams,
+  DescribeTableParams,
+  McpToolResult,
+  MySQLMCPError,
+} from "./types.js";
+
+export class MySQLMCPTools {
+  constructor(private db: MySQLConnection) {}
+
+  async readQuery(params: ReadQueryParams): Promise<McpToolResult> {
+    try {
+      const result = await this.db.executeQuery(params.query);
+
+      const resultText = JSON.stringify(
+        {
+          query: params.query,
+          rowCount: result.rowCount,
+          executionTime: `${result.executionTime}ms`,
+          data: result.data,
+        },
+        null,
+        2
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: resultText,
+          },
+        ],
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof MySQLMCPError
+          ? `MySQL Error: ${error.message}`
+          : `Unexpected error: ${
+              error instanceof Error ? error.message : "Unknown error"
+            }`;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: errorMessage,
+                query: params.query,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+
+  async listTables(): Promise<McpToolResult> {
+    try {
+      const tables = await this.db.listTables();
+
+      const resultText = JSON.stringify(
+        {
+          tableCount: tables.length,
+          tables: tables.map((table) => ({
+            name: table.TABLE_NAME,
+            type: table.TABLE_TYPE,
+            schema: table.TABLE_SCHEMA,
+          })),
+        },
+        null,
+        2
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: resultText,
+          },
+        ],
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof MySQLMCPError
+          ? `MySQL Error: ${error.message}`
+          : `Unexpected error: ${
+              error instanceof Error ? error.message : "Unknown error"
+            }`;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: errorMessage,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+
+  async describeTable(params: DescribeTableParams): Promise<McpToolResult> {
+    try {
+      const columns = await this.db.describeTable(params.tableName);
+
+      const resultText = JSON.stringify(
+        {
+          tableName: params.tableName,
+          columnCount: columns.length,
+          columns: columns.map((column) => ({
+            name: column.COLUMN_NAME,
+            type: column.DATA_TYPE,
+            nullable: column.IS_NULLABLE === "YES",
+            default: column.COLUMN_DEFAULT,
+            key: column.COLUMN_KEY,
+            extra: column.EXTRA,
+            comment: column.COLUMN_COMMENT,
+          })),
+        },
+        null,
+        2
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: resultText,
+          },
+        ],
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof MySQLMCPError
+          ? `MySQL Error: ${error.message}`
+          : `Unexpected error: ${
+              error instanceof Error ? error.message : "Unknown error"
+            }`;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: errorMessage,
+                tableName: params.tableName,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+
+  async showDatabases(): Promise<McpToolResult> {
+    try {
+      const databases = await this.db.showDatabases();
+
+      const resultText = JSON.stringify(
+        {
+          databaseCount: databases.length,
+          databases: databases.map((db) => db.Database),
+        },
+        null,
+        2
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: resultText,
+          },
+        ],
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof MySQLMCPError
+          ? `MySQL Error: ${error.message}`
+          : `Unexpected error: ${
+              error instanceof Error ? error.message : "Unknown error"
+            }`;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: errorMessage,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+export const MySQLConfigSchema = z.object({
+  host: z.string(),
+  port: z.number().min(1).max(65535).default(3306),
+  user: z.string(),
+  password: z.string(),
+  database: z.string(),
+  ssl: z.boolean().optional().default(false),
+  connectionTimeout: z.number().optional().default(30000),
+});
+
+export type MySQLConfig = z.output<typeof MySQLConfigSchema>;
+export type MySQLConfigInput = z.input<typeof MySQLConfigSchema>;
+
+export const ReadQueryParamsSchema = z.object({
+  query: z.string().min(1),
+});
+
+export type ReadQueryParams = z.infer<typeof ReadQueryParamsSchema>;
+
+export const DescribeTableParamsSchema = z.object({
+  tableName: z.string().min(1),
+});
+
+export type DescribeTableParams = z.infer<typeof DescribeTableParamsSchema>;
+
+export interface TableInfo {
+  TABLE_NAME: string;
+  TABLE_TYPE: string;
+  TABLE_SCHEMA: string;
+}
+
+export interface ColumnInfo {
+  COLUMN_NAME: string;
+  DATA_TYPE: string;
+  IS_NULLABLE: string;
+  COLUMN_DEFAULT: string | null;
+  COLUMN_KEY: string;
+  EXTRA: string;
+  COLUMN_COMMENT: string;
+}
+
+export interface DatabaseInfo {
+  Database: string;
+}
+
+export interface QueryResult {
+  data: Record<string, unknown>[];
+  rowCount: number;
+  executionTime: number;
+}
+
+export interface McpToolResult {
+  [x: string]: unknown;
+  content: Array<{
+    type: "text";
+    text: string;
+  }>;
+}
+
+export class MySQLMCPError extends Error {
+  constructor(
+    message: string,
+    public readonly code?: string,
+    public readonly sqlState?: string
+  ) {
+    super(message);
+    this.name = "MySQLMCPError";
+  }
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}