@berthojoris/mcp-mysql-server 1.14.1 → 1.15.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.15.0] - 2025-12-08
+
+### Added
+- **Connection Profiles** - New `dev`, `stage`, and `prod` presets.
+  - `dev`: Full access to all tools.
+  - `stage`: Allows CRUD but blocks destructive DDL (drop, truncate).
+  - `prod`: Strict read-only with explicit denials for modification tools.
+  - Implements allowed/denied tools logic for robust security enforcement.
+- **Agent-Facing Changelog Feed** - New `read_changelog` tool.
+  - Allows AI agents to read the CHANGELOG.md directly to understand new features and changes.
+
 ## [1.14.1] - 2025-12-08
 
 ### Added

package/DOCUMENTATIONS.md

@@ -192,6 +192,16 @@ Preset bundles provide safe starting points and **merge** with any explicit perm
 | `readonly` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,import_export,performance_monitoring,analysis` | Safe read-only access, exports, and diagnostics |
 | `analyst` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,import_export,performance_monitoring,analysis,query_optimization,cache_management,server_management` | Exploration with EXPLAIN, cache, and performance visibility |
 | `dba-lite` | `list,read,utility,ddl,transaction,procedure` | `database_discovery,custom_queries,utilities,server_management,schema_management,table_maintenance,index_management,constraint_management,backup_restore,schema_migrations,performance_monitoring,views_management,triggers_management,functions_management,stored_procedures` | Admin-lite schema care, maintenance, and migrations |
