@neverinfamous/mysql-mcp 2.1.0 → 2.3.0

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

@@ -1,110 +1,171 @@
 /**
  * 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 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';
+  ExplainSchema,
+  ExplainSchemaBase,
+  ExplainAnalyzeSchema,
+  ExplainAnalyzeSchemaBase,
+  SlowQuerySchema,
+  IndexUsageSchema,
+  IndexUsageSchemaBase,
+  TableStatsSchema,
+  TableStatsSchemaBase,
+} from "../../types.js";
+import { z } from "zod";
+
+/**
+ * Maximum reasonable timer value in milliseconds (24 hours).
+ * Values exceeding this threshold are timer overflow artifacts from
+ * performance_schema's unsigned 64-bit picosecond counters wrapping.
+ */
+const MAX_TIMER_MS = 86_400_000;
+
+/**
+ * Sanitize timer fields in query result rows.
+ * Overflowed values (> 24 hours) are clamped to -1 with an `overflow: true` flag.
+ */
+function sanitizeTimerRows(
+  rows: Record<string, unknown>[] | undefined,
+  timerFields: string[],
+): Record<string, unknown>[] {
+  if (!rows) return [];
+  return rows.map((row) => {
+    let hasOverflow = false;
+    const sanitized = { ...row };
+    for (const field of timerFields) {
+      const value = sanitized[field];
+      const numValue =
+        typeof value === "number"
+          ? value
+          : typeof value === "string"
+            ? parseFloat(value)
+            : NaN;
+      if (!isNaN(numValue) && numValue > MAX_TIMER_MS) {
+        sanitized[field] = -1;
+        hasOverflow = true;
+      } else if (!isNaN(numValue)) {
+        sanitized[field] = numValue;
+      }
+    }
+    if (hasOverflow) {
+      sanitized["overflow"] = true;
+    }
+    return sanitized;
+  });
+}
 
 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 };
+  return {
+    name: "mysql_explain",
+    title: "MySQL EXPLAIN",
+    description: "Get query execution plan using EXPLAIN.",
+    group: "performance",
+    inputSchema: ExplainSchemaBase,
+    requiredScopes: ["read"],
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
+    handler: async (params: unknown, _context: RequestContext) => {
+      const { query, format } = ExplainSchema.parse(params);
+
+      const sql = `EXPLAIN FORMAT=${format} ${query}`;
+
+      try {
+        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 };
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes("doesn't exist")) {
+          return { exists: false, error: msg };
+        }
+        return { success: false, error: msg };
+      }
+    },
+  };
 }
 
-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 createExplainAnalyzeTool(
+  adapter: MySQLAdapter,
+): ToolDefinition {
+  return {
+    name: "mysql_explain_analyze",
+    title: "MySQL EXPLAIN ANALYZE",
+    description:
+      "Get query execution plan with actual timing using EXPLAIN ANALYZE (MySQL 8.0+). Only TREE format is supported.",
+    group: "performance",
+    inputSchema: ExplainAnalyzeSchemaBase,
+    requiredScopes: ["read"],
+    annotations: {
+      readOnlyHint: true,
+    },
+    handler: async (params: unknown, _context: RequestContext) => {
+      const { query, format } = ExplainAnalyzeSchema.parse(params);
+
+      // MySQL does not support EXPLAIN ANALYZE with FORMAT=JSON
+      // (requires explain_json_format_version=2 which is not widely available).
+      // Return a descriptive error for JSON format requests.
+      if (format === "JSON") {
+        return {
+          supported: false,
+          reason:
+            "EXPLAIN ANALYZE does not support FORMAT=JSON. Use FORMAT=TREE (default) instead.",
+        };
+      }
+
+      const sql = `EXPLAIN ANALYZE FORMAT=${format} ${query}`;
+
+      try {
+        const result = await adapter.executeReadQuery(sql);
+        return { analysis: result.rows };
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes("doesn't exist")) {
+          return { exists: false, error: msg };
         }
-    };
+        return { success: false, error: msg };
+      }
+    },
+  };
 }
 
 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 = `
+  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,
+                    LEFT(DIGEST_TEXT, 200) as query,
                     COUNT_STAR as executions,
                     AVG_TIMER_WAIT/1000000000 as avg_time_ms,
                     SUM_TIMER_WAIT/1000000000 as total_time_ms,
@@ -113,48 +174,56 @@ export function createSlowQueriesTool(adapter: MySQLAdapter): ToolDefinition {
                 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 };
-        }
-    };
+      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: sanitizeTimerRows(result.rows, [
+          "avg_time_ms",
+          "total_time_ms",
+        ]),
+      };
+    },
+  };
 }
 
 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 = `
