@neverinfamous/mysql-mcp 2.1.0

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

@@ -0,0 +1,32 @@
+
+import { describe, it, expect } from 'vitest';
+import { createMockRequestContext } from '../../../../__tests__/mocks/index.js';
+import { createIndexTuningPrompt } from '../indexTuning.js';
+
+describe('Index Tuning Prompt', () => {
+
+    it('should generate generic tuning advice when no table specified', async () => {
+        const prompt = createIndexTuningPrompt();
+        const result = await prompt.handler!({}, createMockRequestContext());
+
+        expect(result).toContain('Analyze and optimize indexes across the database');
+        expect(result).toContain('Start by reviewing the `mysql://indexes` resource.');
+        expect(result).not.toContain('table: **');
+    });
+
+    it('should generate table-specific tuning advice when table specified', async () => {
+        const prompt = createIndexTuningPrompt();
+        const result = await prompt.handler!({ table: 'users' }, createMockRequestContext());
+
+        expect(result).toContain('Analyze and optimize indexes for table: **users**');
+        expect(result).toContain('Start by analyzing indexes on table **users**.');
+    });
+
+    it('should have correct required argument metadata', () => {
+        const prompt = createIndexTuningPrompt();
+        expect(prompt.name).toBe('mysql_index_tuning');
+        expect(prompt.arguments).toHaveLength(1);
+        expect(prompt.arguments![0].name).toBe('table');
+        expect(prompt.arguments![0].required).toBe(false);
+    });
+});

package/src/adapters/mysql/prompts/__tests__/prompts.test.ts

