@sigma4life/mysql-mcp-server 1.0.0

package/src/handlers/validation.ts

@@ -0,0 +1,165 @@
+import { resolveDatabase, resolveSchema } from '../core/config.js';
+import { logger } from '../core/logger.js';
+import { db } from '../mysql/connection.js';
+
+export interface ValidationResult {
+  exists: boolean;
+  actualName?: string;
+  suggestions?: string[];
+  message: string;
+}
+
+export interface DatabaseValidation extends ValidationResult {
+  databases?: string[];
+}
+
+export interface SchemaValidation extends ValidationResult {
+  schemas?: string[];
+}
+
+export interface TableValidation extends ValidationResult {
+  tables?: Array<{ schema: string; table: string; fullName: string; type?: string; rowCount?: number | null }>;
+}
+
+export async function validateDatabase(database?: string): Promise<DatabaseValidation> {
+  const actualName = resolveDatabase(database);
+  return {
+    exists: true,
+    actualName,
+    message: database && database !== actualName
+      ? `Database found (case mismatch): '${actualName}' (you provided '${database}')`
+      : `Database '${actualName}' is configured for this server`,
+  };
+}
+
+export async function validateSchema(database: string | undefined, schema?: string): Promise<SchemaValidation> {
+  const actualDatabase = resolveDatabase(database);
+  const actualSchema = resolveSchema(schema);
+  return {
+    exists: true,
+    actualName: actualSchema,
+    message: `Schema '${actualSchema}' is available in database '${actualDatabase}'`,
+  };
+}
+
+export async function validateTable(
+  database: string | undefined,
+  table: string,
+  schema?: string,
+): Promise<TableValidation> {
+  const actualDatabase = resolveDatabase(database);
+  resolveSchema(schema);
+
+  try {
+    const matches = await db.query<any>(
+      `
+SELECT
+  TABLE_SCHEMA AS schemaName,
+  TABLE_NAME AS tableName,
+  CONCAT(TABLE_SCHEMA, '.', TABLE_NAME) AS fullName,
+  TABLE_TYPE AS objectType,
+  TABLE_ROWS AS rowCount
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = :database
+  AND LOWER(TABLE_NAME) = LOWER(:table)
+  AND TABLE_TYPE IN ('BASE TABLE', 'VIEW')
+ORDER BY TABLE_NAME
+`,
+      { database: actualDatabase, table },
+    );
+
+    if (matches.length === 1) {
+      const match = matches[0];
+      return {
+        exists: true,
+        actualName: match.fullName,
+        message: match.tableName === table
+          ? `Table '${match.fullName}' exists`
+          : `Table found (case mismatch): '${match.fullName}' (you provided '${table}')`,
+      };
+    }
+
+    const suggestions = await db.query<any>(
+      `
+SELECT
+  TABLE_SCHEMA AS schemaName,
+  TABLE_NAME AS tableName,
+  CONCAT(TABLE_SCHEMA, '.', TABLE_NAME) AS fullName,
+  TABLE_TYPE AS objectType,
+  TABLE_ROWS AS rowCount
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = :database
+  AND LOWER(TABLE_NAME) LIKE CONCAT('%', LOWER(:table), '%')
+  AND TABLE_TYPE IN ('BASE TABLE', 'VIEW')
+ORDER BY TABLE_NAME
+LIMIT 10
+`,
+      { database: actualDatabase, table },
+    );
+
+    const tables = suggestions.map((row) => ({
+      schema: row.schemaName,
+      table: row.tableName,
+      fullName: row.fullName,
+      type: row.objectType,
+      rowCount: row.rowCount,
+    }));
+
+    return {
+      exists: false,
+      tables,
+      suggestions: tables.slice(0, 5).map((row) => row.fullName),
+      message: tables.length
+        ? `Table '${table}' not found in database '${actualDatabase}'. Did you mean: ${tables.slice(0, 5).map((row) => row.fullName).join(', ')}?`
+        : `Table '${table}' not found in database '${actualDatabase}'. No similar tables found.`,
+    };
+  } catch (error) {
+    logger.error('Table validation failed:', error);
+    throw error;
+  }
+}
+
+export async function validateDatabaseObject(
+  database?: string,
+  table?: string,
+  schema?: string,
+): Promise<{
+  valid: boolean;
+  database: DatabaseValidation;
+  schema?: SchemaValidation;
+  table?: TableValidation;
+  message: string;
+}> {
+  const databaseValidation = await validateDatabase(database);
+  const schemaValidation = schema
+    ? await validateSchema(databaseValidation.actualName, schema)
+    : undefined;
+
+  if (table) {
+    const tableValidation = await validateTable(databaseValidation.actualName, table, schemaValidation?.actualName);
+    if (!tableValidation.exists) {
+      return {
+        valid: false,
+        database: databaseValidation,
+        schema: schemaValidation,
+        table: tableValidation,
+        message: tableValidation.message,
+      };
+    }
+
+    return {
+      valid: true,
+      database: databaseValidation,
+      schema: schemaValidation,
+      table: tableValidation,
+      message: `Validation successful: ${tableValidation.actualName}`,
+    };
+  }
+
+  return {
+    valid: true,
+    database: databaseValidation,
+    schema: schemaValidation,
+    message: 'Validation successful',
+  };
+}

