@neverinfamous/mysql-mcp 2.1.0

package/src/utils/logger.ts

@@ -0,0 +1,426 @@
+/**
+ * mysql-mcp - Structured Logger
+ * 
+ * Centralized logging utility with RFC 5424 severity levels and structured output.
+ * Supports dual-mode logging: stderr for local debugging and MCP protocol notifications.
+ * 
+ * Format: [timestamp] [LEVEL] [MODULE] [CODE] message {context}
+ * Example: [2025-12-18T01:30:00Z] [ERROR] [ADAPTER] [MYSQL_CONNECT_FAILED] Failed to connect {"host":"localhost"}
+ */
+
+/**
+ * RFC 5424 syslog severity levels
+ * @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+ */
+export type LogLevel =
+    | 'debug'       // 7 - Debug-level messages
+    | 'info'        // 6 - Informational messages
+    | 'notice'      // 5 - Normal but significant condition
+    | 'warning'     // 4 - Warning conditions
+    | 'error'       // 3 - Error conditions
+    | 'critical'    // 2 - Critical conditions
+    | 'alert'       // 1 - Action must be taken immediately
+    | 'emergency';  // 0 - System is unusable
+
+/**
+ * Module identifiers for log categorization
+ */
+export type LogModule =
+    | 'SERVER'      // MCP server lifecycle
+    | 'ADAPTER'     // Database adapter operations
+    | 'AUTH'        // OAuth/authentication
+    | 'TOOLS'       // Tool execution
+    | 'RESOURCES'   // Resource handlers
+    | 'PROMPTS'     // Prompt handlers
+    | 'TRANSPORT'   // HTTP/SSE/stdio transport
+    | 'QUERY'       // SQL query execution
+    | 'POOL'        // Connection pool
+    | 'FILTER'      // Tool filtering
+    | 'ROUTER'      // MySQL Router
+    | 'PROXYSQL'    // ProxySQL
+    | 'SHELL'       // MySQL Shell
+    | 'CLI';        // Command line interface
+
+/**
+ * Structured log context following MCP logging standards
+ */
+export interface LogContext {
+    /** Module identifier */
+    module?: LogModule;
+    /** Module-prefixed error/event code (e.g., MYSQL_CONNECT_FAILED) */
+    code?: string;
+    /** Operation being performed (e.g., executeQuery, connect) */
+    operation?: string;
+    /** Entity identifier (e.g., table name, connection id) */
+    entityId?: string;
+    /** Request identifier for tracing */
+    requestId?: string;
+    /** Error stack trace */
+    stack?: string;
+    /** Additional context fields */
+    [key: string]: unknown;
+}
+
+interface LogEntry {
+    level: LogLevel;
+    module?: LogModule | undefined;
+    code?: string | undefined;
+    message: string;
+    timestamp: string;
+    context?: LogContext | undefined;
+}
+
+/**
+ * Sensitive patterns to redact from logs
+ * Note: Patterns are designed to avoid ReDoS by using non-overlapping character classes
+ * and avoiding nested quantifiers on ambiguous patterns.
+ */
+const SENSITIVE_PATTERNS = [
+    // Use word boundaries and specific character classes to avoid backtracking
+    /\bpassword[=:]\s*[^\s,;]{1,100}/gi,
+    /\bsecret[=:]\s*[^\s,;]{1,100}/gi,
+    /\btoken[=:]\s*[^\s,;]{1,100}/gi,
+    /\bauthorization:\s*bearer\s+\S{1,500}/gi,
+    // MySQL connection string - use specific pattern with length limits
+    /mysql:\/\/[^:]{1,50}:[^@]{1,100}@/gi,
+];
+
+/**
+ * Maximum length of input to process with regex
+ * Prevents ReDoS on extremely long strings
+ */
+const MAX_REDACT_LENGTH = 10000;
+
+/**
+ * Redact sensitive information from a string
+ */
+function redactSensitive(input: string): string {
+    // Limit input length to prevent ReDoS attacks
+    if (input.length > MAX_REDACT_LENGTH) {
+        // For very long strings, truncate and add indicator
+        // codeql[js/polynomial-redos] - Input is length-limited before regex processing
+        return redactSensitive(input.substring(0, MAX_REDACT_LENGTH)) + '...[TRUNCATED]';
+    }
+
+    let result = input;
+    for (const pattern of SENSITIVE_PATTERNS) {
+        result = result.replace(pattern, (match) => {
+            // Keep the key part, redact the value
+            const colonIndex = match.indexOf(':');
+            const equalIndex = match.indexOf('=');
+            const delimiterIndex = colonIndex >= 0 ? colonIndex : equalIndex;
+
+            if (delimiterIndex >= 0) {
+                return match.substring(0, delimiterIndex + 1) + '[REDACTED]';
+            }
+            return '[REDACTED]';
+        });
+    }
+    return result;
+}
+
+/**
+ * Sensitive keys to redact from context objects
+ */
+const SENSITIVE_KEYS = new Set([
+    'password',
+    'secret',
+    'token',
+    'authorization',
+    'apikey',
+    'api_key',
+    'accesstoken',
+    'access_token',
+    'refreshtoken',
+    'refresh_token',
+    'credential',
+    'credentials',
+    'issuer',
+    'audience',
+    'jwksuri',
+    'jwks_uri',
+    'client_secret',
+    'clientsecret'
+]);
+
+/**
+ * Sanitize log context by redacting sensitive values
+ */
+function sanitizeContext(context: LogContext): LogContext {
+    const result: LogContext = {};
+
+    for (const [key, value] of Object.entries(context)) {
+        const lowerKey = key.toLowerCase();
+
+        const isSensitive = SENSITIVE_KEYS.has(lowerKey) ||
+            [...SENSITIVE_KEYS].some(k => lowerKey.includes(k));
+
+        if (isSensitive && value !== undefined && value !== null) {
+            result[key] = '[REDACTED]';
+        } else if (typeof value === 'string') {
+            result[key] = redactSensitive(value);
+        } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            result[key] = sanitizeContext(value as LogContext);
+        } else {
+            result[key] = value;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Remove control characters from log messages to prevent log injection
+ */
+function sanitizeMessage(message: string): string {
+    let result = '';
+    for (const char of message) {
+        const code = char.charCodeAt(0);
+        // Allow valid printable characters (>= 32), newlines (10), tabs (9), and carriage returns (13)
+        // Exclude DEL (127)
+        if ((code >= 32 && code !== 127) || code === 10 || code === 9 || code === 13) {
+            result += char;
+        }
+    }
+    return result;
+}
+
+/**
+ * RFC 5424 severity priority (lower number = higher severity)
+ */
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+    emergency: 0,
+    alert: 1,
+    critical: 2,
+    error: 3,
+    warning: 4,
+    notice: 5,
+    info: 6,
+    debug: 7
+};
+
+/**
+ * MCP-aware structured logger with dual-mode output
+ * 
+ * Follows MCP Server Logging Standards:
+ * - Centralized logger writing to stderr only (stdout reserved for MCP protocol)
+ * - Include: module, operation, entityId, context, stack traces
+ * - Module-prefixed codes (e.g., MYSQL_CONNECT_FAILED, AUTH_TOKEN_INVALID)
+ * - Severity: RFC 5424 levels
+ * - Format: [timestamp] [LEVEL] [MODULE] [CODE] message {context}
+ */
+class Logger {
+    private minLevel: LogLevel = 'info';
+    private loggerName = 'mysql-mcp';
+    private defaultModule: LogModule = 'SERVER';
+
+    /**
+     * Set the minimum log level
+     */
+    setLevel(level: LogLevel): void {
+        this.minLevel = level;
+    }
+
+    /**
+     * Get the current minimum log level
+     */
+    getLevel(): LogLevel {
+        return this.minLevel;
+    }
+
+    /**
+     * Set the logger name
+     */
+    setLoggerName(name: string): void {
+        this.loggerName = name;
+    }
+
+    /**
+     * Get the logger name
+     */
+    getLoggerName(): string {
+        return this.loggerName;
+    }
+
+    /**
+     * Set the default module for logs without explicit module
+     */
+    setDefaultModule(module: LogModule): void {
+        this.defaultModule = module;
+    }
+
+    private shouldLog(level: LogLevel): boolean {
+        return LEVEL_PRIORITY[level] <= LEVEL_PRIORITY[this.minLevel];
+    }
+
+    /**
+     * Format log entry according to MCP logging standard
+     * Format: [timestamp] [LEVEL] [MODULE] [CODE] message {context}
+     */
+    private formatEntry(entry: LogEntry): string {
+        const parts: string[] = [
+            `[${entry.timestamp}]`,
+            `[${entry.level.toUpperCase()}]`
+        ];
+
+        // Add module if present
+        if (entry.module) {
+            parts.push(`[${entry.module}]`);
+        }
+
+        // Add code if present
+        if (entry.code) {
+            parts.push(`[${entry.code}]`);
+        }
+
+        // Add message
+        parts.push(entry.message);
+
+        // Add context if present (excluding module and code which are already in the format)
+        if (entry.context) {
+            // Destructure out fields that are already in the log line format
+            const { module, code, ...restContext } = entry.context;
+            void module; void code; // Intentionally unused - already in format
+            if (Object.keys(restContext).length > 0) {
+                const sanitizedContext = sanitizeContext(restContext);
+                parts.push(JSON.stringify(sanitizedContext));
+            }
+        }
+
+        return parts.join(' ');
+    }
+
+    /**
+     * Core logging method
+     */
+    private log(level: LogLevel, message: string, context?: LogContext): void {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+
+        const sanitizedMessage = sanitizeMessage(redactSensitive(message));
+
+        const entry: LogEntry = {
+            level,
+            module: context?.module ?? this.defaultModule,
+            code: context?.code,
+            message: sanitizedMessage,
+            timestamp: new Date().toISOString(),
+            context
+        };
+
+        const formatted = this.formatEntry(entry);
+
+        // Write to stderr to avoid interfering with MCP stdio transport
+        console.error(formatted);
+    }
+
+    // =========================================================================
+    // Convenience methods for each log level
+    // =========================================================================
+
+    debug(message: string, context?: LogContext): void {
+        this.log('debug', message, context);
+    }
+
+    info(message: string, context?: LogContext): void {
+        this.log('info', message, context);
+    }
+
+    notice(message: string, context?: LogContext): void {
+        this.log('notice', message, context);
+    }
+
+    warn(message: string, context?: LogContext): void {
+        this.log('warning', message, context);
+    }
+
+    warning(message: string, context?: LogContext): void {
+        this.log('warning', message, context);
+    }
+
+    error(message: string, context?: LogContext): void {
+        this.log('error', message, context);
+    }
+
+    critical(message: string, context?: LogContext): void {
+        this.log('critical', message, context);
+    }
+
+    alert(message: string, context?: LogContext): void {
+        this.log('alert', message, context);
+    }
+
+    emergency(message: string, context?: LogContext): void {
+        this.log('emergency', message, context);
+    }
+
+    // =========================================================================
+    // Module-scoped logging helpers
+    // =========================================================================
+
+    /**
+     * Create a child logger scoped to a specific module
+     */
+    forModule(module: LogModule): ModuleLogger {
+        return new ModuleLogger(this, module);
+    }
+}
+
+/**
+ * Module-scoped logger for cleaner code in specific modules
+ */
+class ModuleLogger {
+    constructor(
+        private parent: Logger,
+        private module: LogModule
+    ) { }
+
+    private withModule(context?: LogContext): LogContext {
+        return { ...context, module: this.module };
+    }
+
+    debug(message: string, context?: LogContext): void {
+        this.parent.debug(message, this.withModule(context));
+    }
+
+    info(message: string, context?: LogContext): void {
+        this.parent.info(message, this.withModule(context));
+    }
+
+    notice(message: string, context?: LogContext): void {
+        this.parent.notice(message, this.withModule(context));
+    }
+
+    warn(message: string, context?: LogContext): void {
+        this.parent.warn(message, this.withModule(context));
+    }
+
+    warning(message: string, context?: LogContext): void {
+        this.parent.warning(message, this.withModule(context));
+    }
+
+    error(message: string, context?: LogContext): void {
+        this.parent.error(message, this.withModule(context));
+    }
+
+    critical(message: string, context?: LogContext): void {
+        this.parent.critical(message, this.withModule(context));
+    }
+
+    alert(message: string, context?: LogContext): void {
+        this.parent.alert(message, this.withModule(context));
+    }
+
+    emergency(message: string, context?: LogContext): void {
+        this.parent.emergency(message, this.withModule(context));
+    }
+}
+
+export const logger = new Logger();
+
+// Initialize log level from environment
+const envLevel = process.env['LOG_LEVEL']?.toLowerCase();
+if (envLevel && envLevel in LEVEL_PRIORITY) {
+    logger.setLevel(envLevel as LogLevel);
+}

package/src/utils/promptGenerator.ts

@@ -0,0 +1,74 @@
+/**
+ * Prompt generator utilities
+ * 
+ * Helpers for generating tool documentation and discovery prompts.
+ */
+import type { ToolDefinition } from '../types/index.js';
+
+/**
+ * Generate a compact index of all tools grouped by category
+ */
+export function generateCompactIndex(tools: ToolDefinition[]): string {
+    // Group tools by category
+    const groups: Record<string, ToolDefinition[]> = {};
+
+    for (const tool of tools) {
+        const group = tool.group ?? 'other';
+        groups[group] ??= [];
+        groups[group].push(tool);
+    }
+
+    // Generate compact format
+    const lines: string[] = [];
+    for (const [group, groupTools] of Object.entries(groups)) {
+        lines.push(`### ${group} (${String(groupTools.length)} tools)`);
+        lines.push('');
+        for (const tool of groupTools) {
+            lines.push(`- **${tool.name}**: ${tool.description}`);
+        }
+        lines.push('');
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate a discovery prompt with common use cases
+ */
+export function generateDiscoveryPrompt(tools: ToolDefinition[]): string {
+    // Find commonly used tools based on tags
+    const queryTools = tools.filter(t =>
+        t.name.includes('query') || t.name.includes('read') || t.name.includes('write')
+    ).slice(0, 3);
+
+    const schemaTools = tools.filter(t =>
+        t.name.includes('table') || t.name.includes('schema') || t.name.includes('describe')
+    ).slice(0, 3);
+
+    const perfTools = tools.filter(t =>
+        t.name.includes('explain') || t.name.includes('performance') || t.name.includes('stats')
+    ).slice(0, 3);
+
+    const lines: string[] = [
+        '## Quick Start',
+        '',
+        '### Query Data',
+    ];
+
+    for (const tool of queryTools) {
+        lines.push(`- \`${tool.name}\`: ${tool.description}`);
+    }
+
+    lines.push('', '### Explore Schema');
+    for (const tool of schemaTools) {
+        lines.push(`- \`${tool.name}\`: ${tool.description}`);
+    }
+
+    lines.push('', '### Analyze Performance');
+    for (const tool of perfTools) {
+        lines.push(`- \`${tool.name}\`: ${tool.description}`);
+    }
+
+    lines.push('');
+    return lines.join('\n');
+}

package/src/utils/validators.ts

@@ -0,0 +1,181 @@
+/**
+ * mysql-mcp - Input Validators
+ * 
+ * Centralized input validation utilities for SQL security.
+ */
+
+/**
+ * Validation error for security-related input issues
+ */
+export class ValidationError extends Error {
+    constructor(message: string, public readonly field: string) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Valid MySQL identifier pattern
+ * - Must start with letter or underscore
+ * - Can contain letters, numbers, underscores
+ * - Max length 64 characters (MySQL limit)
+ */
+const IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]{0,63}$/;
+
+/**
+ * Extended identifier pattern allowing dots for schema.table format
+ */
+const QUALIFIED_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]{0,63}(\.[a-zA-Z_][a-zA-Z0-9_]{0,63})?$/;
+
+/**
+ * Dangerous patterns in WHERE clauses that indicate SQL injection attempts
+ */
+const DANGEROUS_WHERE_PATTERNS = [
+    // Stacked queries - semicolon followed by SQL keyword
+    /;\s*(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|EXEC|EXECUTE)\b/i,
+    // SQL comments that could hide malicious code
+    /--\s*$/m,
+    /\/\*[\s\S]*?\*\//,
+    // Query manipulation keywords (usually not in WHERE)
+    /\bUNION\s+(ALL\s+)?SELECT\b/i,
+    /\bEXCEPT\s+SELECT\b/i,
+    /\bINTERSECT\s+SELECT\b/i,
+    // Dangerous functions
+    /\bINTO\s+(OUTFILE|DUMPFILE)\b/i,
+    /\bLOAD_FILE\s*\(/i,
+    // Information schema probing (common in attacks)
+    /\bINFORMATION_SCHEMA\b.*\bTABLES\b/i,
+    // Benchmark/sleep (timing attacks)
+    /\bBENCHMARK\s*\(/i,
+    /\bSLEEP\s*\(/i,
+];
+
+/**
+ * Validate a SQL identifier (table name, column name, schema name)
+ * 
+ * @param name - The identifier to validate
+ * @param type - Type of identifier for error messages
+ * @throws ValidationError if identifier is invalid
+ */
+export function validateIdentifier(
+    name: string,
+    type: 'table' | 'column' | 'schema' | 'database' | 'index' | 'view' | 'event' | 'procedure' | 'function' = 'table'
+): void {
+    if (!name || typeof name !== 'string') {
+        throw new ValidationError(`${type} name must be a non-empty string`, type);
+    }
+
+    if (name.length > 64) {
+        throw new ValidationError(`${type} name exceeds maximum length of 64 characters`, type);
+    }
+
+    if (!IDENTIFIER_PATTERN.test(name)) {
+        throw new ValidationError(
+            `Invalid ${type} name: must start with letter/underscore and contain only alphanumeric characters`,
+            type
+        );
+    }
+}
+
+/**
+ * Validate a qualified identifier (e.g., schema.table)
+ * 
+ * @param name - The qualified identifier to validate
+ * @param type - Type of identifier for error messages
+ * @throws ValidationError if identifier is invalid
+ */
+export function validateQualifiedIdentifier(
+    name: string,
+    type: 'table' | 'column' | 'view' = 'table'
+): void {
+    if (!name || typeof name !== 'string') {
+        throw new ValidationError(`${type} name must be a non-empty string`, type);
+    }
+
+    if (!QUALIFIED_IDENTIFIER_PATTERN.test(name)) {
+        throw new ValidationError(
+            `Invalid ${type} name: must be alphanumeric with optional schema prefix (schema.name)`,
+            type
+        );
+    }
+}
+
+/**
+ * Escape a SQL identifier for safe inclusion in queries
+ * 
+ * @param name - The identifier to escape
+ * @returns Escaped identifier (backticks escaped)
+ */
+export function escapeIdentifier(name: string): string {
+    // Replace backticks with double backticks (MySQL escaping)
+    return name.replace(/`/g, '``');
+}
+
+/**
+ * Validate a WHERE clause for dangerous SQL injection patterns
+ * 
+ * This performs pattern-based detection of common SQL injection attempts.
+ * It allows legitimate complex WHERE clauses while blocking known attack patterns.
+ * 
+ * @param where - The WHERE clause to validate (without the WHERE keyword)
+ * @throws ValidationError if dangerous patterns are detected
+ */
+export function validateWhereClause(where: string | undefined): void {
+    if (where === undefined || where === null || typeof where !== 'string') {
+        return; // Empty/null WHERE is valid (will be skipped)
+    }
+
+    const trimmed = where.trim();
+    if (trimmed.length === 0) {
+        return;
+    }
+
+    for (const pattern of DANGEROUS_WHERE_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            throw new ValidationError(
+                'WHERE clause contains potentially dangerous SQL patterns',
+                'where'
+            );
+        }
+    }
+
+    // Check for unbalanced quotes (sign of injection attempt)
+    // Note: escaped quotes ('') count as 2, so we check odd counts
+    // after removing escaped quotes
+    const unescapedSingles = trimmed.replace(/''/g, '').match(/'/g);
+    const unescapedDoubles = trimmed.replace(/""/g, '').match(/"/g);
+
+    if ((unescapedSingles?.length ?? 0) % 2 !== 0) {
+        throw new ValidationError(
+            'WHERE clause contains unbalanced single quotes',
+            'where'
+        );
+    }
+
+    if ((unescapedDoubles?.length ?? 0) % 2 !== 0) {
+        throw new ValidationError(
+            'WHERE clause contains unbalanced double quotes',
+            'where'
+        );
+    }
+}
+
+/**
+ * Validate a LIKE pattern for safe usage
+ * Already used in monitoring.ts, but centralized here for consistency
+ * 
+ * @param pattern - The LIKE pattern to escape
+ * @returns Escaped pattern safe for SQL
+ */
+export function escapeLikePattern(pattern: string): string {
+    // Escape single quotes for selected text
+    return pattern.replace(/'/g, "''");
+}
+
+/**
+ * Escape a potentially qualified table name
+ * Handles "table" -> "`table`" and "db.table" -> "`db`.`table`"
+ */
+export function escapeQualifiedTable(table: string): string {
+    return table.split('.').map(part => `\`${part.replace(/`/g, '``')}\``).join('.');
+}