@@ -0,0 +1,301 @@
+/**
+ * mysql-mcp - Prompts Unit Tests
+ * 
+ * Tests for prompt definitions using centralized mocks.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getMySQLPrompts } from '../index.js';
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext } from '../../../../__tests__/mocks/index.js';
+
+describe('getMySQLPrompts', () => {
+    let prompts: ReturnType<typeof getMySQLPrompts>;
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        prompts = getMySQLPrompts(mockAdapter as unknown as MySQLAdapter);
+    });
+
+    it('should return 19 prompts', () => {
+        expect(prompts).toHaveLength(19);
+    });
+
+    it('should have handler functions for all prompts', () => {
+        for (const prompt of prompts) {
+            expect(typeof prompt.handler).toBe('function');
+        }
+    });
+
+    it('should have descriptions for all prompts', () => {
+        for (const prompt of prompts) {
+            expect(prompt.description).toBeDefined();
+            expect(prompt.description.length).toBeGreaterThan(0);
+        }
+    });
+
+    it('should have unique names for all prompts', () => {
+        const names = prompts.map(p => p.name);
+        const uniqueNames = new Set(names);
+        expect(uniqueNames.size).toBe(names.length);
+    });
+});
+
+describe('Prompt Handler Execution', () => {
+    let prompts: ReturnType<typeof getMySQLPrompts>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        const mockAdapter = createMockMySQLAdapter();
+        prompts = getMySQLPrompts(mockAdapter as unknown as MySQLAdapter);
+        mockContext = createMockRequestContext();
+    });
+
+    const findPrompt = (name: string) => prompts.find(p => p.name === name);
+
+    describe('mysql_query_builder', () => {
+        it('should return message with query guidance', async () => {
+            const prompt = findPrompt('mysql_query_builder');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({ query_type: 'SELECT', table: 'users' }, mockContext) as string;
+            expect(typeof result).toBe('string');
+            expect(result).toContain('query');
+            expect(result).toContain('table');
+        });
+    });
+
+    describe('mysql_tool_index', () => {
+        it('should return tool index content', async () => {
+            const prompt = findPrompt('mysql_tool_index');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext) as string;
+            expect(typeof result).toBe('string');
+            expect(result).toContain('tool');
+        });
+    });
+
+    describe('mysql_quick_query', () => {
+        it('should return read query guidance by default', async () => {
+            const prompt = findPrompt('mysql_quick_query');
+            const result = await prompt!.handler({ query: 'SELECT * FROM users' }, mockContext) as string;
+            expect(result).toContain('mysql_read_query');
+        });
+
+        it('should return write query guidance when type is write', async () => {
+            const prompt = findPrompt('mysql_quick_query');
+            const result = await prompt!.handler({ sql: 'INSERT INTO users...', type: 'write' }, mockContext) as string;
+            expect(result).toContain('mysql_write_query');
+        });
+    });
+
+    describe('mysql_schema_design', () => {
+        it('should return schema design guidance', async () => {
+            const prompt = findPrompt('mysql_schema_design');
+            const result = await prompt!.handler({ entity: 'User' }, mockContext) as string;
+            expect(result).toContain('CREATE TABLE');
+        });
+
+        it('should include specific requirements if provided', async () => {
+            const prompt = findPrompt('mysql_schema_design');
+            const result = await prompt!.handler({ entity: 'User', requirements: 'Must include email indexing' }, mockContext) as string;
+            expect(result).toContain('Must include email indexing');
+        });
+    });
+
+    describe('mysql_performance_analysis', () => {
+        it('should return performance analysis guidance', async () => {
+            const prompt = findPrompt('mysql_performance_analysis');
+            const result = await prompt!.handler({ query: 'SELECT * FROM slow_table' }, mockContext) as string;
+            expect(result).toContain('EXPLAIN');
+        });
+
+        it('should include context if provided', async () => {
+            const prompt = findPrompt('mysql_performance_analysis');
+            const result = await prompt!.handler({ query: 'SELECT * FROM slow_table', context: 'Table has 1M rows' }, mockContext) as string;
+            expect(result).toContain('Table has 1M rows');
+        });
+    });
+
+    describe('mysql_migration', () => {
+        it('should return migration guidance', async () => {
+            const prompt = findPrompt('mysql_migration');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({ change: 'Add column', table: 'users' }, mockContext) as string;
+            expect(typeof result).toBe('string');
+            expect(result).toContain('migration');
+        });
+    });
+
+    describe('mysql_database_health_check', () => {
+        it('should return health check guidance', async () => {
+            const prompt = findPrompt('mysql_database_health_check');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('health');
+        });
+
+        it('should include focus area if provided', async () => {
+            const prompt = findPrompt('mysql_database_health_check');
+            const result = await prompt!.handler({ focus: 'security' }, mockContext) as string;
+            expect(result).toContain('**Focus area:** security');
+        });
+    });
+
+    describe('mysql_backup_strategy', () => {
+        it('should return backup strategy guidance', async () => {
+            const prompt = findPrompt('mysql_backup_strategy');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({ rto: '1 hour', rpo: '15 minutes' }, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('backup');
+        });
+
+        it('should handle missing arguments with defaults', async () => {
+            const prompt = findPrompt('mysql_backup_strategy');
+            const result = await prompt!.handler({}, mockContext) as string;
+            expect(result).toContain('to be determined');
+            expect(result).toContain('unknown');
+        });
+    });
+
+    describe('mysql_quick_schema', () => {
+        it('should return schema exploration guidance (list tables) when no table specified', async () => {
+            const prompt = findPrompt('mysql_quick_schema');
+            const result = await prompt!.handler({}, mockContext) as string;
+            expect(result).toContain('mysql_list_tables');
+        });
+
+        it('should return describe table guidance when table is specified', async () => {
+            const prompt = findPrompt('mysql_quick_schema');
+            const result = await prompt!.handler({ table: 'users' }, mockContext) as string;
+            expect(result).toContain('mysql_describe_table');
+            expect(result).toContain('users');
+        });
+    });
+
+    describe('mysql_index_tuning', () => {
+        it('should return index tuning guidance', async () => {
+            const prompt = findPrompt('mysql_index_tuning');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({ table: 'orders' }, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('orders');
+        });
+    });
+
+    describe('mysql_setup_router', () => {
+        it('should return router setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_router');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('Router');
+        });
+    });
+
+    describe('mysql_setup_proxysql', () => {
+        it('should return proxysql setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_proxysql');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('ProxySQL');
+        });
+    });
+
+    describe('mysql_setup_replication', () => {
+        it('should return replication setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_replication');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('replication');
+        });
+
+        it('should return semisync configuration when requested', async () => {
+            const prompt = findPrompt('mysql_setup_replication');
+            const result = await prompt!.handler({ type: 'semisync' }, mockContext) as string;
+            expect(result).toContain('rpl_semi_sync_replica_enabled');
+        });
+    });
+
+
+    describe('mysql_setup_shell', () => {
+        it('should return shell setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_shell');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('MySQL Shell');
+        });
+    });
+
+    describe('mysql_setup_events', () => {
+        it('should return event scheduler guidance', async () => {
+            const prompt = findPrompt('mysql_setup_events');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('event');
+        });
+    });
+
+    describe('mysql_sys_schema_guide', () => {
+        it('should return sys schema guidance', async () => {
+            const prompt = findPrompt('mysql_sys_schema_guide');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('sys');
+        });
+    });
+
+    describe('mysql_setup_spatial', () => {
+        it('should return spatial setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_spatial');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('spatial');
+        });
+    });
+
+    describe('mysql_setup_cluster', () => {
+        it('should return cluster setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_cluster');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('cluster');
+        });
+    });
+
+    describe('mysql_setup_docstore', () => {
+        it('should return docstore setup guidance', async () => {
+            const prompt = findPrompt('mysql_setup_docstore');
+            expect(prompt).toBeDefined();
+
+            const result = await prompt!.handler({}, mockContext);
+            expect(typeof result).toBe('string');
+            expect(result).toContain('document');
+        });
+    });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * MySQL Prompt - Backup Strategy
+ * 
+ * Enterprise backup planning with RTO/RPO considerations.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createBackupStrategyPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_backup_strategy',
+        description: 'Design enterprise backup strategy with RTO/RPO planning',
+        arguments: [
+            { name: 'rpo', description: 'Recovery Point Objective (e.g., "1 hour", "15 minutes")', required: false },
+            { name: 'rto', description: 'Recovery Time Objective (e.g., "4 hours", "30 minutes")', required: false },
+            { name: 'data_size', description: 'Approximate database size (e.g., "100GB", "2TB")', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            const rpo = args['rpo'] ?? 'to be determined';
+            const rto = args['rto'] ?? 'to be determined';
+            const dataSize = args['data_size'] ?? 'unknown';
+
+            return Promise.resolve(`# MySQL Backup Strategy Planning
+
+Design a comprehensive backup strategy for this MySQL database.
+
+**Requirements:**
+- **RPO (Recovery Point Objective):** ${rpo}
+- **RTO (Recovery Time Objective):** ${rto}
+- **Database Size:** ${dataSize}
+
+## Step 1: Assess Current State
+- Check current binary log configuration (\`mysql://replication\`)
+- Review storage engine (InnoDB recommended for consistent backups)
+- Identify critical tables/databases
+
+## Step 2: Choose Backup Method
+
+### Option A: mysqldump (Logical Backup)
+- **Pros:** Portable, human-readable, works with any storage engine
+- **Cons:** Slower for large databases, locks required for consistency
+- Use: \`mysql_create_dump\` tool
+- Best for: < 100GB, development, cross-version migration
+
+### Option B: MySQL Shell Dump (Parallel Logical Backup)
+- **Pros:** 10-20x faster than mysqldump, parallel execution
+- **Cons:** Requires MySQL Shell 8.0+
+- Use: \`mysqlsh_dump_instance\`, \`mysqlsh_dump_schemas\`
+- Best for: 100GB - 2TB, faster recovery needed
+
+### Option C: Physical Backup (Percona XtraBackup)
+- **Pros:** Hot backup, minimal locking, fast for large databases
+- **Cons:** Same MySQL version required for restore
+- Best for: > 500GB, production systems
+
+## Step 3: Configure Point-in-Time Recovery
+1. Enable binary logging:
+   - log_bin = mysql-bin
+   - expire_logs_days = 7 (or binlog_expire_logs_seconds)
+   - sync_binlog = 1 (for durability)
+
+2. Schedule full backups:
+   - Daily for most workloads
+   - Weekly for stable, low-change databases
+
+3. Continuously archive binary logs to separate storage
+
+## Step 4: Test Recovery
+1. Regularly test full restore to a different server
+2. Test point-in-time recovery procedure
+3. Document and automate recovery steps
+
+## Step 5: Create Backup Schedule
+Based on your RPO of ${rpo}:
+- Calculate backup frequency needed
+- Plan retention policy
+- Set up monitoring and alerting
+
+Please provide your RPO/RTO requirements if not specified, and I'll create a tailored backup plan.`);
+        }
+    };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * MySQL Prompt - InnoDB Cluster Setup
+ * 
+ * Complete InnoDB Cluster and Group Replication setup guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupClusterPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_cluster',
+        description: 'Complete MySQL InnoDB Cluster and Group Replication setup guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL InnoDB Cluster Setup Guide
+
+InnoDB Cluster provides a complete high availability solution using Group Replication, MySQL Shell, and MySQL Router.
+
+## Prerequisites
+
+1. **MySQL 8.0+** (required for InnoDB Cluster)
+2. **MySQL Shell** installed
+3. **At least 3 servers** for fault tolerance
+4. **Network connectivity** between all nodes
+
+## Architecture
+
+\`\`\`
+┌─────────────────┐
+│  MySQL Router   │  ← Applications connect here
+└────────┬────────┘
+         │
+┌────────┴────────┐
+│  InnoDB Cluster │
+├─────────────────┤
+│ Primary (R/W)   │
+│ Secondary (R/O) │
+│ Secondary (R/O) │
+└─────────────────┘
+\`\`\`
+
+## Step 1: Configure Instances
+
+On each MySQL server, add to my.cnf:
+\`\`\`ini
+[mysqld]
+server_id = 1  # Unique per server
+gtid_mode = ON
+enforce_gtid_consistency = ON
+binlog_checksum = NONE
+\`\`\`
+
+## Step 2: Create Cluster (MySQL Shell)
+
+\`\`\`javascript
+// Connect to primary
+\\connect admin@primary-host:3306
+
+// Configure instance
+dba.configureInstance('admin@primary-host:3306');
+
+// Create cluster
+var cluster = dba.createCluster('myCluster');
+
+// Add instances
+cluster.addInstance('admin@secondary1:3306');
+cluster.addInstance('admin@secondary2:3306');
+\`\`\`
+
+## Step 3: Check Cluster Status
+
+\`\`\`javascript
+cluster.status()
+\`\`\`
+
+## Step 4: Bootstrap Router
+
+\`\`\`bash
+mysqlrouter --bootstrap admin@primary-host:3306 --user=mysqlrouter
+\`\`\`
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| \`mysql_gr_status\` | Group Replication status |
+| \`mysql_gr_members\` | List group members |
+| \`mysql_gr_primary\` | Identify current primary |
+| \`mysql_gr_transactions\` | Pending/applied transactions |
+| \`mysql_gr_flow_control\` | Flow control stats |
+| \`mysql_cluster_status\` | InnoDB Cluster status |
+| \`mysql_cluster_instances\` | List cluster instances |
+| \`mysql_cluster_topology\` | Cluster topology |
+| \`mysql_cluster_router_status\` | Router integration |
+| \`mysql_cluster_switchover\` | Switchover recommendation |
+
+## Failover Handling
+
+Automatic failover happens when:
+1. Primary becomes unreachable
+2. Majority of nodes agree (quorum)
+3. New primary is elected
+
+Manual failover:
+\`\`\`javascript
+cluster.setPrimaryInstance('admin@new-primary:3306')
+\`\`\`
+
+## Best Practices
+
+1. **Use odd number of nodes** (3, 5, 7) for quorum
+2. **Deploy Router on app servers** for low latency
+3. **Monitor replication lag** with flow control
+4. **Test failover regularly** in staging
+
+Start by checking cluster status with \`mysql_cluster_status\`.`);
+        }
+    };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * MySQL Prompt - Document Store Setup
+ * 
+ * Complete Document Store / X DevAPI setup guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupDocstorePrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_docstore',
+        description: 'Complete MySQL Document Store and X DevAPI setup guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL Document Store Setup Guide
+
+MySQL Document Store allows you to store and query JSON documents using collections, similar to NoSQL databases.
+
+## Prerequisites
+
+1. **MySQL 8.0+** (full Document Store support)
+2. **X Plugin enabled** (default in 8.0)
+3. **MySQL Shell** for X DevAPI access
+4. **Port 33060** open (X Protocol)
+
+## Step 1: Verify X Plugin
+
+\`\`\`sql
+SHOW PLUGINS WHERE Name = 'mysqlx';
+-- Should show: mysqlx | ACTIVE
+\`\`\`
+
+If not enabled:
+\`\`\`sql
+INSTALL PLUGIN mysqlx SONAME 'mysqlx.so';
+\`\`\`
+
+## Step 2: Create a Collection (MySQL Shell)
+
+\`\`\`javascript
+// Connect using X Protocol
+\\connect mysqlx://user@localhost:33060/mydb
+
+// Create collection
+db.createCollection('users')
+
+// Add documents
+db.users.add({
+    "_id": "user001",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "tags": ["admin", "active"]
+})
+\`\`\`
+
+## Step 3: Query Documents
+
+\`\`\`javascript
+// Find all
+db.users.find()
+
+// Find with filter
+db.users.find("name = 'John Doe'")
+
+// Find with JSON path
+db.users.find("'admin' IN tags")
+\`\`\`
+
+## SQL Access to Collections
+
+Collections are regular tables with a JSON column:
+\`\`\`sql
+-- View collection data
+SELECT * FROM mydb.users;
+
+-- Query with JSON functions
+SELECT doc->>'$.name' AS name
+FROM mydb.users
+WHERE JSON_CONTAINS(doc->'$.tags', '"admin"');
+\`\`\`
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| \`mysql_doc_list_collections\` | List collections |
+| \`mysql_doc_create_collection\` | Create collection |
+| \`mysql_doc_drop_collection\` | Drop collection |
+| \`mysql_doc_find\` | Query documents |
+| \`mysql_doc_add\` | Add documents |
+| \`mysql_doc_modify\` | Update documents |
+| \`mysql_doc_remove\` | Delete documents |
+| \`mysql_doc_create_index\` | Create index |
+| \`mysql_doc_collection_info\` | Collection stats |
+
+## Creating Indexes
+
+\`\`\`javascript
+// Index on document field
+db.users.createIndex("email_idx", {
+    fields: [{
+        field: "$.email",
+        type: "TEXT(100)"
+    }]
+})
+\`\`\`
+
+## Best Practices
+
+1. **Use _id field** for document identification
+2. **Create indexes** on frequently queried fields
+3. **Use JSON schema validation** for data integrity
+4. **Consider hybrid approach** - mix relational and document data
+
+## Common Issues
+
+1. **Port 33060 blocked**: Open firewall for X Protocol
+2. **Connection refused**: Verify mysqlx plugin is running
+3. **Schema not found**: Create database first
+
+Start by listing collections with \`mysql_doc_list_collections\`.`);
+        }
+    };
+}