+| `dev` | ALL | ALL | Full access to all tools (Development environment) |
+| `stage` | `list,read,create,update,delete,utility,transaction` | Most categories (except schema_management) | Data modification allowed, but destructive DDL (drop_table, truncate_table) is **explicitly denied** |
+| `prod` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,performance_monitoring,analysis` | Strict read-only. Data modification and DDL are **strictly denied** (even if permissions suggest otherwise) |
+
+### Connection Profiles (Allow/Deny Lists)
+
+The new mechanism introduces "Connection Profiles" which can enforce strict `allow` and `deny` lists for tools, providing security beyond standard permissions.
+
+- **Explicit Deny**: Tools in the `deniedTools` list are blocked *regardless* of their permissions. E.g., `prod` profile denies `create_record` even if `create` permission is somehow granted.
+- **Explicit Allow**: Tools in the `allowedTools` list are enabled even if their category is not listed (unless denied).
 
 **Usage**
 
@@ -324,6 +334,7 @@ This section provides a comprehensive reference of all 120 available tools organ
 |------|-------------|
 | `test_connection` | Test database connectivity and measure latency |
 | `describe_connection` | Get current connection information |
+| `read_changelog` | Read the changelog to see new features/changes |
 | `export_table_to_csv` | Export table data to CSV format |
 | `export_query_to_csv` | Export query results to CSV format |
 
@@ -520,6 +531,11 @@ This section provides a comprehensive reference of all 120 available tools organ
 - Safety: respects the connected database only—cannot introspect other schemas—and notes when tables/columns are truncated.
 - Output includes per-table PKs, FK targets, nullable flags, and approximate row counts from `INFORMATION_SCHEMA.TABLES` (InnoDB estimates).
 
+#### Agent-Facing Changelog Feed
+- **`read_changelog`**: Allows AI agents to read the project's CHANGELOG.md directly.
+- **Purpose**: Enables the agent to understand new features, changes, and deprecations in the version it is running.
+- **Usage**: Call `read_changelog()` to get the latest changes, or `read_changelog(version='1.15.0')` for specific version details.
+
 ---
 
 ## 🏗️ DDL Operations
@@ -3824,6 +3840,61 @@ Each bulk operation returns performance metrics:
  
  ---
  
+
+ ---
+ 
+ ## ⚡ Workflow Macros
+
+ Workflow macros are high-level tools that combine multiple operations into a single, safe, and efficient workflow. They are designed to simplify complex tasks and ensure best practices (like data masking) are automatically applied.
+
+ ### Safe Export Table
+
+ The `safe_export_table` tool allows you to export table data to CSV while strictly enforcing data masking rules. This ensures that sensitive information (PII) is never leaked during exports, even if the agent forgets to apply masking manually.
+
+ #### Features
+
+ - **Forced Masking**: Applies a masking profile (default: `strict`) to all exported data.
+ - **Hard Limit**: Enforces a maximum row limit (10,000) to prevent Out-Of-Memory errors during large exports.
+ - **CSV Formatting**: Automatically handles special characters, quotes, and newlines.
+ - **Header Control**: Option to include or exclude CSV headers.
+
+ #### Usage
+
+ ```json
+ {
+   "tool": "safe_export_table",
+   "arguments": {
+     "table_name": "users",
+     "masking_profile": "partial",
+     "limit": 1000
+   }
+ }
+ ```
+
+ #### Parameters
+
+ | Parameter | Type | Required | Description | Default |
+ |-----------|------|----------|-------------|---------|
+ | `table_name` | string | Yes | Name of the table to export | - |
+ | `masking_profile` | string | No | Masking profile to apply (`strict`, `partial`, `soft`) | `strict` |
+ | `limit` | number | No | Number of rows to export (max 10,000) | 1000 |
+ | `include_headers` | boolean | No | Whether to include CSV headers | `true` |
+
+ #### Response
+
+ ```json
+ {
+   "status": "success",
+   "data": {
+     "csv": "id,name,email\n1,John Doe,j***@example.com...",
+     "row_count": 50,
+     "applied_profile": "partial"
+   }
+ }
+ ```
+
+ ---
+
  ## 🤖 OpenAI Codex Integration
 
 OpenAI Codex CLI and VS Code Extension support MCP servers through a shared TOML configuration file. This section provides detailed setup instructions for integrating the MySQL MCP Server with Codex.
@@ -4210,9 +4281,9 @@ MIT License - see [LICENSE](LICENSE) file for details.
 | Safety Sandbox Mode (runQuery dry-run/EXPLAIN-only) | Medium | Low | 5 | ✅ Completed |
 | Anomaly & Slow-Query Watcher | Medium | Medium | 6 | ✅ Completed |
 | Data Masking Profiles for Responses | Medium | Medium | 7 | ✅ Completed |
-| Workflow Macros (e.g., safe_export_table) | Medium | Low | 8 | Planned |
-| Agent-Facing Changelog Feed | Medium | Low | 9 | Planned |
-| Connection Profiles (dev/stage/prod with allow/deny) | High | Low | 10 | Planned |
+| Workflow Macros (e.g., safe_export_table) | Medium | Low | 8 | ✅ Completed |
+| Agent-Facing Changelog Feed | Medium | Low | 9 | ✅ Completed |
+| Connection Profiles (dev/stage/prod with allow/deny) | High | Low | 10 | ✅ Completed |
 
 ---
 

package/README.md

@@ -50,7 +50,7 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
   - [Environment Variables](#environment-variables-configuration)
   - [Local Development](#local-path-configuration)
 - [Permission System](#-permission-system)
-- [Available Tools (124 total)](#-available-tools)
+- [Available Tools (126 total)](#-available-tools)
 - [Documentation](#-detailed-documentation)
 - [Comparison: MCP vs Manual Access](#-mysql-mcp-vs-manual-database-access)
 - [License](#-license)
@@ -388,6 +388,12 @@ Alternative approach using environment variables instead of connection string:
 
 Add `MCP_PRESET` for the base bundle and optionally layer on `MCP_PERMISSIONS` / `MCP_CATEGORIES` for project-specific overrides.
 
+#### Connection Profiles (dev/stage/prod)
+New presets are available for environment-specific control:
+- `dev`: Full access to all tools (explicitly allows everything).
+- `stage`: Allows data modification but blocks destructive DDL (drop/truncate).
+- `prod`: Strict read-only mode, explicitly denying keys modification keys.
+
 ---
 
 ### Local Path Configuration
@@ -641,11 +647,11 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 
 ## Available Tools
 
-The MCP server provides **124 powerful tools** organized into categories:
+The MCP server provides **126 powerful tools** organized into 22 categories:
 
 ### Quick Reference
 
-**124 Tools Available** - Organized into 22 categories
+**126 Tools Available** - Organized into 22 categories
 
 | Category | Count | Key Tools |
 |----------|-------|-----------|
@@ -667,7 +673,7 @@ The MCP server provides **124 powerful tools** organized into categories:
 | Cache | 5 | `get_cache_stats`, `clear_cache` |
 | Query Optimization | 3 | `analyze_query`, `get_optimization_hints`, `repair_query` |
 | Backup & Restore | 5 | `backup_database`, `restore_from_sql` |
-| Import/Export | 5 | `export_table_to_json`, `import_from_csv` |
+| Import/Export | 6 | `safe_export_table`, `export_table_to_json`, `import_from_csv` |
 | Data Migration | 5 | `copy_table_data`, `sync_table_data` |
 | Schema Migrations | 9 | `create_migration`, `apply_migrations` |
 | Utilities | 4 | `test_connection`, `export_table_to_csv` |

package/dist/config/featureConfig.d.ts

@@ -50,6 +50,8 @@ export interface PermissionPreset {
     description: string;
     permissions: ToolCategory[];
     categories: DocCategory[];
+    allowedTools?: string[];
+    deniedTools?: string[];
 }
 /**
  * Map of tool names to their legacy categories
@@ -68,6 +70,8 @@ export declare const toolDocCategoryMap: Record<string, DocCategory>;
 export declare class FeatureConfig {
     private enabledLegacyCategories;
     private enabledDocCategories;
+    private allowedTools;
+    private deniedTools;
     private originalPermissionsString;
     private originalCategoriesString;
     private useDualLayer;

package/dist/config/featureConfig.js

@@ -115,6 +115,58 @@ const permissionPresets = {
             DocCategory.STORED_PROCEDURES,
         ],
     },
+    dev: {
+        name: "dev",
+        description: "Development profile with full access to all tools",
+        permissions: Object.values(ToolCategory),
+        categories: Object.values(DocCategory),
+        deniedTools: [], // Explicitly allow everything
+    },
+    stage: {
+        name: "stage",
+        description: "Staging profile with data modification but no destructive DDL",
+        permissions: [
+            ToolCategory.LIST,
+            ToolCategory.READ,
+            ToolCategory.CREATE,
+            ToolCategory.UPDATE,
+            ToolCategory.DELETE,
+            ToolCategory.UTILITY,
+            ToolCategory.TRANSACTION,
+        ],
+        categories: [
+            DocCategory.DATABASE_DISCOVERY,
+            DocCategory.CRUD_OPERATIONS,
+            DocCategory.BULK_OPERATIONS,
+            DocCategory.CUSTOM_QUERIES,
+            DocCategory.UTILITIES,
+            DocCategory.TRANSACTION_MANAGEMENT,
+            DocCategory.IMPORT_EXPORT,
+            DocCategory.DATA_MIGRATION,
+            DocCategory.PERFORMANCE_MONITORING,
+            DocCategory.ANALYSIS,
+        ],
+        deniedTools: ["drop_table", "truncate_table", "drop_database"],
+    },
+    prod: {
+        name: "prod",
+        description: "Production profile with strict read-only access and safety checks",
+        permissions: [ToolCategory.LIST, ToolCategory.READ, ToolCategory.UTILITY],
+        categories: [
+            DocCategory.DATABASE_DISCOVERY,
+            DocCategory.CRUD_OPERATIONS, // Read only via permissions
+            DocCategory.CUSTOM_QUERIES,
+            DocCategory.UTILITIES,
+            DocCategory.PERFORMANCE_MONITORING,
+            DocCategory.ANALYSIS,
+        ],
+        deniedTools: [
+            "create_table", "alter_table", "drop_table", "truncate_table",
+            "create_record", "update_record", "delete_record",
+            "bulk_insert", "bulk_update", "bulk_delete",
+            "execute_sql", "execute_ddl"
+        ],
+    },
 };
 /**
  * Map of tool names to their legacy categories
@@ -153,6 +205,8 @@ exports.toolCategoryMap = {
     getTableRelationships: ToolCategory.UTILITY,
     exportTableToCSV: ToolCategory.UTILITY,
     exportQueryToCSV: ToolCategory.UTILITY,
+    safe_export_table: ToolCategory.UTILITY,
+    read_changelog: ToolCategory.UTILITY,
     // Transaction tools
     beginTransaction: ToolCategory.TRANSACTION,
     commitTransaction: ToolCategory.TRANSACTION,
@@ -288,6 +342,7 @@ exports.toolDocCategoryMap = {
     describeConnection: DocCategory.UTILITIES,
     exportTableToCSV: DocCategory.UTILITIES,
     exportQueryToCSV: DocCategory.UTILITIES,
+    read_changelog: DocCategory.UTILITIES,
     // Transaction Management
     beginTransaction: DocCategory.TRANSACTION_MANAGEMENT,
     commitTransaction: DocCategory.TRANSACTION_MANAGEMENT,
@@ -518,6 +573,9 @@ class FeatureConfig {
         const parsed = this.parseConfig(mergedPermissions, mergedCategories);
         this.enabledLegacyCategories = parsed.legacy;
         this.enabledDocCategories = parsed.doc;
+        // Initialize Allow/Deny Lists
+        this.allowedTools = new Set(this.activePreset?.allowedTools || []);
+        this.deniedTools = new Set(this.activePreset?.deniedTools || []);
     }
     /**
      * Normalize and merge preset + user-supplied configuration lists
@@ -576,6 +634,9 @@ class FeatureConfig {
                 docCats.forEach((dc) => docSet.add(dc));
             });
         }
+        // Re-initialize Allow/Deny Lists if preset changed
+        this.allowedTools = new Set(this.activePreset?.allowedTools || []);
+        this.deniedTools = new Set(this.activePreset?.deniedTools || []);
         return {
             legacy: legacySet,
             doc: docSet,
@@ -632,6 +693,15 @@ class FeatureConfig {
             console.warn(`Unknown tool: ${toolName}`);
             return false;
         }
+        // Layer 0: Check explicit Deny/Allow lists
+        // Deny takes precedence
+        if (this.deniedTools.has(toolName)) {
+            return false;
+        }
+        // Allow overrides other checks
+        if (this.allowedTools.has(toolName)) {
+            return true;
+        }
         // Layer 1: Check permission (legacy category)
         const hasPermission = legacyCategory
             ? this.enabledLegacyCategories.has(legacyCategory)
@@ -658,6 +728,9 @@ class FeatureConfig {
         if (!docCategory && !legacyCategory) {
             return `Unknown tool '${toolName}'. This tool is not recognized by the MCP server.`;
         }
+        if (this.deniedTools.has(toolName)) {
+            return `Permission denied: Tool '${toolName}' is explicitly denied by the current profile ('${this.presetName}').`;
+        }
         const isAllEnabled = !this.originalPermissionsString.trim() &&
             !this.originalCategoriesString.trim();
         if (isAllEnabled) {

package/dist/index.d.ts

@@ -190,6 +190,14 @@ export declare class MySQLMCP {
         data?: any;
         error?: string;
     }>;
+    readChangelog(params?: {
+        version?: string;
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     beginTransaction(params?: {
         transactionId?: string;
     }): Promise<import("./tools/transactionTools").TransactionResult | {

package/dist/index.js

@@ -234,6 +234,13 @@ class MySQLMCP {
         }
         return await this.utilityTools.getTableRelationships(params);
     }
+    async readChangelog(params) {
+        const check = this.checkToolEnabled("read_changelog");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.utilityTools.readChangelog(params);
+    }
     // Transaction Tools
     async beginTransaction(params) {
         const check = this.checkToolEnabled("beginTransaction");

package/dist/mcp-server.js

@@ -659,6 +659,23 @@ const TOOLS = [
             properties: {},
         },
     },
+    {
+        name: "read_changelog",
+        description: "Reads the changelog to see what features are new or changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                version: {
+                    type: "string",
+                    description: "Optional: specific version to read (e.g., '1.0.0')",
+                },
+                limit: {
+                    type: "number",
+                    description: "Optional: limit character count (default: 5000)",
+                },
+            },
+        },
+    },
     {
         name: "test_connection",
         description: "Tests the database connection and returns latency information.",
@@ -2874,6 +2891,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "test_connection":
                 result = await mysqlMCP.testConnection();
                 break;
+            case "read_changelog":
+                result = await mysqlMCP.readChangelog((args || {}));
+                break;
             case "get_table_relationships":
                 result = await mysqlMCP.getTableRelationships((args || {}));
                 break;

package/dist/tools/utilityTools.d.ts

@@ -27,4 +27,15 @@ export declare class UtilityTools {
         data?: any;
         error?: string;
     }>;
+    /**
+     * Reads the CHANGELOG.md file from the project root
+     */
+    readChangelog(params?: {
+        version?: string;
+        limit?: number;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
 }

package/dist/tools/utilityTools.js

@@ -7,6 +7,8 @@ exports.UtilityTools = void 0;
 const connection_1 = __importDefault(require("../db/connection"));
 const config_1 = require("../config/config");
 const schemas_1 = require("../validation/schemas");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 class UtilityTools {
     constructor() {
         this.db = connection_1.default.getInstance();
@@ -208,5 +210,74 @@ class UtilityTools {
             };
         }
     }
+    /**
+     * Reads the CHANGELOG.md file from the project root
+     */
+    async readChangelog(params) {
+        try {
+            // Resolve path relative to the built file (dist/tools/utilityTools.js -> ../../CHANGELOG.md)
+            // or source file (src/tools/utilityTools.ts -> ../../CHANGELOG.md)
+            const changelogPath = path_1.default.resolve(__dirname, "..", "..", "CHANGELOG.md");
+            if (!fs_1.default.existsSync(changelogPath)) {
+                return {
+                    status: "error",
+                    error: "CHANGELOG.md not found in the project root.",
+                };
+            }
+            const content = fs_1.default.readFileSync(changelogPath, "utf-8");
+            // If version specified, try to parse and find it
+            if (params?.version) {
+                // Simple parsing - look for headers like "## [1.2.3]"
+                const versionHeader = `## [${params.version}]`;
+                const lines = content.split("\n");
+                let found = false;
+                let versionContent = "";
+                for (const line of lines) {
+                    if (line.startsWith(versionHeader)) {
+                        found = true;
+                        versionContent += line + "\n";
+                        continue;
+                    }
+                    if (found) {
+                        if (line.startsWith("## ["))
+                            break; // Next version starts
+                        versionContent += line + "\n";
+                    }
+                }
+                if (!found) {
+                    return {
+                        status: "error",
+                        error: `Version ${params.version} not found in CHANGELOG.md`,
+                    };
+                }
+                return {
+                    status: "success",
+                    data: {
+                        version: params.version,
+                        content: versionContent.trim(),
+                    },
+                };
+            }
+            // If no version, return the whole file or top N characters/lines?
+            // For now, let's return the most recent versions.
+            // Limit default to 3000 chars to avoid overflowing context
+            const maxLength = params?.limit || 5000;
+            const truncated = content.length > maxLength
+                ? content.substring(0, maxLength) + "\n... (truncated)"
+                : content;
+            return {
+                status: "success",
+                data: {
+                    content: truncated,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: `Failed to read changelog: ${error.message}`,
+            };
+        }
+    }
 }
 exports.UtilityTools = UtilityTools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@berthojoris/mcp-mysql-server",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "description": "Model Context Protocol server for MySQL database integration with dynamic per-project permissions, backup/restore, data import/export, and data migration capabilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -86,4 +86,4 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.2.2"
   }
-}
+}