@berthojoris/mcp-mysql-server 1.14.0 → 1.14.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.14.1] - 2025-12-08
+
+### Added
+- **Workflow Macros** - New `safe_export_table` tool that combines data export with mandatory masking.
+  - Allows safe export of sensitive data by enforcing masking before the data leaves the database.
+  - Supports configurable masking profiles (strict (default), partial, soft).
+
 ## [1.14.0] - 2025-12-08
 
 ### Added

package/DOCUMENTATIONS.md

@@ -26,19 +26,6 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 18. [Performance Monitoring](#📈-performance-monitoring)
 19. [Usage Examples](#📋-usage-examples)
 20. [Query Logging & Automatic SQL Display](#📝-query-logging--automatic-sql-display)
-21. [Security Features](#🔒-security-features)
-22. [Query Result Caching](#💾-query-result-caching)
-23. [Query Optimization Hints](#🎯-query-optimization-hints)
-24. [Guided Query Builder/Fixer](#🤖-guided-query-builderfixer)
-25. [Bulk Operations](#🚀-bulk-operations)
-26. [OpenAI Codex Integration](#🤖-openai-codex-integration)
-27. [Troubleshooting](#🛠️-troubleshooting)
-28. [License](#📄-license)
-29. [Roadmap](#🗺️-roadmap)
-
----
-
-## Dual-Layer Filtering System
 
 Control which database operations are available to AI using a **dual-layer filtering system**:
 
@@ -754,6 +741,47 @@ Both tools support:
 
 ---
 
+## 🔄 Workflow Macros
+
+Workflow Macros are composite tools designed to execute complex, multi-step operations safely and efficiently. They encapsulate best practices and security policies (like data masking) into single, atomic tool calls.
+
+### Available Macros
+
+| Tool | Description |
+|------|-------------|
+| `safe_export_table` | Exports table data to CSV with mandated data masking (redaction/hashing) |
+
+### safe_export_table
+
+Exports table data to CSV format *with enforced data masking*. This is safer than standard export tools because it ensures sensitive data is masked before leaving the database layer, regardless of the global masking configuration.
+
+**Parameters:**
+- `table_name` (required): Name of the table to export.
+- `masking_profile` (optional): "strict" (default), "partial", or "soft".
+- `limit` (optional): Maximum rows to export (default 1000, max 10000).
+- `include_headers` (optional): Whether to include CSV headers (default true).
+
+**Example:**
+*User prompt: "Safely export the users table to a CSV file"*
+
+```json
+{
+  "tool": "safe_export_table",
+  "arguments": {
+    "table_name": "users",
+    "masking_profile": "strict"
+  }
+}
+```
+
+**Result:**
+CSV content where:
+- Emails are masked (e.g., `j***@domain.com`)
+- Passwords/secrets are `[REDACTED]`
+- Phone numbers are partially hidden
+
+---
+
 ## 📥 Data Import Tools
 
 The MySQL MCP Server provides tools to import data from various formats into your database tables.

package/README.md

@@ -56,20 +56,6 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 - [License](#-license)
 
 ---
-
-## Features
-
-| Category | Description |
-|----------|-------------|
-| **Full MCP Support** | Works with Claude Code, Cursor, Windsurf, Zed, Cline, Kilo Code, Roo Code, Gemini CLI, OpenAI Codex, and any MCP-compatible AI agent |
-| **Security First** | Parameterized queries, SQL injection protection, permission-based access control |
-| **124 Powerful Tools** | Complete database operations including CRUD, DDL, transactions, stored procedures, backup/restore, migrations |
-| **Adaptive Presets** | Built-in ReadOnly/Analyst/DBA Lite permission bundles with override merging |
-| **Schema-Aware RAG Pack** | Compact schema snapshots (tables, PK/FK, row estimates) tailored for embeddings-friendly prompts |
-| **Category Filtering** | 22 documentation categories for intuitive, fine-grained access control (backward compatible with 10 legacy categories) |
-| **Transaction Support** | Full ACID transaction management (BEGIN, COMMIT, ROLLBACK) |
-| **Schema Migrations** | Version control for database schema with up/down migrations |
-| **Dual Mode** | Run as MCP server OR as REST API |
 | **Data Masking** | Protect PII/Secrets in responses with configurable profiles (soft/partial/strict) |
 | **TypeScript** | Fully typed with TypeScript definitions |
 

package/dist/config/featureConfig.js

@@ -230,19 +230,6 @@ exports.toolCategoryMap = {
     showReplicationStatus: ToolCategory.LIST,
     // Backup and restore tools
     backupTable: ToolCategory.UTILITY,
-    backupDatabase: ToolCategory.UTILITY,
-    restoreFromSql: ToolCategory.DDL,
-    getCreateTableStatement: ToolCategory.LIST,
-    getDatabaseSchema: ToolCategory.LIST,
-    // Extended data export/import tools
-    exportTableToJSON: ToolCategory.UTILITY,
-    exportQueryToJSON: ToolCategory.UTILITY,
-    exportTableToSql: ToolCategory.UTILITY,
-    importFromCSV: ToolCategory.CREATE,
-    importFromJSON: ToolCategory.CREATE,
-    // Data migration tools
-    copyTableData: ToolCategory.CREATE,
-    moveTableData: ToolCategory.DELETE,
     cloneTable: ToolCategory.DDL,
     compareTableStructure: ToolCategory.LIST,
     syncTableData: ToolCategory.UPDATE,
@@ -397,6 +384,7 @@ exports.toolDocCategoryMap = {
     exportTableToJSON: DocCategory.IMPORT_EXPORT,
     exportQueryToJSON: DocCategory.IMPORT_EXPORT,
     exportTableToSql: DocCategory.IMPORT_EXPORT,
+    safe_export_table: DocCategory.IMPORT_EXPORT,
     importFromCSV: DocCategory.IMPORT_EXPORT,
     importFromJSON: DocCategory.IMPORT_EXPORT,
     // Data Migration

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export declare class MySQLMCP {
     private performanceTools;
     private analysisTools;
     private aiTools;
+    private macroTools;
     private security;
     private featureConfig;
     constructor(permissionsConfig?: string, categoriesConfig?: string, presetName?: string);
@@ -590,6 +591,16 @@ export declare class MySQLMCP {
         suggestions?: string[];
         error?: string;
     }>;
+    safeExportTable(params: {
+        table_name: string;
+        masking_profile?: string;
+        limit?: number;
+        include_headers?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
     getFeatureStatus(): {
         status: string;
         data: {

package/dist/index.js

@@ -25,6 +25,7 @@ const schemaVersioningTools_1 = require("./tools/schemaVersioningTools");
 const performanceTools_1 = require("./tools/performanceTools");
 const analysisTools_1 = require("./tools/analysisTools");
 const aiTools_1 = require("./tools/aiTools");
+const macroTools_1 = require("./tools/macroTools");
 const securityLayer_1 = __importDefault(require("./security/securityLayer"));
 const connection_1 = __importDefault(require("./db/connection"));
 const featureConfig_1 = require("./config/featureConfig");
@@ -56,7 +57,9 @@ class MySQLMCP {
         this.schemaVersioningTools = new schemaVersioningTools_1.SchemaVersioningTools(this.security);
         this.performanceTools = new performanceTools_1.PerformanceTools(this.security);
         this.analysisTools = new analysisTools_1.AnalysisTools(this.security);
+        this.analysisTools = new analysisTools_1.AnalysisTools(this.security);
         this.aiTools = new aiTools_1.AiTools(this.security);
+        this.macroTools = new macroTools_1.MacroTools(this.security);
     }
     // Helper method to check if tool is enabled
     checkToolEnabled(toolName) {
@@ -535,6 +538,14 @@ class MySQLMCP {
         }
         return await this.aiTools.repairQuery(params);
     }
+    // Workflow Macros
+    async safeExportTable(params) {
+        const check = this.checkToolEnabled("safe_export_table");
+        if (!check.enabled) {
+            return { status: "error", error: check.error };
+        }
+        return await this.macroTools.safeExportTable(params);
+    }
     // Get feature configuration status
     getFeatureStatus() {
         const snapshot = this.featureConfig.getConfigSnapshot();

package/dist/mcp-server.js

@@ -476,6 +476,33 @@ const TOOLS = [
             required: ["query"],
         },
     },
+    {
+        name: "safe_export_table",
+        description: "Exports table data to CSV with enforced data masking rules to protect sensitive information.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                table_name: {
+                    type: "string",
+                    description: "Name of the table to export",
+                },
+                masking_profile: {
+                    type: "string",
+                    enum: ["soft", "partial", "strict"],
+                    description: "Masking profile to apply (default: strict). strict=redact all PII/secrets, partial=partial mask PII, soft=mask secrets only.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of rows to export (default: 1000, max: 10000)",
+                },
+                include_headers: {
+                    type: "boolean",
+                    description: "Whether to include CSV headers (default: true)",
+                },
+            },
+            required: ["table_name"],
+        },
+    },
     {
         name: "repair_query",
         description: "Analyzes a SQL query (and optional error) to suggest repairs or optimizations using EXPLAIN and heuristics.",
@@ -3083,6 +3110,12 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "export_query_to_json":
                 result = await mysqlMCP.exportQueryToJSON((args || {}));
                 break;
+            case "export_query_to_csv":
+                result = await mysqlMCP.exportQueryToCSV((args || {}));
+                break;
+            case "safe_export_table":
+                result = await mysqlMCP.safeExportTable((args || {}));
+                break;
             case "export_table_to_sql":
                 result = await mysqlMCP.exportTableToSql((args || {}));
                 break;

package/dist/tools/macroTools.d.ts

@@ -0,0 +1,20 @@
+import SecurityLayer from "../security/securityLayer";
+export declare class MacroTools {
+    private db;
+    private security;
+    constructor(security: SecurityLayer);
+    /**
+     * Safe Export Table: Exports table data to CSV with enforced data masking
+     * This macro prioritizes data safety by applying masking rules before export.
+     */
+    safeExportTable(params: {
+        table_name: string;
+        masking_profile?: string;
+        limit?: number;
+        include_headers?: boolean;
+    }): Promise<{
+        status: string;
+        data?: any;
+        error?: string;
+    }>;
+}

package/dist/tools/macroTools.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MacroTools = void 0;
+const connection_1 = __importDefault(require("../db/connection"));
+const maskingLayer_1 = require("../security/maskingLayer");
+class MacroTools {
+    constructor(security) {
+        this.db = connection_1.default.getInstance();
+        this.security = security;
+    }
+    /**
+     * Safe Export Table: Exports table data to CSV with enforced data masking
+     * This macro prioritizes data safety by applying masking rules before export.
+     */
+    async safeExportTable(params) {
+        try {
+            const { table_name, masking_profile = "strict", limit = 1000, include_headers = true, } = params;
+            // 1. Validate table name
+            const tableValidation = this.security.validateIdentifier(table_name);
+            if (!tableValidation.valid) {
+                return {
+                    status: "error",
+                    error: tableValidation.error,
+                };
+            }
+            // 2. Fetch data (with hard limit to prevent OOM on large safe exports)
+            const maxLimit = 10000;
+            const actualLimit = Math.min(limit, maxLimit);
+            const escapedTableName = this.security.escapeIdentifier(table_name);
+            const query = `SELECT * FROM ${escapedTableName} LIMIT ?`;
+            const results = (await this.db.query(query, [actualLimit]));
+            if (results.length === 0) {
+                return {
+                    status: "success",
+                    data: {
+                        csv: include_headers ? "" : "",
+                        row_count: 0,
+                        applied_profile: masking_profile,
+                    },
+                };
+            }
+            // 3. Apply masking explicitly using a new temporary layer to ensure strictness
+            // We don't rely on the global masking profile here; we use the one requested (default strict)
+            const tempMaskingLayer = new maskingLayer_1.MaskingLayer(masking_profile);
+            const maskedResults = tempMaskingLayer.processResults(results);
+            // 4. Convert to CSV
+            let csv = "";
+            if (include_headers) {
+                const headers = Object.keys(maskedResults[0]).join(",");
+                csv += headers + "\n";
+            }
+            for (const row of maskedResults) {
+                const values = Object.values(row)
+                    .map((value) => {
+                    if (value === null)
+                        return "";
+                    if (value === undefined)
+                        return "";
+                    let str = String(value);
+                    // Escape quotes and wrap in quotes if contains comma, newline or quotes
+                    if (str.includes(",") ||
+                        str.includes("\n") ||
+                        str.includes('"')) {
+                        return `"${str.replace(/"/g, '""')}"`;
+                    }
+                    return str;
+                })
+                    .join(",");
+                csv += values + "\n";
+            }
+            return {
+                status: "success",
+                data: {
+                    csv: csv,
+                    row_count: maskedResults.length,
+                    applied_profile: tempMaskingLayer.getProfile(),
+                },
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                error: error.message,
+            };
+        }
+    }
+}
+exports.MacroTools = MacroTools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@berthojoris/mcp-mysql-server",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "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"
   }
-}
+}