package/src/index.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { appConfig } from './core/config.js';
+import { errorResult, textResult } from './core/mcp.js';
+import { logger } from './core/logger.js';
+import {
+  initAccessControl,
+  loadAccessControlConfig,
+} from './core/security/access-control.js';
+import { executeQuery } from './handlers/data.js';
+import {
+  getAccessibleSchema,
+  getAccessibleTableInfo,
+} from './handlers/accessible-schema.js';
+import { getRelationships } from './handlers/relationships.js';
+import { getSchema, getTableInfo } from './handlers/schema.js';
+import { findTables, searchObjects } from './handlers/search.js';
+import { validateDatabaseObject } from './handlers/validation.js';
+import { db } from './mysql/connection.js';
+
+const databaseProperty = {
+  type: 'string',
+  description:
+    'Optional compatibility field. If provided, it must match the configured DB_NAME.',
+};
+
+const schemaProperty = {
+  type: 'string',
+  description:
+    'Optional compatibility field. MySQL uses DB_NAME as the schema for this server.',
+};
+
+const tools: Tool[] = [
+  {
+    name: 'get_schema',
+    description:
+      'Retrieves MySQL schema information for one or more tables. Returns columns, data types, primary keys, foreign keys, indexes, and optional table statistics.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        tables: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Table names to retrieve. Leave empty to get all tables in the configured database.',
+        },
+        schema: schemaProperty,
+        includeRelationships: {
+          type: 'boolean',
+          description: 'Include foreign key relationships (default: true)',
+          default: true,
+        },
+        includeStatistics: {
+          type: 'boolean',
+          description: 'Include approximate table row/size statistics (default: false)',
+          default: false,
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_table_info',
+    description:
+      'Gets detailed metadata for a single MySQL table or view. Use get_schema for batch table metadata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        table: {
+          type: 'string',
+          description: 'Table or view name, for example "customers"',
+        },
+        schema: schemaProperty,
+      },
+      required: ['table'],
+    },
+  },
+  {
+    name: 'find_tables',
+    description:
+      'Searches MySQL tables/views by name pattern or by containing a matching column. Supports * and ? wildcards.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        pattern: {
+          type: 'string',
+          description: 'Table name pattern, for example "*customer*" or "order_*".',
+        },
+        hasColumn: {
+          type: 'string',
+          description: 'Column name pattern, for example "*email*" or "created_at".',
+        },
+        schema: schemaProperty,
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'search_objects',
+    description:
+      'Searches MySQL table and column names. Returns matching table and column references.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        search: {
+          type: 'string',
+          description: 'Search string or wildcard pattern, for example "order" or "*email*".',
+        },
+        schema: schemaProperty,
+        type: {
+          type: 'string',
+          enum: ['table', 'column'],
+          description: 'Optional object type filter.',
+        },
+      },
+      required: ['search'],
+    },
+  },
+  {
+    name: 'get_relationships',
+    description:
+      'Maps foreign key relationships for JOIN path discovery between MySQL tables.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        fromTable: {
+          type: 'string',
+          description: 'Source table name',
+        },
+        toTable: {
+          type: 'string',
+          description:
+            'Target table name. If omitted, returns direct relationships for fromTable.',
+        },
+        maxDepth: {
+          type: 'number',
+          description: 'Maximum relationship traversal depth (default: 2)',
+          default: 2,
+        },
+        schema: schemaProperty,
+      },
+      required: ['fromTable'],
+    },
+  },
+  {
+    name: 'validate_objects',
+    description:
+      'Validates the configured database and optional MySQL table names, with suggestions for close table-name matches.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        table: {
+          type: 'string',
+          description: 'Single table name to validate.',
+        },
+        tables: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Multiple table names to validate.',
+        },
+        schema: schemaProperty,
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_accessible_schema',
+    description:
+      'Shows tables and columns accessible for SELECT queries based on QUERY_ACCESS_CONFIG.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        schema: schemaProperty,
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_accessible_table_info',
+    description:
+      'Shows table columns with access status according to QUERY_ACCESS_CONFIG.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        database: databaseProperty,
+        table: {
+          type: 'string',
+          description: 'Table name to check.',
+        },
+        schema: schemaProperty,
+      },
+      required: ['table'],
+    },
+  },
+  ...(!appConfig.server.schemaOnlyMode
+    ? [
+        {
+          name: 'execute_query',
+          description:
+            'Executes a guarded read-only MySQL SELECT query. Queries are validated, access-controlled, and automatically limited with LIMIT.',
+          inputSchema: {
+            type: 'object' as const,
+            properties: {
+              database: databaseProperty,
+              query: {
+                type: 'string',
+                description:
+                  'Read-only SELECT query. Supports joins, CTEs, subqueries, WHERE, GROUP BY, HAVING, ORDER BY, and LIMIT.',
+              },
+              parameters: {
+                type: 'object',
+                description:
+                  'Optional named parameters for mysql2 named placeholders, for example {"id": 123}.',
+              },
+            },
+            required: ['query'],
+          },
+        },
+      ]
+    : []),
+];
+
+const server = new Server(
+  {
+    name: appConfig.server.name,
+    version: appConfig.server.version,
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    logger.info(`Tool called: ${name}`, args);
+
+    switch (name) {
+      case 'get_schema':
+        return textResult(await getSchema(args as any));
+      case 'get_table_info':
+        return textResult(await getTableInfo(args as any));
+      case 'find_tables':
+        return textResult(await findTables(args as any));
+      case 'search_objects':
+        return textResult(await searchObjects(args as any));
+      case 'get_relationships':
+        return textResult(await getRelationships(args as any));
+      case 'validate_objects': {
+        const { database, table, tables, schema } = args as any;
+        if (Array.isArray(tables)) {
+          return textResult(
+            await Promise.all(
+              tables.map((candidate: string) =>
+                validateDatabaseObject(database, candidate, schema),
+              ),
+            ),
+          );
+        }
+        return textResult(await validateDatabaseObject(database, table, schema));
+      }
+      case 'get_accessible_schema':
+        return textResult(await getAccessibleSchema(args as any));
+      case 'get_accessible_table_info':
+        return textResult(await getAccessibleTableInfo(args as any));
+      case 'execute_query':
+        if (appConfig.server.schemaOnlyMode) {
+          throw new Error('Data query operations are disabled because SCHEMA_ONLY_MODE=true.');
+        }
+        return textResult(await executeQuery(args as any));
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    logger.error(`Error executing tool ${name}:`, error);
+    return errorResult(error);
+  }
+});
+
+async function main(): Promise<void> {
+  try {
+    await db.connect();
+
+    if (appConfig.server.schemaOnlyMode) {
+      logger.info('SCHEMA_ONLY_MODE enabled - execute_query is disabled');
+    } else if (process.env.QUERY_ACCESS_CONFIG) {
+      try {
+        initAccessControl(loadAccessControlConfig());
+        logger.info('Access control enabled for execute_query');
+      } catch (error) {
+        logger.error('Failed to load access control config:', error);
+      }
+    } else {
+      logger.warn('QUERY_ACCESS_CONFIG not set - execute_query will be blocked');
+    }
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info(`${appConfig.server.name} v${appConfig.server.version} started`);
+  } catch (error) {
+    logger.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+process.on('SIGINT', async () => {
+  logger.info('Shutting down...');
+  await db.close();
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  logger.info('Shutting down...');
+  await db.close();
+  process.exit(0);
+});
+
+main();

package/src/mysql/connection.ts

@@ -0,0 +1,68 @@
+import mysql, { Pool, RowDataPacket } from 'mysql2/promise';
+import { appConfig } from '../core/config.js';
+import { logger } from '../core/logger.js';
+
+class MySqlConnection {
+  private static instance: MySqlConnection;
+  private pool: Pool | null = null;
+
+  private constructor() {}
+
+  static getInstance(): MySqlConnection {
+    if (!MySqlConnection.instance) {
+      MySqlConnection.instance = new MySqlConnection();
+    }
+    return MySqlConnection.instance;
+  }
+
+  private createPool(): Pool {
+    logger.info(`Creating MySQL pool for ${appConfig.db.host}:${appConfig.db.port}/${appConfig.db.name}`);
+    return mysql.createPool({
+      host: appConfig.db.host,
+      port: appConfig.db.port,
+      database: appConfig.db.name,
+      user: appConfig.db.user,
+      password: appConfig.db.password,
+      ssl: appConfig.db.ssl ? { rejectUnauthorized: true } : undefined,
+      namedPlaceholders: true,
+      waitForConnections: true,
+      connectionLimit: 10,
+      maxIdle: 10,
+      idleTimeout: 30000,
+      queueLimit: 0,
+    });
+  }
+
+  async connect(): Promise<Pool> {
+    if (!this.pool) {
+      this.pool = this.createPool();
+      await this.pool.query('SELECT 1');
+      logger.info('Connected to MySQL successfully');
+    }
+    return this.pool;
+  }
+
+  async query<T extends RowDataPacket = RowDataPacket>(
+    sql: string,
+    params?: Record<string, unknown>,
+  ): Promise<T[]> {
+    const pool = await this.connect();
+    logger.debug(`Executing query: ${sql}`);
+    const [rows] = await pool.query<T[]>(sql, (params || {}) as any);
+    return rows;
+  }
+
+  async close(): Promise<void> {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+      logger.info('MySQL connection pool closed');
+    }
+  }
+
+  isConnected(): boolean {
+    return this.pool !== null;
+  }
+}
+
+export const db = MySqlConnection.getInstance();

package/src/mysql/identifiers.test.ts

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { likePattern, quoteIdentifier } from './identifiers.js';
+
+test('quoteIdentifier escapes backticks', () => {
+  assert.equal(quoteIdentifier('order`items'), '`order``items`');
+});
+
+test('likePattern converts simple wildcards', () => {
+  assert.equal(likePattern('*customer?'), '%customer_');
+  assert.equal(likePattern(undefined), null);
+});

package/src/mysql/identifiers.ts

@@ -0,0 +1,10 @@
+export function quoteIdentifier(identifier: string): string {
+  return `\`${identifier.replace(/`/g, '``')}\``;
+}
+
+export function likePattern(pattern?: string): string | null {
+  if (!pattern) {
+    return null;
+  }
+  return pattern.replace(/\*/g, '%').replace(/\?/g, '_');
+}