@berthojoris/mcp-mysql-server 1.40.6 → 1.42.0

package/dist/mcp-server.js

@@ -17,6 +17,8 @@ const toolArgumentValidation_js_1 = require("./tools/toolArgumentValidation.js")
 // Layer 2 (Categories): MCP_CATEGORIES (optional, for fine-grained control)
 const permissions = process.env.MCP_PERMISSIONS || process.env.MCP_CONFIG || "";
 const categories = process.env.MCP_CATEGORIES || "";
+const SERVER_NAME = "mysql-mcp-server";
+const SERVER_VERSION = "1.42.0";
 // Declare the MySQL MCP instance (will be initialized in main())
 let mysqlMCP;
 // Define all available tools with their schemas
@@ -404,6 +406,293 @@ const TOOLS = [
             required: ["table_name", "condition_sets"],
         },
     },
+    {
+        name: "plan_seed_data",
+        description: "🌱 RELATIONAL SEEDER: Analyzes target tables, foreign keys, constraints, and row counts to build a safe parent-first seed plan. Use this before generating preview or inserting dummy relational data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: {
+                    type: "string",
+                    description: "Optional: specific connected database name",
+                },
+                target_tables: {
+                    type: "array",
+                    description: "Target tables to seed",
+                    minItems: 1,
+                    items: { type: "string" },
+                },
+                rows_per_table: {
+                    oneOf: [
+                        { type: "number", minimum: 0 },
+                        { type: "object", additionalProperties: { type: "number", minimum: 0 } },
+                    ],
+                    description: "Rows to create for target tables, either a single number or table-to-count map (default: 10)",
+                },
+                include_dependencies: {
+                    type: "boolean",
+                    description: "Include parent tables required by foreign keys (default: true)",
+                },
+                include_children: {
+                    type: "boolean",
+                    description: "Include child tables that reference included tables for nested relational seeding (default: false)",
+                },
+                child_rows_per_parent: {
+                    type: "number",
+                    description: "Rows to create in child tables for each parent row (default: 2)",
+                    minimum: 1,
+                    maximum: 20,
+                },
+                respect_existing_data: {
+                    type: "boolean",
+                    description: "Reuse existing parent records when possible instead of creating new parent rows (default: true)",
+                },
+                strategy: {
+                    type: "string",
+                    enum: ["append"],
+                    description: "Seed strategy (currently append)",
+                },
+                random_seed: {
+                    type: "number",
+                    description: "Deterministic seed for repeatable preview and execution (default: 42)",
+                },
+                max_rows_per_table: {
+                    type: "number",
+                    description: "Safety cap for generated rows per table (default: 1000)",
+                    minimum: 1,
+                    maximum: 10000,
+                },
+                max_related_tables: {
+                    type: "number",
+                    description: "Safety cap for dependency/child expansion (default: 25)",
+                    minimum: 1,
+                    maximum: 100,
+                },
+                seed_rules: {
+                    type: "object",
+                    description: "Optional generator overrides keyed by table.column or column name",
+                    additionalProperties: true,
+                },
+                require_confirmation: {
+                    type: "boolean",
+                    description: "Require confirm_token for non-dry-run execution (default: true)",
+                },
+            },
+            required: ["target_tables"],
+        },
+    },
+    {
+        name: "generate_seed_preview",
+        description: "🌱 RELATIONAL SEEDER: Generates deterministic dummy row previews from a seed plan without writing to the database. Shows symbolic foreign-key placeholders for review before execution.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                plan_id: {
+                    type: "string",
+                    description: "Seed plan ID returned by plan_seed_data",
+                },
+                locale: {
+                    type: "string",
+                    description: "Optional locale hint for generated values (default: en_US)",
+                },
+                realistic: {
+                    type: "boolean",
+                    description: "Whether to prefer realistic generated values (default: true)",
+                },
+                max_preview_rows_per_table: {
+                    type: "number",
+                    description: "Maximum preview rows per table (default: 3)",
+                    minimum: 1,
+                    maximum: 25,
+                },
+                email_domain: {
+                    type: "string",
+                    description: "Safe email domain for generated emails (default: example.test)",
+                },
+            },
+            required: ["plan_id"],
+        },
+    },
+    {
+        name: "execute_seed_plan",
+        description: "🌱 RELATIONAL SEEDER: Executes a confirmed seed plan with dry-run enabled by default, production-name guard, transaction rollback on errors, and foreign-key ID resolution.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                plan_id: {
+                    type: "string",
+                    description: "Seed plan ID returned by plan_seed_data",
+                },
+                dry_run: {
+                    type: "boolean",
+                    description: "If true, returns execution preview without inserting rows (default: true)",
+                },
+                use_transaction: {
+                    type: "boolean",
+                    description: "Use a transaction and rollback on error (default: true)",
+                },
+                batch_size: {
+                    type: "number",
+                    description: "Reserved batch-size hint for large plans (default: 1 for ID-safe inserts)",
+                    minimum: 1,
+                    maximum: 10000,
+                },
+                on_error: {
+                    type: "string",
+                    enum: ["rollback", "stop"],
+                    description: "Error behavior (default: rollback)",
+                },
+                confirm_token: {
+                    type: "string",
+                    description: "Confirmation token returned by plan_seed_data; required when dry_run is false",
+                },
+                allow_production: {
+                    type: "boolean",
+                    description: "Allow writes to production-like database names (default: false)",
+                },
+                email_domain: {
+                    type: "string",
+                    description: "Safe email domain for generated emails (default: example.test)",
+                },
+            },
+            required: ["plan_id"],
+        },
+    },
+    {
+        name: "validate_seed_integrity",
+        description: "🌱 RELATIONAL SEEDER: Validates seed results with FK orphan checks, required-column checks, unique-collision checks, and inserted row-count checks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                plan_id: {
+                    type: "string",
+                    description: "Seed plan ID returned by plan_seed_data",
+                },
+                tables: {
+                    type: "array",
+                    description: "Optional table subset to validate",
+                    items: { type: "string" },
+                },
+                check_foreign_keys: {
+                    type: "boolean",
+                    description: "Check foreign key integrity (default: true)",
+                },
+                check_orphans: {
+                    type: "boolean",
+                    description: "Alias for check_foreign_keys",
+                },
+                check_required_columns: {
+                    type: "boolean",
+                    description: "Check NOT NULL required columns (default: true)",
+                },
+                check_unique_collisions: {
+                    type: "boolean",
+                    description: "Check unique index collisions (default: true)",
+                },
+                check_row_counts: {
+                    type: "boolean",
+                    description: "Check inserted row counts when execution metadata is available (default: true)",
+                },
+            },
+            required: ["plan_id"],
+        },
+    },
+    {
+        name: "infer_seed_rules",
+        description: "🌱 ADVANCED SEEDER: Infers safe seed generator rules from schema metadata, sample row patterns, unique constraints, and optional ecommerce/POS/CRM domain presets without returning raw PII samples.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: {
+                    type: "string",
+                    description: "Optional: specific connected database name",
+                },
+                tables: {
+                    type: "array",
+                    description: "Optional table subset to analyze; defaults to schema tables up to max_tables",
+                    items: { type: "string" },
+                },
+                domain: {
+                    type: "string",
+                    enum: ["auto", "generic", "ecommerce", "pos", "crm"],
+                    description: "Optional domain preset for better business-like dummy data (default: auto)",
+                },
+                sample_size: {
+                    type: "number",
+                    description: "Number of sample rows per table used to infer ranges and enum-like choices (default: 25, max: 100)",
+                    minimum: 0,
+                    maximum: 100,
+                },
+                max_tables: {
+                    type: "number",
+                    description: "Maximum number of tables to analyze when tables is omitted (default: 50)",
+                    minimum: 1,
+                    maximum: 200,
+                },
+            },
+        },
+    },
+    {
+        name: "seed_from_template",
+        description: "🌱 TEMPLATE SEEDER: Creates a plan-first FK-aware seed workflow from ecommerce, POS, or CRM templates. It detects matching tables, applies domain rules, and returns a seed plan for preview/execution.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: {
+                    type: "string",
+                    description: "Optional: specific connected database name",
+                },
+                template: {
+                    type: "string",
+                    enum: ["ecommerce", "pos", "crm"],
+                    description: "Business seed template to apply",
+                },
+                scale: {
+                    type: "string",
+                    enum: ["small", "medium", "large"],
+                    description: "Template size preset (default: small)",
+                },
+                include: {
+                    type: "array",
+                    description: "Optional concrete table list to seed instead of auto-detected template matches",
+                    items: { type: "string" },
+                },
+                exclude: {
+                    type: "array",
+                    description: "Optional table names to ignore during template matching",
+                    items: { type: "string" },
+                },
+                rows_per_table: {
+                    oneOf: [
+                        { type: "number", minimum: 0 },
+                        { type: "object", additionalProperties: { type: "number", minimum: 0 } },
+                    ],
+                    description: "Optional row-count override for the generated plan",
+                },
+                include_dependencies: {
+                    type: "boolean",
+                    description: "Include parent tables required by foreign keys (default: true)",
+                },
+                include_children: {
+                    type: "boolean",
+                    description: "Include child tables that reference included template tables (default: false)",
+                },
+                respect_existing_data: {
+                    type: "boolean",
+                    description: "Reuse existing parent records when possible instead of creating new parent rows (default: true)",
+                },
+                random_seed: {
+                    type: "number",
+                    description: "Deterministic seed for repeatable preview and execution",
+                },
+                require_confirmation: {
+                    type: "boolean",
+                    description: "Require confirm_token for non-dry-run execution (default: true)",
+                },
+            },
+            required: ["template"],
+        },
+    },
     {
         name: "run_select_query",
         description: "⚡ PRIMARY TOOL FOR SELECT QUERIES. Executes read-only SELECT statements with parameterization, optimizer hints, query caching, and dry-run mode. Supports complex queries with JOINs, subqueries, and aggregations. ⚠️ ONLY for SELECT - use execute_write_query for INSERT/UPDATE/DELETE, use execute_ddl for CREATE/ALTER/DROP.",
@@ -1862,8 +2151,8 @@ const TOOLS = [
 ];
 // Create the MCP server
 const server = new index_js_1.Server({
-    name: "mysql-mcp-server",
-    version: "1.40.6",
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
 }, {
     capabilities: {
         tools: {},
@@ -1884,6 +2173,20 @@ const TOOL_METHOD_OVERRIDES = {
     export_query_to_csv: "exportQueryToCSV",
 };
 const toCamelCase = (value) => value.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+const getRuntimeToolCatalog = () => {
+    const enabledTools = (0, toolRegistry_js_1.getEnabledTools)(mysqlMCP, TOOLS);
+    return {
+        tools: TOOLS.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+        enabledToolNames: enabledTools.map((tool) => tool.name),
+        accessProfile: mysqlMCP.getAccessProfile(),
+        serverName: SERVER_NAME,
+        serverVersion: SERVER_VERSION,
+    };
+};
 const getCursorRequestFilePath = () => {
     const configuredPath = process.env.MYSQL_MCP_CURSOR_REQUEST_FILE ||
         process.env.MCP_MYSQL_REQUEST_FILE ||
@@ -1919,6 +2222,13 @@ const executeToolByName = async (toolName, args = {}) => {
     if (toolName === "cursor_execute_request") {
         throw new Error("cursor_execute_request cannot dispatch to itself");
     }
+    const validation = (0, toolArgumentValidation_js_1.validateToolArguments)(toolName, args);
+    if (!validation.valid) {
+        throw new Error(`Validation Error: ${validation.errors?.join(", ") || "Invalid arguments"}`);
+    }
+    if (toolName === "list_all_tools") {
+        return await mysqlMCP.listAllTools(getRuntimeToolCatalog());
+    }
     const methodName = TOOL_METHOD_OVERRIDES[toolName] || toCamelCase(toolName);
     const method = mysqlMCP[methodName];
     if (typeof method !== "function") {
@@ -2025,6 +2335,24 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "bulk_delete":
                 result = await mysqlMCP.bulkDelete((args || {}));
                 break;
+            case "plan_seed_data":
+                result = await mysqlMCP.planSeedData(args || {});
+                break;
+            case "generate_seed_preview":
+                result = await mysqlMCP.generateSeedPreview(args || {});
+                break;
+            case "execute_seed_plan":
+                result = await mysqlMCP.executeSeedPlan(args || {});
+                break;
+            case "validate_seed_integrity":
+                result = await mysqlMCP.validateSeedIntegrity(args || {});
+                break;
+            case "infer_seed_rules":
+                result = await mysqlMCP.inferSeedRules(args || {});
+                break;
+            case "seed_from_template":
+                result = await mysqlMCP.seedFromTemplate(args || {});
+                break;
             // Query Tools
             case "run_select_query":
                 result = await mysqlMCP.runSelectQuery((args || {}));
@@ -2055,7 +2383,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 result = await mysqlMCP.testConnection();
                 break;
             case "list_all_tools":
-                result = await mysqlMCP.listAllTools();
+                result = await mysqlMCP.listAllTools(getRuntimeToolCatalog());
                 break;
             case "read_changelog":
                 result = await mysqlMCP.readChangelog((args || {}));
@@ -2102,6 +2430,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "export_table_to_csv":
                 result = await mysqlMCP.exportTableToCSV((args || {}));
                 break;
+            case "export_query_to_csv":
+                result = await mysqlMCP.exportQueryToCSV((args || {}));
+                break;
             // Query Optimization Tools
             case "analyze_query":
                 result = mysqlMCP.analyzeQuery((args || {}));

package/dist/security/securityLayer.d.ts

@@ -71,7 +71,7 @@ export declare class SecurityLayer {
     /**
      * Check if a query is a read-only SELECT query or information query (SHOW, DESCRIBE, etc.)
      */
-    isReadOnlyQuery(query: string): boolean;
+    isReadOnlyQuery(query: string, bypassDangerousCheck?: boolean): boolean;
     /**
      * Check if a query contains dangerous operations
      */

package/dist/security/securityLayer.js

@@ -404,13 +404,13 @@ class SecurityLayer {
     /**
      * Check if a query is a read-only SELECT query or information query (SHOW, DESCRIBE, etc.)
      */
-    isReadOnlyQuery(query) {
+    isReadOnlyQuery(query, bypassDangerousCheck = false) {
         // Check if it's an information query first (SHOW, DESCRIBE, EXPLAIN, etc.)
         if (this.isInformationQuery(query)) {
             return true;
         }
         // Check if it's a SELECT query
-        const validation = this.validateQuery(query);
+        const validation = this.validateQuery(query, bypassDangerousCheck);
         return validation.valid && validation.queryType === "SELECT";
     }
     /**

package/dist/tools/dataExportTools.d.ts

@@ -12,6 +12,8 @@ export declare class DataExportTools {
      * Escape string value for SQL INSERT statements
      */
     private escapeValue;
+    private escapeCsvValue;
+    private rowsToCSV;
     /**
      * Export table data to CSV format
      */
@@ -26,4 +28,13 @@ export declare class DataExportTools {
         data?: any;
         error?: string;
     }>;
+    exportQueryToCSV(queryParams: {
+        query: string;
+        params?: any[];
+        include_headers?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
 }

package/dist/tools/dataExportTools.js

@@ -62,6 +62,33 @@ class DataExportTools {
             .replace(/\0/g, "\\0");
         return `'${escaped}'`;
     }
+    escapeCsvValue(value) {
+        if (value === null || value === undefined)
+            return "";
+        const normalizedValue = value instanceof Date
+            ? value.toISOString()
+            : Buffer.isBuffer(value)
+                ? value.toString("base64")
+                : String(value);
+        if (/[",\r\n]/.test(normalizedValue)) {
+            return `"${normalizedValue.replace(/"/g, '""')}"`;
+        }
+        return normalizedValue;
+    }
+    rowsToCSV(rows, includeHeaders) {
+        if (rows.length === 0) {
+            return "";
+        }
+        const columns = Object.keys(rows[0]);
+        const csvRows = [];
+        if (includeHeaders) {
+            csvRows.push(columns.map((column) => this.escapeCsvValue(column)).join(","));
+        }
+        for (const row of rows) {
+            csvRows.push(columns.map((column) => this.escapeCsvValue(row[column])).join(","));
+        }
+        return `${csvRows.join("\n")}\n`;
+    }
     /**
      * Export table data to CSV format
      */
@@ -179,33 +206,7 @@ class DataExportTools {
                     },
                 };
             }
-            // Generate CSV
-            let csv = "";
-            // Add headers if requested
-            if (include_headers) {
-                const headers = Object.keys(results[0]).join(",");
-                csv += headers + "\n";
-            }
-            // Add data rows
-            for (const row of results) {
-                const values = Object.values(row)
-                    .map((value) => {
-                    if (value === null)
-                        return "";
-                    if (typeof value === "string") {
-                        // Escape quotes and wrap in quotes if contains comma or newline
-                        if (value.includes(",") ||
-                            value.includes("\n") ||
-                            value.includes('"')) {
-                            return `"${value.replace(/"/g, '""')}"`;
-                        }
-                        return value;
-                    }
-                    return String(value);
-                })
-                    .join(",");
-                csv += values + "\n";
-            }
+            const csv = this.rowsToCSV(results, include_headers);
             return {
                 status: "success",
                 data: {
@@ -221,5 +222,45 @@ class DataExportTools {
             };
         }
     }
+    async exportQueryToCSV(queryParams) {
+        try {
+            const { query, params = [], include_headers = true, } = queryParams;
+            const queryValidation = this.security.validateQuery(query, this.security.hasExecutePermission());
+            if (!queryValidation.valid) {
+                return {
+                    status: "error",
+                    error: `Query validation failed: ${queryValidation.error}`,
+                };
+            }
+            if (queryValidation.queryType !== "SELECT") {
+                return {
+                    status: "error",
+                    error: "export_query_to_csv only accepts SELECT queries.",
+                };
+            }
+            const paramValidation = this.security.validateParameters(params);
+            if (!paramValidation.valid) {
+                return {
+                    status: "error",
+                    error: `Parameter validation failed: ${paramValidation.error}`,
+                };
+            }
+            const results = await this.db.query(query, paramValidation.sanitizedParams, false);
+            const maskedResults = this.security.masking.processResults(results);
+            return {
+                status: "success",
+                data: {
+                    csv: this.rowsToCSV(maskedResults, include_headers),
+                    row_count: maskedResults.length,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: error.message,
+            };
+        }
+    }
 }
 exports.DataExportTools = DataExportTools;

package/dist/tools/ddlTools.d.ts

@@ -7,6 +7,8 @@ export declare class DdlTools {
      * Sanitize default value for SQL safety
      */
     private sanitizeDefaultValue;
+    private validateColumnType;
+    private validateIdentifier;
     /**
      * Create a new table
      */