@neverinfamous/mysql-mcp 2.1.0

package/src/adapters/mysql/tools/shell/data-transfer.ts

@@ -0,0 +1,256 @@
+/**
+ * MySQL Shell - Data Transfer Tools
+ * 
+ * Tools for importing and exporting data using MySQL Shell utilities.
+ */
+
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import {
+    ShellExportTableInputSchema,
+    ShellImportTableInputSchema,
+    ShellImportJSONInputSchema
+} from '../../types/shell-types.js';
+import { getShellConfig, escapeForJS, execShellJS, execMySQLShell } from './common.js';
+
+/**
+ * Export table to file
+ */
+export function createShellExportTableTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_export_table',
+        title: 'MySQL Shell Export Table',
+        description: 'Export a MySQL table to a file using util.exportTable(). Supports CSV, TSV, and JSON formats with filtering.',
+        group: 'shell',
+        inputSchema: ShellExportTableInputSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { schema, table, outputPath, format, where } =
+                ShellExportTableInputSchema.parse(params);
+
+            // Escape path for JavaScript
+            const escapedPath = outputPath.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            if (format === 'csv') {
+                options.push('fieldsTerminatedBy: ","');
+                options.push('fieldsEnclosedBy: "\\""');
+            } else if (format === 'tsv') {
+                options.push('fieldsTerminatedBy: "\\t"');
+            }
+            if (where) {
+                options.push(`where: "${escapeForJS(where)}"`);
+            }
+
+            const optionsStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
+            const jsCode = `return util.exportTable("${schema}.${table}", "${escapedPath}"${optionsStr});`;
+
+            const result = await execShellJS(jsCode);
+
+            return {
+                success: true,
+                schema,
+                table,
+                outputPath,
+                format,
+                result
+            };
+        }
+    };
+}
+
+/**
+ * Import table from file
+ */
+export function createShellImportTableTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_import_table',
+        title: 'MySQL Shell Import Table',
+        description: 'Parallel table import using util.importTable(). Imports CSV, TSV, or other delimited files into a MySQL table using multiple threads.',
+        group: 'shell',
+        inputSchema: ShellImportTableInputSchema,
+        requiredScopes: ['write'],
+        annotations: {
+            readOnlyHint: false,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { inputPath, schema, table, threads, skipRows, columns, fieldsTerminatedBy, linesTerminatedBy, updateServerSettings } =
+                ShellImportTableInputSchema.parse(params);
+
+            const escapedPath = inputPath.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            options.push(`schema: "${schema}"`);
+            options.push(`table: "${table}"`);
+            if (threads) {
+                options.push(`threads: ${threads}`);
+            }
+            if (skipRows !== undefined) {
+                options.push(`skipRows: ${skipRows}`);
+            }
+            if (columns && columns.length > 0) {
+                options.push(`columns: ${JSON.stringify(columns)}`);
+            }
+            if (fieldsTerminatedBy) {
+                options.push(`fieldsTerminatedBy: ${JSON.stringify(fieldsTerminatedBy)}`);
+            }
+            if (linesTerminatedBy) {
+                options.push(`linesTerminatedBy: ${JSON.stringify(linesTerminatedBy)}`);
+            }
+
+            // Build JavaScript code that optionally enables local_infile
+            let jsCode: string;
+            if (updateServerSettings) {
+                jsCode = `
+                    session.runSql("SET GLOBAL local_infile = ON");
+                    return util.importTable("${escapedPath}", { ${options.join(', ')} });
+                `;
+            } else {
+                jsCode = `return util.importTable("${escapedPath}", { ${options.join(', ')} });`;
+            }
+
+            try {
+                const result = await execShellJS(jsCode);
+                return {
+                    success: true,
+                    inputPath,
+                    schema,
+                    table,
+                    localInfileEnabled: updateServerSettings,
+                    result
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('local_infile') || errorMessage.includes('Loading local data is disabled')) {
+                    throw new Error(
+                        `Import failed: local_infile is disabled on the server. ` +
+                        `Either set updateServerSettings: true (requires SUPER or SYSTEM_VARIABLES_ADMIN privilege), ` +
+                        `or manually run: SET GLOBAL local_infile = ON`
+                    );
+                }
+                throw error;
+            }
+        }
+    };
+}
+
+/**
+ * Import JSON documents
+ */
+export function createShellImportJSONTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_import_json',
+        title: 'MySQL Shell Import JSON',
+        description: 'Import JSON documents from a file using util.importJson(). Can import into a collection (X DevAPI) or a table column. REQUIRES X Protocol (port 33060).',
+        group: 'shell',
+        inputSchema: ShellImportJSONInputSchema,
+        requiredScopes: ['write'],
+        annotations: {
+            readOnlyHint: false,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { inputPath, schema, collection, tableColumn, convertBsonTypes } =
+                ShellImportJSONInputSchema.parse(params);
+            const config = getShellConfig();
+
+            const escapedPath = inputPath.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            options.push(`schema: "${schema}"`);
+
+            if (tableColumn) {
+                // Importing to a table column
+                options.push(`table: "${collection}"`);
+                options.push(`tableColumn: "${tableColumn}"`);
+            } else {
+                // Importing to a collection
+                options.push(`collection: "${collection}"`);
+            }
+
+            if (convertBsonTypes) {
+                options.push('convertBsonTypes: true');
+            }
+
+            const jsCode = `return util.importJson("${escapedPath}", { ${options.join(', ')} });`;
+
+            // util.importJson() ALWAYS requires X Protocol (X DevAPI)
+            let result;
+            try {
+                result = await execMySQLShell([
+                    '--uri', config.xConnectionUri,
+                    '--js',
+                    '-e', `
+                        var __result__;
+                        try {
+                            __result__ = (function() { ${jsCode} })();
+                            print(JSON.stringify({ success: true, result: __result__ }));
+                        } catch (e) {
+                            print(JSON.stringify({ success: false, error: e.message }));
+                        }
+                    `
+                ]);
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new Error(
+                    `X Protocol connection failed: ${errorMessage}. ` +
+                    `Ensure MySQL X Plugin is enabled (port ${process.env['MYSQL_XPORT'] ?? '33060'}) ` +
+                    `and the user has access. Check: SHOW PLUGINS LIKE 'mysqlx';`
+                );
+            }
+
+            // Check for X Protocol access denied errors in stderr
+            if (result.stderr.includes('Access denied') || result.stderr.includes('1045')) {
+                throw new Error(
+                    `X Protocol authentication failed. The user may not have access via X Protocol (port ${process.env['MYSQL_XPORT'] ?? '33060'}). ` +
+                    `Verify: 1) X Plugin is enabled, 2) User has proper grants, 3) Authentication plugin is compatible (mysql_native_password or caching_sha2_password).`
+                );
+            }
+
+            // Parse result
+            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 {
+                        success: true,
+                        inputPath,
+                        schema,
+                        collection,
+                        protocol: 'X Protocol',
+                        result: parsed.result
+                    };
+                }
+            }
+
+            if (result.exitCode !== 0) {
+                throw new Error(result.stderr || result.stdout || 'MySQL Shell import failed');
+            }
+
+            return {
+                success: true,
+                inputPath,
+                schema,
+                collection,
+                protocol: 'X Protocol',
+                result: { raw: result.stdout }
+            };
+        }
+    };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * MySQL Shell Management Tools
+ * 
+ * Tools for executing MySQL Shell (mysqlsh) commands via subprocess.
+ * Provides access to util.* functions for backup, restore, migration, and scripting.
+ * 10 tools total.
+ * 
+ * MySQL Shell documentation:
+ * https://dev.mysql.com/doc/mysql-shell/8.0/en/
+ */
+
+import type { ToolDefinition } from '../../../../types/index.js';
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+
+// Import all tool creation functions from submodules
+import { createShellVersionTool } from './info.js';
+import { createShellCheckUpgradeTool } from './utilities.js';
+import {
+    createShellExportTableTool,
+    createShellImportTableTool,
+    createShellImportJSONTool
+} from './data-transfer.js';
+import {
+    createShellDumpInstanceTool,
+    createShellDumpSchemasTool,
+    createShellDumpTablesTool
+} from './backup.js';
+import {
+    createShellLoadDumpTool,
+    createShellRunScriptTool
+} from './restore.js';
+
+/**
+ * Get all MySQL Shell tools
+ */
+export function getShellTools(_adapter: MySQLAdapter): ToolDefinition[] {
+    return [
+        createShellVersionTool(),
+        createShellCheckUpgradeTool(),
+        createShellExportTableTool(),
+        createShellImportTableTool(),
+        createShellImportJSONTool(),
+        createShellDumpInstanceTool(),
+        createShellDumpSchemasTool(),
+        createShellDumpTablesTool(),
+        createShellLoadDumpTool(),
+        createShellRunScriptTool()
+    ];
+}

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