+  const schema = z.object({
+    orderBy: z
+      .enum(["total_time", "avg_time", "executions"])
+      .optional()
+      .default("total_time"),
+    limit: z.number().optional().default(10),
+  });
+
+  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,
+                    LEFT(DIGEST_TEXT, 200) as query_text,
                     COUNT_STAR as execution_count,
                     AVG_TIMER_WAIT/1000000000 as avg_time_ms,
                     MAX_TIMER_WAIT/1000000000 as max_time_ms,
@@ -169,28 +238,47 @@ export function createQueryStatsTool(adapter: MySQLAdapter): ToolDefinition {
                 LIMIT ${limit}
             `;
 
-            const result = await adapter.executeReadQuery(sql);
-            return { queries: result.rows };
-        }
-    };
+      const result = await adapter.executeReadQuery(sql);
+      return {
+        queries: sanitizeTimerRows(result.rows, [
+          "avg_time_ms",
+          "max_time_ms",
+          "total_time_ms",
+        ]),
+      };
+    },
+  };
 }
 
 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 = `
+  return {
+    name: "mysql_index_usage",
+    title: "MySQL Index Usage",
+    description: "Get index usage statistics from performance_schema.",
+    group: "performance",
+    inputSchema: IndexUsageSchemaBase,
+    requiredScopes: ["read"],
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+    },
+    handler: async (params: unknown, _context: RequestContext) => {
+      const { table, limit } = IndexUsageSchema.parse(params);
+
+      // P154: Check table existence when a specific table is requested
+      if (table) {
+        const check = await adapter.executeReadQuery(
+          `SELECT 1 FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`,
+          [table],
+        );
+        if (!check.rows || check.rows.length === 0) {
+          return { exists: false, table };
+        }
+      }
+
+      // Always filter to current database to avoid returning thousands of
+      // MySQL internal indexes with zero counts
+      let sql = `
                 SELECT 
                     object_schema as database_name,
                     object_name as table_name,
@@ -203,36 +291,38 @@ export function createIndexUsageTool(adapter: MySQLAdapter): ToolDefinition {
                     count_delete
                 FROM performance_schema.table_io_waits_summary_by_index_usage
                 WHERE index_name IS NOT NULL
+                  AND object_schema = DATABASE()
             `;
 
-            if (table) {
-                sql += ` AND object_name = ?`;
-            }
+      if (table) {
+        sql += ` AND object_name = ?`;
+      }
 
-            sql += ` ORDER BY count_read + count_write DESC`;
+      sql += ` ORDER BY count_read + count_write DESC LIMIT ${limit}`;
 
-            const result = await adapter.executeReadQuery(sql, table ? [table] : []);
-            return { indexUsage: result.rows };
-        }
-    };
+      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 = `
+  return {
+    name: "mysql_table_stats",
+    title: "MySQL Table Stats",
+    description:
+      "Get detailed table statistics including size, rows, and engine info.",
+    group: "performance",
+    inputSchema: TableStatsSchemaBase,
+    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,
@@ -251,54 +341,68 @@ export function createTableStatsTool(adapter: MySQLAdapter): ToolDefinition {
                   AND TABLE_NAME = ?
             `;
 
-            const result = await adapter.executeReadQuery(sql, [table]);
-            return { stats: result.rows?.[0] };
-        }
-    };
+      const result = await adapter.executeReadQuery(sql, [table]);
+
+      if (!result.rows || result.rows.length === 0) {
+        return { exists: false, 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 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) => {
+      const result = await adapter.executeReadQuery(
+        `SELECT POOL_ID, POOL_SIZE, FREE_BUFFERS, DATABASE_PAGES,
+                OLD_DATABASE_PAGES, MODIFIED_DATABASE_PAGES, PENDING_DECOMPRESS,
+                PENDING_READS, PENDING_FLUSH_LRU, PENDING_FLUSH_LIST,
+                PAGES_MADE_YOUNG, PAGES_NOT_MADE_YOUNG,
+                PAGES_MADE_YOUNG_RATE, PAGES_MADE_NOT_YOUNG_RATE,
+                NUMBER_PAGES_READ, NUMBER_PAGES_CREATED, NUMBER_PAGES_WRITTEN,
+                PAGES_READ_RATE, PAGES_CREATE_RATE, PAGES_WRITTEN_RATE,
+                HIT_RATE, YOUNG_MAKE_PER_THOUSAND_GETS,
+                NOT_YOUNG_MAKE_PER_THOUSAND_GETS
+         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(`
+  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,
@@ -316,7 +420,7 @@ export function createThreadStatsTool(adapter: MySQLAdapter): ToolDefinition {
                 ORDER BY PROCESSLIST_TIME DESC
             `);
 
-            return { threads: result.rows };
-        }
-    };
+      return { threads: result.rows };
+    },
+  };
 }