@neverinfamous/mysql-mcp 2.1.0

package/src/adapters/mysql/tools/performance/analysis.ts

@@ -0,0 +1,322 @@
+/**
+ * MySQL Performance Tools - Analysis
+ * 
+ * Query analysis and performance monitoring tools.
+ * 8 tools: explain, explain_analyze, slow_queries, query_stats, index_usage, table_stats, buffer_pool_stats, thread_stats.
+ */
+
+
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import {
+    ExplainSchema,
+    SlowQuerySchema,
+    IndexUsageSchema,
+    TableStatsSchema
+} from '../../types.js';
+import { z } from 'zod';
+
+export function createExplainTool(adapter: MySQLAdapter): ToolDefinition {
+    return {
+        name: 'mysql_explain',
+        title: 'MySQL EXPLAIN',
+        description: 'Get query execution plan using EXPLAIN.',
+        group: 'performance',
+        inputSchema: ExplainSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { query, format } = ExplainSchema.parse(params);
+
+            const sql = format === 'JSON'
+                ? `EXPLAIN FORMAT=JSON ${query}`
+                : format === 'TREE'
+                    ? `EXPLAIN FORMAT=TREE ${query}`
+                    : `EXPLAIN ${query}`;
+
+            const result = await adapter.executeReadQuery(sql);
+
+            if (format === 'JSON' && result.rows?.[0] !== undefined) {
+                const explainRow = result.rows[0];
+                const jsonStr = explainRow['EXPLAIN'];
+                if (typeof jsonStr === 'string') {
+                    return { plan: JSON.parse(jsonStr) as unknown };
+                }
+            }
+
+            return { plan: result.rows };
+        }
+    };
+}
+
+export function createExplainAnalyzeTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({
+        query: z.string().describe('SQL query to analyze'),
+        format: z.enum(['JSON', 'TREE']).optional().default('TREE')
+    });
+
+    return {
+        name: 'mysql_explain_analyze',
+        title: 'MySQL EXPLAIN ANALYZE',
+        description: 'Get query execution plan with actual timing using EXPLAIN ANALYZE (MySQL 8.0+).',
+        group: 'performance',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { query, format } = schema.parse(params);
+
+            const sql = `EXPLAIN ANALYZE FORMAT=${format} ${query}`;
+            const result = await adapter.executeReadQuery(sql);
+
+            if (format === 'JSON' && result.rows?.[0] !== undefined) {
+                const explainRow = result.rows[0];
+                const jsonStr = explainRow['EXPLAIN'];
+                if (typeof jsonStr === 'string') {
+                    return { analysis: JSON.parse(jsonStr) as unknown };
+                }
+            }
+
+            return { analysis: result.rows };
+        }
+    };
+}
+
+export function createSlowQueriesTool(adapter: MySQLAdapter): ToolDefinition {
+    return {
+        name: 'mysql_slow_queries',
+        title: 'MySQL Slow Queries',
+        description: 'Get slow queries from performance_schema (if available).',
+        group: 'performance',
+        inputSchema: SlowQuerySchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { limit, minTime } = SlowQuerySchema.parse(params);
+
+            let sql = `
+                SELECT 
+                    DIGEST_TEXT as query,
+                    COUNT_STAR as executions,
+                    AVG_TIMER_WAIT/1000000000 as avg_time_ms,
+                    SUM_TIMER_WAIT/1000000000 as total_time_ms,
+                    SUM_ROWS_EXAMINED as rows_examined,
+                    SUM_ROWS_SENT as rows_sent
+                FROM performance_schema.events_statements_summary_by_digest
+            `;
+
+            if (minTime !== undefined) {
+                sql += ` WHERE AVG_TIMER_WAIT > ${minTime * 1000000000}`;
+            }
+
+            sql += ` ORDER BY AVG_TIMER_WAIT DESC LIMIT ${limit}`;
+
+            const result = await adapter.executeReadQuery(sql);
+            return { slowQueries: result.rows };
+        }
+    };
+}
+
+export function createQueryStatsTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({
+        orderBy: z.enum(['total_time', 'avg_time', 'executions']).optional().default('total_time'),
+        limit: z.number().optional().default(20)
+    });
+
+    return {
+        name: 'mysql_query_stats',
+        title: 'MySQL Query Stats',
+        description: 'Get query statistics from performance_schema.',
+        group: 'performance',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { orderBy, limit } = schema.parse(params);
+
+            const orderColumn = {
+                total_time: 'SUM_TIMER_WAIT',
+                avg_time: 'AVG_TIMER_WAIT',
+                executions: 'COUNT_STAR'
+            }[orderBy];
+
+            const sql = `
+                SELECT 
+                    SCHEMA_NAME as database_name,
+                    DIGEST_TEXT as query_text,
+                    COUNT_STAR as execution_count,
+                    AVG_TIMER_WAIT/1000000000 as avg_time_ms,
+                    MAX_TIMER_WAIT/1000000000 as max_time_ms,
+                    SUM_TIMER_WAIT/1000000000 as total_time_ms,
+                    SUM_ROWS_EXAMINED as total_rows_examined,
+                    SUM_ROWS_SENT as total_rows_sent,
+                    FIRST_SEEN as first_seen,
+                    LAST_SEEN as last_seen
+                FROM performance_schema.events_statements_summary_by_digest
+                WHERE DIGEST_TEXT IS NOT NULL
+                ORDER BY ${orderColumn} DESC
+                LIMIT ${limit}
+            `;
+
+            const result = await adapter.executeReadQuery(sql);
+            return { queries: result.rows };
+        }
+    };
+}
+
+export function createIndexUsageTool(adapter: MySQLAdapter): ToolDefinition {
+    return {
+        name: 'mysql_index_usage',
+        title: 'MySQL Index Usage',
+        description: 'Get index usage statistics from performance_schema.',
+        group: 'performance',
+        inputSchema: IndexUsageSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { table } = IndexUsageSchema.parse(params);
+
+            let sql = `
+                SELECT 
+                    object_schema as database_name,
+                    object_name as table_name,
+                    index_name,
+                    count_read,
+                    count_write,
+                    count_fetch,
+                    count_insert,
+                    count_update,
+                    count_delete
+                FROM performance_schema.table_io_waits_summary_by_index_usage
+                WHERE index_name IS NOT NULL
+            `;
+
+            if (table) {
+                sql += ` AND object_name = ?`;
+            }
+
+            sql += ` ORDER BY count_read + count_write DESC`;
+
+            const result = await adapter.executeReadQuery(sql, table ? [table] : []);
+            return { indexUsage: result.rows };
+        }
+    };
+}
+
+export function createTableStatsTool(adapter: MySQLAdapter): ToolDefinition {
+    return {
+        name: 'mysql_table_stats',
+        title: 'MySQL Table Stats',
+        description: 'Get detailed table statistics including size, rows, and engine info.',
+        group: 'performance',
+        inputSchema: TableStatsSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { table } = TableStatsSchema.parse(params);
+
+            const sql = `
+                SELECT 
+                    TABLE_NAME as table_name,
+                    ENGINE as engine,
+                    ROW_FORMAT as row_format,
+                    TABLE_ROWS as estimated_rows,
+                    AVG_ROW_LENGTH as avg_row_length,
+                    DATA_LENGTH as data_size_bytes,
+                    INDEX_LENGTH as index_size_bytes,
+                    DATA_FREE as free_space_bytes,
+                    AUTO_INCREMENT as auto_increment,
+                    CREATE_TIME as create_time,
+                    UPDATE_TIME as update_time,
+                    TABLE_COLLATION as collation
+                FROM information_schema.TABLES
+                WHERE TABLE_SCHEMA = DATABASE()
+                  AND TABLE_NAME = ?
+            `;
+
+            const result = await adapter.executeReadQuery(sql, [table]);
+            return { stats: result.rows?.[0] };
+        }
+    };
+}
+
+export function createBufferPoolStatsTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({});
+
+    return {
+        name: 'mysql_buffer_pool_stats',
+        title: 'MySQL Buffer Pool Stats',
+        description: 'Get InnoDB buffer pool statistics.',
+        group: 'performance',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (_params: unknown, _context: RequestContext) => {
+            // Use SELECT * for compatibility across MySQL versions
+            // Different MySQL versions have different column sets
+            const result = await adapter.executeReadQuery(
+                `SELECT * FROM information_schema.INNODB_BUFFER_POOL_STATS`
+            );
+
+            return { bufferPoolStats: result.rows };
+        }
+    };
+}
+
+export function createThreadStatsTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({});
+
+    return {
+        name: 'mysql_thread_stats',
+        title: 'MySQL Thread Stats',
+        description: 'Get thread activity statistics.',
+        group: 'performance',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (_params: unknown, _context: RequestContext) => {
+            const result = await adapter.executeReadQuery(`
+                SELECT 
+                    THREAD_ID,
+                    NAME,
+                    TYPE,
+                    PROCESSLIST_ID,
+                    PROCESSLIST_USER,
+                    PROCESSLIST_HOST,
+                    PROCESSLIST_DB,
+                    PROCESSLIST_COMMAND,
+                    PROCESSLIST_TIME,
+                    PROCESSLIST_STATE,
+                    CONNECTION_TYPE
+                FROM performance_schema.threads
+                WHERE PROCESSLIST_ID IS NOT NULL
+                ORDER BY PROCESSLIST_TIME DESC
+            `);
+
+            return { threads: result.rows };
+        }
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * MySQL Performance & Optimization Tools
+ * 
+ * Query analysis, EXPLAIN, and optimization tools.
+ * 12 tools total (8 performance + 4 optimization).
+ */
+
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import type { ToolDefinition } from '../../../../types/index.js';
+
+// Import from submodules
+import {
+    createExplainTool,
+    createExplainAnalyzeTool,
+    createSlowQueriesTool,
+    createQueryStatsTool,
+    createIndexUsageTool,
+    createTableStatsTool,
+    createBufferPoolStatsTool,
+    createThreadStatsTool
+} from './analysis.js';
+
+import {
+    createIndexRecommendationTool,
+    createQueryRewriteTool,
+    createForceIndexTool,
+    createOptimizerTraceTool
+} from './optimization.js';
+
+/**
+ * Get performance analysis tools
+ */
+export function getPerformanceTools(adapter: MySQLAdapter): ToolDefinition[] {
+    return [
+        createExplainTool(adapter),
+        createExplainAnalyzeTool(adapter),
+        createSlowQueriesTool(adapter),
+        createQueryStatsTool(adapter),
+        createIndexUsageTool(adapter),
+        createTableStatsTool(adapter),
+        createBufferPoolStatsTool(adapter),
+        createThreadStatsTool(adapter)
+    ];
+}
+
+/**
+ * Get optimization tools
+ */
+export function getOptimizationTools(adapter: MySQLAdapter): ToolDefinition[] {
+    return [
+        createIndexRecommendationTool(adapter),
+        createQueryRewriteTool(adapter),
+        createForceIndexTool(adapter),
+        createOptimizerTraceTool(adapter)
+    ];
+}

package/src/adapters/mysql/tools/performance/optimization.ts

@@ -0,0 +1,218 @@
+/**
+ * MySQL Performance Tools - Optimization
+ * 
+ * Query optimization and index recommendation tools.
+ * 4 tools: index_recommendation, query_rewrite, force_index, optimizer_trace.
+ */
+
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+import { z } from 'zod';
+
+export function createIndexRecommendationTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({
+        table: z.string().describe('Table to analyze for missing indexes')
+    });
+
+    return {
+        name: 'mysql_index_recommendation',
+        title: 'MySQL Index Recommendation',
+        description: 'Analyze table and suggest potentially missing indexes based on query patterns.',
+        group: 'optimization',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { table } = schema.parse(params);
+
+            // Get columns
+            const columns = await adapter.describeTable(table);
+
+            // Get existing indexes
+            const indexes = await adapter.getTableIndexes(table);
+            const indexedColumns = new Set(indexes.flatMap(i => i.columns));
+
+            // Analyze which columns might benefit from indexing
+            const recommendations: { column: string; reason: string }[] = [];
+
+            for (const col of columns.columns ?? []) {
+                if (indexedColumns.has(col.name)) continue;
+
+                // Suggest indexes for common patterns
+                if (col.name.endsWith('_id') || col.name === 'id') {
+                    recommendations.push({
+                        column: col.name,
+                        reason: 'Foreign key or ID column often benefits from indexing'
+                    });
+                } else if (['created_at', 'updated_at', 'date', 'timestamp'].some(s => col.name.includes(s))) {
+                    recommendations.push({
+                        column: col.name,
+                        reason: 'Timestamp columns often used in range queries'
+                    });
+                } else if (col.name === 'status' || col.name === 'type' || col.name === 'category') {
+                    recommendations.push({
+                        column: col.name,
+                        reason: 'Status/type columns often used in filtering'
+                    });
+                }
+            }
+
+            return {
+                table,
+                existingIndexes: indexes.map(i => ({ name: i.name, columns: i.columns })),
+                recommendations
+            };
+        }
+    };
+}
+
+export function createQueryRewriteTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({
+        query: z.string().describe('SQL query to analyze for optimization')
+    });
+
+    return {
+        name: 'mysql_query_rewrite',
+        title: 'MySQL Query Rewrite',
+        description: 'Analyze a query and suggest optimizations.',
+        group: 'optimization',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { query } = schema.parse(params);
+
+            const suggestions: string[] = [];
+            const upperQuery = query.toUpperCase();
+
+            // Basic query analysis
+            if (upperQuery.includes('SELECT *')) {
+                suggestions.push('Consider selecting only needed columns instead of SELECT *');
+            }
+
+            if (!upperQuery.includes('LIMIT') && upperQuery.includes('SELECT')) {
+                suggestions.push('Consider adding LIMIT to prevent large result sets');
+            }
+
+            if (upperQuery.includes('LIKE') && query.includes('%')) {
+                if (query.includes("LIKE '%")) {
+                    suggestions.push('Leading wildcard in LIKE prevents index usage; consider FULLTEXT search');
+                }
+            }
+
+            if (upperQuery.includes('OR')) {
+                suggestions.push('OR conditions may prevent index usage; consider UNION instead');
+            }
+
+            if (upperQuery.includes('ORDER BY') && !upperQuery.includes('LIMIT')) {
+                suggestions.push('ORDER BY without LIMIT may cause full table sort');
+            }
+
+            if (upperQuery.includes('NOT IN') || upperQuery.includes('NOT EXISTS')) {
+                suggestions.push('NOT IN/NOT EXISTS can be slow; consider LEFT JOIN with NULL check');
+            }
+
+            // Get EXPLAIN for the query
+            let explainResult: unknown;
+            try {
+                const explainSql = `EXPLAIN FORMAT=JSON ${query}`;
+                const result = await adapter.executeReadQuery(explainSql);
+                if (result.rows?.[0]) {
+                    const explainStr = result.rows[0]['EXPLAIN'];
+                    if (typeof explainStr === 'string') {
+                        explainResult = JSON.parse(explainStr) as unknown;
+                    }
+                }
+            } catch {
+                // Ignore explain errors
+            }
+
+            return {
+                originalQuery: query,
+                suggestions,
+                explainPlan: explainResult
+            };
+        }
+    };
+}
+
+export function createForceIndexTool(_adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({
+        table: z.string(),
+        query: z.string().describe('Original query'),
+        indexName: z.string().describe('Index name to force')
+    });
+
+    return {
+        name: 'mysql_force_index',
+        title: 'MySQL Force Index',
+        description: 'Generate a query with FORCE INDEX hint.',
+        group: 'optimization',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: (params: unknown, _context: RequestContext) => {
+            const { table, query, indexName } = schema.parse(params);
+
+            // Simple replacement - insert FORCE INDEX after table name
+            const rewritten = query.replace(
+                new RegExp(`FROM\\s+\`?${table}\`?`, 'i'),
+                `FROM \`${table}\` FORCE INDEX (\`${indexName}\`)`
+            );
+
+            return Promise.resolve({
+                originalQuery: query,
+                rewrittenQuery: rewritten,
+                hint: `FORCE INDEX (\`${indexName}\`)`
+            });
+        }
+    };
+}
+
+export function createOptimizerTraceTool(adapter: MySQLAdapter): ToolDefinition {
+    const schema = z.object({
+        query: z.string().describe('Query to trace')
+    });
+
+    return {
+        name: 'mysql_optimizer_trace',
+        title: 'MySQL Optimizer Trace',
+        description: 'Get detailed optimizer trace for a query.',
+        group: 'optimization',
+        inputSchema: schema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { query } = schema.parse(params);
+
+            // Enable optimizer trace
+            await adapter.executeQuery('SET optimizer_trace="enabled=on"');
+
+            try {
+                // Execute the query
+                await adapter.executeReadQuery(query);
+
+                // Get the trace
+                const traceResult = await adapter.executeReadQuery(
+                    'SELECT * FROM information_schema.OPTIMIZER_TRACE'
+                );
+
+                return { trace: traceResult.rows };
+            } finally {
+                // Disable optimizer trace
+                await adapter.executeQuery('SET optimizer_trace="enabled=off"');
+            }
+        }
+    };
+}