@neverinfamous/mysql-mcp 2.2.0 → 2.3.0

package/src/codemode/worker-script.ts

@@ -0,0 +1,144 @@
+/**
+ * mysql-mcp - Code Mode Worker Script
+ *
+ * This script runs in a worker thread to execute user code in isolation.
+ * It uses Node.js vm module within the worker for additional sandboxing.
+ */
+
+import { parentPort, workerData } from "node:worker_threads";
+import vm from "node:vm";
+
+interface WorkerData {
+  code: string;
+  apiBindings: Record<string, string[]>;
+  timeout: number;
+}
+
+interface WorkerResult {
+  success: boolean;
+  result?: unknown;
+  error?: string | undefined;
+  stack?: string | undefined;
+}
+
+/**
+ * Execute code in a sandboxed vm context within the worker
+ */
+async function executeCode(): Promise<void> {
+  const { code, timeout } = workerData as WorkerData;
+
+  try {
+    // Create minimal sandbox context
+    const logBuffer: string[] = [];
+    const sandbox = {
+      console: {
+        log: (...args: unknown[]) => {
+          logBuffer.push(
+            args
+              .map((a) =>
+                typeof a === "object" && a !== null
+                  ? JSON.stringify(a)
+                  : String(a),
+              )
+              .join(" "),
+          );
+        },
+        warn: (...args: unknown[]) =>
+          logBuffer.push("[WARN] " + args.map((a) => String(a)).join(" ")),
+        error: (...args: unknown[]) =>
+          logBuffer.push("[ERROR] " + args.map((a) => String(a)).join(" ")),
+        info: (...args: unknown[]) =>
+          logBuffer.push("[INFO] " + args.map((a) => String(a)).join(" ")),
+      },
+      // Block dangerous globals
+      require: undefined,
+      process: undefined,
+      global: undefined,
+      globalThis: undefined,
+      __dirname: undefined,
+      __filename: undefined,
+      module: undefined,
+      exports: undefined,
+      // Safe built-ins
+      JSON,
+      Math,
+      Date,
+      Array,
+      Object,
+      String,
+      Number,
+      Boolean,
+      Map,
+      Set,
+      Promise,
+      Error,
+      TypeError,
+      RangeError,
+      SyntaxError,
+      // Disabled for security
+      setTimeout: undefined,
+      setInterval: undefined,
+      setImmediate: undefined,
+      // mysql API placeholder (populated by main thread via message passing)
+      mysql: {},
+    };
+
+    const context = vm.createContext(sandbox);
+
+    // Wrap code in async IIFE to support await
+    const wrappedCode = `
+            (async () => {
+                ${code}
+            })();
+        `;
+
+    // Compile and run with timeout
+    const script = new vm.Script(wrappedCode, {
+      filename: "worker-codemode-script.js",
+    });
+
+    const result = await (script.runInContext(context, {
+      timeout,
+      breakOnSigint: true,
+    }) as Promise<unknown>);
+
+    const response: WorkerResult = {
+      success: true,
+      result,
+    };
+
+    parentPort?.postMessage(response);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+
+    // Check for timeout
+    if (errorMessage.includes("Script execution timed out")) {
+      const response: WorkerResult = {
+        success: false,
+        error: `Execution timeout: exceeded ${String(timeout)}ms limit`,
+        stack,
+      };
+      parentPort?.postMessage(response);
+      return;
+    }
+
+    const response: WorkerResult = {
+      success: false,
+      error: errorMessage,
+      stack,
+    };
+
+    parentPort?.postMessage(response);
+  }
+}
+
+// Execute immediately
+executeCode().catch((error: unknown) => {
+  const response: WorkerResult = {
+    success: false,
+    error: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+  };
+  parentPort?.postMessage(response);
+});

package/src/constants/ServerInstructions.ts

