@berthojoris/mcp-mysql-server 1.10.5 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.13.0] - 2025-12-07
+
+### Added
+- **Guided Query Builder/Fixer** - New `repair_query` tool that uses deterministic heuristics and `EXPLAIN` to analyze and fix SQL queries.
+  - Suggests optimizations (e.g., adding indexes, limits).
+  - Analyzes execution plans for performance issues like full table scans.
+  - Provides actionable feedback for specific error messages.
+
+## [1.12.0] - 2025-12-05
+
+### Added
+- Schema-Aware RAG Context Pack via `get_schema_rag_context`, delivering compact table/column/PK/FK snapshots with row estimates for embeddings-friendly prompts.
+
+### Fixed
+- Exposed analysis tools (`get_database_summary`, `get_schema_erd`, `get_column_statistics`) and the new RAG context pack through MCP tool registration and routing.
+
+### Changed
+- Updated documentation and tool counts to 120, reflecting the new analysis capability and refreshed README guidance.
+
 ## [1.10.5] - 2025-12-02
 
 ### Changed
@@ -14,6 +33,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.10.4] - 2025-12-02
 
+### Added
+- **AI Context Optimization** - Added 4 new AI-centric tools:
+  - `get_database_summary` - High-level database overview (tables, columns, row counts) optimized for context window
+  - `get_schema_erd` - Generates Mermaid.js ER diagrams for visual schema representation
+  - `get_column_statistics` - Deep data profiling (min/max, nulls, distinct counts) for intelligent query building
+  - `run_query` Safe Mode - Added `dry_run` flag to preview query plans and costs without execution
+
 ### Fixed
 - Removed "IMPORTANT_INSTRUCTION_TO_ASSISTANT" instruction from documentation - no longer needed
 - Removed "SQL_QUERY_EXECUTED" message references from documentation - simplified response structure
@@ -467,6 +493,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Direct access to `mysql`, `performance_schema`, `sys` databases
   - `USER` / `PASSWORD` manipulation
 
+## [1.11.0] - 2025-12-05
+
+### Added
+- Adaptive permission presets (`readonly`, `analyst`, `dba-lite`) with mergeable overrides
+- CLI `--preset` flag and `MCP_PRESET`/`MCP_PERMISSION_PRESET` env support with resolved-config logging
+
+### Changed
+- Safe fallback to read-only defaults when an unknown preset is requested without overrides
+- Feature status endpoint now exposes preset-aware configuration snapshots for easier debugging
+
 ## [1.4.3] - 2025-01-06
 
 ### Added
@@ -512,6 +548,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version History Summary
 
+- **1.11.0** - Adaptive permission presets with CLI/env support and preset-aware logging
 - **1.9.0** - Schema Versioning & Migrations (9 new tools), MCP integration for 12 AI tools
 - **1.8.0** - Data Migration Tools
 - **1.7.0** - Database Backup/Restore, Data Import/Export

package/DOCUMENTATIONS.md

@@ -6,8 +6,8 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 
 ## Table of Contents
 