@@ -0,0 +1,45 @@
+/**
+ * MySQL Shell - Version and Info Tools
+ * 
+ * Tools for checking MySQL Shell version and installation status.
+ */
+
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import { ShellVersionInputSchema } from '../../types/shell-types.js';
+import { getShellConfig, execMySQLShell } from './common.js';
+
+/**
+ * Get MySQL Shell version and status
+ */
+export function createShellVersionTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_version',
+        title: 'MySQL Shell Version',
+        description: 'Get MySQL Shell version and installation status. Useful for verifying MySQL Shell is available before running other shell tools.',
+        group: 'shell',
+        inputSchema: ShellVersionInputSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true
+        },
+        handler: async (_params: unknown, _context: RequestContext) => {
+            const config = getShellConfig();
+
+            const result = await execMySQLShell(['--version']);
+
+            // Parse version from output like "mysqlsh   Ver 8.0.44 for Win64 on x86_64"
+            const versionRegex = /Ver\s+(\d+\.\d+\.\d+)/;
+            const versionMatch = versionRegex.exec(result.stdout);
+            const version = versionMatch ? versionMatch[1] : 'unknown';
+
+            return {
+                success: true,
+                version,
+                binPath: config.binPath,
+                rawOutput: result.stdout.trim()
+            };
+        }
+    };
+}

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

