@neverinfamous/mysql-mcp 2.1.0

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

@@ -0,0 +1,115 @@
+/**
+ * MySQL Prompt - ProxySQL Setup
+ * 
+ * Complete ProxySQL configuration guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupProxysqlPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_proxysql',
+        description: 'Complete ProxySQL setup and configuration guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# ProxySQL Setup Guide
+
+ProxySQL is a high-performance MySQL proxy supporting connection pooling, query routing, and caching.
+
+## Prerequisites
+
+1. **ProxySQL installed** (v2.x recommended)
+2. **MySQL backend servers** accessible
+3. **Admin access** to ProxySQL (default: admin:admin on port 6032)
+
+## Step 1: Connect to ProxySQL Admin
+
+\`\`\`bash
+mysql -h 127.0.0.1 -P 6032 -u admin -padmin
+\`\`\`
+
+## Step 2: Configure Backend Servers
+
+\`\`\`sql
+-- Add primary server (hostgroup 0 = writers)
+INSERT INTO mysql_servers (hostgroup_id, hostname, port, weight)
+VALUES (0, 'primary-host', 3306, 1000);
+
+-- Add replica servers (hostgroup 1 = readers)
+INSERT INTO mysql_servers (hostgroup_id, hostname, port, weight)
+VALUES (1, 'replica1-host', 3306, 500),
+       (1, 'replica2-host', 3306, 500);
+
+-- Load and save configuration
+LOAD MYSQL SERVERS TO RUNTIME;
+SAVE MYSQL SERVERS TO DISK;
+\`\`\`
+
+## Step 3: Configure Users
+
+\`\`\`sql
+-- Add MySQL users that will connect through ProxySQL
+INSERT INTO mysql_users (username, password, default_hostgroup)
+VALUES ('app_user', 'password', 0);
+
+LOAD MYSQL USERS TO RUNTIME;
+SAVE MYSQL USERS TO DISK;
+\`\`\`
+
+## Step 4: Configure Query Rules
+
+\`\`\`sql
+-- Route SELECT queries to readers (hostgroup 1)
+INSERT INTO mysql_query_rules (rule_id, active, match_pattern, destination_hostgroup)
+VALUES (1, 1, '^SELECT.*FOR UPDATE', 0),      -- SELECT FOR UPDATE to writers
+       (2, 1, '^SELECT', 1);                   -- Other SELECTs to readers
+
+LOAD MYSQL QUERY RULES TO RUNTIME;
+SAVE MYSQL QUERY RULES TO DISK;
+\`\`\`
+
+## Step 5: Configure MCP Server
+
+Set environment variables:
+\`\`\`bash
+PROXYSQL_HOST=localhost
+PROXYSQL_PORT=6032
+PROXYSQL_USER=admin
+PROXYSQL_PASSWORD=admin
+\`\`\`
+
+## Step 6: Verify with MCP Tools
+
+Use ProxySQL tools to verify:
+- \`proxysql_status\` - Check ProxySQL is running
+- \`proxysql_servers\` - List configured servers
+- \`proxysql_hostgroups\` - View hostgroup configuration
+- \`proxysql_query_rules\` - Review routing rules
+- \`proxysql_query_digest\` - Analyze query patterns
+
+## Connection Pooling
+
+ProxySQL provides connection multiplexing:
+\`\`\`sql
+-- Configure max connections per hostgroup
+UPDATE mysql_servers SET max_connections = 100;
+LOAD MYSQL SERVERS TO RUNTIME;
+\`\`\`
+
+## Monitoring Queries
+
+Use \`proxysql_query_digest\` to find:
+- Slow queries
+- Most frequent queries
+- Queries for caching candidates
+
+## Best Practices
+
+1. **Connection pooling**: Set max_connections appropriately
+2. **Query caching**: Cache read-heavy, stable queries
+3. **Health checks**: Configure proper health check intervals
+4. **Monitor**: Watch query digest for performance issues
+
+Start by checking ProxySQL connection with \`proxysql_status\`.`);
+        }
+    };
+}

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

@@ -0,0 +1,147 @@
+/**
+ * MySQL Prompt - Replication Setup
+ * 
+ * MySQL replication configuration guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupReplicationPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_replication',
+        description: 'MySQL replication setup and configuration guide',
+        arguments: [
+            { name: 'type', description: 'Replication type: async, semisync, group', required: false }
+        ],
+        handler: (args: Record<string, string>, _context: RequestContext) => {
+            const replicationType = args['type'] ?? 'async';
+
+            return Promise.resolve(`# MySQL Replication Setup Guide
+
+Configure MySQL replication for high availability and read scaling.
+
+**Replication Type:** ${replicationType}
+
+## Step 1: Check Current Replication Status
+
+Use \`mysql://replication\` resource to check:
+- Current role (source/replica/standalone)
+- Binary log configuration
+- GTID status
+
+## Step 2: Prepare Source Server
+
+### Enable Binary Logging
+\`\`\`ini
+# my.cnf on source
+[mysqld]
+server-id = 1
+log_bin = mysql-bin
+binlog_format = ROW
+gtid_mode = ON
+enforce_gtid_consistency = ON
+\`\`\`
+
+### Create Replication User
+\`\`\`sql
+CREATE USER 'repl'@'%' IDENTIFIED BY 'replication_password';
+GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%';
+\`\`\`
+
+## Step 3: Prepare Replica Server
+
+### Configure Replica
+\`\`\`ini
+# my.cnf on replica
+[mysqld]
+server-id = 2
+log_bin = mysql-bin
+relay_log = relay-bin
+gtid_mode = ON
+enforce_gtid_consistency = ON
+read_only = ON
+super_read_only = ON
+${replicationType === 'semisync' ? `
+# Semi-synchronous replication
+rpl_semi_sync_replica_enabled = 1` : ''}
+\`\`\`
+
+## Step 4: Initialize Replica
+
+### Option A: GTID-based (Recommended)
+\`\`\`sql
+CHANGE REPLICATION SOURCE TO
+    SOURCE_HOST = 'source-host',
+    SOURCE_PORT = 3306,
+    SOURCE_USER = 'repl',
+    SOURCE_PASSWORD = 'replication_password',
+    SOURCE_AUTO_POSITION = 1;
+
+START REPLICA;
+\`\`\`
+
+### Option B: Binary Log Position
+\`\`\`sql
+-- Get position from source
+SHOW BINARY LOG STATUS;
+
+-- On replica
+CHANGE REPLICATION SOURCE TO
+    SOURCE_HOST = 'source-host',
+    SOURCE_PORT = 3306,
+    SOURCE_USER = 'repl',
+    SOURCE_PASSWORD = 'replication_password',
+    SOURCE_LOG_FILE = 'mysql-bin.000001',
+    SOURCE_LOG_POS = 123456;
+
+START REPLICA;
+\`\`\`
+
+## Step 5: Verify Replication
+
+Use these tools to verify:
+- \`mysql_replication_status\` - Detailed status
+- \`mysql_replication_lag\` - Check replication delay
+- \`mysql://replication\` - Overall status
+
+\`\`\`sql
+SHOW REPLICA STATUS\\G
+\`\`\`
+
+Key things to check:
+- Replica_IO_Running: Yes
+- Replica_SQL_Running: Yes
+- Seconds_Behind_Source: 0 (or low)
+
+## Semi-Synchronous Replication
+
+For reduced data loss risk:
+\`\`\`sql
+-- On source
+INSTALL PLUGIN rpl_semi_sync_source SONAME 'semisync_source.so';
+SET GLOBAL rpl_semi_sync_source_enabled = 1;
+
+-- On replica
+INSTALL PLUGIN rpl_semi_sync_replica SONAME 'semisync_replica.so';
+SET GLOBAL rpl_semi_sync_replica_enabled = 1;
+\`\`\`
+
+## Monitoring
+
+Regular monitoring should include:
+- Replication lag trends
+- Binary log volume
+- Error log for replication errors
+- GTID gaps
+
+## Failover Procedure
+
+1. Verify replica is caught up
+2. Stop replication on replica
+3. Promote replica: \`SET GLOBAL read_only = OFF;\`
+4. Update application connection strings
+5. Re-point other replicas to new source
+
+Start by checking current replication status with \`mysql://replication\`.`);
+        }
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * MySQL Prompt - Router Setup
+ * 
+ * Complete MySQL Router configuration guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupRouterPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_router',
+        description: 'Complete MySQL Router setup and configuration guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL Router Setup Guide
+
+MySQL Router provides transparent routing between applications and MySQL servers, supporting InnoDB Cluster for high availability.
+
+## Prerequisites
+
+1. **MySQL Router installed** (comes with MySQL 8.0+)
+2. **InnoDB Cluster** (optional but recommended for HA)
+3. **Admin credentials** for MySQL servers
+
+## Step 1: Bootstrap Router (InnoDB Cluster)
+
+If using InnoDB Cluster:
+\`\`\`bash
+mysqlrouter --bootstrap admin@primary-host:3306 --user=mysqlrouter
+\`\`\`
+
+This auto-configures Router to work with your cluster.
+
+## Step 2: Manual Configuration
+
+For manual setup, edit \`mysqlrouter.conf\`:
+\`\`\`ini
+[routing:primary]
+bind_address = 0.0.0.0
+bind_port = 6446
+destinations = primary-host:3306
+routing_strategy = first-available
+mode = read-write
+
+[routing:secondary]
+bind_address = 0.0.0.0
+bind_port = 6447
+destinations = secondary1:3306,secondary2:3306
+routing_strategy = round-robin
+mode = read-only
+\`\`\`
+
+## Step 3: Enable REST API (for monitoring)
+
+Add to mysqlrouter.conf:
+\`\`\`ini
+[rest_api]
+require_realm = default_realm
+
+[rest_router]
+require_realm = default_realm
+
+[rest_metadata_cache]
+require_realm = default_realm
+
+[http_server]
+port = 8443
+ssl = 1
+ssl_cert = /path/to/router-cert.pem
+ssl_key = /path/to/router-key.pem
+\`\`\`
+
+## Step 4: Configure MCP Server
+
+Set environment variables:
+\`\`\`bash
+MYSQL_ROUTER_URL=https://localhost:8443
+MYSQL_ROUTER_USERNAME=admin
+MYSQL_ROUTER_PASSWORD=your_password
+MYSQL_ROUTER_INSECURE=true  # For self-signed certs
+\`\`\`
+
+## Step 5: Verify with MCP Tools
+
+Use Router tools to verify:
+- \`mysql_router_status\` - Check Router is running
+- \`mysql_router_routes\` - List configured routes
+- \`mysql_router_route_health\` - Check route health
+
+## Routing Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| first-available | Routes to first healthy server | Primary writes |
+| round-robin | Distributes across all servers | Read scaling |
+| round-robin-with-fallback | Round-robin with fallback | HA reads |
+
+## Common Issues
+
+1. **Connection refused**: Check Router is running and ports are open
+2. **SSL errors**: Use MYSQL_ROUTER_INSECURE=true for self-signed certs
+3. **No destinations**: Verify backend servers are healthy
+
+Start by checking if MySQL Router is installed and running.`);
+        }
+    };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * MySQL Prompt - Spatial/GIS Setup
+ * 
+ * Complete Spatial data and GIS setup guide.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSetupSpatialPrompt(): PromptDefinition {
+    return {
+        name: 'mysql_setup_spatial',
+        description: 'Complete MySQL Spatial/GIS setup and usage guide',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL Spatial/GIS Setup Guide
+
+MySQL provides native spatial data support with geometry types and spatial functions (ST_*).
+
+## Prerequisites
+
+1. **MySQL 5.7+** for full spatial support
+2. **MySQL 8.0+** for proper SRID enforcement
+3. **InnoDB engine** for spatial indexes
+
+## Step 1: Create Spatial Columns
+
+\`\`\`sql
+CREATE TABLE locations (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    name VARCHAR(100),
+    location POINT NOT NULL SRID 4326,
+    boundary POLYGON SRID 4326,
+    SPATIAL INDEX (location)
+);
+\`\`\`
+
+## Step 2: Insert Spatial Data
+
+\`\`\`sql
+-- Using WKT (Well-Known Text)
+INSERT INTO locations (name, location) VALUES
+('Office', ST_GeomFromText('POINT(40.7484 -73.9857)', 4326));
+
+-- Using GeoJSON
+INSERT INTO locations (name, location) VALUES
+('Store', ST_GeomFromGeoJSON('{"type":"Point","coordinates":[-73.9857,40.7484]}'));
+\`\`\`
+
+## Step 3: Query Spatial Data
+
+\`\`\`sql
+-- Find points within distance (meters for SRID 4326)
+SELECT name, ST_Distance_Sphere(
+    location,
+    ST_GeomFromText('POINT(40.7128 -74.0060)', 4326)
+) AS distance_meters
+FROM locations
+ORDER BY distance_meters
+LIMIT 10;
+
+-- Points within polygon
+SELECT * FROM locations
+WHERE ST_Contains(
+    ST_GeomFromText('POLYGON((...))'),
+    location
+);
+\`\`\`
+
+## Common SRIDs
+
+| SRID | Name | Use Case |
+|------|------|----------|
+| 4326 | WGS 84 | GPS coordinates (lon/lat) |
+| 3857 | Web Mercator | Web maps |
+| 0 | Planar | Local/metric calculations |
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| \`mysql_spatial_create_column\` | Add geometry column |
+| \`mysql_spatial_create_index\` | Create SPATIAL index |
+| \`mysql_spatial_point\` | Create POINT geometry |
+| \`mysql_spatial_polygon\` | Create POLYGON geometry |
+| \`mysql_spatial_distance\` | Calculate distance |
+| \`mysql_spatial_distance_sphere\` | Spherical distance |
+| \`mysql_spatial_contains\` | ST_Contains check |
+| \`mysql_spatial_within\` | ST_Within check |
+| \`mysql_spatial_intersection\` | Find intersection |
+| \`mysql_spatial_buffer\` | Create buffer zone |
+| \`mysql_spatial_transform\` | Transform SRID |
+| \`mysql_spatial_geojson\` | Convert GeoJSON |
+
+## Best Practices
+
+1. **Always specify SRID** for geographic data
+2. **Use SRID 4326** for GPS/lon-lat coordinates
+3. **Index spatial columns** for query performance
+4. **Use ST_Distance_Sphere** for earth distance calculations
+
+## Common Issues
+
+1. **SRID mismatch**: Ensure all geometries use same SRID
+2. **Coordinate order**: MySQL 8.0+ with SRID 4326 uses (X, Y) = (latitude, longitude) per EPSG standard
+3. **Index not used**: Check column is NOT NULL
+
+Start by creating a spatial column with \`mysql_spatial_create_column\`.`);
+        }
+    };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * MySQL Prompt - sys Schema Guide
+ * 
+ * Complete sys schema usage guide for diagnostics.
+ */
+import type { PromptDefinition, RequestContext } from '../../../types/index.js';
+
+export function createSysSchemaGuidePrompt(): PromptDefinition {
+    return {
+        name: 'mysql_sys_schema_guide',
+        description: 'Complete MySQL sys schema usage guide for diagnostics and troubleshooting',
+        arguments: [],
+        handler: (_args: Record<string, string>, _context: RequestContext) => {
+            return Promise.resolve(`# MySQL sys Schema Guide
+
+The sys schema provides human-readable views built on Performance Schema data for database diagnostics.
+
+## Prerequisites
+
+1. **MySQL 5.7+** (sys schema included by default)
+2. **Performance Schema enabled** (default ON in 5.7+)
+3. **SELECT privilege** on sys schema
+
+## Key Views for Diagnostics
+
+### User Activity
+\`\`\`sql
+-- Who is consuming resources?
+SELECT * FROM sys.user_summary;
+SELECT * FROM sys.user_summary_by_file_io;
+SELECT * FROM sys.user_summary_by_statement_type;
+\`\`\`
+
+### Statement Analysis
+\`\`\`sql
+-- Find slow queries
+SELECT * FROM sys.statements_with_runtimes_in_95th_percentile;
+
+-- Full table scans
+SELECT * FROM sys.statements_with_full_table_scans;
+
+-- Temporary tables
+SELECT * FROM sys.statements_with_temp_tables;
+\`\`\`
+
+### I/O Analysis
+\`\`\`sql
+-- Hot tables by I/O
+SELECT * FROM sys.io_global_by_file_by_bytes;
+
+-- Wait analysis
+SELECT * FROM sys.wait_classes_global_by_avg_latency;
+\`\`\`
+
+### Lock Analysis
+\`\`\`sql
+-- Current lock waits
+SELECT * FROM sys.innodb_lock_waits;
+
+-- Blocked transactions
+SELECT * FROM sys.schema_table_lock_waits;
+\`\`\`
+
+### Memory Analysis
+\`\`\`sql
+-- Memory by user
+SELECT * FROM sys.memory_by_user_by_current_bytes;
+
+-- Memory by thread
+SELECT * FROM sys.memory_by_thread_by_current_bytes;
+\`\`\`
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| \`mysql_sys_user_summary\` | User activity summary |
+| \`mysql_sys_io_summary\` | I/O by file/table |
+| \`mysql_sys_statement_summary\` | Statement statistics |
+| \`mysql_sys_wait_summary\` | Wait event analysis |
+| \`mysql_sys_innodb_lock_waits\` | Lock contention |
+| \`mysql_sys_schema_stats\` | Schema object stats |
+| \`mysql_sys_host_summary\` | Host connection summary |
+| \`mysql_sys_memory_summary\` | Memory usage |
+
+## Useful Procedures
+
+\`\`\`sql
+-- Reset statement stats
+CALL sys.ps_truncate_all_tables(FALSE);
+
+-- Kill a connection
+CALL sys.kill_connection(thread_id);
+
+-- Get statement digest
+SELECT sys.format_statement('SELECT * FROM users WHERE id = 1');
+\`\`\`
+
+## Best Practices
+
+1. **Don't query in production peaks** - sys views can be heavy
+2. **Use x$ views for exact values** (no formatting)
+3. **Reset stats after schema changes**
+4. **Monitor performance_schema memory**
+
+Start by checking overall user activity with \`mysql_sys_user_summary\`.`);
+        }
+    };
+}

