@berthojoris/mcp-mysql-server 1.4.14 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.4.15] - 2025-11-22
+
+### Fixed
+- **README.md Unicode encoding** - Fixed broken Unicode characters in Features section
+  - Corrected emoji encodings: 🌟 (star), ✅ (checkmark), 🔐 (lock), 🛠️ (tools), 🎛️ (control knobs), 🗃️ (file cabinet), 💎 (gem), 🌐 (globe), 📊 (chart)
+  - Removed BOM (Byte Order Mark) from file
+  - All emojis now display correctly across all platforms
+  - Fixed table formatting in Bulk Operations section
+
+### Documentation
+- Enhanced visual consistency in Features section
+- Improved readability with proper emoji rendering
+
 ## [1.4.14] - 2025-11-22
 
 ### Fixed

package/DOCUMENTATIONS.md

@@ -13,10 +13,12 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 5. [Usage Examples](#📋-usage-examples)
 6. [Query Logging & Automatic SQL Display](#📝-query-logging--automatic-sql-display)
 7. [Security Features](#🔒-security-features)
-8. [Bulk Operations](#🚀-bulk-operations)
-9. [Troubleshooting](#🛠️-troubleshooting)
-10. [License](#📄-license)
-11. [Roadmap](#🗺️-roadmap)
+8. [Query Result Caching](#💾-query-result-caching)
+9. [Query Optimization Hints](#🎯-query-optimization-hints)
+10. [Bulk Operations](#🚀-bulk-operations)
+11. [Troubleshooting](#🛠️-troubleshooting)
+12. [License](#📄-license)
+13. [Roadmap](#🗺️-roadmap)
 
 ---
 
@@ -1026,6 +1028,186 @@ console.log(`Query log memory usage: ~${estimatedMemory} KB`);
 
 ---
 
+## 💾 Query Result Caching
+
+The MySQL MCP server includes an intelligent LRU (Least Recently Used) cache system that dramatically improves performance for repeated queries.
+
+### Cache Features
+
+- **LRU Eviction**: Automatically removes least recently used entries when cache is full
+- **TTL Support**: Configurable time-to-live for cache entries (default: 60 seconds)
+- **Automatic Invalidation**: Cache is automatically invalidated when data is modified
+- **Memory Management**: Configurable maximum entries and memory limits
+- **Cache Statistics**: Track hit rates and monitor cache performance
+
+### Cache Configuration
+
+Cache can be configured via environment variables or programmatically:
+
+```bash
+# Environment variables
+CACHE_ENABLED=true          # Enable/disable cache (default: true)
+CACHE_TTL_MS=60000          # Cache TTL in milliseconds (default: 60000)
+CACHE_MAX_SIZE=100          # Maximum cached entries (default: 100)
+CACHE_MAX_MEMORY_MB=50      # Maximum memory in MB (default: 50)
+```
+
+### Cache Management Tools
+
+#### Get Cache Statistics
+```json
+{
+  "tool": "get_cache_stats"
+}
+```
+
+Returns:
+```json
+{
+  "totalHits": 150,
+  "totalMisses": 50,
+  "hitRate": 0.75,
+  "currentSize": 45,
+  "maxSize": 100,
+  "ttlMs": 60000,
+  "enabled": true
+}
+```
+
+#### Configure Cache
+```json
+{
+  "tool": "configure_cache",
+  "arguments": {
+    "enabled": true,
+    "ttlMs": 120000,
+    "maxSize": 200
+  }
+}
+```
+
+#### Clear Cache
+```json
+{
+  "tool": "clear_cache"
+}
+```
+
+#### Invalidate Table Cache
+```json
+{
+  "tool": "invalidate_table_cache",
+  "arguments": {
+    "table_name": "users"
+  }
+}
+```
+
+### Cache Behavior
+
+- **SELECT queries only**: Only SELECT queries are cached
+- **Automatic invalidation**: INSERT, UPDATE, DELETE operations automatically invalidate related cache entries
+- **Per-query control**: Use `useCache: false` in `run_query` to bypass cache for specific queries
+
+---
+
+## 🎯 Query Optimization Hints
+
+The MySQL MCP server provides advanced query optimization tools that help you improve query performance using MySQL 8.0+ optimizer hints.
+
+### Optimization Features
+
+- **Optimizer Hints**: Apply MySQL 8.0+ optimizer hints to queries
+- **Query Analysis**: Analyze queries and get optimization suggestions
+- **Goal-Based Hints**: Get suggested hints based on optimization goals (SPEED, MEMORY, STABILITY)
+
+### Using Optimizer Hints
+
+When running queries with `run_query`, you can include optimizer hints:
+
+```json
+{
+  "tool": "run_query",
+  "arguments": {
+    "query": "SELECT * FROM orders WHERE customer_id = ?",
+    "params": [123],
+    "hints": {
+      "maxExecutionTime": 5000,
+      "forceIndex": "idx_customer_id",
+      "straightJoin": true
+    }
+  }
+}
+```
+
+### Available Hint Options
+
+| Hint | Type | Description |
+|------|------|-------------|
+| `maxExecutionTime` | number | Maximum execution time in milliseconds |
+| `forceIndex` | string/array | Force usage of specific index(es) |
+| `ignoreIndex` | string/array | Ignore specific index(es) |
+| `straightJoin` | boolean | Force join order as specified in query |
+| `noCache` | boolean | Disable query cache for this query |
+| `sqlBigResult` | boolean | Optimize for large result sets |
+| `sqlSmallResult` | boolean | Optimize for small result sets |
+
+### Query Analysis Tool
+
+Analyze a query to get optimization suggestions:
+
+```json
+{
+  "tool": "analyze_query",
+  "arguments": {
+    "query": "SELECT o.*, c.name FROM orders o JOIN customers c ON o.customer_id = c.id WHERE o.status = 'pending' ORDER BY o.created_at"
+  }
+}
+```
+
+Returns analysis with suggestions:
+```json
+{
+  "originalQuery": "SELECT o.*, c.name FROM orders o JOIN customers c...",
+  "queryType": "SELECT",
+  "tables": ["orders", "customers"],
+  "hasJoins": true,
+  "hasSubqueries": false,
+  "hasGroupBy": false,
+  "hasOrderBy": true,
+  "hasLimit": false,
+  "estimatedComplexity": "MEDIUM",
+  "suggestions": [
+    {
+      "type": "STRUCTURE",
+      "priority": "MEDIUM",
+      "description": "ORDER BY without LIMIT may cause full result set sorting",
+      "suggestedAction": "Consider adding LIMIT clause to improve performance"
+    }
+  ]
+}
+```
+
+### Get Optimization Hints by Goal
+
+Get suggested hints for a specific optimization goal:
+
+```json
+{
+  "tool": "get_optimization_hints",
+  "arguments": {
+    "goal": "SPEED"
+  }
+}
+```
+
+Available goals:
+- **SPEED**: Optimize for faster query execution
+- **MEMORY**: Optimize for lower memory usage
+- **STABILITY**: Optimize for consistent, predictable performance
+
+---
+
 ## 🚀 Bulk Operations
 
 The MySQL MCP server includes powerful bulk operation tools designed for high-performance data processing. These tools are optimized for handling large datasets efficiently.
@@ -1202,8 +1384,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - ✅ **Stored procedure execution** - **COMPLETED!**
 - ✅ **Bulk operations (batch insert/update/delete)** - **COMPLETED!**
 - ✅ **Add query log on output** - **COMPLETED!**
-- [ ] Query result caching
-- [ ] Advanced query optimization hints
+- ✅ **Query result caching** - **COMPLETED!**
+- ✅ **Advanced query optimization hints** - **COMPLETED!**
 
 ### Enterprise Features
 - [ ] **Database backup and restore tools**
@@ -1225,7 +1407,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 ### Recommended Implementation Order
 
 #### **Phase 1: Performance & Monitoring** 🚀
-- [ ] **Query result caching** - Dramatically improve response times for repeated queries
+- ✅ **Query result caching** - Dramatically improve response times for repeated queries - **COMPLETED!**
 - [ ] **Performance metrics** - Track query execution times and database performance
 - [ ] **Connection pool monitoring** - Monitor database connection health and usage
 - [ ] **Database health checks** - Comprehensive system health monitoring
@@ -1239,7 +1421,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 #### **Phase 3: Enterprise Features** 🏢
 - [ ] **Audit logging and compliance** - Track all database operations for security
 - [ ] **Schema versioning and migrations** - Version control for database schema changes
-- [ ] **Query optimization** - Automatic query analysis and optimization suggestions
+- ✅ **Query optimization** - Automatic query analysis and optimization suggestions - **COMPLETED!**
 - [ ] **Advanced security features** - Enhanced access control and monitoring
 
 #### **Phase 4: Multi-Database Support** 🌐
@@ -1250,16 +1432,16 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 #### **Implementation Priority Matrix**
 
-| Feature | Impact | Effort | Priority |
-|---------|--------|--------|----------|
-| Query Result Caching | High | Medium | 1 |
-| Database Backup/Restore | High | High | 2 |
-| Performance Monitoring | High | Medium | 3 |
-| Data Migration | High | High | 4 |
-| Query Optimization | Medium | Medium | 5 |
-| PostgreSQL Adapter | High | High | 6 |
-| Audit Logging | Medium | Low | 7 |
-| Schema Versioning | Medium | Medium | 8 |
+| Feature | Impact | Effort | Priority | Status |
+|---------|--------|--------|----------|--------|
+| Query Result Caching | High | Medium | 1 | ✅ COMPLETED |
+| Database Backup/Restore | High | High | 2 | Pending |
+| Performance Monitoring | High | Medium | 3 | Pending |
+| Data Migration | High | High | 4 | Pending |
+| Query Optimization | Medium | Medium | 5 | ✅ COMPLETED |
+| PostgreSQL Adapter | High | High | 6 | Pending |
+| Audit Logging | Medium | Low | 7 | Pending |
+| Schema Versioning | Medium | Medium | 8 | Pending |
 
 ---
 

package/README.md

@@ -7,16 +7,16 @@ A fully-featured **Model Context Protocol (MCP)** server for MySQL database inte
 
 ---
 
-## 🌟 Features
-
-- ✅ **Full MCP Protocol Support** - Works with Claude Desktop, Cline, Windsurf, and any MCP-compatible AI agent
-- 📝’ **Secure by Default** - Parameterized queries, SQL injection protection, permission-based access control
-- 🛠️ **30 Powerful Tools** - Complete database operations (CRUD, DDL, queries, schema inspection, transactions, stored procedures, bulk operations)
-- 🎛️ **Dynamic Per-Project Permissions** - Each AI agent can have different access levels
-- 🏗️ **DDL Support** - Create, alter, and drop tables (when explicitly enabled)
-- 💰 **Transaction Support** - Full ACID transaction management (BEGIN, COMMIT, ROLLBACK)
-- 🌐 **Dual Mode** - Run as MCP server OR as REST API
-- 📊 **Rich Metadata** - Table schemas, relationships, connection info
+## 🌟 Features
+
+- ✅ **Full MCP Protocol Support** - Works with Claude Desktop, Cline, Windsurf, and any MCP-compatible AI agent
+- 🔐 **Secure by Default** - Parameterized queries, SQL injection protection, permission-based access control
+- 🛠️ **30 Powerful Tools** - Complete database operations (CRUD, DDL, queries, schema inspection, transactions, stored procedures, bulk operations)
+- 🎛️ **Dynamic Per-Project Permissions** - Each AI agent can have different access levels
+- 🗃️ **DDL Support** - Create, alter, and drop tables (when explicitly enabled)
+- 💎 **Transaction Support** - Full ACID transaction management (BEGIN, COMMIT, ROLLBACK)
+- 🌐 **Dual Mode** - Run as MCP server OR as REST API
+- 📊 **Rich Metadata** - Table schemas, relationships, connection info
 - ⚡ **TypeScript** - Fully typed with TypeScript definitions
 
 ---
@@ -254,7 +254,7 @@ Control access with these permission categories:
 {
   "args": [
     "mysql://user:pass@localhost:3306/db",
-    "list,read,utility"  // ← Permissions here
+    "list,read,utility"  // ← Permissions here
   ]
 }
 ```
@@ -356,7 +356,7 @@ The MySQL MCP Server provides clear, user-friendly error messages when operation
 When a tool is called without the required permission, you'll receive a detailed error message like:
 
 ```
-❌ Permission denied: Cannot use tool 'create_table'. This tool requires 'ddl' permission.
+❌ Permission denied: Cannot use tool 'create_table'. This tool requires 'ddl' permission.
 
 Current permissions: list,read,utility
 To enable this tool, add 'ddl' to your permissions configuration.
@@ -375,7 +375,7 @@ Tool description: Create new tables with columns and indexes
 
 **Error response when DDL not enabled:**
 ```
-❌ Permission denied: Cannot use tool 'create_table'. This tool requires 'ddl' permission.
+❌ Permission denied: Cannot use tool 'create_table'. This tool requires 'ddl' permission.
 
 Current permissions: list,read,utility
 To enable this tool, add 'ddl' to your permissions configuration.
@@ -392,7 +392,7 @@ Tool description: Create new tables with columns and indexes
 
 **Error response when CREATE not enabled:**
 ```
-❌ Permission denied: Cannot use tool 'create_record'. This tool requires 'create' permission.
+❌ Permission denied: Cannot use tool 'create_record'. This tool requires 'create' permission.
 
 Current permissions: list,read,utility
 To enable this tool, add 'create' to your permissions configuration.
@@ -409,7 +409,7 @@ Tool description: Insert new records with automatic SQL generation
 
 **Error response when UPDATE not enabled:**
 ```
-❌ Permission denied: Cannot use tool 'update_record'. This tool requires 'update' permission.
+❌ Permission denied: Cannot use tool 'update_record'. This tool requires 'update' permission.
 
 Current permissions: list,read,utility
 To enable this tool, add 'update' to your permissions configuration.
@@ -461,7 +461,7 @@ After (DDL enabled):
 
 ---
 
-## 🛠️ Available Tools
+## 🛠️ Available Tools
 
 The MCP server provides **30 powerful tools**:
 
@@ -485,7 +485,9 @@ The MCP server provides **30 powerful tools**:
 
 ### Bulk Operations (3 tools)
 
-| Tool | Description | Performance |
+| Tool | Description | 
+
+| Performance |
 |------|-------------|-------------|
 | `bulk_insert` | Insert multiple records in batches for optimal performance | Up to 10,000 records per batch |
 | `bulk_update` | Update multiple records with different conditions in batches | Up to 1,000 operations per batch |
@@ -538,21 +540,21 @@ The MCP server provides **30 powerful tools**:
 
 ---
 
-## 📚 Detailed Documentation
+## 📚 Detailed Documentation
 
 For comprehensive documentation on all features, please see **[DOCUMENTATIONS.md](DOCUMENTATIONS.md)** which includes:
 
-- 🏗️ **DDL Operations** - Create, alter, and drop tables
-- 📤 **Data Export Tools** - Export data to CSV format
-- 💰 **Transaction Management** - ACID transactions with BEGIN, COMMIT, ROLLBACK
+- 🗃️ **DDL Operations** - Create, alter, and drop tables
+- 📤 **Data Export Tools** - Export data to CSV format
+- 💎 **Transaction Management** - ACID transactions with BEGIN, COMMIT, ROLLBACK
 - 🔧 **Stored Procedures** - Create and execute stored procedures with IN/OUT/INOUT parameters
-- 📋 **Usage Examples** - Real-world examples for all tools
-- 📝 **Query Logging & Automatic SQL Display** - See all SQL queries executed automatically
-- 📝’ **Security Features** - Built-in security and best practices
+- 📋 **Usage Examples** - Real-world examples for all tools
+- 🔍 **Query Logging & Automatic SQL Display** - See all SQL queries executed automatically
+- 🔐 **Security Features** - Built-in security and best practices
 - 🚀 **Bulk Operations** - High-performance batch processing
-- 🛠️ **Troubleshooting** - Common issues and solutions
-- 📄 **License** - MIT License details
-- 🗺️ **Roadmap** - Upcoming features and improvements
+- 🛠️ **Troubleshooting** - Common issues and solutions
+- 📄 **License** - MIT License details
+- 🗺️ **Roadmap** - Upcoming features and improvements
 
 ---
 
@@ -562,7 +564,6 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Made with ❤️ for the AI community**
+**Made with ❤️ for the AI community**
 
 *Help AI agents interact with MySQL databases safely and efficiently!*
-

package/dist/cache/queryCache.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Cache entry interface
+ */
+export interface CacheEntry {
+    data: any;
+    timestamp: number;
+    hitCount: number;
+    queryHash: string;
+    sql: string;
+    params?: any[];
+}
+/**
+ * Cache statistics interface
+ */
+export interface CacheStats {
+    totalHits: number;
+    totalMisses: number;
+    hitRate: number;
+    currentSize: number;
+    maxSize: number;
+    ttlMs: number;
+    enabled: boolean;
+}
+/**
+ * Cache configuration interface
+ */
+export interface CacheConfig {
+    enabled: boolean;
+    ttlMs: number;
+    maxSize: number;
+    maxMemoryMB: number;
+}
+/**
+ * LRU Query Cache with TTL support
+ * Implements an in-memory cache for query results to improve performance
+ */
+export declare class QueryCache {
+    private static instance;
+    private cache;
+    private config;
+    private stats;
+    private accessOrder;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): QueryCache;
+    /**
+     * Load cache configuration from environment variables
+     */
+    private loadConfigFromEnv;
+    /**
+     * Generate a unique hash for a query and its parameters
+     */
+    private generateHash;
+    /**
+     * Check if a query result is cached and valid
+     */
+    get(sql: string, params?: any[]): CacheEntry | null;
+    /**
+     * Cache a query result
+     */
+    set(sql: string, params: any[] | undefined, data: any): void;
+    /**
+     * Invalidate cache entries matching a pattern
+     * Used when data is modified (INSERT, UPDATE, DELETE)
+     */
+    invalidate(pattern?: string | RegExp): number;
+    /**
+     * Escape special regex characters in a string
+     */
+    private escapeRegex;
+    /**
+     * Invalidate cache entries related to a specific table
+     */
+    invalidateTable(tableName: string): number;
+    /**
+     * Evict least recently used entries if cache is full
+     */
+    private evictIfNeeded;
+    /**
+     * Update access order for LRU tracking
+     */
+    private updateAccessOrder;
+    /**
+     * Remove hash from access order
+     */
+    private removeFromAccessOrder;
+    /**
+     * Estimate memory usage of the cache
+     */
+    private estimateMemoryUsage;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get current cache configuration
+     */
+    getConfig(): CacheConfig;
+    /**
+     * Update cache configuration
+     */
+    setConfig(config: Partial<CacheConfig>): void;
+    /**
+     * Enable caching
+     */
+    enable(): void;
+    /**
+     * Disable caching
+     */
+    disable(): void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Get all cached entries (for debugging)
+     */
+    getAllEntries(): CacheEntry[];
+}
+export default QueryCache;