@berthojoris/mcp-mysql-server 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -2,25 +2,41 @@
 
 All notable changes to the MySQL MCP Server will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.12.0] - 2025-12-05
-
-### Added
-- Schema-Aware RAG Context Pack via `get_schema_rag_context`, delivering compact table/column/PK/FK snapshots with row estimates for embeddings-friendly prompts.
-
-### Fixed
-- Exposed analysis tools (`get_database_summary`, `get_schema_erd`, `get_column_statistics`) and the new RAG context pack through MCP tool registration and routing.
-
-### Changed
-- Updated documentation and tool counts to 120, reflecting the new analysis capability and refreshed README guidance.
-
-## [1.10.5] - 2025-12-02
-
-### Changed
-- Removed queryLog field from all tool responses - simplified response structure
-- Updated source code to remove query logging output from tool responses
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.14.0] - 2025-12-08
+
+### Added
+- **Data Masking Profiles** - New security feature to mask sensitive data in query responses.
+  - Configurable via `MCP_MASKING_PROFILE` environment variable.
+  - Profiles: `none` (default), `soft` (secrets), `partial` (secrets + PII), `strict` (all sensitive).
+  - Automatically applies to `run_query` and `read_records`.
+
+## [1.13.0] - 2025-12-07
+
+### Added
+- **Guided Query Builder/Fixer** - New `repair_query` tool that uses deterministic heuristics and `EXPLAIN` to analyze and fix SQL queries.
+  - Suggests optimizations (e.g., adding indexes, limits).
+  - Analyzes execution plans for performance issues like full table scans.
+  - Provides actionable feedback for specific error messages.
+
+## [1.12.0] - 2025-12-05
+
+### Added
+- Schema-Aware RAG Context Pack via `get_schema_rag_context`, delivering compact table/column/PK/FK snapshots with row estimates for embeddings-friendly prompts.
+
+### Fixed
+- Exposed analysis tools (`get_database_summary`, `get_schema_erd`, `get_column_statistics`) and the new RAG context pack through MCP tool registration and routing.
+
+### Changed
+- Updated documentation and tool counts to 120, reflecting the new analysis capability and refreshed README guidance.
+
+## [1.10.5] - 2025-12-02
+
+### Changed
+- Removed queryLog field from all tool responses - simplified response structure
+- Updated source code to remove query logging output from tool responses
 - Streamlined tool response format for cleaner API interaction
 
 ## [1.10.4] - 2025-12-02
@@ -485,21 +501,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Direct access to `mysql`, `performance_schema`, `sys` databases
   - `USER` / `PASSWORD` manipulation
 
-## [1.11.0] - 2025-12-05
-
-### Added
-- Adaptive permission presets (`readonly`, `analyst`, `dba-lite`) with mergeable overrides
-- CLI `--preset` flag and `MCP_PRESET`/`MCP_PERMISSION_PRESET` env support with resolved-config logging
-
-### Changed
-- Safe fallback to read-only defaults when an unknown preset is requested without overrides
-- Feature status endpoint now exposes preset-aware configuration snapshots for easier debugging
-
-## [1.4.3] - 2025-01-06
-
-### Added
-- Improved permission error handling with detailed messages
-- Enhanced documentation for permission system
+## [1.11.0] - 2025-12-05
+
+### Added
+- Adaptive permission presets (`readonly`, `analyst`, `dba-lite`) with mergeable overrides
+- CLI `--preset` flag and `MCP_PRESET`/`MCP_PERMISSION_PRESET` env support with resolved-config logging
+
+### Changed
+- Safe fallback to read-only defaults when an unknown preset is requested without overrides
+- Feature status endpoint now exposes preset-aware configuration snapshots for easier debugging
+
+## [1.4.3] - 2025-01-06
+
+### Added
+- Improved permission error handling with detailed messages
+- Enhanced documentation for permission system
 
 ### Fixed
 - Fixed undefined/null parameter handling in all tool calls