@@ -86,6 +86,7 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 
 - **Prepared statements**: \`mysql_read_query\` and \`mysql_write_query\` support parameterized queries via the \`params\` array. Use \`?\` placeholders: \`query: "SELECT * FROM users WHERE id = ?", params: [123]\`.
 - **DDL statements**: DDL (e.g., \`CREATE TABLE\`, \`ALTER TABLE\`) is automatically handled via text protocol fallback in \`mysql_write_query\`.
+- **Query error handling**: \`mysql_read_query\` and \`mysql_write_query\` return \`{ success: false, error }\` for all query errors (nonexistent table, syntax, permissions, etc.), instead of throwing raw errors.
 - **Boolean defaults**: \`mysql_create_table\` auto-converts boolean \`default: true\` to \`1\` and \`default: false\` to \`0\` for MySQL compatibility. Alternatively, use \`TINYINT(1)\` with numeric defaults directly.
 - **Existence checks**: \`mysql_describe_table\` and \`mysql_get_indexes\` return \`{ exists: false, table: "..." }\` gracefully when the table does not exist, avoiding raw SQL errors.
 - **Create/Drop safety**: \`mysql_create_table\` returns \`{ success: false, reason }\` when the table already exists (without \`ifNotExists\`). \`mysql_drop_table\` returns \`{ success: false, reason }\` when the table does not exist (without \`ifExists\`). With \`ifExists: true\`, dropping a nonexistent table returns \`{ success: true, skipped: true, reason: "Table did not exist" }\`.
@@ -115,8 +116,8 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 - **Cluster status**: \`mysql_cluster_status\` returns cluster metadata. Use \`summary: true\` for condensed output without Router configuration schemas. Returns \`isInnoDBCluster: false\` if not in a cluster.
 - **Instance list**: \`mysql_cluster_instances\` lists all configured instances with their current member state and role.
 - **Topology**: \`mysql_cluster_topology\` returns a structured \`topology\` object (with \`primary\`, \`secondaries\`, \`recovering\`, \`offline\` arrays) and a \`visualization\` string grouping members by role.
-- **Router status**: \`mysql_cluster_router_status\` lists registered routers from cluster metadata. Use \`summary: true\` to return only essential router info without full configuration blobs.
-- **Switchover analysis**: \`mysql_cluster_switchover\` evaluates replication lag on secondaries and provides target recommendations. Returns \`canSwitchover: false\` with a \`warning\` field if no viable candidates exist.
+- **Router status**: \`mysql_cluster_router_status\` lists registered routers from cluster metadata. Use \`summary: true\` to return routerId, routerName, address, version, lastCheckIn, roPort, rwPort, and localCluster. Each router includes \`isStale\` (true if lastCheckIn is null or >1 hour old). The response includes \`staleCount\` for quick filtering.
+- **Switchover analysis**: \`mysql_cluster_switchover\` evaluates replication lag on secondaries and rates each as GOOD (fully synced), ACCEPTABLE (<100 pending), or NOT_RECOMMENDED (>=100 pending). Returns \`canSwitchover: false\` with a \`warning\` field if no viable candidates exist.
 
 ## MySQL Router Tools (\`mysql_router_*\`)
 
@@ -124,7 +125,7 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 - **Self-signed certificates**: Set \`MYSQL_ROUTER_INSECURE=true\` to bypass TLS certificate verification for development/testing environments.
 - **Route names**: Use \`mysql_router_routes\` to list available routes (e.g., \`bootstrap_rw\`, \`bootstrap_ro\`).
 - **Metadata cache**: The \`metadataName\` parameter is typically \`bootstrap\` for bootstrapped routers.
-- **Connection pools**: Pool name is typically \`main\` for standard Router configurations.
+- **Connection pools**: \`mysql_router_pool_status\` requires the \`[rest_connection_pool]\` REST plugin AND \`connection_sharing=1\` on routes. Without these, the endpoint returns 404. When enabled, pool name is \`main\`.
 - **Unavailability handling**: When Router REST API is unreachable, tools return \`{ available: false, reason: "..." }\` with descriptive error message instead of throwing.
 
 ## Partitioning Tools (\`mysql_partition_*\`, \`mysql_add_partition\`, \`mysql_drop_partition\`, \`mysql_reorganize_partition\`)
@@ -167,7 +168,7 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 
 - **EXPLAIN formats**: \`mysql_explain\` supports JSON (default), TREE, and TRADITIONAL formats.
 - **EXPLAIN ANALYZE**: \`mysql_explain_analyze\` shows actual execution times (MySQL 8.0+). Only TREE format is supported; JSON format returns \`{ supported: false, reason }\`.
-- **Performance schema**: \`mysql_slow_queries\`, \`mysql_query_stats\`, and \`mysql_index_usage\` require \`performance_schema\` enabled. \`mysql_slow_queries\` and \`mysql_query_stats\` truncate query digests to 200 characters for payload efficiency.
+- **Performance schema**: \`mysql_slow_queries\`, \`mysql_query_stats\`, and \`mysql_index_usage\` require \`performance_schema\` enabled. \`mysql_slow_queries\` and \`mysql_query_stats\` truncate query digests to 200 characters for payload efficiency. Timer values exceeding 24 hours are clamped to \`-1\` with \`overflow: true\` on the row (indicates a \`performance_schema\` counter overflow artifact, not a real value).
 - **Index usage**: \`mysql_index_usage\` filters to the current database by default. Use \`table\` parameter to filter further. Use \`limit\` (default: 10) to cap results. Returns \`{ exists: false, table }\` when the specified table does not exist.
 - **Table stats**: \`mysql_table_stats\` returns \`{ exists: false, table: "..." }\` gracefully when the table does not exist.
 - **Server-level tools**: \`mysql_slow_queries\`, \`mysql_query_stats\`, \`mysql_buffer_pool_stats\`, and \`mysql_thread_stats\` query server-level \`performance_schema\` metadata. They do not take a table parameter and return empty results when no data is available. No table existence checks apply.
@@ -234,8 +235,8 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 - **I/O analysis**: \`mysql_sys_io_summary\` supports \`table\` (default), \`file\`, and \`global\` types for I/O breakdown (default \`limit: 20\`).
 - **Wait events**: \`mysql_sys_wait_summary\` supports \`global\` (default), \`by_host\`, \`by_user\`, and \`by_instance\` types for wait analysis. The \`by_instance\` type queries \`performance_schema\` directly (no sys view exists) and returns \`event\`, \`total\`, \`total_latency\`, and \`avg_latency\` columns with formatted latencies.
 - **Lock contention**: \`mysql_sys_innodb_lock_waits\` shows active lock waits. Returns \`hasContention: false\` when none.
-- **Memory usage**: \`mysql_sys_memory_summary\` returns \`globalMemory\` (by event type) and \`memoryByUser\` arrays. The \`limit\` parameter (default 10) applies to both arrays.
-- **Schema stats**: \`mysql_sys_schema_stats\` returns 3 arrays: \`tableStatistics\` (DML and I/O per table), \`indexStatistics\` (per-index usage), and \`autoIncrementStatus\` (usage ratios). Filter by \`schema\` (defaults to current database). Returns \`{ exists: false, schema }\` when the specified schema does not exist. The \`limit\` parameter (default 10) applies per array.
+- **Memory usage**: \`mysql_sys_memory_summary\` returns \`globalMemory\` (by event type) and \`memoryByUser\` arrays with corresponding \`globalMemoryCount\` and \`memoryByUserCount\` fields. The \`limit\` parameter (default 10) applies to both arrays.
+- **Schema stats**: \`mysql_sys_schema_stats\` returns 3 arrays: \`tableStatistics\` (DML and I/O per table), \`indexStatistics\` (per-index usage), and \`autoIncrementStatus\` (usage ratios), each with a corresponding count field (\`tableStatisticsCount\`, \`indexStatisticsCount\`, \`autoIncrementStatusCount\`). Filter by \`schema\` (defaults to current database). Returns \`{ exists: false, schema }\` when the specified schema does not exist. The \`limit\` parameter (default 10) applies per array.
 
 ## Stats Tools (\`mysql_stats_*\`)
 
@@ -254,7 +255,7 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 - **SSL status**: \`mysql_security_ssl_status\` returns SSL/TLS connection status, cipher, certificate paths, and session statistics.
 - **Encryption status**: \`mysql_security_encryption_status\` checks TDE availability, keyring plugins, encrypted tablespaces, and encryption settings.
 - **Password validation**: \`mysql_security_password_validate\` uses MySQL \`validate_password\` component to check password strength (0-100 scale). Returns \`available: false\` if component not installed.
-- **Data masking**: \`mysql_security_mask_data\` masks sensitive data. Types: \`email\` (preserves domain), \`phone\` (shows last 4), \`ssn\` (shows last 4), \`credit_card\` (shows first/last 4), \`partial\` (uses \`keepFirst\`/\`keepLast\`). Credit card masking requires at least 8 digits; shorter values are fully masked with a \`warning\` field.
+- **Data masking**: \`mysql_security_mask_data\` masks sensitive data. Types: \`email\` (preserves domain), \`phone\` (shows last 4), \`ssn\` (shows last 4), \`credit_card\` (shows first/last 4), \`partial\` (uses \`keepFirst\`/\`keepLast\`). Credit card masking requires more than 8 digits; values with 8 or fewer digits are fully masked with a \`warning\` field.
 - **User privileges**: \`mysql_security_user_privileges\` returns comprehensive user privilege report. Filter with \`user\` parameter to reduce payload. Returns \`{ exists: false, user }\` for nonexistent users (P154). Use \`summary: true\` for condensed output (privilege counts instead of raw GRANT strings). Summary mode caps \`globalPrivileges\` at 10 entries and includes \`totalGlobalPrivileges\` for the full count.
 - **Sensitive tables**: \`mysql_security_sensitive_tables\` identifies columns matching sensitive patterns (password, email, ssn, etc.). Use \`schema\` parameter to limit scope. Returns \`{ exists: false, schema }\` for nonexistent schemas (P154).
 - **Enterprise features**: \`mysql_security_audit\`, \`mysql_security_firewall_status\`, \`mysql_security_firewall_rules\` report availability and suggest installation for MySQL Enterprise Edition.
@@ -275,15 +276,38 @@ const BASE_INSTRUCTIONS = `# mysql-mcp Usage Instructions
 
 - **Prerequisites**: MySQL Shell must be installed and accessible via \`MYSQLSH_PATH\` environment variable or system PATH.
 - **Version check**: \`mysqlsh_version\` verifies MySQL Shell availability before running other shell tools.
-- **Upgrade checking**: \`mysqlsh_check_upgrade\` analyzes MySQL server for upgrade compatibility issues. Returns \`errorCount\`, \`warningCount\`, and \`noticeCount\` summary with full JSON report. **Note**: Returns \`{ success: false, error }\` when \`targetVersion\` is lower than the current server version (no downgrade analysis is possible).
+- **Upgrade checking**: \`mysqlsh_check_upgrade\` analyzes MySQL server for upgrade compatibility issues. Returns \`errorCount\`, \`warningCount\`, and \`noticeCount\` summary with full JSON report. **Note**: Returns \`{ success: false, error }\` when MySQL Shell's version is lower than the current server version—Shell cannot analyze a server newer than itself. Also fails when \`targetVersion\` is lower than the current server version (no downgrade analysis).
 - **Script execution**: \`mysqlsh_run_script\` supports JavaScript (\`js\`), Python (\`py\`), and SQL (\`sql\`) languages with full access to MySQL Shell APIs. SQL scripts support comments and multi-statement syntax.
 - **Table export**: \`mysqlsh_export_table\` uses \`util.exportTable()\` for CSV or TSV export. Use \`where\` parameter for filtered exports. Returns structured error for privilege issues.
 - **Parallel import**: \`mysqlsh_import_table\` uses \`util.importTable()\` for high-performance parallel import. **Important**: For CSV files, explicitly set \`fieldsTerminatedBy: ","\` as the delimiter is not auto-detected. Requires \`local_infile\` enabled on server (use \`updateServerSettings: true\` to auto-enable). Use \`skipRows: 1\` to skip header row. The \`columns\` parameter maps input fields **by position** to the specified table columns. **Note**: On InnoDB Cluster (Group Replication), target tables must have a PRIMARY KEY.
 - **JSON import**: \`mysqlsh_import_json\` uses \`util.importJson()\` for document import. Supports both NDJSON (one JSON object per line) and multi-line JSON objects. **Does NOT support JSON arrays.** **Requires X Protocol (port 33060)**.
 - **Dump utilities**: \`mysqlsh_dump_instance\`, \`mysqlsh_dump_schemas\`, \`mysqlsh_dump_tables\` create compressed parallel dumps. Use \`dryRun: true\` to preview. All dump tools return structured error messages for privilege issues with actionable guidance.
-- **Load utility**: \`mysqlsh_load_dump\` restores dumps. Requires \`local_infile\` enabled or \`updateServerSettings: true\`. Returns \`{ success: false, error, hint }\` for duplicate object conflicts.
+- **Load utility**: \`mysqlsh_load_dump\` restores dumps. Requires \`local_infile\` enabled or \`updateServerSettings: true\`. Use \`dryRun: true\` to preview what would be loaded without applying changes. Returns \`{ success: false, error, hint }\` for duplicate object conflicts.
 - **Privilege note**: Dump operations may require EVENT, TRIGGER, or ROUTINE privileges. Use \`ddlOnly: true\` (schemas) or \`all: false\` (tables) to skip restricted metadata.
 - **Error handling**: All shell tools return \`{ success: false, error }\` for operational failures instead of throwing raw exceptions. Privilege, local_infile, and X Protocol errors include a \`hint\` field with actionable remediation guidance.
+
+## Parameter Aliases
+
+Many tools accept **alternative parameter names** (aliases) for commonly used fields. The server normalizes these automatically—use whichever feels most natural:
+
+- **Table name**: \`table\`, \`tableName\`, or \`name\` — accepted by Core tools (\`mysql_describe_table\`, \`mysql_get_indexes\`, \`mysql_drop_table\`, \`mysql_create_index\`), Text tools (\`mysql_like_search\`, \`mysql_regexp_match\`, \`mysql_soundex\`, \`mysql_substring\`, \`mysql_concat\`, \`mysql_collation_convert\`), Backup tools (\`mysql_export_table\`, \`mysql_import_data\`), Partitioning tools (\`mysql_partition_info\`, \`mysql_add_partition\`, \`mysql_drop_partition\`, \`mysql_reorganize_partition\`), Performance tools (\`mysql_table_stats\`, \`mysql_index_usage\`), and Admin tools (\`mysql_optimize_table\`, \`mysql_analyze_table\`, \`mysql_check_table\`, \`mysql_flush_tables\`).
+- **Query/SQL**: \`query\` or \`sql\` — accepted by \`mysql_read_query\`, \`mysql_write_query\`, \`mysql_explain\`, \`mysql_explain_analyze\`, \`mysql_query_rewrite\`, and \`mysql_optimizer_trace\`.
+- **WHERE clause**: \`where\` or \`filter\` — accepted by \`mysql_export_table\` and Text tools (\`mysql_like_search\`, \`mysql_regexp_match\`, \`mysql_soundex\`, \`mysql_substring\`, \`mysql_concat\`, \`mysql_collation_convert\`).
+- **Column name**: \`column\` or \`col\` — accepted by Text tools (\`mysql_like_search\`, \`mysql_regexp_match\`, \`mysql_soundex\`, \`mysql_substring\`, \`mysql_collation_convert\`).
+- **Admin tables array**: Admin maintenance tools accept a singular \`table\` (or \`tableName\`/\`name\`) as an alias for the \`tables\` array parameter, automatically wrapping it in an array.
+
+## Code Mode (\`mysql_execute_code\`)
+
+- **Purpose**: Execute JavaScript/TypeScript code in a sandboxed VM with access to all MySQL tools via the \`mysql.*\` API namespace. Ideal for multi-step workflows, data aggregation, conditional logic, and complex orchestrations that would otherwise require many sequential tool calls.
+- **When to use**: Prefer Code Mode when a task requires 3+ sequential tool calls, conditional branching based on query results, data transformation between steps, or aggregation across multiple tables.
+- **API namespace**: The \`mysql\` object exposes 24 groups matching the tool groups: \`mysql.core\`, \`mysql.json\`, \`mysql.transactions\`, \`mysql.text\`, \`mysql.fulltext\`, \`mysql.performance\`, \`mysql.optimization\`, \`mysql.admin\`, \`mysql.monitoring\`, \`mysql.backup\`, \`mysql.replication\`, \`mysql.partitioning\`, \`mysql.schema\`, \`mysql.shell\`, \`mysql.events\`, \`mysql.sysschema\`, \`mysql.stats\`, \`mysql.spatial\`, \`mysql.security\`, \`mysql.roles\`, \`mysql.docstore\`, \`mysql.cluster\`, \`mysql.proxysql\`, \`mysql.router\`.
+- **Method naming**: Tool names map to methods by stripping the prefix: \`mysql_read_query\` → \`mysql.core.readQuery(sql)\`, \`mysql_json_extract\` → \`mysql.json.extract({...})\`, \`mysqlsh_version\` → \`mysql.shell.version()\`.
+- **Positional shorthand**: Common tools accept positional arguments: \`mysql.core.readQuery("SELECT 1")\` instead of \`mysql.core.readQuery({ query: "SELECT 1" })\`.
+- **Help**: Call \`mysql.help()\` for a full API overview, or \`mysql.<group>.help()\` for group-specific methods and examples.
+- **Return value**: The last expression in the code block is returned as the result. Use \`return\` in async functions or let the final expression evaluate.
+- **Security**: Code runs in an isolated VM sandbox. Blocked patterns include \`require\`, \`import\`, \`process\`, \`eval\`, \`Function\`, filesystem/network access. Rate-limited to prevent abuse.
+- **Transaction cleanup**: Any transactions opened but not committed are automatically rolled back when execution completes.
+- **Scope**: Requires \`admin\` scope.
 `;
 
 /**

package/src/filtering/ToolConstants.ts

@@ -253,6 +253,7 @@ export const TOOL_GROUPS: Record<ToolGroup, string[]> = {
     "mysql_doc_create_index",
     "mysql_doc_collection_info",
   ],
+  codemode: ["mysql_execute_code"],
 };
 
 /**
@@ -262,22 +263,22 @@ export const TOOL_GROUPS: Record<ToolGroup, string[]> = {
  * STRICT LIMIT: NO group may exceed 50 tools.
  *
  * Tool counts (verified):
- *   starter:       38
- *   essential:     15
- *   dev-power:     46 (core:8 + schema:10 + performance:8 + stats:8 + fulltext:5 + transactions:7)
- *   ai-data:       45 (core:8 + json:17 + docstore:9 + text:6 + fulltext:5)
- *   ai-spatial:    43 (core:8 + spatial:12 + stats:8 + performance:8 + transactions:7)
- *   dba-monitor:   35 (core:8 + monitoring:7 + performance:8 + sysschema:8 + optimization:4)
- *   dba-manage:    33 (core:8 + admin:6 + backup:4 + replication:5 + partitioning:4 + events:6)
- *   dba-secure:    32 (core:8 + security:9 + roles:8 + transactions:7)
- *   base-core:     48 (core:8 + json:17 + transactions:7 + text:6 + schema:10)
- *   base-advanced: 40 (docstore:9 + spatial:12 + stats:8 + fulltext:5 + events:6)
- *   ecosystem:     41 (router:9 + proxysql:12 + shell:10 + cluster:10)
+ *   starter:       39 (core:8 + json:17 + transactions:7 + text:6 + codemode:1)
+ *   essential:     16 (core:8 + transactions:7 + codemode:1)
+ *   dev-power:     47 (core:8 + schema:10 + performance:8 + stats:8 + fulltext:5 + transactions:7 + codemode:1)
+ *   ai-data:       46 (core:8 + json:17 + docstore:9 + text:6 + fulltext:5 + codemode:1)
+ *   ai-spatial:    44 (core:8 + spatial:12 + stats:8 + performance:8 + transactions:7 + codemode:1)
+ *   dba-monitor:   36 (core:8 + monitoring:7 + performance:8 + sysschema:8 + optimization:4 + codemode:1)
+ *   dba-manage:    34 (core:8 + admin:6 + backup:4 + replication:5 + partitioning:4 + events:6 + codemode:1)
+ *   dba-secure:    33 (core:8 + security:9 + roles:8 + transactions:7 + codemode:1)
+ *   base-core:     49 (core:8 + json:17 + transactions:7 + text:6 + schema:10 + codemode:1)
+ *   base-advanced: 41 (docstore:9 + spatial:12 + stats:8 + fulltext:5 + events:6 + codemode:1)
+ *   ecosystem:     42 (router:9 + proxysql:12 + shell:10 + cluster:10 + codemode:1)
  */
 export const META_GROUPS: Record<MetaGroup, ToolGroup[]> = {
   // 1. General Use
-  starter: ["core", "json", "transactions", "text"],
-  essential: ["core", "transactions"],
+  starter: ["core", "json", "transactions", "text", "codemode"],
+  essential: ["core", "transactions", "codemode"],
   "dev-power": [
     "core",
     "schema",
@@ -285,11 +286,19 @@ export const META_GROUPS: Record<MetaGroup, ToolGroup[]> = {
     "stats",
     "fulltext",
     "transactions",
+    "codemode",
   ],
 
   // 2. AI Workloads
-  "ai-data": ["core", "json", "docstore", "text", "fulltext"],
-  "ai-spatial": ["core", "spatial", "stats", "performance", "transactions"],
+  "ai-data": ["core", "json", "docstore", "text", "fulltext", "codemode"],
+  "ai-spatial": [
+    "core",
+    "spatial",
+    "stats",
+    "performance",
+    "transactions",
+    "codemode",
+  ],
 
   // 3. DBA Workloads
   "dba-monitor": [
@@ -298,6 +307,7 @@ export const META_GROUPS: Record<MetaGroup, ToolGroup[]> = {
     "performance",
     "sysschema",
     "optimization",
+    "codemode",
   ],
   "dba-manage": [
     "core",
@@ -306,13 +316,21 @@ export const META_GROUPS: Record<MetaGroup, ToolGroup[]> = {
     "replication",
     "partitioning",
     "events",
+    "codemode",
   ],
-  "dba-secure": ["core", "security", "roles", "transactions"],
+  "dba-secure": ["core", "security", "roles", "transactions", "codemode"],
 
   // 4. Base Blocks (Building Blocks)
-  "base-core": ["core", "json", "transactions", "text", "schema"],
-  "base-advanced": ["docstore", "spatial", "stats", "fulltext", "events"],
+  "base-core": ["core", "json", "transactions", "text", "schema", "codemode"],
+  "base-advanced": [
+    "docstore",
+    "spatial",
+    "stats",
+    "fulltext",
+    "events",
+    "codemode",
+  ],
 
   // 5. Ecosystem
-  ecosystem: ["router", "proxysql", "shell", "cluster"],
+  ecosystem: ["router", "proxysql", "shell", "cluster", "codemode"],
 };

package/src/filtering/ToolFilter.ts

@@ -230,6 +230,21 @@ export function parseToolFilter(
     }
   }
 
+  // Auto-inject codemode tools (mysql_execute_code) in whitelist mode only.
+  // In blacklist mode (starts with -), codemode is already in the initial set
+  // and user exclusions are respected. In whitelist mode, raw group filters
+  // (e.g., "core") would otherwise miss codemode — every meta-group includes it.
+  if (!startsWithExclude && enabledTools.size > 0) {
+    const codemodeExplicitlyExcluded = parts.some(
+      (p) => p === "-codemode" || p === "-mysql_execute_code",
+    );
+    if (!codemodeExplicitlyExcluded) {
+      for (const tool of TOOL_GROUPS.codemode) {
+        enabledTools.add(tool);
+      }
+    }
+  }
+
   return {
     raw: filterString,
     rules,

package/src/filtering/__tests__/ToolFilter.test.ts

@@ -23,7 +23,7 @@ import {
 import type { ToolDefinition } from "../../types/index.js";
 
 describe("TOOL_GROUPS", () => {
-  it("should contain all 24 tool groups", () => {
+  it("should contain all 25 tool groups", () => {
     const expectedGroups = [
       "core",
       "json",
@@ -49,9 +49,10 @@ describe("TOOL_GROUPS", () => {
       "cluster",
       "roles",
       "docstore",
+      "codemode",
     ];
 
-    expect(Object.keys(TOOL_GROUPS)).toHaveLength(24);
+    expect(Object.keys(TOOL_GROUPS)).toHaveLength(25);
     for (const group of expectedGroups) {
       expect(TOOL_GROUPS).toHaveProperty(group);
     }
@@ -82,11 +83,12 @@ describe("TOOL_GROUPS", () => {
     expect(TOOL_GROUPS.cluster).toHaveLength(10);
     expect(TOOL_GROUPS.roles).toHaveLength(8);
     expect(TOOL_GROUPS.docstore).toHaveLength(9);
+    expect(TOOL_GROUPS.codemode).toHaveLength(1);
   });
 
-  it("should total 192 tools across all groups", () => {
+  it("should total 193 tools across all groups", () => {
     const totalTools = Object.values(TOOL_GROUPS).flat().length;
-    expect(totalTools).toBe(192);
+    expect(totalTools).toBe(193);
   });
 });
 
@@ -128,9 +130,9 @@ describe("META_GROUPS", () => {
 });
 
 describe("getAllToolNames", () => {
-  it("should return all 192 tool names", () => {
+  it("should return all 193 tool names", () => {
     const tools = getAllToolNames();
-    expect(tools).toHaveLength(192);
+    expect(tools).toHaveLength(193);
   });
 
   it("should return unique tool names", () => {
@@ -168,81 +170,81 @@ describe("getToolGroup", () => {
 describe("getMetaGroupTools", () => {
   it("should return all tools for starter meta-group", () => {
     const tools = getMetaGroupTools("starter");
-    // starter = core(8) + json(17) + transactions(7) + text(6) = 38
-    expect(tools).toHaveLength(38);
+    // starter = core(8) + json(17) + transactions(7) + text(6) + codemode(1) = 39
+    expect(tools).toHaveLength(39);
   });
 
   it("should return all tools for essential meta-group", () => {
     const tools = getMetaGroupTools("essential");
-    // essential = core(8) + transactions(7) = 15
-    expect(tools).toHaveLength(15);
+    // essential = core(8) + transactions(7) + codemode(1) = 16
+    expect(tools).toHaveLength(16);
   });
 
   it("should return all tools for ecosystem meta-group", () => {
     const tools = getMetaGroupTools("ecosystem");
-    // ecosystem = router(9) + proxysql(12) + shell(10) + cluster(10) = 41
-    expect(tools).toHaveLength(41);
+    // ecosystem = router(9) + proxysql(12) + shell(10) + cluster(10) + codemode(1) = 42
+    expect(tools).toHaveLength(42);
   });
 
   it("should return correct tools for base-core meta-group", () => {
     const tools = getMetaGroupTools("base-core");
-    // base-core = core(8) + json(17) + transactions(7) + text(6) + schema(10) = 48
-    expect(tools).toHaveLength(48);
+    // base-core = core(8) + json(17) + transactions(7) + text(6) + schema(10) + codemode(1) = 49
+    expect(tools).toHaveLength(49);
   });
 
   it("should return correct tools for base-advanced meta-group", () => {
     const tools = getMetaGroupTools("base-advanced");
-    // base-advanced = docstore(9) + spatial(12) + stats(8) + fulltext(5) + events(6) = 40
-    expect(tools).toHaveLength(40);
+    // base-advanced = docstore(9) + spatial(12) + stats(8) + fulltext(5) + events(6) + codemode(1) = 41
+    expect(tools).toHaveLength(41);
   });
 
   it("should return correct tools for dba-monitor meta-group", () => {
     const tools = getMetaGroupTools("dba-monitor");
-    expect(tools).toHaveLength(35);
+    expect(tools).toHaveLength(36);
   });
 
   it("should return correct tools for dba-manage meta-group", () => {
     const tools = getMetaGroupTools("dba-manage");
-    expect(tools).toHaveLength(33);
+    expect(tools).toHaveLength(34);
   });
 
   it("should return correct tools for dba-secure meta-group", () => {
     const tools = getMetaGroupTools("dba-secure");
-    expect(tools).toHaveLength(32);
+    expect(tools).toHaveLength(33);
   });
 });
 
 describe("parseToolFilter", () => {
-  it("should return starter tools (38) enabled for empty filter", () => {
+  it("should return starter tools (39) enabled for empty filter", () => {
     const config = parseToolFilter("");
-    expect(config.enabledTools.size).toBe(38);
+    expect(config.enabledTools.size).toBe(39);
     expect(config.rules).toHaveLength(0);
     expect(config.enabledTools.has("mysql_read_query")).toBe(true);
   });
 
-  it("should return starter tools (38) enabled for undefined filter", () => {
+  it("should return starter tools (39) enabled for undefined filter", () => {
     const config = parseToolFilter(undefined);
-    expect(config.enabledTools.size).toBe(38);
+    expect(config.enabledTools.size).toBe(39);
     expect(config.rules).toHaveLength(0);
   });
 
   it("should disable a single tool", () => {
     const config = parseToolFilter("-mysql_read_query");
-    expect(config.enabledTools.size).toBe(191);
+    expect(config.enabledTools.size).toBe(192);
     expect(config.enabledTools.has("mysql_read_query")).toBe(false);
     expect(config.enabledTools.has("mysql_write_query")).toBe(true);
   });
 
   it("should disable a tool group", () => {
     const config = parseToolFilter("-core");
-    expect(config.enabledTools.size).toBe(184); // 192 - 8
+    expect(config.enabledTools.size).toBe(185); // 193 - 8
     expect(config.enabledTools.has("mysql_read_query")).toBe(false);
     expect(config.enabledTools.has("mysql_json_extract")).toBe(true);
   });
 
   it("should disable a meta-group", () => {
     const config = parseToolFilter("-ecosystem");
-    expect(config.enabledTools.size).toBe(151); // 192 - 41
+    expect(config.enabledTools.size).toBe(151); // 193 - 42
     expect(config.enabledTools.has("mysql_router_status")).toBe(false);
     expect(config.enabledTools.has("proxysql_status")).toBe(false);
     expect(config.enabledTools.has("mysqlsh_version")).toBe(false);
@@ -258,18 +260,18 @@ describe("parseToolFilter", () => {
   it("should handle complex filter chains", () => {
     // Disable all, then enable starter
     const config = parseToolFilter("starter");
-    expect(config.enabledTools.size).toBe(38); // starter has 38 tools
+    expect(config.enabledTools.size).toBe(39); // starter has 39 tools
   });
 
   it("should handle explicit whitelist syntax (+group)", () => {
     const config = parseToolFilter("+starter");
-    expect(config.enabledTools.size).toBe(38);
+    expect(config.enabledTools.size).toBe(39);
   });
 
   it("should handle whitelist with exclusion (starter,-json)", () => {
-    // starter(38) - json(17) = 21
+    // starter(39) - json(17) = 22
     const config = parseToolFilter("starter,-json");
-    expect(config.enabledTools.size).toBe(21);
+    expect(config.enabledTools.size).toBe(22);
   });
 
   it("should process rules left-to-right", () => {
@@ -278,7 +280,7 @@ describe("parseToolFilter", () => {
     const config1 = parseToolFilter("+core,-mysql_read_query");
     expect(config1.enabledTools.has("mysql_read_query")).toBe(false);
     expect(config1.enabledTools.has("mysql_write_query")).toBe(true);
-    expect(config1.enabledTools.size).toBe(7); // core(8) - 1 = 7
+    expect(config1.enabledTools.size).toBe(8); // core(8) - 1 + codemode(1) = 8
   });
 
   it("should handle whitespace in filter string", () => {
@@ -286,6 +288,31 @@ describe("parseToolFilter", () => {
     expect(config.enabledTools.has("mysql_read_query")).toBe(true);
     expect(config.enabledTools.has("mysql_write_query")).toBe(false);
   });
+
+  // Codemode auto-injection tests
+  it("should auto-inject codemode when using a raw group filter", () => {
+    const config = parseToolFilter("core");
+    expect(config.enabledTools.has("mysql_execute_code")).toBe(true);
+    expect(config.enabledTools.size).toBe(9); // core(8) + codemode(1)
+  });
+
+  it("should not inject codemode when explicitly excluded with -codemode", () => {
+    const config = parseToolFilter("core,-codemode");
+    expect(config.enabledTools.has("mysql_execute_code")).toBe(false);
+    expect(config.enabledTools.size).toBe(8); // core(8) only
+  });
+
+  it("should not inject codemode when mysql_execute_code explicitly excluded", () => {
+    const config = parseToolFilter("core,-mysql_execute_code");
+    expect(config.enabledTools.has("mysql_execute_code")).toBe(false);
+    expect(config.enabledTools.size).toBe(8); // core(8) only
+  });
+
+  it("should not inject codemode when all tools are excluded", () => {
+    const config = parseToolFilter("-all");
+    expect(config.enabledTools.size).toBe(0);
+    expect(config.enabledTools.has("mysql_execute_code")).toBe(false);
+  });
 });
 
 describe("isToolEnabled", () => {
@@ -355,14 +382,14 @@ describe("filterTools", () => {
 
 describe("calculateTokenSavings", () => {
   it("should calculate correct savings", () => {
-    const result = calculateTokenSavings(191, 38);
-    // (191 - 38) * 200 = 30600 tokens
+    const result = calculateTokenSavings(192, 39);
+    // (192 - 39) * 200 = 30600 tokens
     expect(result.tokensSaved).toBe(30600);
     expect(result.percentSaved).toBe(80); // ~80% disabled
   });
 
   it("should return 0 for no filtering", () => {
-    const result = calculateTokenSavings(191, 191);
+    const result = calculateTokenSavings(192, 192);
     expect(result.tokensSaved).toBe(0);
     expect(result.percentSaved).toBe(0);
   });
@@ -384,7 +411,7 @@ describe("getFilterSummary", () => {
   it("should generate summary for no filter", () => {
     const config = parseToolFilter("");
     const summary = getFilterSummary(config);
-    expect(summary).toContain("38/192 tools");
+    expect(summary).toContain("39/193 tools");
     expect(summary).toContain("Token savings");
   });
 
@@ -416,9 +443,9 @@ describe("getFilterSummary", () => {
 });
 
 describe("getToolGroupInfo", () => {
-  it("should return info for all 24 groups", () => {
+  it("should return info for all 25 groups", () => {
     const info = getToolGroupInfo();
-    expect(info).toHaveLength(24);
+    expect(info).toHaveLength(25);
   });
 
   it("should include correct counts", () => {
@@ -440,7 +467,7 @@ describe("getMetaGroupInfo", () => {
     const info = getMetaGroupInfo();
     const starterInfo = info.find((g) => g.metaGroup === "starter");
     expect(starterInfo).toBeDefined();
-    expect(starterInfo?.count).toBe(38);
+    expect(starterInfo?.count).toBe(39);
     expect(starterInfo?.groups).toContain("core");
   });
 });

package/src/server/McpServer.ts

@@ -182,7 +182,7 @@ export class McpServer {
         const transport = createHttpTransport(
           {
             port,
-            host: "localhost", // Default to localhost, could be configurable
+            host: this.config.host ?? "localhost",
             corsOrigins: ["*"], // Allow all for now, or make configurable
             // Pass OAuth config if enabled
             ...(this.config.oauth?.enabled

package/src/types/modules/server.ts

@@ -28,6 +28,9 @@ export interface McpServerConfig {
   /** HTTP port (for http/sse transports) */
   port?: number;
 
+  /** Host to bind HTTP transport to (default: localhost) */
+  host?: string;
+
   /** Database configurations */
   databases: DatabaseConfig[];