@@ -0,0 +1,153 @@
+/**
+ * MySQL Shell - Restore and Scripting Tools
+ * 
+ * Tools for restoring dumps and running custom scripts.
+ */
+
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import {
+    ShellLoadDumpInputSchema,
+    ShellRunScriptInputSchema
+} from '../../types/shell-types.js';
+import { getShellConfig, execShellJS, execMySQLShell } from './common.js';
+
+/**
+ * Load dump to instance
+ */
+export function createShellLoadDumpTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_load_dump',
+        title: 'MySQL Shell Load Dump',
+        description: 'Load a MySQL Shell dump using util.loadDump(). Restores data from a dump created by dumpInstance, dumpSchemas, or dumpTables. Supports parallel loading.',
+        group: 'shell',
+        inputSchema: ShellLoadDumpInputSchema,
+        requiredScopes: ['admin'],
+        annotations: {
+            readOnlyHint: false,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const {
+                inputDir, threads, dryRun, includeSchemas, excludeSchemas,
+                includeTables, excludeTables, ignoreExistingObjects, ignoreVersion, resetProgress, updateServerSettings
+            } = ShellLoadDumpInputSchema.parse(params);
+
+            const escapedPath = inputDir.replace(/\\/g, '\\\\');
+
+            const options: string[] = [];
+            if (threads) {
+                options.push(`threads: ${threads}`);
+            }
+            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 (includeTables && includeTables.length > 0) {
+                options.push(`includeTables: ${JSON.stringify(includeTables)}`);
+            }
+            if (excludeTables && excludeTables.length > 0) {
+                options.push(`excludeTables: ${JSON.stringify(excludeTables)}`);
+            }
+            if (ignoreExistingObjects) {
+                options.push('ignoreExistingObjects: true');
+            }
+            if (ignoreVersion) {
+                options.push('ignoreVersion: true');
+            }
+            if (resetProgress) {
+                options.push('resetProgress: true');
+            }
+
+            const optionsStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
+            
+            // Build JavaScript code that optionally enables local_infile
+            let jsCode: string;
+            if (updateServerSettings) {
+                jsCode = `
+                    session.runSql("SET GLOBAL local_infile = ON");
+                    return util.loadDump("${escapedPath}"${optionsStr});
+                `;
+            } else {
+                jsCode = `return util.loadDump("${escapedPath}"${optionsStr});`;
+            }
+
+            try {
+                const result = await execShellJS(jsCode, { timeout: 3600000 });
+                return {
+                    success: true,
+                    inputDir,
+                    dryRun: dryRun ?? false,
+                    localInfileEnabled: updateServerSettings,
+                    result
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('local_infile') || errorMessage.includes('Loading local data is disabled')) {
+                    throw new Error(
+                        `Load failed: local_infile is disabled on the server. ` +
+                        `Either set updateServerSettings: true (requires SUPER or SYSTEM_VARIABLES_ADMIN privilege), ` +
+                        `or manually run: SET GLOBAL local_infile = ON`
+                    );
+                }
+                throw error;
+            }
+        }
+    };
+}
+
+/**
+ * Execute script via MySQL Shell
+ */
+export function createShellRunScriptTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_run_script',
+        title: 'MySQL Shell Run Script',
+        description: 'Execute a JavaScript, Python, or SQL script via MySQL Shell. Provides access to X DevAPI, AdminAPI, and all MySQL Shell features.',
+        group: 'shell',
+        inputSchema: ShellRunScriptInputSchema,
+        requiredScopes: ['admin'],
+        annotations: {
+            readOnlyHint: false,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { script, language, timeout } = ShellRunScriptInputSchema.parse(params);
+            const config = getShellConfig();
+
+            // Build command based on language
+            let langFlag: string;
+            switch (language) {
+                case 'js':
+                    langFlag = '--js';
+                    break;
+                case 'py':
+                    langFlag = '--py';
+                    break;
+                case 'sql':
+                    langFlag = '--sql';
+                    break;
+            }
+
+            const args = [
+                '--uri', config.connectionUri,
+                langFlag,
+                '-e', script
+            ];
+
+            const result = await execMySQLShell(args, { timeout });
+
+            return {
+                success: result.exitCode === 0,
+                language,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr
+            };
+        }
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * MySQL Shell - Utility Tools
+ * 
+ * Tools for server maintenance and upgrade compatibility checking.
+ */
+
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import { ShellCheckUpgradeInputSchema } from '../../types/shell-types.js';
+import { getShellConfig, escapeForJS, execShellJS } from './common.js';
+
+/**
+ * Check server upgrade compatibility
+ */
+export function createShellCheckUpgradeTool(): ToolDefinition {
+    return {
+        name: 'mysqlsh_check_upgrade',
+        title: 'MySQL Shell Check Upgrade',
+        description: 'Check MySQL server upgrade compatibility using util.checkForServerUpgrade(). Identifies potential issues before upgrading to a newer MySQL version.',
+        group: 'shell',
+        inputSchema: ShellCheckUpgradeInputSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { targetVersion, outputFormat } = ShellCheckUpgradeInputSchema.parse(params);
+            const config = getShellConfig();
+
+            // Use connection URI string instead of session object
+            // The util.checkForServerUpgrade() accepts a URI string as first arg
+            const escapedUri = escapeForJS(config.connectionUri);
+            let jsCode = `return util.checkForServerUpgrade("${escapedUri}"`;
+
+            const options: string[] = [];
+            if (targetVersion) {
+                options.push(`targetVersion: "${targetVersion}"`);
+            }
+            if (outputFormat) {
+                options.push(`outputFormat: "${outputFormat}"`);
+            }
+
+            if (options.length > 0) {
+                jsCode += `, { ${options.join(', ')} }`;
+            }
+            jsCode += ');';
+
+            const result = await execShellJS(jsCode, { timeout: 120000 });
+
+            return {
+                success: true,
+                upgradeCheck: result
+            };
+        }
+    };
+}

