@arvoretech/mysql-mcp 1.0.0

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+export declare const MySQLConfigSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodDefault<z.ZodNumber>;
+    user: z.ZodString;
+    password: z.ZodString;
+    database: z.ZodString;
+    ssl: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    connectionTimeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    ssl: boolean;
+    connectionTimeout: number;
+}, {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port?: number | undefined;
+    ssl?: boolean | undefined;
+    connectionTimeout?: number | undefined;
+}>;
+export type MySQLConfig = z.output<typeof MySQLConfigSchema>;
+export type MySQLConfigInput = z.input<typeof MySQLConfigSchema>;
+export declare const ReadQueryParamsSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export type ReadQueryParams = z.infer<typeof ReadQueryParamsSchema>;
+export declare const DescribeTableParamsSchema: z.ZodObject<{
+    tableName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    tableName: string;
+}, {
+    tableName: string;
+}>;
+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 declare class MySQLMCPError extends Error {
+    readonly code?: string | undefined;
+    readonly sqlState?: string | undefined;
+    constructor(message: string, code?: string | undefined, sqlState?: string | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;EAQ5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC7D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEjE,eAAO,MAAM,qBAAqB;;;;;;EAEhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,yBAAyB;;;;;;EAEpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACrB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED,qBAAa,aAAc,SAAQ,KAAK;aAGpB,IAAI,CAAC,EAAE,MAAM;aACb,QAAQ,CAAC,EAAE,MAAM;gBAFjC,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,QAAQ,CAAC,EAAE,MAAM,YAAA;CAKpC"}

package/dist/types.js

@@ -0,0 +1,27 @@
+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 const ReadQueryParamsSchema = z.object({
+    query: z.string().min(1),
+});
+export const DescribeTableParamsSchema = z.object({
+    tableName: z.string().min(1),
+});
+export class MySQLMCPError extends Error {
+    code;
+    sqlState;
+    constructor(message, code, sqlState) {
+        super(message);
+        this.code = code;
+        this.sqlState = sqlState;
+        this.name = "MySQLMCPError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC1C,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CACxD,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACzB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7B,CAAC,CAAC;AAsCH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAGpB;IACA;IAHlB,YACE,OAAe,EACC,IAAa,EACb,QAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAS;QACb,aAAQ,GAAR,QAAQ,CAAS;QAGjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/eslint.config.js

@@ -0,0 +1,54 @@
+import eslint from "@eslint/js";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+
+export default [
+  eslint.configs.recommended,
+  {
+    files: ["src/**/*.ts"],
+    ignores: ["**/*.test.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+        project: "./tsconfig.json",
+      },
+      globals: {
+        console: "readonly",
+        process: "readonly",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      "@typescript-eslint/no-unused-vars": "error",
+      "@typescript-eslint/explicit-function-return-type": "warn",
+      "@typescript-eslint/no-explicit-any": "warn",
+    },
+  },
+  {
+    files: ["src/**/*.test.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+      },
+      globals: {
+        console: "readonly",
+        process: "readonly",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      "@typescript-eslint/no-unused-vars": "error",
+      "@typescript-eslint/no-explicit-any": "off",
+    },
+  },
+];

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@arvoretech/mysql-mcp",
+  "version": "1.0.0",
+  "description": "MySQL MCP Server for read-only database operations",
+  "main": "dist/index.js",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "mysql-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:cov": "vitest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix"
+  },
+  "keywords": [
+    "mcp",
+    "mysql",
+    "database",
+    "llm",
+    "ai",
+    "arvore"
+  ],
+  "author": "Arvore",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arvoreeducacao/arvore-mcp-servers.git",
+    "directory": "packages/mysql"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "mysql2": "^3.6.5",
+    "zod": "^3.22.4"
+  }
+}

package/src/database.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MySQLConnection } from "./database.js";
+import { MySQLMCPError } from "./types.js";
+import mysql from "mysql2/promise";
+
+vi.mock("mysql2/promise", () => ({
+  default: {
+    createConnection: vi.fn(),
+  },
+}));
+
+describe("MySQLConnection", () => {
+  let connection: MySQLConnection;
+  let mockConnection: {
+    execute: ReturnType<typeof vi.fn>;
+    end: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConnection = {
+      execute: vi.fn(),
+      end: vi.fn(),
+    };
+    (mysql.createConnection as ReturnType<typeof vi.fn>).mockResolvedValue(
+      mockConnection
+    );
+
+    connection = new MySQLConnection({
+      host: "localhost",
+      port: 3306,
+      user: "testuser",
+      password: "testpass",
+      database: "testdb",
+    });
+  });
+
+  describe("connect", () => {
+    it("should successfully connect to MySQL", async () => {
+      await expect(connection.connect()).resolves.toBeUndefined();
+      expect(mysql.createConnection).toHaveBeenCalledWith(
+        expect.objectContaining({
+          host: "localhost",
+          port: 3306,
+          user: "testuser",
+          password: "testpass",
+          database: "testdb",
+        })
+      );
+      expect(mockConnection.end).toHaveBeenCalled();
+    });
+
+    it("should throw MySQLMCPError on connection failure", async () => {
+      (mysql.createConnection as ReturnType<typeof vi.fn>).mockRejectedValue(
+        new Error("Connection failed")
+      );
+
+      await expect(connection.connect()).rejects.toThrow(MySQLMCPError);
+      await expect(connection.connect()).rejects.toThrow(
+        "Failed to connect to MySQL"
+      );
+    });
+
+    it("should use SSL when configured", async () => {
+      const sslConnection = new MySQLConnection({
+        host: "localhost",
+        port: 3306,
+        user: "testuser",
+        password: "testpass",
+        database: "testdb",
+        ssl: true,
+      });
+
+      await sslConnection.connect();
+
+      expect(mysql.createConnection).toHaveBeenCalledWith(
+        expect.objectContaining({
+          ssl: {},
+        })
+      );
+    });
+  });
+
+  describe("executeQuery", () => {
+    it("should execute SELECT query successfully", async () => {
+      const mockRows = [
+        { id: 1, name: "John" },
+        { id: 2, name: "Jane" },
+      ];
+      mockConnection.execute.mockResolvedValue([mockRows, []]);
+
+      const result = await connection.executeQuery("SELECT * FROM users");
+
+      expect(result.data).toEqual(mockRows);
+      expect(result.rowCount).toBe(2);
+      expect(result.executionTime).toBeGreaterThanOrEqual(0);
+      expect(mockConnection.end).toHaveBeenCalled();
+    });
+
+    it("should allow SHOW queries", async () => {
+      mockConnection.execute.mockResolvedValue([[], []]);
+
+      await expect(
+        connection.executeQuery("SHOW TABLES")
+      ).resolves.toBeDefined();
+    });
+
+    it("should allow DESCRIBE queries", async () => {
+      mockConnection.execute.mockResolvedValue([[], []]);
+
+      await expect(
+        connection.executeQuery("DESCRIBE users")
+      ).resolves.toBeDefined();
+    });
+
+    it("should allow EXPLAIN queries", async () => {
+      mockConnection.execute.mockResolvedValue([[], []]);
+
+      await expect(
+        connection.executeQuery("EXPLAIN SELECT * FROM users")
+      ).resolves.toBeDefined();
+    });
+
+    it("should reject INSERT queries", async () => {
+      await expect(
+        connection.executeQuery("INSERT INTO users VALUES (1, 'Test')")
+      ).rejects.toThrow(MySQLMCPError);
+      await expect(
+        connection.executeQuery("INSERT INTO users VALUES (1, 'Test')")
+      ).rejects.toThrow("Only read-only queries are allowed");
+    });
+
+    it("should reject UPDATE queries", async () => {
+      await expect(
+        connection.executeQuery("UPDATE users SET name='Test' WHERE id=1")
+      ).rejects.toThrow(MySQLMCPError);
+    });
+
+    it("should reject DELETE queries", async () => {
+      await expect(
+        connection.executeQuery("DELETE FROM users WHERE id=1")
+      ).rejects.toThrow(MySQLMCPError);
+    });
+
+    it("should reject DROP queries", async () => {
+      await expect(connection.executeQuery("DROP TABLE users")).rejects.toThrow(
+        MySQLMCPError
+      );
+    });
+
+    it("should reject CREATE queries", async () => {
+      await expect(
+        connection.executeQuery("CREATE TABLE test (id INT)")
+      ).rejects.toThrow(MySQLMCPError);
+    });
+
+    it("should throw MySQLMCPError on query execution failure", async () => {
+      const mockError = {
+        message: "Syntax error",
+        code: "ER_PARSE_ERROR",
+        sqlState: "42000",
+      };
+      mockConnection.execute.mockRejectedValue(mockError);
+
+      await expect(
+        connection.executeQuery("SELECT * FROM invalid")
+      ).rejects.toThrow(MySQLMCPError);
+    });
+
+    it("should close connection even if query fails", async () => {
+      mockConnection.execute.mockRejectedValue(new Error("Query failed"));
+
+      try {
+        await connection.executeQuery("SELECT * FROM users");
+      } catch (error) {
+        expect(error).toBeDefined();
+      }
+
+      expect(mockConnection.end).toHaveBeenCalled();
+    });
+  });
+
+  describe("listTables", () => {
+    it("should list all tables in database", async () => {
+      const mockTables = [
+        {
+          TABLE_NAME: "users",
+          TABLE_TYPE: "BASE TABLE",
+          TABLE_SCHEMA: "testdb",
+        },
+        {
+          TABLE_NAME: "posts",
+          TABLE_TYPE: "BASE TABLE",
+          TABLE_SCHEMA: "testdb",
+        },
+      ];
+      mockConnection.execute.mockResolvedValue([mockTables, []]);
+
+      const result = await connection.listTables();
+
+      expect(result).toHaveLength(2);
+      expect(result[0].TABLE_NAME).toBe("users");
+      expect(result[1].TABLE_NAME).toBe("posts");
+    });
+
+    it("should return empty array when no tables exist", async () => {
+      mockConnection.execute.mockResolvedValue([[], []]);
+
+      const result = await connection.listTables();
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("describeTable", () => {
+    it("should describe table structure", async () => {
+      const mockColumns = [
+        {
+          COLUMN_NAME: "id",
+          DATA_TYPE: "int",
+          IS_NULLABLE: "NO",
+          COLUMN_DEFAULT: null,
+          COLUMN_KEY: "PRI",
+          EXTRA: "auto_increment",
+          COLUMN_COMMENT: "",
+        },
+        {
+          COLUMN_NAME: "name",
+          DATA_TYPE: "varchar",
+          IS_NULLABLE: "YES",
+          COLUMN_DEFAULT: null,
+          COLUMN_KEY: "",
+          EXTRA: "",
+          COLUMN_COMMENT: "User name",
+        },
+      ];
+      mockConnection.execute.mockResolvedValue([mockColumns, []]);
+
+      const result = await connection.describeTable("users");
+
+      expect(result).toHaveLength(2);
+      expect(result[0].COLUMN_NAME).toBe("id");
+      expect(result[0].COLUMN_KEY).toBe("PRI");
+      expect(result[1].COLUMN_NAME).toBe("name");
+    });
+  });
+
+  describe("showDatabases", () => {
+    it("should list all databases", async () => {
+      const mockDatabases = [
+        { Database: "testdb" },
+        { Database: "production" },
+      ];
+      mockConnection.execute.mockResolvedValue([mockDatabases, []]);
+
+      const result = await connection.showDatabases();
+
+      expect(result).toHaveLength(2);
+      expect(result[0].Database).toBe("testdb");
+      expect(result[1].Database).toBe("production");
+    });
+  });
+
+  describe("testConnection", () => {
+    it("should return true on successful connection test", async () => {
+      mockConnection.execute.mockResolvedValue([[{ test: 1 }], []]);
+
+      const result = await connection.testConnection();
+
+      expect(result).toBe(true);
+      expect(mockConnection.end).toHaveBeenCalled();
+    });
+
+    it("should return false on connection test failure", async () => {
+      (mysql.createConnection as ReturnType<typeof vi.fn>).mockRejectedValue(
+        new Error("Connection failed")
+      );
+
+      const result = await connection.testConnection();
+
+      expect(result).toBe(false);
+    });
+
+    it("should close connection even if test fails", async () => {
+      mockConnection.execute.mockRejectedValue(new Error("Test failed"));
+
+      await connection.testConnection();
+
+      expect(mockConnection.end).toHaveBeenCalled();
+    });
+  });
+
+  describe("disconnect", () => {
+    it("should be a no-op", async () => {
+      await expect(connection.disconnect()).resolves.toBeUndefined();
+    });
+  });
+});

package/src/database.ts

@@ -0,0 +1,163 @@
+import mysql from "mysql2/promise";
+import {
+  MySQLConfig,
+  MySQLConfigInput,
+  MySQLConfigSchema,
+  QueryResult,
+  TableInfo,
+  ColumnInfo,
+  DatabaseInfo,
+  MySQLMCPError,
+} from "./types.js";
+
+export class MySQLConnection {
+  private readonly config: MySQLConfig;
+
+  constructor(config: MySQLConfigInput) {
+    this.config = MySQLConfigSchema.parse(config);
+  }
+
+  private async createConnection(): Promise<mysql.Connection> {
+    try {
+      const connectionOptions: mysql.ConnectionOptions = {
+        host: this.config.host,
+        port: this.config.port,
+        user: this.config.user,
+        password: this.config.password,
+        database: this.config.database,
+        connectTimeout: this.config.connectionTimeout,
+      };
+
+      if (this.config.ssl) {
+        connectionOptions.ssl = {};
+      }
+
+      return await mysql.createConnection(connectionOptions);
+    } catch (error) {
+      throw new MySQLMCPError(
+        `Failed to connect to MySQL: ${
+          error instanceof Error ? error.message : "Unknown error"
+        }`,
+        "CONNECTION_ERROR"
+      );
+    }
+  }
+
+  async connect(): Promise<void> {
+    const connection = await this.createConnection();
+    await connection.end();
+  }
+
+  async disconnect(): Promise<void> {
+    // No-op: connections are managed per-query
+  }
+
+  private validateReadOnlyQuery(query: string): void {
+    const trimmedQuery = query.trim().toLowerCase();
+    const readOnlyPatterns = [
+      /^select\s/,
+      /^show\s/,
+      /^describe\s/,
+      /^desc\s/,
+      /^explain\s/,
+    ];
+
+    const isReadOnly = readOnlyPatterns.some((pattern) =>
+      pattern.test(trimmedQuery)
+    );
+
+    if (!isReadOnly) {
+      throw new MySQLMCPError(
+        "Only read-only queries are allowed (SELECT, SHOW, DESCRIBE, EXPLAIN)",
+        "WRITE_OPERATION_NOT_ALLOWED"
+      );
+    }
+  }
+
+  async executeQuery(query: string): Promise<QueryResult> {
+    this.validateReadOnlyQuery(query);
+
+    const startTime = Date.now();
+    let connection: mysql.Connection | null = null;
+
+    try {
+      connection = await this.createConnection();
+      const [rows] = await connection.execute(query);
+      const executionTime = Date.now() - startTime;
+
+      const data = Array.isArray(rows)
+        ? (rows as Record<string, unknown>[])
+        : [];
+
+      return {
+        data,
+        rowCount: data.length,
+        executionTime,
+      };
+    } catch (error) {
+      const mysqlError = error as mysql.QueryError;
+      throw new MySQLMCPError(
+        `Query execution failed: ${mysqlError.message}`,
+        mysqlError.code,
+        mysqlError.sqlState
+      );
+    } finally {
+      if (connection) {
+        await connection.end();
+      }
+    }
+  }
+
+  async listTables(): Promise<TableInfo[]> {
+    const result = await this.executeQuery(`
+      SELECT 
+        TABLE_NAME,
+        TABLE_TYPE,
+        TABLE_SCHEMA
+      FROM information_schema.TABLES 
+      WHERE TABLE_SCHEMA = '${this.config.database}'
+      ORDER BY TABLE_NAME
+    `);
+
+    return result.data as unknown as TableInfo[];
+  }
+
+  async describeTable(tableName: string): Promise<ColumnInfo[]> {
+    const result = await this.executeQuery(`
+      SELECT 
+        COLUMN_NAME,
+        DATA_TYPE,
+        IS_NULLABLE,
+        COLUMN_DEFAULT,
+        COLUMN_KEY,
+        EXTRA,
+        COLUMN_COMMENT
+      FROM information_schema.COLUMNS 
+      WHERE TABLE_SCHEMA = '${this.config.database}' 
+        AND TABLE_NAME = '${tableName}'
+      ORDER BY ORDINAL_POSITION
+    `);
+
+    return result.data as unknown as ColumnInfo[];
+  }
+
+  async showDatabases(): Promise<DatabaseInfo[]> {
+    const result = await this.executeQuery("SHOW DATABASES");
+    return result.data as unknown as DatabaseInfo[];
+  }
+
+  async testConnection(): Promise<boolean> {
+    let connection: mysql.Connection | null = null;
+    try {
+      connection = await this.createConnection();
+      await connection.execute("SELECT 1 as test");
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (connection) {
+        await connection.end();
+      }
+    }
+  }
+}