@berthojoris/mcp-mysql-server 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -2,25 +2,33 @@
 
 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.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 +493,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 +546,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

@@ -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.
@@ -4095,10 +4140,10 @@ 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 |
+| 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 | Planned |
 | Workflow Macros (e.g., safe_export_table) | Medium | Low | 8 | Planned |
 | Agent-Facing Changelog Feed | Medium | Low | 9 | Planned |

package/README.md

@@ -63,7 +63,7 @@ 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 |
+| **121 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) |
@@ -656,7 +656,7 @@ The MCP server provides **120 powerful tools** organized into categories:
 
 ### Quick Reference
 
-**120 Tools Available** - Organized into 22 categories
+**121 Tools Available** - Organized into 22 categories
 
 | Category | Count | Key Tools |
 |----------|-------|-----------|
@@ -676,7 +676,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;

package/dist/tools/aiTools.d.ts

@@ -0,0 +1,22 @@
+import { SecurityLayer } from "../security/securityLayer";
+export declare class AiTools {
+    private db;
+    private security;
+    private analyzer;
+    private optimizer;
+    constructor(security: SecurityLayer);
+    /**
+     * guided_query_fixer
+     * Analyzes a query (and optional error) to suggest repairs or optimizations using EXPLAIN.
+     */
+    repairQuery(params: {
+        query: string;
+        error_message?: string;
+    }): Promise<{
+        status: string;
+        analysis?: any;
+        fixed_query?: string;
+        suggestions?: string[];
+        error?: string;
+    }>;
+}

package/dist/tools/aiTools.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiTools = void 0;
+const connection_1 = __importDefault(require("../db/connection"));
+const explainAnalyzer_1 = require("../optimization/explainAnalyzer");
+const queryOptimizer_1 = require("../optimization/queryOptimizer");
+class AiTools {
+    constructor(security) {
+        this.db = connection_1.default.getInstance();
+        this.security = security;
+        this.analyzer = explainAnalyzer_1.ExplainAnalyzer.getInstance();
+        this.optimizer = queryOptimizer_1.QueryOptimizer.getInstance();
+    }
+    /**
+     * guided_query_fixer
+     * Analyzes a query (and optional error) to suggest repairs or optimizations using EXPLAIN.
+     */
+    async repairQuery(params) {
+        const { query, error_message } = params;
+        // 1. If there is a syntax error provided, we can't run EXPLAIN.
+        // We try to provided simple heuristics or just return the analysis of the error.
+        if (error_message) {
+            return {
+                status: "success",
+                suggestions: [
+                    "Check SQL syntax matching your MySQL version.",
+                    "Verify table and column names using 'list_tables' or 'read_table_schema'.",
+                    "Ensure string literals are quoted correctly."
+                ],
+                fixed_query: query, // We can't auto-fix syntax errors reliably without an LLM
+                analysis: {
+                    issue: "Syntax/Execution Error",
+                    details: error_message
+                }
+            };
+        }
+        // 2. Validate query generally (security check)
+        // We assume this tool is used by an agent who might have 'read' permissions at least.
+        // If the query is unsafe (e.g. injection), we return that.
+        const validation = this.security.validateQuery(query, true); // validate with execute permission simulation to check structure
+        if (!validation.valid) {
+            return {
+                status: "error",
+                error: `Query rejected by security layer: ${validation.error}`
+            };
+        }
+        // 3. Run EXPLAIN
+        try {
+            const explainQuery = `EXPLAIN FORMAT=JSON ${query}`;
+            // Note: We use the raw connection or executeSql equivalent.
+            // But EXPLAIN is safe-ish if the inner query is safe.
+            // validation passed, so we try EXPLAIN.
+            const explainResult = await this.db.query(explainQuery);
+            const analysis = this.analyzer.analyze(explainResult);
+            // 4. Try to apply simple fixes based on analysis (e.g. Missing Limit)
+            let fixedQuery = query;
+            if (analysis.complexity === "HIGH" && !query.toLowerCase().includes("limit")) {
+                // Suggest adding LIMIT if not present and complexity is high
+                analysis.suggestions.push("Consider adding 'LIMIT 100' to prevent massive data transfer.");
+            }
+            return {
+                status: "success",
+                analysis: analysis,
+                suggestions: analysis.suggestions,
+                fixed_query: fixedQuery
+            };
+        }
+        catch (e) {
+            return {
+                status: "error",
+                error: `Failed to analyze query: ${e.message}`,
+                suggestions: ["Verify the query is valid SQL before analyzing."]
+            };
+        }
+    }
+}
+exports.AiTools = AiTools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@berthojoris/mcp-mysql-server",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Model Context Protocol server for MySQL database integration with dynamic per-project permissions, backup/restore, data import/export, and data migration capabilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -86,4 +86,4 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.2.2"
   }
-}
+}