@berthojoris/mcp-mysql-server 1.40.7 → 1.42.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.42.0] - 2026-05-11
+
+### Added
+- Added composite FK/PK tuple resolution for relational seeding so multi-column relationships are selected and validated as intact parent key tuples.
+- Added `infer_seed_rules` to infer safe seed generators from schema, samples, unique indexes, and ecommerce/POS/CRM domain presets.
+- Added `seed_from_template` to create plan-first ecommerce, POS, and CRM seed workflows with detected tables and template-scale row counts.
+
+### Changed
+- Updated seed tool count to 6 and total MCP tools to 85.
+
+## [1.41.0] - 2026-05-11
+
+### Added
+- Added `seed_operations` category with `plan_seed_data`, `generate_seed_preview`, `execute_seed_plan`, and `validate_seed_integrity` for FK-aware relational dummy data seeding.
+- Added deterministic seed planning, preview, confirmation token, transaction rollback, production-name guard, and integrity validation support.
+
+### Changed
+- Updated tool totals and version metadata to `1.41.0`.
+
 ## [1.40.7] - 2026-05-06
 
 ### Added

package/DOCUMENTATIONS.md

@@ -1,8 +1,8 @@
 # MySQL MCP Server - Documentation
 
-**Last Updated:** 2026-05-06 22:38:42
-**Version:** 1.40.7
-**Total Tools:** 79
+**Last Updated:** 2026-05-11 10:44:46
+**Version:** 1.42.0
+**Total Tools:** 85
 
 Comprehensive documentation for the MySQL MCP Server. For quick start, see [README.md](README.md).
 