package/src/adapters/mysql/resources/__tests__/capabilities.test.ts

@@ -0,0 +1,52 @@
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createCapabilitiesResource } from '../capabilities.js';
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext, createMockQueryResult } from '../../../../__tests__/mocks/index.js';
+
+interface CapabilitiesResult {
+    server: { version: string; features: { json: boolean; fulltext: boolean; partitioning: boolean } };
+    toolGroups: unknown[];
+    metaGroups: unknown[];
+}
+
+describe('Capabilities Resource', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+    });
+
+    it('should return server capabilities', async () => {
+        mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{ version: '8.0.35' }]));
+
+        const resource = createCapabilitiesResource(mockAdapter as unknown as MySQLAdapter);
+        const result = await resource.handler('mysql://capabilities', mockContext) as CapabilitiesResult;
+
+        expect(result).toHaveProperty('server');
+        expect(result.server).toHaveProperty('version');
+        expect(result).toHaveProperty('toolGroups');
+        expect(result).toHaveProperty('metaGroups');
+    });
+
+    it('should include server features', async () => {
+        mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{ version: '8.0.35' }]));
+
+        const resource = createCapabilitiesResource(mockAdapter as unknown as MySQLAdapter);
+        const result = await resource.handler('mysql://capabilities', mockContext) as CapabilitiesResult;
+
+        expect(result.server).toHaveProperty('features');
+        expect(result.server.features).toHaveProperty('json');
+        expect(result.server.features).toHaveProperty('fulltext');
+        expect(result.server.features).toHaveProperty('partitioning');
+    });
+
+    it('should have correct metadata', () => {
+        const resource = createCapabilitiesResource(mockAdapter as unknown as MySQLAdapter);
+        expect(resource.uri).toBe('mysql://capabilities');
+        expect(resource.mimeType).toBe('application/json');
+    });
+});