-1. [🆕 Category Filtering System](#🆕-category-filtering-system) - NEW!
-2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 119 tools organized by category
+1. [Category Filtering System](#🆕-category-filtering-system) - NEW!
+2. [🔧 Complete Tools Reference](#🔧-complete-tools-reference) - All 120 tools organized by category
 3. [DDL Operations](#🏗️-ddl-operations)
 4. [Data Export Tools](#📤-data-export-tools)
 5. [Data Import Tools](#📥-data-import-tools)
@@ -29,15 +29,16 @@ This file contains detailed documentation for all features of the MySQL MCP Serv
 21. [Security Features](#🔒-security-features)
 22. [Query Result Caching](#💾-query-result-caching)
 23. [Query Optimization Hints](#🎯-query-optimization-hints)
-24. [Bulk Operations](#🚀-bulk-operations)
-25. [OpenAI Codex Integration](#🤖-openai-codex-integration)
-26. [Troubleshooting](#🛠️-troubleshooting)
-27. [License](#📄-license)
-28. [Roadmap](#🗺️-roadmap)
+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
+## Dual-Layer Filtering System
 
 Control which database operations are available to AI using a **dual-layer filtering system**:
 
@@ -71,7 +72,8 @@ schema_management,utilities,transaction_management,stored_procedures,
 views_management,triggers_management,functions_management,index_management,
 constraint_management,table_maintenance,server_management,
 performance_monitoring,cache_management,query_optimization,
-backup_restore,import_export,data_migration,schema_migrations
+backup_restore,import_export,data_migration,schema_migrations,
+analysis
 ```
 
 ### Configuration Examples
@@ -194,6 +196,24 @@ Data operations without schema changes:
 
 **Enabled**: Full data CRUD + bulk ops + transactions - NO schema changes (no `ddl` permission).
 
+### Adaptive Permission Presets (ReadOnly/Analyst/DBA Lite)
+
+Preset bundles provide safe starting points and **merge** with any explicit permissions/categories you pass (CLI args or env vars).
+
+| Preset | Permissions | Categories | Intended Use |
+|--------|-------------|------------|--------------|
+| `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 |
+
+**Usage**
+
+- CLI: `mcp-mysql mysql://user:pass@host:3306/db --preset readonly`
+- CLI with overrides: `mcp-mysql mysql://... --preset analyst "list,read,utility" "performance_monitoring"`
+- Env: `MCP_PRESET=analyst` (or `MCP_PERMISSION_PRESET=analyst`) and optionally extend with `MCP_PERMISSIONS` / `MCP_CATEGORIES`
+
+If a preset name is not recognized and no overrides are provided, the server falls back to a safe read-only baseline instead of enabling everything.
+
 ### Permissions Reference (Layer 1)
 
 | Permission | Operations Allowed | Example Tools |
@@ -222,7 +242,7 @@ The system uses both arguments to determine access:
 - **3rd argument**: Categories (Layer 2, optional) - comma-separated documentation categories
 
 **Decision logic**:
-1. If no arguments: All 119 tools enabled
+1. If no arguments: All 120 tools enabled
 2. If only 2nd argument (permissions): Tools enabled if they match permission
 3. If both arguments: Tools enabled if they match BOTH permission AND category
 
@@ -267,7 +287,7 @@ Add 'bulk_operations' to the categories argument.
 
 ## 🔧 Complete Tools Reference
 
-This section provides a comprehensive reference of all 119 available tools organized by category.
+This section provides a comprehensive reference of all 120 available tools organized by category.
 
 ### Database Discovery
 
@@ -498,6 +518,21 @@ This section provides a comprehensive reference of all 119 available tools organ
 | `reset_failed_migration` | Reset failed migration to pending | `ddl` |
 | `generate_migration_from_diff` | Generate migration from table diff | `ddl` |
 
+### AI Context & Analysis Tools
+
+| Tool | Description | Requires |
+|------|-------------|----------|
+| `get_database_summary` | High-level overview (tables, columns, rows) for AI context | `list` |
+| `get_schema_erd` | Generate Mermaid.js ER diagram for visualization | `list` |
+| `get_schema_rag_context` | Condensed schema snapshot (tables, PK/FK, row estimates) for RAG prompts | `list` |
+| `get_column_statistics` | Profile data (min, max, nulls, distinct) for analysis | `read` |
+
+#### Schema-Aware RAG Context Pack
+- Purpose-built for embeddings: returns a `context_text` block plus structured `tables` and `relationships` so agents can self-orient without pulling a full ERD.
+- Tunable size: `max_tables` (default 50, max 200) and `max_columns` (default 12) to control output length; set `include_relationships` to `false` to omit FK lines.
+- 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).
+
 ---
 
 ## 🏗️ DDL Operations
@@ -3605,6 +3640,50 @@ Available goals:
 
 ---
 
+---
+
+## 🤖 Guided Query Builder/Fixer
+
+The `repair_query` tool acts as an AI-powered assistant for SQL query optimization and troubleshooting.
+
+### Features
+
+- **Query Analysis**: Uses `EXPLAIN` to understand query execution plans.
+- **Auto-Fixing**: Identifying missing indexes, inefficient scans, and syntax errors.
+- **Heuristic suggestions**: Provides actionable advice (e.g. "Add index on column X", "Add LIMIT clause").
+
+### Usage Example
+
+**Request:**
+```json
+{
+  "tool": "repair_query",
+  "arguments": {
+    "query": "SELECT * FROM users WHERE email = 'test@example.com'",
+    "error_message": "Optional error message if query failed"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "analysis": {
+    "complexity": "HIGH",
+    "issues": ["Full Table Scan on table 'users'"],
+    "suggestions": ["Consider adding an index on table 'users' for the columns used in WHERE clause."]
+  },
+  "fixed_query": "SELECT * FROM users WHERE email = 'test@example.com'",
+  "suggestions": [
+    "Consider adding an index on table 'users' for the columns used in WHERE clause.",
+    "Consider adding 'LIMIT 100' to prevent massive data transfer."
+  ]
+}
+```
+
+---
+
 ## 🚀 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.
@@ -4018,16 +4097,6 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - ✅ **Data export/import utilities** (CSV, JSON, SQL dumps) - **COMPLETED!**
 - ✅ **Data migration utilities** - **COMPLETED!**
 - ✅ **Schema versioning and migrations** - **COMPLETED!**
-- [ ] **Performance monitoring and metrics**
-- [ ] **Connection pool monitoring**
-- [ ] **Audit logging and compliance**
-
-### Database Adapters
-- [ ] PostgreSQL adapter
-- [ ] MongoDB adapter
-- [ ] SQLite adapter
-- [ ] Oracle Database adapter
-- [ ] SQL Server adapter
 
 ### Recommended Implementation Order
 
@@ -4041,19 +4110,10 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - ✅ **Database backup and restore tools** - Essential for production data safety - **COMPLETED!**
 - ✅ **Data migration utilities** - Move data between databases and environments - **COMPLETED!**
 - ✅ **Enhanced export/import** - Support for JSON, SQL dump formats - **COMPLETED!**
-- [ ] **Query history & analytics** - Track and analyze database usage patterns
 
 #### **Phase 3: Enterprise Features** 🏢
-- [ ] **Audit logging and compliance** - Track all database operations for security
 - ✅ **Schema versioning and migrations** - Version control for database schema changes - **COMPLETED!**
 - ✅ **Query optimization** - Automatic query analysis and optimization suggestions - **COMPLETED!**
-- [ ] **Advanced security features** - Enhanced access control and monitoring
-
-#### **Phase 4: Multi-Database Support** 🌐
-- [ ] **PostgreSQL adapter** - Extend support to PostgreSQL databases
-- [ ] **MongoDB adapter** - Add NoSQL document database support
-- [ ] **SQLite adapter** - Support for lightweight embedded databases
-- [ ] **Database-agnostic operations** - Unified API across different database types
 
 #### **Implementation Priority Matrix**
 
@@ -4073,8 +4133,21 @@ MIT License - see [LICENSE](LICENSE) file for details.
 | Data Migration | High | High | 12 | ✅ COMPLETED |
 | Schema Versioning | Medium | Medium | 13 | ✅ COMPLETED |
 | Performance Monitoring | High | Medium | 14 | ✅ COMPLETED |
-| PostgreSQL Adapter | High | High | 15 | Pending |
-| Audit Logging | Medium | Low | 16 | Pending |
+
+#### **Proposed Enhancements (AI Productivity)**
+
+| Feature | Impact | Effort | Priority | Status |
+|---------|--------|--------|----------|--------|
+| Adaptive Permission Presets (ReadOnly/Analyst/DBA Lite) | High | Medium | 1 | ✅ Completed |
+| Schema-Aware RAG Context Pack | High | Medium | 2 | ✅ Completed |
+| Guided Query Builder/Fixer (Intent → Safe SQL + EXPLAIN Repair) | High | Medium | 3 | ✅ Completed |
+| Drift & Migration Assistant (Schema diff + risk summary) | High | High | 4 | ✅ Completed |
+| 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 | Planned |
+| 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 |
 
 ---
 

package/README.md

@@ -46,11 +46,11 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 - [AI Agent Configuration](#-ai-agent-configuration)
   - [Standard JSON Config](#standard-json-configuration)
   - [OpenAI Codex (TOML)](#openai-codex-cli--vs-code-extension)
-  - [Zed IDE](#zed-ide)
+- [Zed IDE](#zed-ide)
   - [Environment Variables](#environment-variables-configuration)
   - [Local Development](#local-path-configuration)
 - [Permission System](#-permission-system)
-- [Available Tools (119 total)](#-available-tools)
+- [Available Tools (120 total)](#-available-tools)
 - [Documentation](#-detailed-documentation)
 - [Comparison: MCP vs Manual Access](#-mysql-mcp-vs-manual-database-access)
 - [License](#-license)
@@ -63,8 +63,10 @@ Add to your AI agent config (`.mcp.json`, `.cursor/mcp.json`, etc.):
 |----------|-------------|
 | **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 |
-| **119 Powerful Tools** | Complete database operations including CRUD, DDL, transactions, stored procedures, backup/restore, migrations |
-| **🆕 Category Filtering** | 22 documentation categories for intuitive, fine-grained access control (backward compatible with 10 legacy categories) |
+| **121 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 |
@@ -329,6 +331,8 @@ Zed IDE uses a different structure in `~/.config/zed/settings.json`:
 
 Alternative approach using environment variables instead of connection string:
 
+**Option 1: Permissions Only (Simple)**
+
 ```json
 {
   "mcpServers": {
@@ -348,6 +352,53 @@ Alternative approach using environment variables instead of connection string:
 }
 ```
 
+**Option 2: Permissions + Categories (Recommended)**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@berthojoris/mysql-mcp"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your_password",
+        "DB_NAME": "your_database",
+        "MCP_PERMISSIONS": "list,read,utility",
+        "MCP_CATEGORIES": "database_discovery,performance_monitoring"
+      }
+    }
+  }
+}
+```
+
+**Option 3: Adaptive Preset (Merges with Overrides)**
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@berthojoris/mysql-mcp"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your_password",
+        "DB_NAME": "your_database",
+        "MCP_PRESET": "readonly",
+        "MCP_PERMISSIONS": "list,read,utility",
+        "MCP_CATEGORIES": "performance_monitoring"
+      }
+    }
+  }
+}
+```
+
+Add `MCP_PRESET` for the base bundle and optionally layer on `MCP_PERMISSIONS` / `MCP_CATEGORIES` for project-specific overrides.
+
 ---
 
 ### Local Path Configuration
@@ -422,7 +473,7 @@ Control database access with a **dual-layer filtering system** that provides bot
 
 **Filtering Logic**: `Tool enabled = (Has Permission) AND (Has Category OR No categories specified)`
 
-### 🆕 Documentation Categories (Recommended)
+### Documentation Categories (Recommended)
 
 Use these categories for fine-grained control that matches the tool organization:
 
@@ -450,6 +501,7 @@ Use these categories for fine-grained control that matches the tool organization
 | `import_export` | 5 | Import/export JSON, CSV, SQL |
 | `data_migration` | 5 | Copy, move, clone, sync table data |
 | `schema_migrations` | 9 | Version control for database schema |
+| `analysis` | 3 | AI context optimization and data analysis |
 
 ### Legacy Categories (Backward Compatible)
 
@@ -479,7 +531,7 @@ Use these categories for fine-grained control that matches the tool organization
 | **Application Backend** | `database_discovery,crud_operations,bulk_operations,custom_queries,transaction_management` | Full app support |
 | **Development & Testing** | `database_discovery,crud_operations,bulk_operations,custom_queries,schema_management,utilities,transaction_management` | Development access |
 | **DBA & DevOps** | `database_discovery,schema_management,table_maintenance,backup_restore,schema_migrations,performance_monitoring` | Admin tasks |
-| **Full Access** | *(leave empty)* | All 119 tools enabled |
+| **Full Access** | *(leave empty)* | All 120 tools enabled |
 
 #### Using Legacy Categories (Backward Compatible)
 
@@ -492,6 +544,24 @@ Use these categories for fine-grained control that matches the tool organization
 | **Development** | `list,read,create,update,delete,execute,ddl,transaction,utility` | Full access |
 | **DBA Tasks** | `list,ddl,utility` | Schema management only |
 
+### Adaptive Permission Presets (ReadOnly/Analyst/DBA Lite)
+
+Use presets to bootstrap safe defaults. They **merge** with any explicit permissions/categories you pass via CLI args or env vars.
+
+| Preset | Permissions | Categories | Ideal for |
+|--------|-------------|------------|-----------|
+| `readonly` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,import_export,performance_monitoring,analysis` | Safe read-only data access + exports |
+| `analyst` | `list,read,utility` | `database_discovery,crud_operations,custom_queries,utilities,import_export,performance_monitoring,analysis,query_optimization,cache_management,server_management` | Analytics with plan insights and cache/perf 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, migrations, and maintenance |
+
+**Usage**
+
+- CLI: `mcp-mysql mysql://user:pass@host:3306/db --preset readonly`
+- CLI with overrides: `mcp-mysql mysql://... --preset analyst "list,read,utility" "performance_monitoring"`
+- Env: `MCP_PRESET=analyst` (or `MCP_PERMISSION_PRESET=analyst`) plus optional `MCP_PERMISSIONS` / `MCP_CATEGORIES` to extend
+
+If an unknown preset is requested without overrides, the server falls back to a safe read-only baseline instead of enabling everything.
+
 ### Per-Project Configuration
 
 #### Single-Layer: Permissions Only (Backward Compatible)
@@ -582,11 +652,11 @@ Use both 2nd argument (permissions) and 3rd argument (categories):
 
 ## Available Tools
 
-The MCP server provides **119 powerful tools** organized into categories:
+The MCP server provides **120 powerful tools** organized into categories:
 
 ### Quick Reference
 
-**119 Tools Available** - Organized into 22 categories
+**121 Tools Available** - Organized into 22 categories
 
 | Category | Count | Key Tools |
 |----------|-------|-----------|
@@ -606,12 +676,13 @@ The MCP server provides **119 powerful tools** organized into categories:
 | Server Management | 9 | `show_process_list`, `explain_query` |
 | Performance Monitoring | 10 | `get_performance_metrics`, `get_database_health_check` |
 | Cache | 5 | `get_cache_stats`, `clear_cache` |
-| Query Optimization | 2 | `analyze_query`, `get_optimization_hints` |
+| 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` |
 | Data Migration | 5 | `copy_table_data`, `sync_table_data` |
 | Schema Migrations | 9 | `create_migration`, `apply_migrations` |
 | Utilities | 4 | `test_connection`, `export_table_to_csv` |
+| Analysis | 4 | `get_column_statistics`, `get_database_summary`, `get_schema_erd`, `get_schema_rag_context` |
 
 > **📖 For detailed tool descriptions, parameters, and examples, see [DOCUMENTATIONS.md](DOCUMENTATIONS.md#🔧-complete-tools-reference)**
 

package/bin/mcp-mysql.js

@@ -10,16 +10,55 @@ const path = require("path");
 const { spawn } = require("child_process");
 require("dotenv").config();
 
-// Get MySQL connection string, permissions, and optional categories from command line arguments
-const mysqlUrl = process.argv[2];
-const permissions = process.argv[3]; // Optional: comma-separated list of permissions (legacy categories)
-const categories = process.argv[4]; // Optional: comma-separated list of documentation categories
+// Get MySQL connection string, permissions, categories, and optional preset
+const args = process.argv.slice(2);
+const mysqlUrl = args.shift();
+
+let permissions;
+let categories;
+let preset;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  const normalized = (arg || "").toLowerCase();
+
+  if (normalized === "--preset") {
+    preset = args[i + 1];
+    i++;
+    continue;
+  }
+
+  if (normalized.startsWith("--preset=")) {
+    preset = arg.split("=")[1];
+    continue;
+  }
+
+  if (normalized.startsWith("preset:")) {
+    preset = arg.split(":")[1];
+    continue;
+  }
+
+  if (["readonly", "analyst", "dba-lite", "dba_lite", "dba lite"].includes(normalized)) {
+    preset = arg;
+    continue;
+  }
+
+  if (permissions === undefined) {
+    permissions = arg;
+    continue;
+  }
+
+  if (categories === undefined) {
+    categories = arg;
+    continue;
+  }
+}
 
 if (!mysqlUrl) {
   console.error("Error: MySQL connection URL is required");
-  console.error(
-    "Usage: mcp-mysql mysql://user:password@host:port/dbname [permissions] [categories]",
-  );
+  console.error(
+    "Usage: mcp-mysql mysql://user:password@host:port/dbname [permissions] [categories] [--preset <name>]",
+  );
   console.error("");
   console.error("Examples:");
   console.error("  # All tools enabled (no filtering)");
@@ -33,9 +72,17 @@ if (!mysqlUrl) {
   console.error(
     "  # Dual-layer: Permissions + Categories (fine-grained control)",
   );
-  console.error(
-    '  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility" "database_discovery,performance_monitoring"',
-  );
+  console.error(
+    '  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility" "database_discovery,performance_monitoring"',
+  );
+  console.error("");
+  console.error("  # Adaptive presets (auto-merge with overrides)");
+  console.error(
+    '  mcp-mysql mysql://root:pass@localhost:3306/mydb --preset readonly',
+  );
+  console.error(
+    '  mcp-mysql mysql://root:pass@localhost:3306/mydb --preset analyst "performance_monitoring"',
+  );
   console.error("");
   console.error("Permissions (Layer 1 - Broad Control):");
   console.error(
@@ -58,20 +105,26 @@ if (!mysqlUrl) {
   console.error(
     "  performance_monitoring, cache_management, query_optimization,",
   );
-  console.error(
-    "  backup_restore, import_export, data_migration, schema_migrations",
-  );
-  console.error("");
-  console.error("Filtering Logic:");
+  console.error(
+    "  backup_restore, import_export, data_migration, schema_migrations",
+  );
+  console.error("");
+  console.error("Filtering Logic:");
   console.error(
     "  - If only permissions: All tools within those permissions enabled",
   );
-  console.error(
-    "  - If permissions + categories: Only tools matching BOTH layers enabled",
-  );
-  console.error("  - If nothing specified: All 119 tools enabled");
-  process.exit(1);
-}
+  console.error(
+    "  - If permissions + categories: Only tools matching BOTH layers enabled",
+  );
+  console.error("  - If nothing specified: All 119 tools enabled");
+  console.error("");
+  console.error("Presets:");
+  console.error("  readonly, analyst, dba-lite");
+  console.error(
+    "  Presets merge with provided permissions/categories so you can add project-specific overrides.",
+  );
+  process.exit(1);
+}
 
 // Parse the MySQL URL to extract connection details
 let connectionConfig;
@@ -115,24 +168,39 @@ const dbMessage = database
   ? `${connectionConfig.host}:${connectionConfig.port}/${database}`
   : `${connectionConfig.host}:${connectionConfig.port} (no specific database selected)`;
 
-// Set permissions/categories as environment variables if provided
-if (permissions) {
-  process.env.MCP_PERMISSIONS = permissions;
-  console.error(`Permissions (Layer 1): ${permissions}`);
-}
-
-if (categories) {
-  process.env.MCP_CATEGORIES = categories;
-  console.error(`Categories (Layer 2): ${categories}`);
-}
-
-if (!permissions && !categories) {
-  console.error("Access Control: All tools enabled (no filtering)");
-} else if (permissions && !categories) {
-  console.error("Filtering Mode: Permission-based only");
-} else if (permissions && categories) {
-  console.error("Filtering Mode: Dual-layer (Permissions + Categories)");
-}
+// Set permissions/categories/preset as environment variables if provided
+if (permissions) {
+  process.env.MCP_PERMISSIONS = permissions;
+  console.error(`Permissions (Layer 1): ${permissions}`);
+}
+
+if (categories) {
+  process.env.MCP_CATEGORIES = categories;
+  console.error(`Categories (Layer 2): ${categories}`);
+}
+
+if (preset) {
+  process.env.MCP_PRESET = preset;
+  console.error(`Permission preset: ${preset}`);
+}
+
+if (!permissions && !categories && !preset) {
+  console.error("Access Control: All tools enabled (no filtering)");
+} else if (preset && !permissions && !categories) {
+  console.error("Filtering Mode: Preset-based (auto permissions + categories)");
+} else if (permissions && categories) {
+  console.error(
+    `Filtering Mode: Dual-layer (Permissions + Categories${preset ? ", preset merged" : ""})`,
+  );
+} else if (permissions && !categories) {
+  console.error(
+    `Filtering Mode: Permission-based only${preset ? " (preset merged)" : ""}`,
+  );
+} else if (!permissions && categories) {
+  console.error(
+    `Filtering Mode: Category-only${preset ? " (preset merged)" : ""}`,
+  );
+}
 
 // Log to stderr (not stdout, which is used for MCP protocol)
 console.error(`Starting MySQL MCP server with connection to ${dbMessage}`);