@berthojoris/mcp-mysql-server 1.22.0 → 1.23.0

package/DOCUMENTATIONS.md

@@ -9,7 +9,7 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 ## Table of Contents
 
 1. [Setup & Configuration (Extended)](#setup--configuration-extended) - Permissions + Categories
-2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 144 tools organized by category
+2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 157 tools organized by category
 3. [DDL Operations](#🏗️-ddl-operations)
 4. [Data Export Tools](#📤-data-export-tools)
 5. [Data Import Tools](#📥-data-import-tools)
@@ -201,7 +201,7 @@ Add 'bulk_operations' to the categories argument.
 
 ## 🔧 Complete Tools Reference
 
-This section provides a comprehensive reference of all 144 available tools organized by category.
+This section provides a comprehensive reference of all 157 available tools organized by category.
 
 ### Database Discovery
 
@@ -2983,6 +2983,238 @@ The AI Enhancement tools provide intelligent, AI-powered features for database e
 | `predict_query_performance` | Predicts query scan/cost changes under growth assumptions (heuristic) | `ai_enhancement` |
 | `forecast_database_growth` | Forecasts table/database growth from current sizes and rates | `ai_enhancement` |
 
+### Smart Query Builder
+
+| Tool | Description | Category |
+|------|-------------|----------|
+| `start_query_builder` | Starts an interactive query building session with step-by-step guidance | `ai_enhancement` |
+| `add_tables_to_query` | Adds tables to the current query building session | `ai_enhancement` |
+| `define_joins` | Defines table relationships and join conditions for the query | `ai_enhancement` |
+| `select_columns` | Selects columns to include in the query output | `ai_enhancement` |
+| `add_conditions` | Adds WHERE conditions to filter query results | `ai_enhancement` |
+| `add_aggregations` | Adds aggregate functions (COUNT, SUM, AVG, MIN, MAX) to the query | `ai_enhancement` |
+| `configure_grouping_and_ordering` | Configures GROUP BY, ORDER BY, LIMIT, and OFFSET clauses | `ai_enhancement` |
+| `preview_query` | Previews the generated SQL query without executing it | `ai_enhancement` |
+| `execute_query` | Executes the built query with optional dry-run mode | `ai_enhancement` |
+| `get_session_state` | Retrieves the current state of the query building session | `ai_enhancement` |
+| `get_query_templates` | Provides pre-built query templates for common analysis tasks | `ai_enhancement` |
+| `apply_query_template` | Applies a predefined template to the current session | `ai_enhancement` |
+| `suggest_next_step` | AI-powered suggestions for the next logical step in query building | `ai_enhancement` |
+| `end_session` | Ends the current query building session and cleans up resources | `ai_enhancement` |
+
+#### `start_query_builder`
+
+Starts an interactive query building session with step-by-step guidance and AI-powered suggestions.
+
+```javascript
+// Start a basic session
+{
+  "tool": "start_query_builder",
+  "arguments": {
+    "intent": "Show me customer orders with total amounts",
+    "context": "analytics"
+  }
+}
+
+// Start with specific database
+{
+  "tool": "start_query_builder",
+  "arguments": {
+    "intent": "Analyze sales performance by region",
+    "context": "reporting",
+    "database": "sales_db"
+  }
+}
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `intent` | string | Natural language description of the query goal (required) |
+| `context` | string | Query context: `analytics`, `reporting`, `data_entry`, `schema_exploration` |
+| `database` | string | Target database name (optional) |
+
+**Response includes:**
+- Session ID for subsequent operations
+- Initial suggestions based on intent
+- Available query templates
+- Recommended next steps
+
+#### `add_tables_to_query`
+
+Adds tables to the current query building session with validation and relationship detection.
+
+```javascript
+{
+  "tool": "add_tables_to_query",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "tables": ["customers", "orders", "products"]
+  }
+}
+```
+
+#### `define_joins`
+
+Defines table relationships and join conditions with automatic foreign key detection.
+
+```javascript
+{
+  "tool": "define_joins",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "joins": [
+      {
+        "from_table": "customers",
+        "from_column": "customer_id",
+        "to_table": "orders",
+        "to_column": "customer_id",
+        "join_type": "INNER"
+      }
+    ]
+  }
+}
+```
+
+#### `select_columns`
+
+Selects specific columns to include in the query output with optional aliases.
+
+```javascript
+{
+  "tool": "select_columns",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "columns": [
+      {"table": "customers", "column": "name", "alias": "customer_name"},
+      {"table": "orders", "column": "total_amount"}
+    ]
+  }
+}
+```
+
+#### `add_conditions`
+
+Adds WHERE conditions to filter query results with various operators.
+
+```javascript
+{
+  "tool": "add_conditions",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "conditions": [
+      {
+        "table": "orders",
+        "column": "order_date",
+        "operator": "gte",
+        "value": "2024-01-01"
+      }
+    ]
+  }
+}
+```
+
+#### `add_aggregations`
+
+Adds aggregate functions for data analysis and reporting.
+
+```javascript
+{
+  "tool": "add_aggregations",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "aggregations": [
+      {
+        "function": "SUM",
+        "column": "total_amount",
+        "alias": "total_sales",
+        "table": "orders"
+      }
+    ]
+  }
+}
+```
+
+#### `configure_grouping_and_ordering`
+
+Configures GROUP BY, ORDER BY, LIMIT, and OFFSET clauses for result organization.
+
+```javascript
+{
+  "tool": "configure_grouping_and_ordering",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "group_by": [
+      {"table": "customers", "column": "region"}
+    ],
+    "order_by": [
+      {"table": "orders", "column": "order_date", "direction": "desc"}
+    ],
+    "limit": 100
+  }
+}
+```
+
+#### `preview_query`
+
+Previews the generated SQL query without executing it, allowing for review and validation.
+
+```javascript
+{
+  "tool": "preview_query",
+  "arguments": {
+    "session_id": "uuid-session-id"
+  }
+}
+```
+
+#### `execute_query`
+
+Executes the built query with optional dry-run mode for testing.
+
+```javascript
+{
+  "tool": "execute_query",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "dry_run": false
+  }
+}
+```
+
+#### `get_query_templates`
+
+Provides pre-built query templates for common analysis tasks.
+
+```javascript
+{
+  "tool": "get_query_templates",
+  "arguments": {
+    "category": "analytics"
+  }
+}
+```
+
+**Available Templates:**
+- Customer Analysis (customer lifetime value, purchase patterns)
+- Sales Reporting (regional performance, product trends)
+- Product Analytics (inventory analysis, category performance)
+- User Activity (session analysis, engagement metrics)
+
+#### `suggest_next_step`
+
+AI-powered suggestions for the next logical step in query building based on current state.
+
+```javascript
+{
+  "tool": "suggest_next_step",
+  "arguments": {
+    "session_id": "uuid-session-id",
+    "user_input": "I want to see the top customers"
+  }
+}
+```
+
 ### Intelligent Query Assistant
 
 #### `build_query_from_intent`

package/README.md

@@ -4,7 +4,7 @@
 
 **A production-ready Model Context Protocol (MCP) server for MySQL database integration with AI agents**
 
-**Last Updated:** 2025-12-17 15:30:00
+**Last Updated:** 2025-12-18 13:45:00
 
 [![npm version](https://img.shields.io/npm/v/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mysql-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/@berthojoris/mysql-mcp)](https://www.npmjs.com/package/@berthojoris/mysql-mcp)

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export declare class MySQLMCP {
     private schemaPatternTools;
     private queryVisualizationTools;
     private forecastingTools;
+    private smartQueryBuilderTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string, categoriesConfig?: string);
@@ -1564,5 +1565,247 @@ export declare class MySQLMCP {
         data?: any;
         error?: string;
     }>;
+    startQueryBuilder(params: {
+        intent: string;
+        context?: "analytics" | "reporting" | "data_entry" | "schema_exploration";
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            suggestions: string[];
+            template_suggestions?: import("./tools/smartQueryBuilderTools").QueryTemplate[];
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    addTablesToQuery(params: {
+        session_id: string;
+        tables: string[];
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            added_tables: string[];
+            suggested_joins: Array<{
+                from_table: string;
+                to_table: string;
+                on_column: string;
+                join_type: string;
+            }>;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    defineJoins(params: {
+        session_id: string;
+        joins: Array<{
+            from_table: string;
+            from_column: string;
+            to_table: string;
+            to_column: string;
+            join_type?: "INNER" | "LEFT" | "RIGHT" | "FULL";
+        }>;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            added_joins: number;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    selectColumns(params: {
+        session_id: string;
+        columns: Array<{
+            table: string;
+            column: string;
+            alias?: string;
+        }>;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            selected_columns: number;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    addConditions(params: {
+        session_id: string;
+        conditions: Array<{
+            table: string;
+            column: string;
+            operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "in" | "not_in" | "is_null" | "is_not_null";
+            value?: any;
+            values?: any[];
+        }>;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            added_conditions: number;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    addAggregations(params: {
+        session_id: string;
+        aggregations: Array<{
+            function: "COUNT" | "SUM" | "AVG" | "MIN" | "MAX";
+            column: string;
+            alias: string;
+            table: string;
+        }>;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            added_aggregations: number;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    configureGroupingAndOrdering(params: {
+        session_id: string;
+        group_by?: Array<{
+            table: string;
+            column: string;
+        }>;
+        order_by?: Array<{
+            table: string;
+            column: string;
+            direction: "asc" | "desc";
+        }>;
+        limit?: number;
+        offset?: number;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    previewQuery(params: {
+        session_id: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            generated_query: string;
+            query_complexity: "simple" | "medium" | "complex";
+            estimated_rows?: number;
+            optimization_suggestions: string[];
+            current_step: string;
+        };
+        error?: string;
+    }>;
+    executeQuery(params: {
+        session_id: string;
+        dry_run?: boolean;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            executed_query: string;
+            results?: any[];
+            execution_time?: number;
+            row_count?: number;
+            is_dry_run: boolean;
+        };
+        error?: string;
+    }>;
+    getSessionState(params: {
+        session_id: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session: import("./tools/smartQueryBuilderTools").QueryBuilderSession;
+            current_step: string;
+            progress: {
+                tables_selected: boolean;
+                joins_defined: boolean;
+                columns_selected: boolean;
+                conditions_added: boolean;
+                aggregations_added: boolean;
+                grouping_configured: boolean;
+                ready_to_execute: boolean;
+            };
+        };
+        error?: string;
+    }>;
+    getQueryTemplates(params: {
+        category?: "analytics" | "reporting" | "data_entry" | "schema_exploration";
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            templates: import("./tools/smartQueryBuilderTools").QueryTemplate[];
+            total_count: number;
+        };
+        error?: string;
+    }>;
+    applyQueryTemplate(params: {
+        session_id: string;
+        template_name: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            applied_template: string;
+            suggested_tables: string[];
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    suggestNextStep(params: {
+        session_id: string;
+        user_input?: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            current_step: string;
+            suggestions: Array<{
+                type: "action" | "table" | "column" | "condition" | "template";
+                description: string;
+                command?: string;
+                parameters?: any;
+            }>;
+            next_actions: string[];
+        };
+        error?: string;
+    }>;
+    endSession(params: {
+        session_id: string;
+        database?: string;
+    }): Promise<{
+        status: string;
+        data?: {
+            session_id: string;
+            session_ended: boolean;
+            final_query?: string;
+        };
+        error?: string;
+    }>;
 }
 export default MySQLMCP;

package/dist/index.js

@@ -36,6 +36,7 @@ const testDataTools_1 = require("./tools/testDataTools");
 const schemaPatternTools_1 = require("./tools/schemaPatternTools");
 const queryVisualizationTools_1 = require("./tools/queryVisualizationTools");
 const forecastingTools_1 = require("./tools/forecastingTools");
+const smartQueryBuilderTools_1 = require("./tools/smartQueryBuilderTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -80,6 +81,7 @@ class MySQLMCP {
         this.schemaPatternTools = new schemaPatternTools_1.SchemaPatternTools(this.security);
         this.queryVisualizationTools = new queryVisualizationTools_1.QueryVisualizationTools(this.security);
         this.forecastingTools = new forecastingTools_1.ForecastingTools(this.security);
+        this.smartQueryBuilderTools = new smartQueryBuilderTools_1.SmartQueryBuilderTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
@@ -1202,6 +1204,91 @@ class MySQLMCP {
             return { status: "error", error: check.error };
         return await this.forecastingTools.forecastDatabaseGrowth(params);
     }
+    // Smart Query Builder Tools
+    async startQueryBuilder(params) {
+        const check = this.checkToolEnabled("startQueryBuilder");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.startQueryBuilder(params);
+    }
+    async addTablesToQuery(params) {
+        const check = this.checkToolEnabled("addTablesToQuery");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.addTablesToQuery(params);
+    }
+    async defineJoins(params) {
+        const check = this.checkToolEnabled("defineJoins");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.defineJoins(params);
+    }
+    async selectColumns(params) {
+        const check = this.checkToolEnabled("selectColumns");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.selectColumns(params);
+    }
+    async addConditions(params) {
+        const check = this.checkToolEnabled("addConditions");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.addConditions(params);
+    }
+    async addAggregations(params) {
+        const check = this.checkToolEnabled("addAggregations");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.addAggregations(params);
+    }
+    async configureGroupingAndOrdering(params) {
+        const check = this.checkToolEnabled("configureGroupingAndOrdering");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.configureGroupingAndOrdering(params);
+    }
+    async previewQuery(params) {
+        const check = this.checkToolEnabled("previewQuery");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.previewQuery(params);
+    }
+    async executeQuery(params) {
+        const check = this.checkToolEnabled("executeQuery");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.executeQuery(params);
+    }
+    async getSessionState(params) {
+        const check = this.checkToolEnabled("getSessionState");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.getSessionState(params);
+    }
+    async getQueryTemplates(params) {
+        const check = this.checkToolEnabled("getQueryTemplates");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.getQueryTemplates(params);
+    }
+    async applyQueryTemplate(params) {
+        const check = this.checkToolEnabled("applyQueryTemplate");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.applyQueryTemplate(params);
+    }
+    async suggestNextStep(params) {
+        const check = this.checkToolEnabled("suggestNextStep");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.suggestNextStep(params);
+    }
+    async endSession(params) {
+        const check = this.checkToolEnabled("endSession");
+        if (!check.enabled)
+            return { status: "error", error: check.error };
+        return await this.smartQueryBuilderTools.endSession(params);
+    }
 }
 exports.MySQLMCP = MySQLMCP;
 exports.default = MySQLMCP;