@@ -538,12 +554,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## Version History Summary
-
-- **1.11.0** - Adaptive permission presets with CLI/env support and preset-aware logging
-- **1.9.0** - Schema Versioning & Migrations (9 new tools), MCP integration for 12 AI tools
-- **1.8.0** - Data Migration Tools
-- **1.7.0** - Database Backup/Restore, Data Import/Export
+## Version History Summary
+
+- **1.11.0** - Adaptive permission presets with CLI/env support and preset-aware logging
+- **1.9.0** - Schema Versioning & Migrations (9 new tools), MCP integration for 12 AI tools
+- **1.8.0** - Data Migration Tools
+- **1.7.0** - Database Backup/Restore, Data Import/Export
 - **1.6.3** - Fixed missing tools in toolCategoryMap, security keyword refinement
 - **1.6.2** - Fixed security keyword false positive bug
 - **1.4.16** - Added get_table_size tool to manifest

package/DOCUMENTATIONS.md

@@ -7,7 +7,7 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 ## Table of Contents
 
 1. [Category Filtering System](#🆕-category-filtering-system) - NEW!
-2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 120 tools organized by category
+2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 124 tools organized by category
 3. [DDL Operations](#🏗️-ddl-operations)
 4. [Data Export Tools](#📤-data-export-tools)
 5. [Data Import Tools](#📥-data-import-tools)
@@ -29,11 +29,12 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 21. [Security Features](#🔒-security-features)
 22. [Query Result Caching](#💾-query-result-caching)
 23. [Query Optimization Hints](#🎯-query-optimization-hints)
-24. [Bulk Operations](#🚀-bulk-operations)
-25. [OpenAI Codex Integration](#🤖-openai-codex-integration)
-26. [Troubleshooting](#🛠️-troubleshooting)
-27. [License](#📄-license)
-28. [Roadmap](#🗺️-roadmap)
+24. [Guided Query Builder/Fixer](#🤖-guided-query-builderfixer)
+25. [Bulk Operations](#🚀-bulk-operations)
+26. [OpenAI Codex Integration](#🤖-openai-codex-integration)
+27. [Troubleshooting](#🛠️-troubleshooting)
+28. [License](#📄-license)
+29. [Roadmap](#🗺️-roadmap)
 
 ---
 
@@ -3639,6 +3640,50 @@ Available goals:
 
 ---
 
+---
+
+## 🤖 Guided Query Builder/Fixer
+
+The `repair_query` tool acts as an AI-powered assistant for SQL query optimization and troubleshooting.
+
+### Features
+
+- **Query Analysis**: Uses `EXPLAIN` to understand query execution plans.
+- **Auto-Fixing**: Identifying missing indexes, inefficient scans, and syntax errors.
+- **Heuristic suggestions**: Provides actionable advice (e.g. "Add index on column X", "Add LIMIT clause").
+
+### Usage Example
+
+**Request:**
+```json
+{
+  "tool": "repair_query",
+  "arguments": {
+    "query": "SELECT * FROM users WHERE email = 'test@example.com'",
+    "error_message": "Optional error message if query failed"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "analysis": {
+    "complexity": "HIGH",
+    "issues": ["Full Table Scan on table 'users'"],
+    "suggestions": ["Consider adding an index on table 'users' for the columns used in WHERE clause."]
+  },
+  "fixed_query": "SELECT * FROM users WHERE email = 'test@example.com'",
+  "suggestions": [
+    "Consider adding an index on table 'users' for the columns used in WHERE clause.",
+    "Consider adding 'LIMIT 100' to prevent massive data transfer."
+  ]
+}
+```
+
+---
+
 ## 🚀 Bulk Operations
 
 The MySQL MCP server includes powerful bulk operation tools designed for high-performance data processing. These tools are optimized for handling large datasets efficiently.
@@ -3714,7 +3759,44 @@ Each bulk operation returns performance metrics:
 
 ---
 
-## 🤖 OpenAI Codex Integration
+## 🎭 Data Masking
+ 
+ The MySQL MCP server includes a robust data masking layer to protect sensitive information (PII, credentials) in query results. This is useful when sharing database access with AI agents or third parties.
+ 
+ ### Features
+ 
+ - **Profile-Based Masking**: Easy configuration profiles (`none`, `soft`, `partial`, `strict`)
+ - **Automatic Detection**: Automatically identifies sensitive columns by name (e.g., `email`, `password`, `ssn`)
+ - **Multiple Strategies**:
+   - **REDACT**: Replaces value with `[REDACTED]`
+   - **PARTIAL**: Partially masks email (`j***@d.com`) and phone/CC (`***1234`)
+   - **HASH**: (Internal placeholder)
+ 
+ ### Configuration
+ 
+ Configure the masking profile via the `MCP_MASKING_PROFILE` environment variable:
+ 
+ ```bash
+ MCP_MASKING_PROFILE=partial
+ ```
+ 
+ ### Profiles Reference
+ 
+ | Profile | Description | Credentials (password, key) | PII (email, phone, ssn) |
+ |---------|-------------|-----------------------------|-------------------------|
+ | `none` | No masking (default) | Show | Show |
+ | `soft` | Protect secrets only | **REDACT** | Show |
+ | `partial` | Balanced security | **REDACT** | **PARTIAL** (j***@...) |
+ | `strict` | Maximum security | **REDACT** | **REDACT** |
+ 
+ ### Behavior
+ 
+ - Masking applies automatically to `run_query` and `read_records` results.
+ - It filters output **after** the query is run, so WHERE clauses still work on the real data (e.g., you can search by email, but the result will be masked).
+ 
+ ---
+ 
+ ## 🤖 OpenAI Codex Integration
 
 OpenAI Codex CLI and VS Code Extension support MCP servers through a shared TOML configuration file. This section provides detailed setup instructions for integrating the MySQL MCP Server with Codex.
 
@@ -4095,11 +4177,11 @@ MIT License - see [LICENSE](LICENSE) file for details.
 |---------|--------|--------|----------|--------|
 | Adaptive Permission Presets (ReadOnly/Analyst/DBA Lite) | High | Medium | 1 | ✅ Completed |
 | Schema-Aware RAG Context Pack | High | Medium | 2 | ✅ Completed |
-| Guided Query Builder/Fixer (Intent → Safe SQL + EXPLAIN Repair) | High | Medium | 3 | Planned |
-| Drift & Migration Assistant (Schema diff + risk summary) | High | High | 4 | Planned |
-| Safety Sandbox Mode (runQuery dry-run/EXPLAIN-only) | Medium | Low | 5 | Planned |
-| Anomaly & Slow-Query Watcher | Medium | Medium | 6 | Planned |
-| Data Masking Profiles for Responses | Medium | Medium | 7 | Planned |
+| Guided Query Builder/Fixer (Intent → Safe SQL + EXPLAIN Repair) | High | Medium | 3 | ✅ Completed |
+| Drift & Migration Assistant (Schema diff + risk summary) | High | High | 4 | ✅ Completed |
+| Safety Sandbox Mode (runQuery dry-run/EXPLAIN-only) | Medium | Low | 5 | ✅ Completed |
+| Anomaly & Slow-Query Watcher | Medium | Medium | 6 | ✅ Completed |
+| Data Masking Profiles for Responses | Medium | Medium | 7 | ✅ Completed |
 | Workflow Macros (e.g., safe_export_table) | Medium | Low | 8 | Planned |
 | Agent-Facing Changelog Feed | Medium | Low | 9 | Planned |
 | Connection Profiles (dev/stage/prod with allow/deny) | High | Low | 10 | Planned |

package/README.md

@@ -50,7 +50,7 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
   - [Environment Variables](#environment-variables-configuration)
   - [Local Development](#local-path-configuration)
 - [Permission System](#-permission-system)
-- [Available Tools (120 total)](#-available-tools)
+- [Available Tools (124 total)](#-available-tools)
 - [Documentation](#-detailed-documentation)
 - [Comparison: MCP vs Manual Access](#-mysql-mcp-vs-manual-database-access)
 - [License](#-license)
@@ -63,13 +63,14 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 |----------|-------------|
 | **Full MCP Support** | Works with Claude Code, Cursor, Windsurf, Zed, Cline, Kilo Code, Roo Code, Gemini CLI, OpenAI Codex, and any MCP-compatible AI agent |
 | **Security First** | Parameterized queries, SQL injection protection, permission-based access control |
-| **120 Powerful Tools** | Complete database operations including CRUD, DDL, transactions, stored procedures, backup/restore, migrations |
+| **124 Powerful Tools** | Complete database operations including CRUD, DDL, transactions, stored procedures, backup/restore, migrations |
 | **Adaptive Presets** | Built-in ReadOnly/Analyst/DBA Lite permission bundles with override merging |
 | **Schema-Aware RAG Pack** | Compact schema snapshots (tables, PK/FK, row estimates) tailored for embeddings-friendly prompts |
 | **Category Filtering** | 22 documentation categories for intuitive, fine-grained access control (backward compatible with 10 legacy categories) |
 | **Transaction Support** | Full ACID transaction management (BEGIN, COMMIT, ROLLBACK) |
 | **Schema Migrations** | Version control for database schema with up/down migrations |
 | **Dual Mode** | Run as MCP server OR as REST API |
+| **Data Masking** | Protect PII/Secrets in responses with configurable profiles (soft/partial/strict) |
 | **TypeScript** | Fully typed with TypeScript definitions |
 
 ---
@@ -106,6 +107,7 @@ DB_USER=root
 DB_PASSWORD=yourpassword
 DB_NAME=yourdatabase
 MCP_CONFIG=list,read,utility
+MCP_MASKING_PROFILE=partial
 ```
 
 ### 2. Build Project (If Cloned Locally)
@@ -367,7 +369,8 @@ Alternative approach using environment variables instead of connection string:
         "DB_PASSWORD": "your_password",
         "DB_NAME": "your_database",
         "MCP_PERMISSIONS": "list,read,utility",
-        "MCP_CATEGORIES": "database_discovery,performance_monitoring"
+        "MCP_CATEGORIES": "database_discovery,performance_monitoring",
+        "MCP_MASKING_PROFILE": "partial"
       }
     }
   }
@@ -496,12 +499,12 @@ Use these categories for fine-grained control that matches the tool organization
 | `server_management` | 9 | Process list, explain queries, server info |
 | `performance_monitoring` | 10 | Metrics, slow queries, health checks |
 | `cache_management` | 5 | Query cache stats and configuration |
-| `query_optimization` | 2 | Analyze queries, get optimization hints |
+| `query_optimization` | 3 | Analyze queries, get optimization hints |
 | `backup_restore` | 5 | Backup/restore database and tables |
 | `import_export` | 5 | Import/export JSON, CSV, SQL |
 | `data_migration` | 5 | Copy, move, clone, sync table data |
 | `schema_migrations` | 9 | Version control for database schema |
-| `analysis` | 3 | AI context optimization and data analysis |
+| `analysis` | 4 | AI context optimization and data analysis |
 
 ### Legacy Categories (Backward Compatible)
 
@@ -531,7 +534,7 @@ Use these categories for fine-grained control that matches the tool organization
 | **Application Backend** | `database_discovery,crud_operations,bulk_operations,custom_queries,transaction_management` | Full app support |
 | **Development & Testing** | `database_discovery,crud_operations,bulk_operations,custom_queries,schema_management,utilities,transaction_management` | Development access |
 | **DBA & DevOps** | `database_discovery,schema_management,table_maintenance,backup_restore,schema_migrations,performance_monitoring` | Admin tasks |
-| **Full Access** | *(leave empty)* | All 120 tools enabled |
+| **Full Access** | *(leave empty)* | All 124 tools enabled |
 
 #### Using Legacy Categories (Backward Compatible)
 
@@ -652,11 +655,11 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 
 ## Available Tools
 
-The MCP server provides **120 powerful tools** organized into categories:
+The MCP server provides **124 powerful tools** organized into categories:
 
 ### Quick Reference
 
-**120 Tools Available** - Organized into 22 categories
+**124 Tools Available** - Organized into 22 categories
 
 | Category | Count | Key Tools |
 |----------|-------|-----------|
@@ -676,7 +679,7 @@ The MCP server provides **120 powerful tools** organized into categories:
 | Server Management | 9 | `show_process_list`, `explain_query` |
 | Performance Monitoring | 10 | `get_performance_metrics`, `get_database_health_check` |
 | Cache | 5 | `get_cache_stats`, `clear_cache` |
-| Query Optimization | 2 | `analyze_query`, `get_optimization_hints` |
+| Query Optimization | 3 | `analyze_query`, `get_optimization_hints`, `repair_query` |
 | Backup & Restore | 5 | `backup_database`, `restore_from_sql` |
 | Import/Export | 5 | `export_table_to_json`, `import_from_csv` |
 | Data Migration | 5 | `copy_table_data`, `sync_table_data` |

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export declare class MySQLMCP {
     private schemaVersioningTools;
     private performanceTools;
     private analysisTools;
+    private aiTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string, categoriesConfig?: string, presetName?: string);
@@ -579,6 +580,16 @@ export declare class MySQLMCP {
         data?: any;
         error?: string;
     }>;
+    repairQuery(params: {
+        query: string;
+        error_message?: string;
+    }): Promise<{
+        status: string;
+        analysis?: any;
+        fixed_query?: string;
+        suggestions?: string[];
+        error?: string;
+    }>;
     getFeatureStatus(): {
         status: string;
         data: {

package/dist/index.js

@@ -24,6 +24,7 @@ const migrationTools_1 = require("./tools/migrationTools");
 const schemaVersioningTools_1 = require("./tools/schemaVersioningTools");
 const performanceTools_1 = require("./tools/performanceTools");
 const analysisTools_1 = require("./tools/analysisTools");
+const aiTools_1 = require("./tools/aiTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -55,6 +56,7 @@ class MySQLMCP {
         this.schemaVersioningTools = new schemaVersioningTools_1.SchemaVersioningTools(this.security);
         this.performanceTools = new performanceTools_1.PerformanceTools(this.security);
         this.analysisTools = new analysisTools_1.AnalysisTools(this.security);
+        this.aiTools = new aiTools_1.AiTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
@@ -525,6 +527,14 @@ class MySQLMCP {
         }
         return await this.schemaVersioningTools.generateMigrationFromDiff(params);
     }
+    // AI Productivity Tools
+    async repairQuery(params) {
+        const check = this.checkToolEnabled("repairQuery");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.aiTools.repairQuery(params);
+    }
     // Get feature configuration status
     getFeatureStatus() {
         const snapshot = this.featureConfig.getConfigSnapshot();

package/dist/mcp-server.js

@@ -476,6 +476,24 @@ const TOOLS = [
             required: ["query"],
         },
     },
+    {
+        name: "repair_query",
+        description: "Analyzes a SQL query (and optional error) to suggest repairs or optimizations using EXPLAIN and heuristics.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "The SQL query to analyze or repair",
+                },
+                error_message: {
+                    type: "string",
+                    description: "Optional error message received when executing the query",
+                },
+            },
+            required: ["query"],
+        },
+    },
     {
         name: "create_table",
         description: 'Creates a new table with the specified columns and indexes. Requires "ddl" permission.',
@@ -2641,7 +2659,7 @@ const TOOLS = [
     // Performance Monitoring Tools
     {
         name: "get_performance_metrics",
-        description: "Get comprehensive performance metrics including query performance, connection stats, buffer pool metrics, and InnoDB statistics.",
+        description: "Get comprehensive MySQL performance metrics including query performance, connection stats, buffer pool metrics, and InnoDB statistics.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -2814,36 +2832,6 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "read_table_schema":
                 result = await mysqlMCP.readTableSchema((args || {}));
                 break;
-            case "create_record":
-                result = await mysqlMCP.createRecord((args || {}));
-                break;
-            case "read_records":
-                result = await mysqlMCP.readRecords((args || {}));
-                break;
-            case "update_record":
-                result = await mysqlMCP.updateRecord((args || {}));
-                break;
-            case "delete_record":
-                result = await mysqlMCP.deleteRecord((args || {}));
-                break;
-            case "bulk_insert":
-                result = await mysqlMCP.bulkInsert((args || {}));
-                break;
-            case "bulk_update":
-                result = await mysqlMCP.bulkUpdate((args || {}));
-                break;
-            case "bulk_delete":
-                result = await mysqlMCP.bulkDelete((args || {}));
-                break;
-            case "run_query":
-                result = await mysqlMCP.runQuery((args || {}));
-                break;
-            case "execute_sql":
-                result = await mysqlMCP.executeSql((args || {}));
-                break;
-            case "create_table":
-                result = await mysqlMCP.createTable(args || {});
-                break;
             case "alter_table":
                 result = await mysqlMCP.alterTable(args || {});
                 break;
@@ -3180,6 +3168,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "reset_performance_stats":
                 result = await mysqlMCP.resetPerformanceStats();
                 break;
+            case "repair_query":
+                result = await mysqlMCP.repairQuery((args || {}));
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/optimization/explainAnalyzer.d.ts

@@ -0,0 +1,21 @@
+export interface ExplainAnalysis {
+    complexity: "LOW" | "MEDIUM" | "HIGH";
+    issues: string[];
+    suggestions: string[];
+    summary: string;
+}
+export declare class ExplainAnalyzer {
+    private static instance;
+    private constructor();
+    static getInstance(): ExplainAnalyzer;
+    /**
+     * Analyze EXPLAIN output (assumed to be in JSON format or standard table format)
+     * Note: The server should prefer EXPLAIN FORMAT=JSON for better analysis,
+     * but we will handle the standard result set array as well.
+     */
+    analyze(explainResult: any[]): ExplainAnalysis;
+    private analyzeJsonFormat;
+    private traverseJsonPlan;
+    private analyzeRow;
+    private generateSummary;
+}

package/dist/optimization/explainAnalyzer.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplainAnalyzer = void 0;
+class ExplainAnalyzer {
+    constructor() { }
+    static getInstance() {
+        if (!ExplainAnalyzer.instance) {
+            ExplainAnalyzer.instance = new ExplainAnalyzer();
+        }
+        return ExplainAnalyzer.instance;
+    }
+    /**
+     * Analyze EXPLAIN output (assumed to be in JSON format or standard table format)
+     * Note: The server should prefer EXPLAIN FORMAT=JSON for better analysis,
+     * but we will handle the standard result set array as well.
+     */
+    analyze(explainResult) {
+        const issues = [];
+        const suggestions = [];
+        let maxComplexity = 0;
+        // Check if result is empty
+        if (!explainResult || explainResult.length === 0) {
+            return {
+                complexity: "LOW",
+                issues: ["No EXPLAIN output returned"],
+                suggestions: [],
+                summary: "Query validation failed or produced no execution plan."
+            };
+        }
+        // Detect format (JSON string in first column or standard columns)
+        // If using EXPLAIN FORMAT=JSON, output is usually [{ EXPLAIN: '...json...' }]
+        const firstRow = explainResult[0];
+        if (firstRow && (firstRow['EXPLAIN'] || firstRow['JSON_EXPLAIN'])) {
+            return this.analyzeJsonFormat(firstRow['EXPLAIN'] || firstRow['JSON_EXPLAIN']);
+        }
+        // Analyze standard tabular format
+        for (const row of explainResult) {
+            this.analyzeRow(row, issues, suggestions);
+            // Heuristic for complexity
+            if (row.type === 'ALL')
+                maxComplexity = Math.max(maxComplexity, 3);
+            else if (row.type === 'index')
+                maxComplexity = Math.max(maxComplexity, 2);
+            else
+                maxComplexity = Math.max(maxComplexity, 1);
+        }
+        let complexity = "LOW";
+        if (maxComplexity >= 3)
+            complexity = "HIGH";
+        else if (maxComplexity === 2)
+            complexity = "MEDIUM";
+        return {
+            complexity,
+            issues: Array.from(new Set(issues)),
+            suggestions: Array.from(new Set(suggestions)),
+            summary: this.generateSummary(complexity, issues)
+        };
+    }
+    analyzeJsonFormat(jsonString) {
+        try {
+            const data = JSON.parse(jsonString);
+            const queryBlock = data.query_block || data; // Root might be query_block directly in some versions
+            const issues = [];
+            const suggestions = [];
+            this.traverseJsonPlan(queryBlock, issues, suggestions);
+            const distinctIssues = Array.from(new Set(issues));
+            const complexity = distinctIssues.some(i => i.includes("Full Table Scan")) ? "HIGH" : "MEDIUM"; // Simplified
+            return {
+                complexity,
+                issues: distinctIssues,
+                suggestions: Array.from(new Set(suggestions)),
+                summary: this.generateSummary(complexity, distinctIssues)
+            };
+        }
+        catch (e) {
+            return {
+                complexity: "LOW",
+                issues: ["Failed to parse EXPLAIN JSON output"],
+                suggestions: [],
+                summary: "Could not analyze the execution plan details."
+            };
+        }
+    }
+    traverseJsonPlan(node, issues, suggestions) {
+        if (!node)
+            return;
+        // Check for full table scans
+        if (node.access_type === 'ALL') {
+            issues.push(`Full Table Scan on table '${node.table_name || 'unknown'}'`);
+            suggestions.push(`Consider adding an index on table '${node.table_name || 'unknown'}' for the columns used in WHERE clause.`);
+        }
+        // Check for filesort
+        if (node.filesort || (node.extra && node.extra.includes('Using filesort'))) {
+            issues.push("Using Filesort (sorting without index)");
+            suggestions.push("Consider adding an index that matches the ORDER BY clause.");
+        }
+        // Check for temporary tables
+        if (node.temporary_table || (node.extra && node.extra.includes('Using temporary'))) {
+            issues.push("Using Temporary Table");
+            suggestions.push("Optimize query to avoid temporary tables (e.g. check GROUP BY or ORDER BY columns).");
+        }
+        // Recursive traversal (simplified)
+        if (node.nested_loop) {
+            for (const child of node.nested_loop) {
+                this.traverseJsonPlan(child.table, issues, suggestions);
+            }
+        }
+        // TODO: Add more structural traversal if needed for specific JSON structures
+    }
+    analyzeRow(row, issues, suggestions) {
+        const table = row.table || 'unknown';
+        const type = row.type;
+        const extra = row.Extra || '';
+        const possible_keys = row.possible_keys;
+        const key = row.key;
+        if (type === 'ALL') {
+            issues.push(`Full Table Scan on table '${table}'`);
+            suggestions.push(`Add an index to '${table}' to avoid full scan.`);
+        }
+        if (type === 'index') {
+            issues.push(`Full Index Scan on table '${table}'`);
+            suggestions.push(`Query scans entire index tree for '${table}'. Consider specific range or key.`);
+        }
+        if (!key && possible_keys && type !== 'ALL') {
+            // Indexes exist but not used? Rare case if not ALL.
+        }
+        if (extra.includes('Using filesort')) {
+            issues.push(`Using Filesort on table '${table}'`);
+            suggestions.push(`Add index for ORDER BY clause on '${table}'.`);
+        }
+        if (extra.includes('Using temporary')) {
+            issues.push(`Using Temporary Table for '${table}'`);
+            suggestions.push(`Check GROUP BY / ORDER BY columns on '${table}'.`);
+        }
+        if (extra.includes('Range checked for each record')) {
+            issues.push(`Inefficient join buffer usage on '${table}'`);
+            suggestions.push(`Check join conditions and indexes on '${table}'.`);
+        }
+    }
+    generateSummary(complexity, issues) {
+        if (issues.length === 0) {
+            return "Query plan looks good. No obvious performance issues detected.";
+        }
+        return `Query has ${complexity} complexity with ${issues.length} potential performance issue(s): ${issues.join("; ")}`;
+    }
+}
+exports.ExplainAnalyzer = ExplainAnalyzer;