@@ -109,7 +109,7 @@ For CSV exports, use `export_table_to_csv` for table-based exports and `export_q
 |------------|------------|---------------|
 | `list` | List/discover objects | `list_databases`, `list_tables` |
 | `read` | Read data | `read_records`, `run_select_query` |
-| `create` | Insert records | `create_record`, `bulk_insert` |
+| `create` | Insert records and seed data | `create_record`, `bulk_insert`, `execute_seed_plan` |
 | `update` | Update records | `update_record`, `bulk_update` |
 | `delete` | Delete records | `delete_record`, `bulk_delete` |
 | `execute` | Custom SQL | `execute_write_query` |
@@ -149,22 +149,30 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `bulk_update` - Batch update (performance)
 - `bulk_delete` - Batch delete (performance)
 
-### 4. Query Management (3 tools)
+### 4. Seed Operations (6 tools)
+- `plan_seed_data` - Build FK-aware relational seed plans
+- `generate_seed_preview` - Preview deterministic dummy rows without writing
+- `execute_seed_plan` - Execute confirmed seed plans with transaction and rollback safety
+- `validate_seed_integrity` - Validate row counts, FK orphans, required columns, and unique collisions
+- `infer_seed_rules` - Infer advanced generators from schema, samples, unique indexes, and domain presets
+- `seed_from_template` - Create reusable plan-first seed workflows for ecommerce, POS, and CRM domains
+
+### 5. Query Management (3 tools)
 - `run_select_query` - Execute SELECT queries
 - `execute_write_query` - Execute INSERT/UPDATE/DELETE
 - `repair_query` - Diagnose and fix SQL errors
 
-### 5. Schema Management (4 tools)
+### 6. Schema Management (4 tools)
 - `create_table` - Create new tables
 - `alter_table` - Modify table structure
 - `drop_table` - Delete tables
 - `execute_ddl` - Execute raw DDL
 
-### 6. Data Export (2 tools)
+### 7. Data Export (2 tools)
 - `export_table_to_csv` - Export table data to CSV
 - `export_query_to_csv` - Export SELECT query results to CSV
 
-### 7. Index Management (10 tools)
+### 8. Index Management (10 tools)
 - `list_indexes` - List table indexes
 - `get_index_info` - Get index details
 - `create_index` - Create indexes
@@ -176,7 +184,7 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `get_fulltext_stats` - Get FULLTEXT index statistics
 - `optimize_fulltext` - Optimize FULLTEXT indexes
 
-### 8. Constraint Management (7 tools)
+### 9. Constraint Management (7 tools)
 - `list_foreign_keys` - List foreign keys
 - `list_constraints` - List all constraints
 - `add_foreign_key` - Add foreign key
@@ -185,7 +193,7 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `drop_constraint` - Remove constraint
 - `add_check_constraint` - Add check constraint
 
-### 9. Stored Procedures (6 tools)
+### 10. Stored Procedures (6 tools)
 - `list_stored_procedures` - List procedures
 - `get_stored_procedure_info` - Get procedure details
 - `execute_stored_procedure` - Execute procedures
@@ -193,7 +201,7 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `drop_stored_procedure` - Remove procedures
 - `show_create_procedure` - Show CREATE statement
 
-### 10. Views Management (6 tools)
+### 11. Views Management (6 tools)
 - `list_views` - List views
 - `get_view_info` - Get view details
 - `create_view` - Create views
@@ -201,14 +209,14 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `drop_view` - Remove views
 - `show_create_view` - Show CREATE statement
 
-### 11. Triggers Management (5 tools)
+### 12. Triggers Management (5 tools)
 - `list_triggers` - List triggers
 - `get_trigger_info` - Get trigger details
 - `create_trigger` - Create triggers
 - `drop_trigger` - Remove triggers
 - `show_create_trigger` - Show CREATE statement
 
-### 12. Table Maintenance (8 tools)
+### 13. Table Maintenance (8 tools)
 - `analyze_table` - Update statistics
 - `optimize_table` - Reclaim space
 - `check_table` - Check for errors
@@ -218,19 +226,19 @@ Tool enabled = (Has Permission) AND (Has Category OR No categories specified)
 - `flush_table` - Close/reopen table
 - `get_table_size` - Get size information
 
-### 13. Transaction Management (5 tools)
+### 14. Transaction Management (5 tools)
 - `begin_transaction` - Start transaction
 - `commit_transaction` - Commit transaction
 - `rollback_transaction` - Rollback transaction
 - `get_transaction_status` - Check transaction state
 - `execute_in_transaction` - Execute within transaction
 
-### 14. Query Optimization (3 tools)
+### 15. Query Optimization (3 tools)
 - `analyze_query` - Analyze query performance
 - `get_optimization_hints` - Get optimizer hints
 - `repair_query` - Repair broken SQL queries
 
-### 15. Utilities (5 tools)
+### 16. Utilities (5 tools)
 - `test_connection` - Test connectivity
 - `describe_connection` - Connection info
 - `read_changelog` - Read changelog
@@ -329,6 +337,57 @@ For high-performance operations with large datasets:
 - **Bulk Update**: Update multiple records with different conditions
 - **Bulk Delete**: Delete multiple record sets in batches
 
+### Relational Data Seeder
+
+For dummy data on related tables, use the seed workflow:
+
+```javascript
+const plan = await mcp.call("plan_seed_data", {
+  target_tables: ["orders"],
+  rows_per_table: 20,
+  include_dependencies: true,
+  include_children: true,
+  random_seed: 42
+});
+
+await mcp.call("generate_seed_preview", {
+  plan_id: plan.plan_id,
+  max_preview_rows_per_table: 3
+});
+
+await mcp.call("execute_seed_plan", {
+  plan_id: plan.plan_id,
+  dry_run: false,
+  confirm_token: plan.confirm_token
+});
+
+await mcp.call("validate_seed_integrity", {
+  plan_id: plan.plan_id
+});
+```
+
+`execute_seed_plan` defaults to dry-run, requires confirmation for writes, blocks production-like database names unless explicitly allowed, and uses transaction rollback on errors.
+
+Composite FK/PK support resolves multi-column parent tuples together, so relations such as `(tenant_id, region_id)` or `(tenant_id, region_id, order_id)` are not mixed across different parent rows.
+
+Advanced rule inference and templates:
+
+```javascript
+await mcp.call("infer_seed_rules", {
+  tables: ["orders", "order_items"],
+  domain: "ecommerce",
+  sample_size: 25
+});
+
+await mcp.call("seed_from_template", {
+  template: "ecommerce",
+  scale: "small",
+  random_seed: 42
+});
+```
+
+`seed_from_template` is plan-first and does not write data directly. Review its plan/preview, then execute with `execute_seed_plan`.
+
 ### Transaction Management
 
 Full ACID transaction support:

package/README.md

@@ -4,7 +4,7 @@
 
 **A production-ready Model Context Protocol (MCP) server for MySQL database integration with AI agents**
 
-**Last Updated:** 2026-05-06 22:38:42
+**Last Updated:** 2026-05-11 10:44:46
 
 [![npm version](https://img.shields.io/npm/v/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mcp-mysql-server)
 [![npm downloads](https://img.shields.io/npm/dm/@berthojoris/mcp-mysql-server)](https://www.npmjs.com/package/@berthojoris/mcp-mysql-server)
@@ -148,8 +148,8 @@ If you want ready-to-copy snippets per client (Claude Code/Cursor/Windsurf/Cline
         "-y",
         "@berthojoris/mcp-mysql-server",
         "mysql://user:password@localhost:3306/database_name_here",
-        "list,read,utility,create,update,ddl",
-        "database_discovery,crud_operations,custom_queries,schema_management,index_management,constraint_management,table_maintenance,query_optimization,analysis"
+        "list,read,utility,create,update,ddl,transaction",
+        "database_discovery,crud_operations,custom_queries,schema_management,index_management,constraint_management,table_maintenance,query_optimization,analysis,seed_operations"
       ]
     }
   }
@@ -282,6 +282,7 @@ Use documentation categories to fine-tune which tools are exposed (Layer 2):
 | `database_discovery` | Explore databases, tables, and schema structure | `get_all_tables_relationships, list_databases, list_tables, read_table_schema` |
 | `crud_operations` | Create, read, update, delete operations on data | `create_record, delete_record, read_records, update_record` |
 | `bulk_operations` | High-performance batch processing operations | `bulk_delete, bulk_insert, bulk_update` |
+| `seed_operations` | FK-aware relational dummy data seeding | `execute_seed_plan, generate_seed_preview, infer_seed_rules, plan_seed_data, seed_from_template, validate_seed_integrity` |
 | `custom_queries` | Execute custom SQL queries and advanced operations | `execute_write_query, run_select_query` |
 | `schema_management` | Manage database schema, tables, and structure | `alter_table, create_table, drop_table, execute_ddl` |
 | `utilities` | Database utilities, diagnostics, and helper functions | `cursor_execute_request, describe_connection, export_query_to_csv, export_table_to_csv, list_all_tools, read_changelog, test_connection` |
@@ -299,7 +300,7 @@ Use documentation categories to fine-tune which tools are exposed (Layer 2):
   <summary>Copy/paste list (comma-separated, no spaces)</summary>
 
 ```text
