@neverinfamous/mysql-mcp 2.1.0

package/src/adapters/mysql/tools/shell/__tests__/utilities.test.ts

@@ -0,0 +1,154 @@
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as child_process from 'child_process';
+import { createMockMySQLAdapter, createMockRequestContext } from '../../../../../__tests__/mocks/index.js';
+import { createShellCheckUpgradeTool } from '../utilities.js';
+
+vi.mock('child_process', () => ({
+    spawn: vi.fn()
+}));
+
+describe('Shell Utilities Tools', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+    let mockSpawn: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+        mockSpawn = child_process.spawn as any;
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    function setupMockSpawn(stdout = '', stderr = '', exitCode = 0) {
+        // Explicitly clear any previous call history
+        mockSpawn.mockClear();
+
+        const mockChild = {
+            stdout: {
+                on: vi.fn().mockImplementation((event, cb) => {
+                    if (event === 'data') cb(Buffer.from(stdout));
+                })
+            },
+            stderr: {
+                on: vi.fn().mockImplementation((event, cb) => {
+                    if (event === 'data') cb(Buffer.from(stderr));
+                })
+            },
+            stdin: {
+                write: vi.fn(),
+                end: vi.fn()
+            },
+            on: vi.fn().mockImplementation((event, cb) => {
+                if (event === 'close') cb(exitCode);
+            }),
+            kill: vi.fn()
+        };
+        mockSpawn.mockReturnValue(mockChild);
+        return mockChild;
+    }
+
+    describe('mysqlsh_check_upgrade', () => {
+        it('should run upgrade check and return JSON result', async () => {
+            const successJson = JSON.stringify({ success: true, result: { status: 'OK' } });
+            setupMockSpawn(`${successJson}\n`, '');
+
+            const tool = createShellCheckUpgradeTool();
+            const result = await tool.handler({ targetVersion: '8.0.35' }, mockContext) as any;
+
+            expect(result.success).toBe(true);
+            expect(result.upgradeCheck).toEqual({ status: 'OK' });
+
+            // Check command args
+            const callArgs = mockSpawn.mock.calls[0][1];
+            expect(callArgs).toContain('--uri');
+            expect(callArgs).toContain('--js');
+            expect(callArgs[4]).toContain('util.checkForServerUpgrade');
+        });
+
+        it('should return raw output if JSON parsing fails', async () => {
+            setupMockSpawn('Raw text output', '', 0);
+
+            const tool = createShellCheckUpgradeTool();
+            const result = await tool.handler({}, mockContext) as any;
+
+            expect(result.success).toBe(true);
+            expect(result.upgradeCheck).toEqual({ raw: 'Raw text output' });
+        });
+
+        it('should handle JSON parsing errors', async () => {
+            // Mock valid JSON first line but invalid second, or just invalid json
+            // execShellJS parses output lines from bottom up looking for JSON
+            const shellOutput = `
+             some logs
+             { invalid json }
+             `;
+
+            // We need to fail execution to bubble up the stderr/stdout if parsing fails
+            setupMockSpawn(shellOutput, '', 1);
+
+            const tool = createShellCheckUpgradeTool();
+
+            await expect(tool.handler({
+                targetVersion: '8.4.0'
+            }, mockContext)).rejects.toThrow();
+        });
+
+        it('should return raw output if JSON parsing fails but exit code is 0', async () => {
+            setupMockSpawn('Non-JSON output', '', 0);
+
+            const tool = createShellCheckUpgradeTool();
+            const result = await tool.handler({ targetVersion: '8.0.0' }, mockContext) as any;
+
+            expect(result.upgradeCheck.raw).toBe('Non-JSON output');
+        });
+
+        it('should support outputFormat option', async () => {
+            setupMockSpawn(JSON.stringify({ success: true }));
+
+            const tool = createShellCheckUpgradeTool();
+            await tool.handler({
+                targetVersion: '8.4.0',
+                outputFormat: 'TEXT'
+            }, mockContext);
+
+            const jsArg = mockSpawn.mock.calls[0][1][4];
+            expect(jsArg).toContain('outputFormat: "TEXT"');
+        });
+
+        it('should include targetVersion option when provided', async () => {
+            setupMockSpawn(JSON.stringify({ success: true }));
+
+            const tool = createShellCheckUpgradeTool();
+            await tool.handler({ targetVersion: '8.4.0' }, mockContext);
+
+            const jsArg = mockSpawn.mock.calls[0][1][4] as string;
+            expect(jsArg).toContain('targetVersion: "8.4.0"');
+        });
+
+        it('should include outputFormat option when provided alone', async () => {
+            setupMockSpawn(JSON.stringify({ success: true }));
+
+            const tool = createShellCheckUpgradeTool();
+            await tool.handler({ outputFormat: 'JSON' }, mockContext);
+
+            const jsArg = mockSpawn.mock.calls[0][1][4] as string;
+            expect(jsArg).toContain('outputFormat: "JSON"');
+        });
+
+        it('should include both options when both provided', async () => {
+            setupMockSpawn(JSON.stringify({ success: true }));
+
+            const tool = createShellCheckUpgradeTool();
+            await tool.handler({ targetVersion: '9.0.0', outputFormat: 'TEXT' }, mockContext);
+
+            const jsArg = mockSpawn.mock.calls[0][1][4] as string;
+            expect(jsArg).toContain('targetVersion: "9.0.0"');
+            expect(jsArg).toContain('outputFormat: "TEXT"');
+        });
+    });
+});

