@neverinfamous/mysql-mcp 2.1.0

package/src/adapters/mysql/prompts/eventScheduler.ts

@@ -0,0 +1,103 @@
+/**
+ * MySQL Prompt - Event Scheduler Setup
+ * 
+ * Complete Event Scheduler configuration guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupEventsPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_events',
+        description: 'Complete MySQL Event Scheduler setup and configuration guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL Event Scheduler Setup Guide
+
+MySQL Event Scheduler allows you to schedule SQL statements to run at specific times or intervals.
+
+## Prerequisites
+
+1. **MySQL 5.1+** (Event Scheduler available)
+2. **EVENT privilege** for creating events
+3. **Event Scheduler enabled** globally
+
+## Step 1: Enable Event Scheduler
+
+Check current status:
+\`\`\`sql
+SHOW VARIABLES LIKE 'event_scheduler';
+\`\`\`
+
+Enable permanently in my.cnf:
+\`\`\`ini
+[mysqld]
+event_scheduler = ON
+\`\`\`
+
+Enable at runtime:
+\`\`\`sql
+SET GLOBAL event_scheduler = ON;
+\`\`\`
+
+## Step 2: Create a One-Time Event
+
+\`\`\`sql
+CREATE EVENT cleanup_old_logs
+ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR
+DO
+    DELETE FROM logs WHERE created_at < DATE_SUB(NOW(), INTERVAL 30 DAY);
+\`\`\`
+
+## Step 3: Create a Recurring Event
+
+\`\`\`sql
+CREATE EVENT daily_stats_rollup
+ON SCHEDULE EVERY 1 DAY
+STARTS CURRENT_TIMESTAMP
+DO
+    INSERT INTO daily_stats (date, total_orders, revenue)
+    SELECT DATE(created_at), COUNT(*), SUM(amount)
+    FROM orders
+    WHERE DATE(created_at) = DATE_SUB(CURDATE(), INTERVAL 1 DAY)
+    GROUP BY DATE(created_at);
+\`\`\`
+
+## Step 4: Event with Expiration
+
+\`\`\`sql
+CREATE EVENT temp_promotion
+ON SCHEDULE EVERY 1 HOUR
+STARTS '2024-01-01 00:00:00'
+ENDS '2024-01-31 23:59:59'
+DO
+    UPDATE products SET discount = 0.10 WHERE category = 'promo';
+\`\`\`
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| \`mysql_event_create\` | Create scheduled event |
+| \`mysql_event_alter\` | Modify existing event |
+| \`mysql_event_drop\` | Remove event |
+| \`mysql_event_list\` | List all events |
+| \`mysql_event_status\` | Event execution history |
+| \`mysql_scheduler_status\` | Scheduler global status |
+
+## Best Practices
+
+1. **Use DISABLE ON SLAVE** in replication environments
+2. **Set appropriate DEFINER** for security
+3. **Monitor event execution** with performance_schema
+4. **Handle errors gracefully** - events don't report errors visibly
+
+## Common Issues
+
+1. **Events not running**: Check event_scheduler is ON
+2. **Permission denied**: Grant EVENT privilege
+3. **Event disappeared**: Check ON COMPLETION PRESERVE setting
+
+Start by checking the scheduler status with \`mysql_scheduler_status\`.`);
+        }
+    };
+}

package/src/adapters/mysql/prompts/healthCheck.ts

@@ -0,0 +1,56 @@
+/**
+ * MySQL Prompt - Database Health Check
+ * 
+ * Guides user through comprehensive database health assessment.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createDatabaseHealthCheckPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_database_health_check',
+        description: 'Comprehensive database health assessment workflow',
+        arguments: [
+            { name: 'focus', description: 'Optional focus area: connections, performance, replication, storage', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            const focus = args['focus'] ?? 'all';
+
+            return Promise.resolve(`# MySQL Database Health Check
+
+Perform a comprehensive health assessment for this MySQL database.
+${focus !== 'all' ? `**Focus area:** ${focus}` : ''}
+
+## Step 1: Check Connection Health
+Use \`mysql://health\` resource or \`mysql_pool_stats\` tool to verify:
+- Connection pool utilization (should be < 80%)
+- No connection errors or timeouts
+- Thread activity within normal range
+
+## Step 2: Assess Performance
+Use \`mysql://performance\` resource or performance tools:
+- Buffer pool hit ratio (should be > 99%)
+- Slow query count and trends
+- Table scan vs index usage ratio
+- Temporary tables to disk ratio (should be < 10%)
+
+## Step 3: Check Storage and Tables
+- Table fragmentation (use \`mysql_check_table\`)
+- Index health and unused indexes (\`mysql://indexes\`)
+- InnoDB status (\`mysql://innodb\`)
+
+## Step 4: Replication Status (if applicable)
+Use \`mysql://replication\` resource:
+- Replication lag (should be < 1 second typically)
+- IO and SQL thread status
+- Binary log position
+
+## Step 5: Generate Recommendations
+Based on findings, provide:
+1. Critical issues requiring immediate attention
+2. Performance optimization opportunities
+3. Maintenance tasks to schedule
+
+Please proceed with the health check and report findings.`);
+        }
+    };
+}

package/src/adapters/mysql/prompts/index.ts

@@ -0,0 +1,329 @@
+/**
+ * MySQL MCP Prompts
+ * 
+ * AI-powered prompts for query building, schema design, and optimization.
+ * 19 prompts total.
+ */
+import type { MySQLAdapter } from '../MySQLAdapter.js';
+import type { PromptDefinition, RequestContext, ToolDefinition } from '../../../types/index.js';
+import { generateCompactIndex, generateDiscoveryPrompt } from '../../../utils/promptGenerator.js';
+
+// Modular prompt imports
+import { createDatabaseHealthCheckPrompt } from './healthCheck.js';
+import { createBackupStrategyPrompt } from './backupStrategy.js';
+import { createIndexTuningPrompt } from './indexTuning.js';
+import { createSetupRouterPrompt } from './routerSetup.js';
+import { createSetupProxysqlPrompt } from './proxysqlSetup.js';
+import { createSetupReplicationPrompt } from './replicationSetup.js';
+import { createSetupMysqlshPrompt } from './mysqlshSetup.js';
+// New prompts (5)
+import { createSetupEventsPrompt } from './eventScheduler.js';
+import { createSysSchemaGuidePrompt } from './sysSchema.js';
+import { createSetupSpatialPrompt } from './spatialSetup.js';
+import { createSetupClusterPrompt } from './clusterSetup.js';
+import { createSetupDocstorePrompt } from './docstoreSetup.js';
+
+/**
+ * Get all MySQL prompts (14 total)
+ * 
+ * Core (7):
+ * - mysql_tool_index - Lazy hydration tool index
+ * - mysql_quick_query - Quick query shortcut
+ * - mysql_quick_schema - Quick schema exploration
+ * - mysql_query_builder - Query construction assistance
+ * - mysql_schema_design - Schema design guidance
+ * - mysql_performance_analysis - Query performance analysis
+ * - mysql_migration - Migration script generation
+ * 
+ * Extended (7):
+ * - mysql_database_health_check - Comprehensive health assessment
+ * - mysql_backup_strategy - Enterprise backup planning
+ * - mysql_index_tuning - Index analysis and optimization
+ * - mysql_setup_router - MySQL Router configuration
+ * - mysql_setup_proxysql - ProxySQL configuration
+ * - mysql_setup_replication - Replication setup guide
+ * - mysql_setup_shell - MySQL Shell usage guide
+ */
+export function getMySQLPrompts(adapter: MySQLAdapter): PromptDefinition[] {
+    // Get tool definitions for generating indexes
+    const toolDefs = adapter.getToolDefinitions();
+
+    return [
+        // Lazy hydration prompts
+        createToolIndexPrompt(toolDefs),
+        createQuickQueryPrompt(),
+        createQuickSchemaPrompt(),
+        // Original prompts
+        createQueryBuilderPrompt(),
+        createSchemaDesignPrompt(),
+        createPerformanceAnalysisPrompt(),
+        createMigrationPrompt(),
+        // Extended prompts (modular imports)
+        createDatabaseHealthCheckPrompt(),
+        createBackupStrategyPrompt(),
+        createIndexTuningPrompt(),
+        createSetupRouterPrompt(),
+        createSetupProxysqlPrompt(),
+        createSetupReplicationPrompt(),
+        createSetupMysqlshPrompt(),
+        // New prompts (5)
+        createSetupEventsPrompt(),
+        createSysSchemaGuidePrompt(),
+        createSetupSpatialPrompt(),
+        createSetupClusterPrompt(),
+        createSetupDocstorePrompt()
+    ];
+}
+
+// =============================================================================
+// Core Prompts (inline for simplicity)
+// =============================================================================
+
+function createQueryBuilderPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_query_builder',
+        description: 'Help build SQL queries for common operations',
+        arguments: [
+            { name: 'operation', description: 'Type of query (SELECT, INSERT, UPDATE, DELETE)', required: true },
+            { name: 'table', description: 'Target table name', required: true },
+            { name: 'description', description: 'What you want to accomplish', required: true }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext): Promise<string> => {
+            return Promise.resolve(`
+You are a MySQL query expert. Help build a ${args['operation']} query for the table "${args['table']}".
+
+User's goal: ${args['description']}
+
+Please provide:
+1. The complete SQL query with proper escaping
+2. Explanation of what the query does
+3. Any indexes that would improve performance
+4. Security considerations (parameterization, input validation)
+
+Use MySQL best practices:
+- Use backticks for identifiers
+- Use prepared statement placeholders (?)
+- Include appropriate WHERE clauses
+- Consider using LIMIT for large result sets
+`);
+        }
+    };
+}
+
+/**
+ * Tool index prompt - shows all available tools in a compact format
+ */
+function createToolIndexPrompt(toolDefs: ToolDefinition[]): PromptDefinition {
+    const compactIndex = generateCompactIndex(toolDefs);
+    const discovery = generateDiscoveryPrompt(toolDefs);
+
+    return {
+        name: 'mysql_tool_index',
+        description: 'Show all available MySQL tools organized by category',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`
+# MySQL MCP Tool Index
+
+This server provides ${String(toolDefs.length)} MySQL tools for database operations.
+
+${discovery}
+## Complete Tool List
+
+${compactIndex}
+
+**Usage**: Call any tool by name with the required arguments. Use \`mysql_read_query\` for SELECT queries and \`mysql_write_query\` for INSERT/UPDATE/DELETE.
+`);
+        }
+    };
+}
+
+/**
+ * Quick query prompt - shortcut for running queries
+ */
+function createQuickQueryPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_quick_query',
+        description: 'Quickly run a SQL query - shortcut for mysql_read_query or mysql_write_query',
+        arguments: [
+            { name: 'sql', description: 'SQL query to execute', required: true },
+            { name: 'type', description: 'Query type: read or write (default: read)', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            const queryType = args['type']?.toLowerCase() === 'write' ? 'write' : 'read';
+            const toolName = queryType === 'write' ? 'mysql_write_query' : 'mysql_read_query';
+
+            return Promise.resolve(`
+Execute this ${queryType} query using the \`${toolName}\` tool:
+
+\`\`\`sql
+${args['sql']}
+\`\`\`
+
+**Tool to use**: \`${toolName}\`
+**Arguments**: \`{ "query": "${(args['sql'] ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"')}" }\`
+`);
+        }
+    };
+}
+
+/**
+ * Quick schema prompt - shortcut for exploring database schema
+ */
+function createQuickSchemaPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_quick_schema',
+        description: 'Quickly explore database schema - lists tables or describes a specific table',
+        arguments: [
+            { name: 'table', description: 'Table name to describe (leave empty to list all tables)', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            if (args['table']) {
+                return Promise.resolve(`
+Describe the structure of table **${args['table']}** using the \`mysql_describe_table\` tool:
+
+**Tool to use**: \`mysql_describe_table\`
+**Arguments**: \`{ "table": "${args['table']}" }\`
+
+This will show columns, types, indexes, and constraints.
+`);
+            }
+
+            return Promise.resolve(`
+List all tables in the database using the \`mysql_list_tables\` tool:
+
+**Tool to use**: \`mysql_list_tables\`
+**Arguments**: \`{}\`
+
+This will show all tables with their row counts and metadata.
+`);
+        }
+    };
+}
+
+function createSchemaDesignPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_schema_design',
+        description: 'Help design table schemas',
+        arguments: [
+            { name: 'entity', description: 'What entity/data you want to store', required: true },
+            { name: 'requirements', description: 'Any specific requirements', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`
+You are a MySQL database architect. Design a schema for: ${args['entity']}
+
+${args['requirements'] ? `Requirements: ${args['requirements']}` : ''}
+
+Please provide:
+1. CREATE TABLE statement with:
+   - Appropriate data types
+   - Primary key
+   - Indexes for common queries
+   - Foreign key relationships if applicable
+   - Engine: InnoDB (for transactions)
+   - Charset: utf8mb4 (for full Unicode support)
+
+2. Explanation of design choices
+
+3. Sample INSERT statements
+
+4. Common SELECT queries with indexes
+
+Best practices to follow:
+- Use underscore_case for column names
+- Include created_at and updated_at timestamps
+- Use UNSIGNED for positive-only integers
+- Consider JSON columns for flexible data
+- Add appropriate indexes based on query patterns
+`);
+        }
+    };
+}
+
+function createPerformanceAnalysisPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_performance_analysis',
+        description: 'Analyze and optimize slow queries',
+        arguments: [
+            { name: 'query', description: 'The slow query to analyze', required: true },
+            { name: 'context', description: 'Table structure and data volume', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`
+You are a MySQL performance expert. Analyze this query:
+
+\`\`\`sql
+${args['query']}
+\`\`\`
+
+${args['context'] ? `Context: ${args['context']}` : ''}
+
+Please provide:
+1. Run EXPLAIN on the query and interpret results
+2. Identify performance bottlenecks:
+   - Full table scans
+   - Missing indexes
+   - Suboptimal join order
+   - Unnecessary columns in SELECT
+   
+3. Recommended optimizations:
+   - Index recommendations
+   - Query rewrites
+   - Schema changes if needed
+   
+4. Estimated improvement
+
+Use these MySQL tools to analyze:
+- mysql_explain for execution plan
+- mysql_explain_analyze for actual timing
+- mysql_index_usage to check index utilization
+- mysql_table_stats for data volume
+`);
+        }
+    };
+}
+
+function createMigrationPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_migration',
+        description: 'Generate migration scripts for schema changes',
+        arguments: [
+            { name: 'change', description: 'What schema change you need', required: true },
+            { name: 'table', description: 'Target table name', required: true }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`
+You are a MySQL migration expert. Create a migration for: ${args['change']}
+
+Target table: ${args['table']}
+
+Please provide:
+1. UP migration (apply the change):
+   - ALTER TABLE statements
+   - Create any new indexes
+   - Update any constraints
+   
+2. DOWN migration (rollback):
+   - Reverse all changes
+   - Handle data safely
+   
+3. Safety considerations:
+   - Impact on running queries
+   - Lock time estimates
+   - Data preservation
+   
+4. For large tables, provide online migration options:
+   - pt-online-schema-change approach
+   - gh-ost compatibility
+   - Rolling deployment strategy
+
+Best practices:
+- Test on staging first
+- Backup before migration
+- Run during low-traffic periods
+- Monitor for lock contention
+`);
+        }
+    };
+}