-database_discovery,crud_operations,bulk_operations,custom_queries,schema_management,utilities,transaction_management,stored_procedures,views_management,triggers_management,index_management,constraint_management,table_maintenance,query_optimization,analysis
+database_discovery,crud_operations,bulk_operations,seed_operations,custom_queries,schema_management,utilities,transaction_management,stored_procedures,views_management,triggers_management,index_management,constraint_management,table_maintenance,query_optimization,analysis
 ```
 
 </details>
@@ -310,7 +311,7 @@ Full category → tool mapping (and examples) lives in **[DOCUMENTATIONS.md →
 
 ## Available Tools
 
-The server exposes **79 tools** organized into categories (CRUD, schema, and utilities).
+The server exposes **85 tools** organized into categories (CRUD, seed, schema, and utilities).
 
 - Complete list of tools: **[DOCUMENTATIONS.md → Complete Tools Reference](DOCUMENTATIONS.md#🔧-complete-tools-reference)**
 
@@ -322,6 +323,7 @@ For comprehensive documentation, see **[DOCUMENTATIONS.md](DOCUMENTATIONS.md)**:
 
 - **DDL Operations** - Create, alter, and drop tables
 - **Data Export Tools** - Export to CSV, JSON, and SQL formats
+- **Relational Data Seeder** - Plan, preview, execute, validate, infer rules, and template FK-aware dummy data
 - **Data Import Tools** - Import from CSV and JSON sources
 - **Data Migration Tools** - Copy, move, clone, compare, and sync data
 - **Schema Versioning** - Version control for database schema changes

package/bin/mcp-mysql.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * MCP MySQL Server CLI
@@ -50,7 +50,7 @@ if (!mysqlUrl) {
     "  # Dual-layer: Permissions + Categories (fine-grained control)",
   );
   console.error(
-    '  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility" "database_discovery,custom_queries,analysis"',
+    '  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility" "database_discovery,custom_queries,analysis"',
   );
   console.error("");
   console.error("Permissions (Layer 1 - Broad Control):");
@@ -66,13 +66,13 @@ if (!mysqlUrl) {
     "  schema_management, utilities, transaction_management, stored_procedures,",
   );
   console.error(
-    "  views_management, triggers_management, index_management,",
+    "  views_management, triggers_management, index_management,",
   );
   console.error(
-    "  constraint_management, table_maintenance, query_optimization,",
+    "  constraint_management, table_maintenance, query_optimization,",
   );
   console.error(
-    "  analysis",
+    "  analysis, seed_operations",
   );
   console.error("");
   console.error("Filtering Logic:");

package/dist/config/featureConfig.d.ts

@@ -14,7 +14,7 @@ export declare enum ToolCategory {
     PROCEDURE = "procedure"
 }
 /**
- * Documentation categories from README (13 categories)
+ * Documentation categories from README
  * More intuitive and matches user mental model
  */
 export declare enum DocCategory {
@@ -32,7 +32,8 @@ export declare enum DocCategory {
     CONSTRAINT_MANAGEMENT = "constraint_management",
     TABLE_MAINTENANCE = "table_maintenance",
     QUERY_OPTIMIZATION = "query_optimization",
-    ANALYSIS = "analysis"
+    ANALYSIS = "analysis",
+    SEED_OPERATIONS = "seed_operations"
 }
 /**
  * Map of tool names to their legacy categories

package/dist/config/featureConfig.js

@@ -24,7 +24,7 @@ var ToolCategory;
     ToolCategory["PROCEDURE"] = "procedure";
 })(ToolCategory || (exports.ToolCategory = ToolCategory = {}));
 /**
- * Documentation categories from README (13 categories)
+ * Documentation categories from README
  * More intuitive and matches user mental model
  */
 var DocCategory;
@@ -44,6 +44,7 @@ var DocCategory;
     DocCategory["TABLE_MAINTENANCE"] = "table_maintenance";
     DocCategory["QUERY_OPTIMIZATION"] = "query_optimization";
     DocCategory["ANALYSIS"] = "analysis";
+    DocCategory["SEED_OPERATIONS"] = "seed_operations";
 })(DocCategory || (exports.DocCategory = DocCategory = {}));
 /**
  * Map of tool names to their legacy categories
@@ -72,6 +73,19 @@ exports.toolCategoryMap = {
     bulkInsert: ToolCategory.CREATE,
     bulkUpdate: ToolCategory.UPDATE,
     bulkDelete: ToolCategory.DELETE,
+    // Seed operations
+    planSeedData: ToolCategory.LIST,
+    plan_seed_data: ToolCategory.LIST,
+    generateSeedPreview: ToolCategory.READ,
+    generate_seed_preview: ToolCategory.READ,
+    executeSeedPlan: ToolCategory.CREATE,
+    execute_seed_plan: ToolCategory.CREATE,
+    validateSeedIntegrity: ToolCategory.READ,
+    validate_seed_integrity: ToolCategory.READ,
+    inferSeedRules: ToolCategory.READ,
+    infer_seed_rules: ToolCategory.READ,
+    seedFromTemplate: ToolCategory.LIST,
+    seed_from_template: ToolCategory.LIST,
     // Query tools
     runSelectQuery: ToolCategory.READ,
     executeWriteQuery: ToolCategory.EXECUTE,
@@ -175,6 +189,19 @@ exports.toolDocCategoryMap = {
     bulkInsert: DocCategory.BULK_OPERATIONS,
     bulkUpdate: DocCategory.BULK_OPERATIONS,
     bulkDelete: DocCategory.BULK_OPERATIONS,
+    // Seed Operations
+    planSeedData: DocCategory.SEED_OPERATIONS,
+    plan_seed_data: DocCategory.SEED_OPERATIONS,
+    generateSeedPreview: DocCategory.SEED_OPERATIONS,
+    generate_seed_preview: DocCategory.SEED_OPERATIONS,
+    executeSeedPlan: DocCategory.SEED_OPERATIONS,
+    execute_seed_plan: DocCategory.SEED_OPERATIONS,
+    validateSeedIntegrity: DocCategory.SEED_OPERATIONS,
+    validate_seed_integrity: DocCategory.SEED_OPERATIONS,
+    inferSeedRules: DocCategory.SEED_OPERATIONS,
+    infer_seed_rules: DocCategory.SEED_OPERATIONS,
+    seedFromTemplate: DocCategory.SEED_OPERATIONS,
+    seed_from_template: DocCategory.SEED_OPERATIONS,
     // Custom Queries
     runSelectQuery: DocCategory.CUSTOM_QUERIES,
     executeWriteQuery: DocCategory.CUSTOM_QUERIES,
@@ -283,11 +310,13 @@ const legacyToDocCategoryMap = {
         DocCategory.TABLE_MAINTENANCE,
         DocCategory.ANALYSIS,
         DocCategory.UTILITIES,
+        DocCategory.SEED_OPERATIONS,
     ],
-    read: [DocCategory.CRUD_OPERATIONS, DocCategory.CUSTOM_QUERIES, DocCategory.ANALYSIS],
+    read: [DocCategory.CRUD_OPERATIONS, DocCategory.CUSTOM_QUERIES, DocCategory.ANALYSIS, DocCategory.SEED_OPERATIONS],
     create: [
         DocCategory.CRUD_OPERATIONS,
         DocCategory.BULK_OPERATIONS,
+        DocCategory.SEED_OPERATIONS,
     ],
     update: [
         DocCategory.CRUD_OPERATIONS,
@@ -311,7 +340,7 @@ const legacyToDocCategoryMap = {
         DocCategory.TABLE_MAINTENANCE,
         DocCategory.QUERY_OPTIMIZATION,
     ],
-    transaction: [DocCategory.TRANSACTION_MANAGEMENT],
+    transaction: [DocCategory.TRANSACTION_MANAGEMENT, DocCategory.SEED_OPERATIONS],
     procedure: [DocCategory.STORED_PROCEDURES],
 };
 /**

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export declare class MySQLMCP {
     private macroTools;
     private smartQueryBuilderTools;
     private fulltextSearchTools;
+    private relationalSeederTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string, categoriesConfig?: string);
@@ -427,6 +428,36 @@ export declare class MySQLMCP {
         data?: any;
         error?: string;
     }>;
+    planSeedData(params: any): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    generateSeedPreview(params: any): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    executeSeedPlan(params: any): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    validateSeedIntegrity(params: any): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    inferSeedRules(params: any): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+    seedFromTemplate(params: any): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     close(): Promise<void>;
     /**
      * Analyze a query and get optimization suggestions

package/dist/index.js

@@ -22,6 +22,7 @@ const aiTools_1 = require("./tools/aiTools");
 const macroTools_1 = require("./tools/macroTools");
 const smartQueryBuilderTools_1 = require("./tools/smartQueryBuilderTools");
 const fulltextSearchTools_1 = require("./tools/fulltextSearchTools");
+const relationalSeederTools_1 = require("./tools/relationalSeederTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -51,6 +52,7 @@ class MySQLMCP {
         this.macroTools = new macroTools_1.MacroTools(this.security);
         this.smartQueryBuilderTools = new smartQueryBuilderTools_1.SmartQueryBuilderTools(this.security);
         this.fulltextSearchTools = new fulltextSearchTools_1.FulltextSearchTools(this.security);
+        this.relationalSeederTools = new relationalSeederTools_1.RelationalSeederTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
@@ -414,6 +416,49 @@ class MySQLMCP {
         }
         return this.crudTools.bulkDelete(params);
     }
+    // Relational Data Seeder Tools
+    async planSeedData(params) {
+        const check = this.checkToolEnabled("planSeedData");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.relationalSeederTools.planSeedData(params);
+    }
+    async generateSeedPreview(params) {
+        const check = this.checkToolEnabled("generateSeedPreview");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.relationalSeederTools.generateSeedPreview(params);
+    }
+    async executeSeedPlan(params) {
+        const check = this.checkToolEnabled("executeSeedPlan");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.relationalSeederTools.executeSeedPlan(params);
+    }
+    async validateSeedIntegrity(params) {
+        const check = this.checkToolEnabled("validateSeedIntegrity");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.relationalSeederTools.validateSeedIntegrity(params);
+    }
+    async inferSeedRules(params) {
+        const check = this.checkToolEnabled("inferSeedRules");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.relationalSeederTools.inferSeedRules(params);
+    }
+    async seedFromTemplate(params) {
+        const check = this.checkToolEnabled("seedFromTemplate");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.relationalSeederTools.seedFromTemplate(params);
+    }
     // Close database connection
     async close() {
         const db = connection_1.default.getInstance();