package/src/adapters/mysql/tools/shell/backup.ts

@@ -0,0 +1,215 @@
+/**
+ * MySQL Shell - Backup Tools
+ * 
+ * Tools for creating database dumps using MySQL Shell.
+ */
+
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import {
+    ShellDumpInstanceInputSchema,
+    ShellDumpSchemasInputSchema,
+    ShellDumpTablesInputSchema
+} from '../../types/shell-types.js';
+import { escapeForJS, execShellJS } from './common.js';
+
+/**
+ * Dump entire MySQL instance
+ */
+export function createShellDumpInstanceTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_dump_instance',
+        title: 'MySQL Shell Dump Instance',
+        description: 'Dump entire MySQL instance using util.dumpInstance(). Creates a compressed, parallel dump of all schemas (excluding system schemas). Ideal for full backups and migrations.',
+        group: 'shell',
+        inputSchema: ShellDumpInstanceInputSchema,
+        requiredScopes: ['admin'],
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { outputDir, threads, compression, dryRun, includeSchemas, excludeSchemas, consistent, users } =
+                ShellDumpInstanceInputSchema.parse(params);
+
+            const escapedPath = outputDir.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            if (threads) {
+                options.push(`threads: ${threads}`);
+            }
+            if (compression && compression !== 'zstd') {
+                options.push(`compression: "${compression}"`);
+            }
+            if (dryRun) {
+                options.push('dryRun: true');
+            }
+            if (includeSchemas && includeSchemas.length > 0) {
+                options.push(`includeSchemas: ${JSON.stringify(includeSchemas)}`);
+            }
+            if (excludeSchemas && excludeSchemas.length > 0) {
+                options.push(`excludeSchemas: ${JSON.stringify(excludeSchemas)}`);
+            }
+            if (consistent !== undefined && !consistent) {
+                options.push('consistent: false');
+            }
+            if (users !== undefined && !users) {
+                options.push('users: false');
+            }
+
+            const optionsStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
+            const jsCode = `return util.dumpInstance("${escapedPath}"${optionsStr});`;
+
+            const result = await execShellJS(jsCode, { timeout: 3600000 }); // 1 hour timeout
+
+            return {
+                success: true,
+                outputDir,
+                dryRun: dryRun ?? false,
+                result
+            };
+        }
+    };
+}
+
+/**
+ * Dump selected schemas
+ */
+export function createShellDumpSchemasTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_dump_schemas',
+        title: 'MySQL Shell Dump Schemas',
+        description: 'Dump selected schemas using util.dumpSchemas(). Creates a compressed, parallel dump of specified schemas. Use for partial backups.',
+        group: 'shell',
+        inputSchema: ShellDumpSchemasInputSchema,
+        requiredScopes: ['admin'],
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { schemas, outputDir, threads, compression, dryRun, includeTables, excludeTables, ddlOnly } =
+                ShellDumpSchemasInputSchema.parse(params);
+
+            const escapedPath = outputDir.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            if (threads) {
+                options.push(`threads: ${threads}`);
+            }
+            if (compression && compression !== 'zstd') {
+                options.push(`compression: "${compression}"`);
+            }
+            if (dryRun) {
+                options.push('dryRun: true');
+            }
+            if (includeTables && includeTables.length > 0) {
+                options.push(`includeTables: ${JSON.stringify(includeTables)}`);
+            }
+            if (excludeTables && excludeTables.length > 0) {
+                options.push(`excludeTables: ${JSON.stringify(excludeTables)}`);
+            }
+            // ddlOnly mode disables all metadata that requires extra privileges
+            if (ddlOnly) {
+                options.push('events: false');
+                options.push('triggers: false');
+                options.push('routines: false');
+            }
+
+            const optionsStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
+            const jsCode = `return util.dumpSchemas(${JSON.stringify(schemas)}, "${escapedPath}"${optionsStr});`;
+
+            try {
+                const result = await execShellJS(jsCode, { timeout: 3600000 });
+                return {
+                    success: true,
+                    schemas,
+                    outputDir,
+                    dryRun: dryRun ?? false,
+                    ddlOnly: ddlOnly ?? false,
+                    result
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('EVENT') || errorMessage.includes('TRIGGER') || errorMessage.includes('privilege')) {
+                    throw new Error(
+                        `Dump failed due to missing privileges: ${errorMessage}. ` +
+                        `Try setting ddlOnly: true to skip events, triggers, and routines.`
+                    );
+                }
+                throw error;
+            }
+        }
+    };
+}
+
+/**
+ * Dump specific tables
+ */
+export function createShellDumpTablesTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_dump_tables',
+        title: 'MySQL Shell Dump Tables',
+        description: 'Dump specific tables using util.dumpTables(). Creates a compressed, parallel dump of specified tables from a schema.',
+        group: 'shell',
+        inputSchema: ShellDumpTablesInputSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { schema, tables, outputDir, threads, compression, where, all } =
+                ShellDumpTablesInputSchema.parse(params);
+
+            const escapedPath = outputDir.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            if (threads) {
+                options.push(`threads: ${threads}`);
+            }
+            if (compression && compression !== 'zstd') {
+                options.push(`compression: "${compression}"`);
+            }
+            if (where && Object.keys(where).length > 0) {
+                const whereEntries = Object.entries(where)
+                    .map(([tbl, cond]) => `"${escapeForJS(tbl)}": "${escapeForJS(cond)}"`)
+                    .join(', ');
+                options.push(`where: { ${whereEntries} }`);
+            }
+            // When all is explicitly false, disable triggers/routines dumping
+            if (!all) {
+                options.push('triggers: false');
+            }
+
+            const optionsStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
+            const jsCode = `return util.dumpTables("${schema}", ${JSON.stringify(tables)}, "${escapedPath}"${optionsStr});`;
+
+            try {
+                const result = await execShellJS(jsCode, { timeout: 3600000 });
+                return {
+                    success: true,
+                    schema,
+                    tables,
+                    outputDir,
+                    triggersExcluded: !all,
+                    result
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('privilege') || errorMessage.includes('Access denied') || errorMessage.includes('TRIGGER')) {
+                    throw new Error(
+                        `Dump failed due to missing privileges: ${errorMessage}. ` +
+                        `Try setting all: false to skip triggers if you lack TRIGGER privilege.`
+                    );
+                }
+                if (errorMessage.includes('Fatal error during dump')) {
+                    throw new Error(
+                        `Dump failed: ${errorMessage}. ` +
+                        `This may be due to missing privileges on the schema. Try setting all: false to skip metadata that requires extra privileges.`
+                    );
+                }
+                throw error;
+            }
+        }
+    };
+}