package/src/adapters/mysql/prompts/indexTuning.ts

@@ -0,0 +1,90 @@
+/**
+ * MySQL Prompt - Index Tuning
+ * 
+ * Index analysis and optimization workflow.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createIndexTuningPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_index_tuning',
+        description: 'Analyze and optimize database indexes',
+        arguments: [
+            { name: 'table', description: 'Specific table to analyze (optional, analyzes all if not provided)', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            const table = args['table'];
+
+            return Promise.resolve(`# MySQL Index Tuning Workflow
+
+${table ? `Analyze and optimize indexes for table: **${table}**` : 'Analyze and optimize indexes across the database'}
+
+## Step 1: Identify Index Issues
+
+### Check for Unused Indexes
+Use \`mysql://indexes\` resource to find indexes with zero scans.
+Unused indexes:
+- Waste storage space
+- Slow down INSERT/UPDATE/DELETE operations
+- Should be reviewed for removal
+
+### Check for Missing Indexes
+Use \`mysql_index_usage\` or \`mysql_explain_analyze\` on slow queries:
+- Look for full table scans (type = ALL)
+- Look for range scans that could use indexes (type = range without index)
+- Check for filesort and temporary table usage
+
+### Check for Duplicate Indexes
+The \`mysql://indexes\` resource identifies potential duplicates:
+- Indexes with same leading columns
+- Redundant indexes (e.g., INDEX(a) when INDEX(a,b) exists)
+
+## Step 2: Analyze Query Patterns
+
+### Find Slow Queries
+Use \`mysql://performance\` resource or \`mysql_slow_queries\` tool:
+- Identify top queries by execution time
+- Look for queries without appropriate indexes
+
+### EXPLAIN Analysis
+For each slow query, use \`mysql_explain_analyze\`:
+\`\`\`
+Key things to look for:
+- type: ALL (full table scan - bad)
+- type: index (full index scan - often bad)
+- type: range, ref, eq_ref (good)
+- Extra: Using filesort (may need index)
+- Extra: Using temporary (may need index)
+\`\`\`
+
+## Step 3: Index Recommendations
+
+Use \`mysql_index_recommendation\` tool for AI-powered suggestions:
+- Composite index recommendations
+- Covering index opportunities
+- Index order optimization
+
+## Step 4: Implement Changes
+
+### Adding Indexes
+\`\`\`sql
+CREATE INDEX idx_name ON table_name (column1, column2);
+-- Or for large tables, use pt-online-schema-change
+\`\`\`
+
+### Removing Unused Indexes
+\`\`\`sql
+-- First verify the index is truly unused
+DROP INDEX idx_name ON table_name;
+\`\`\`
+
+## Step 5: Verify Improvements
+After changes:
+1. Re-run EXPLAIN on problematic queries
+2. Compare query execution times
+3. Monitor \`mysql://performance\` for improvements
+
+${table ? `\nStart by analyzing indexes on table **${table}**.` : '\nStart by reviewing the `mysql://indexes` resource.'}`);
+        }
+    };
+}

package/src/adapters/mysql/prompts/mysqlshSetup.ts

@@ -0,0 +1,119 @@
+/**
+ * MySQL Prompt - MySQL Shell Setup
+ * 
+ * MySQL Shell installation and usage guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupMysqlshPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_shell',
+        description: 'MySQL Shell setup and usage guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL Shell Setup Guide
+
+MySQL Shell is an advanced client with JavaScript, Python, and SQL modes, plus powerful dump/load utilities.
+
+## Step 1: Verify Installation
+
+Use \`mysqlsh_version\` tool to check if MySQL Shell is installed:
+- Requires MySQL Shell 8.0+
+- Should be in PATH or configured via MYSQLSH_PATH
+
+## Step 2: Configure Environment
+
+Set environment variables for MCP server:
+\`\`\`bash
+# Path to mysqlsh binary (if not in PATH)
+MYSQLSH_PATH=/usr/bin/mysqlsh
+
+# Working directory for dump/load operations
+MYSQLSH_WORK_DIR=/tmp/mysql-dumps
+
+# Timeout for shell commands (ms, default: 300000 = 5 min)
+MYSQLSH_TIMEOUT=300000
+\`\`\`
+
+## Step 3: Basic MySQL Shell Usage
+
+### SQL Mode
+\`\`\`bash
+mysqlsh --sql mysql://user:pass@localhost/dbname
+\`\`\`
+
+### JavaScript Mode
+\`\`\`bash
+mysqlsh --js mysql://user:pass@localhost
+\\js session.runSql("SELECT 1")
+\`\`\`
+
+### Python Mode
+\`\`\`bash
+mysqlsh --py mysql://user:pass@localhost
+\\py session.run_sql("SELECT 1")
+\`\`\`
+
+## Step 4: Available MCP Tools
+
+### Version and Upgrade Check
+- \`mysqlsh_version\` - Check Shell version
+- \`mysqlsh_check_upgrade\` - Check MySQL server upgrade compatibility
+
+### Data Export
+- \`mysqlsh_export_table\` - Export table to CSV/TSV/JSON
+- \`mysqlsh_dump_instance\` - Dump entire instance (parallel, fast)
+- \`mysqlsh_dump_schemas\` - Dump specific schemas
+- \`mysqlsh_dump_tables\` - Dump specific tables
+
+### Data Import
+- \`mysqlsh_import_table\` - Parallel table import
+- \`mysqlsh_import_json\` - Import JSON documents
+- \`mysqlsh_load_dump\` - Load MySQL Shell dump
+
+### Scripting
+- \`mysqlsh_run_script\` - Execute JS/Python/SQL script
+
+## Step 5: Common Workflows
+
+### Fast Instance Backup
+\`\`\`
+Use mysqlsh_dump_instance tool:
+- 10-20x faster than mysqldump
+- Parallel execution
+- Consistent snapshot
+\`\`\`
+
+### Large Table Import
+\`\`\`
+Use mysqlsh_import_table tool:
+- Parallel chunk loading
+- Automatic transaction management
+- Progress reporting
+\`\`\`
+
+### Schema Migration
+\`\`\`
+1. Check upgrade compatibility: mysqlsh_check_upgrade
+2. Dump source: mysqlsh_dump_instance
+3. Load to target: mysqlsh_load_dump
+\`\`\`
+
+## Step 6: Best Practices
+
+1. **Use dump utilities for large databases** - Much faster than mysqldump
+2. **Set appropriate work directory** - Ensure enough disk space
+3. **Adjust timeout for large operations** - Dumps may take hours
+4. **Use compression** - Reduces storage and transfer time
+
+## Troubleshooting
+
+- **mysqlsh not found**: Set MYSQLSH_PATH
+- **Permission denied**: Check work directory permissions
+- **Timeout**: Increase MYSQLSH_TIMEOUT for large operations
+- **Connection errors**: Verify MySQL connection string
+
+Start by running \`mysqlsh_version\` to verify installation.`);
+        }
+    };
+}