package/src/adapters/mysql/tools/spatial/__tests__/geometry.test.ts

@@ -0,0 +1,101 @@
+/**
+ * mysql-mcp - Spatial Geometry Tools Unit Tests
+ * 
+ * Comprehensive tests for geometry.ts module functions.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+    createSpatialPointTool,
+    createSpatialPolygonTool
+} from '../geometry.js';
+import type { MySQLAdapter } from '../../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext, createMockQueryResult } from '../../../../../__tests__/mocks/index.js';
+
+describe('Spatial Geometry Tools', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+    });
+
+    describe('createSpatialPointTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialPointTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_point');
+            expect(tool.group).toBe('spatial');
+        });
+
+        it('should create point from coordinates', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                wkt: 'POINT(20 10)',
+                geoJson: '{"type":"Point","coordinates":[10,20]}'
+            }]));
+
+            const tool = createSpatialPointTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ longitude: 10, latitude: 20 }, mockContext) as { wkt: string; geoJson: any };
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            // With axis-order=long-lat, longitude comes first in POINT
+            expect(call).toContain('POINT(10 20)');
+            expect(call).toContain('axis-order=long-lat');
+            expect(result.wkt).toBe('POINT(20 10)');
+            expect(result.geoJson).toEqual({ type: 'Point', coordinates: [10, 20] });
+        });
+
+        it('should use default SRID 4326', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialPointTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({ longitude: 10, latitude: 20 }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('4326');
+        });
+
+        it('should handle custom SRID', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialPointTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({ longitude: 10, latitude: 20, srid: 3857 }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('3857');
+        });
+    });
+
+    describe('createSpatialPolygonTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialPolygonTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_polygon');
+        });
+
+        it('should create polygon from coordinates', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                wkt: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))',
+                geoJson: '{"type":"Polygon"}',
+                area: 100
+            }]));
+
+            const tool = createSpatialPolygonTool(mockAdapter as unknown as MySQLAdapter);
+            const coordinates = [
+                [[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]
+            ] as [number, number][][];
+
+            const result = await tool.handler({ coordinates }, mockContext) as { wkt: string; area: number };
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_GeomFromText(?)');
+            const args = mockAdapter.executeQuery.mock.calls[0][1] as any[];
+            expect(args[0]).toBe('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))');
+
+            expect(result.wkt).toBe('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))');
+            expect(result.area).toBe(100);
+        });
+    });
+});