package/src/adapters/mysql/tools/shell/common.ts

@@ -0,0 +1,227 @@
+/**
+ * MySQL Shell - Shared Configuration and Utilities
+ * 
+ * Configuration helpers and subprocess execution utilities shared by all shell tools.
+ */
+
+import { spawn } from 'child_process';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+export interface ShellConfig {
+    binPath: string;
+    connectionUri: string;
+    xConnectionUri: string;
+    timeout: number;
+    workDir: string;
+}
+
+/**
+ * Get MySQL Shell configuration from environment variables
+ */
+export function getShellConfig(): ShellConfig {
+    const host = process.env['MYSQL_HOST'] ?? 'localhost';
+    const port = process.env['MYSQL_PORT'] ?? '3306';
+    const xPort = process.env['MYSQL_XPORT'] ?? '33060';
+    const user = process.env['MYSQL_USER'] ?? 'root';
+    const password = process.env['MYSQL_PASSWORD'] ?? '';
+    const database = process.env['MYSQL_DATABASE'] ?? '';
+
+    // Build connection URI for mysqlsh (classic protocol)
+    const connectionUri = password
+        ? `mysql://${user}:${encodeURIComponent(password)}@${host}:${port}/${database}`
+        : `mysql://${user}@${host}:${port}/${database}`;
+
+    // Build X Protocol connection URI for document operations
+    const xConnectionUri = password
+        ? `mysqlx://${user}:${encodeURIComponent(password)}@${host}:${xPort}/${database}`
+        : `mysqlx://${user}@${host}:${xPort}/${database}`;
+
+    return {
+        binPath: process.env['MYSQLSH_PATH'] ?? 'mysqlsh',
+        connectionUri,
+        xConnectionUri,
+        timeout: parseInt(process.env['MYSQLSH_TIMEOUT'] ?? '300000', 10),
+        workDir: process.env['MYSQLSH_WORK_DIR'] ?? process.cwd()
+    };
+}
+
+/**
+ * Escape a string for safe embedding in JavaScript string literals.
+ * Escapes backslashes first, then double quotes, to prevent injection attacks.
+ */
+export function escapeForJS(str: string): string {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+// =============================================================================
+// Subprocess Execution Helpers
+// =============================================================================
+
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+
+/**
+ * Execute MySQL Shell command as subprocess
+ */
+export async function execMySQLShell(
+    args: string[],
+    options?: {
+        timeout?: number;
+        cwd?: string;
+        input?: string;
+    }
+): Promise<ExecResult> {
+    const config = getShellConfig();
+
+    return new Promise((resolve, reject) => {
+        const timeout = options?.timeout ?? config.timeout;
+        const cwd = options?.cwd ?? config.workDir;
+
+        const child = spawn(config.binPath, args, {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true
+        });
+
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill('SIGTERM');
+            reject(new Error(`MySQL Shell command timed out after ${timeout}ms`));
+        }, timeout);
+
+        child.stdout.on('data', (data: Buffer) => {
+            stdout += data.toString();
+        });
+
+        child.stderr.on('data', (data: Buffer) => {
+            stderr += data.toString();
+        });
+
+        if (options?.input) {
+            child.stdin.write(options.input);
+            child.stdin.end();
+        }
+
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (!killed) {
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: code ?? 0
+                });
+            }
+        });
+
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            if (err.message.includes('ENOENT')) {
+                reject(new Error(
+                    `MySQL Shell not found at '${config.binPath}'. ` +
+                    'Please install MySQL Shell or set MYSQLSH_PATH environment variable.'
+                ));
+            } else {
+                reject(err);
+            }
+        });
+    });
+}
+
+/**
+ * Execute a JavaScript expression in MySQL Shell and return JSON result
+ */
+export async function execShellJS(
+    jsCode: string,
+    options?: { timeout?: number }
+): Promise<unknown> {
+    const config = getShellConfig();
+
+    // Wrap code to output JSON result
+    const wrappedCode = `
+        var __result__;
+        try {
+            __result__ = (function() { ${jsCode} })();
+            print(JSON.stringify({ success: true, result: __result__ }));
+        } catch (e) {
+            print(JSON.stringify({ success: false, error: e.message }));
+        }
+    `;
+
+    const result = await execMySQLShell([
+        '--uri', config.connectionUri,
+        '--js',
+        '-e', wrappedCode
+    ], options);
+
+    // Check for critical errors in stderr (excluding common warnings)
+    const stderrClean = result.stderr
+        .replace(/WARNING: Using a password on the command line interface can be insecure\.\s*/gi, '')
+        .trim();
+    
+    // Detect specific error conditions in stderr
+    if (stderrClean) {
+        // local_infile disabled error
+        if (stderrClean.includes('local_infile') || stderrClean.includes('Loading local data is disabled')) {
+            throw new Error(
+                `MySQL Shell operation failed: local_infile is disabled on the server. ` +
+                `Set updateServerSettings: true (requires SUPER or SYSTEM_VARIABLES_ADMIN privilege), ` +
+                `or manually run: SET GLOBAL local_infile = ON`
+            );
+        }
+        // Privilege errors
+        if (stderrClean.includes('privilege') || stderrClean.includes('Access denied')) {
+            throw new Error(`MySQL Shell operation failed due to insufficient privileges: ${stderrClean}`);
+        }
+        // Fatal dump errors
+        if (stderrClean.includes('Fatal error during dump')) {
+            throw new Error(
+                `MySQL Shell dump failed: ${stderrClean}. ` +
+                `This may be caused by missing privileges. For dumpSchemas, try excludeEvents: true. ` +
+                `For dumpTables, try all: false.`
+            );
+        }
+    }
+
+    // Try to parse JSON from output
+    const lines = result.stdout.trim().split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line) continue;
+        const trimmedLine = line.trim();
+        if (trimmedLine.startsWith('{')) {
+            let parsed: { success: boolean; result?: unknown; error?: string };
+            try {
+                parsed = JSON.parse(trimmedLine) as { success: boolean; result?: unknown; error?: string };
+            } catch {
+                continue;
+            }
+
+            if (!parsed.success) {
+                throw new Error(parsed.error ?? 'Unknown MySQL Shell error');
+            }
+            return parsed.result;
+        }
+    }
+
+    // If no JSON found but there's stderr content, that's likely an error
+    if (stderrClean && result.exitCode !== 0) {
+        throw new Error(stderrClean);
+    }
+
+    // If no JSON found, return raw output
+    if (result.exitCode !== 0) {
+        throw new Error(result.stderr || result.stdout || 'MySQL Shell command failed');
+    }
+
+    return { raw: result.stdout };
+}