@neverinfamous/mysql-mcp 2.2.0 → 2.3.0

package/src/codemode/api.ts

@@ -0,0 +1,1224 @@
+/**
+ * mysql-mcp - Code Mode API
+ *
+ * Exposes all MySQL tools organized by their 24 groups
+ * for use within the sandboxed execution environment.
+ */
+
+import type { MySQLAdapter } from "../adapters/mysql/MySQLAdapter.js";
+import type { ToolDefinition } from "../types/index.js";
+
+/**
+ * Method aliases for code mode API.
+ * Maps alternate method names to their canonical method names.
+ * Format: { groupName: { aliasName: canonicalName } }
+ *
+ * These aliases handle common naming misguesses where agents
+ * might try the redundant prefix pattern (e.g., jsonExtract vs extract).
+ */
+const METHOD_ALIASES: Record<string, Record<string, string>> = {
+  // JSON: mysql_json_extract → extract, but agent might try jsonExtract
+  json: {
+    jsonExtract: "extract",
+    jsonSet: "set",
+    jsonInsert: "insert",
+    jsonRemove: "remove",
+    jsonContains: "contains",
+    jsonKeys: "keys",
+    jsonReplace: "replace",
+    jsonGet: "get",
+    jsonSearch: "search",
+    jsonUpdate: "update",
+    jsonValidate: "validate",
+    jsonMerge: "merge",
+    jsonNormalize: "normalize",
+    jsonDiff: "diff",
+    jsonIndexSuggest: "indexSuggest",
+    jsonStats: "stats",
+    jsonArrayAppend: "arrayAppend",
+  },
+  // Text: mysql_regexp_match → regexpMatch, but also regex
+  text: {
+    regex: "regexpMatch",
+    regexp: "regexpMatch",
+    like: "likeSearch",
+    pattern: "likeSearch",
+    sound: "soundex",
+    substr: "substring",
+    concatenate: "concat",
+    collation: "collationConvert",
+  },
+  // Fulltext: intuitive aliases
+  fulltext: {
+    create: "fulltextCreate",
+    drop: "fulltextDrop",
+    search: "fulltextSearch",
+    boolean: "fulltextBoolean",
+    expand: "fulltextExpand",
+    createIndex: "fulltextCreate",
+    dropIndex: "fulltextDrop",
+    naturalLanguage: "fulltextSearch",
+    booleanMode: "fulltextBoolean",
+    queryExpansion: "fulltextExpand",
+  },
+  // Transactions: shorter aliases
+  transactions: {
+    begin: "transactionBegin",
+    commit: "transactionCommit",
+    rollback: "transactionRollback",
+    savepoint: "transactionSavepoint",
+    release: "transactionRelease",
+    rollbackTo: "transactionRollbackTo",
+    execute: "transactionExecute",
+  },
+  // Performance: intuitive aliases
+  performance: {
+    queryPlan: "explain",
+    analyze: "explainAnalyze",
+    slowLog: "slowQueries",
+    slow: "slowQueries",
+    trace: "optimizerTrace",
+    bufferPool: "bufferPoolStats",
+    innodb: "innodbStatus",
+    stats: "tableStats",
+    threads: "threadStats",
+    health: "serverHealth",
+    processes: "showProcesslist",
+    processlist: "showProcesslist",
+  },
+  // Optimization: shorter aliases
+  optimization: {
+    recommend: "indexRecommendation",
+    indexAdvice: "indexRecommendation",
+    hint: "forceIndex",
+    forceHint: "forceIndex",
+    rewrite: "queryRewrite",
+  },
+  // Admin: intuitive aliases
+  admin: {
+    check: "checkTable",
+    repair: "repairTable",
+    optimize: "optimizeTable",
+    analyze: "analyzeTable",
+    flush: "flushTables",
+    kill: "killQuery",
+    pool: "poolStats",
+  },
+  // Monitoring: intuitive aliases
+  monitoring: {
+    status: "showStatus",
+    variables: "showVariables",
+    processes: "showProcesslist",
+    processlist: "showProcesslist",
+    queries: "queryStats",
+    slowlog: "slowQueries",
+  },
+  // Backup: shorter aliases
+  backup: {
+    dump: "createDump",
+    export: "exportTable",
+    import: "importData",
+    restore: "restoreDump",
+  },
+  // Replication: intuitive aliases
+  replication: {
+    status: "slaveStatus",
+    master: "masterStatus",
+    slave: "slaveStatus",
+    binlog: "binlogEvents",
+    gtid: "gtidStatus",
+  },
+  // Partitioning: shorter aliases
+  partitioning: {
+    add: "addPartition",
+    drop: "dropPartition",
+    reorganize: "reorganizePartition",
+    info: "partitionInfo",
+    list: "partitionInfo", // list() → partitionInfo()
+  },
+  // Schema: intuitive aliases
+  schema: {
+    views: "listViews",
+    functions: "listFunctions",
+    procedures: "listStoredProcedures",
+    triggers: "listTriggers",
+    constraints: "listConstraints",
+    schemas: "listSchemas",
+    createDb: "createSchema",
+    dropDb: "dropSchema",
+  },
+  // Events: shorter aliases
+  events: {
+    create: "eventCreate",
+    drop: "eventDrop",
+    alter: "eventAlter",
+    list: "eventList",
+    status: "eventStatus",
+    scheduler: "schedulerStatus",
+  },
+  // Stats: intuitive aliases
+  stats: {
+    summary: "descriptive",
+    percentile: "percentiles",
+    movingAverage: "timeSeries",
+    time_series: "timeSeries",
+  },
+  // Spatial: intuitive aliases
+  spatial: {
+    addColumn: "createColumn",
+    addIndex: "createIndex",
+    dist: "distance",
+    distSphere: "distanceSphere",
+
+    pointInPolygon: "contains",
+  },
+  // Security: intuitive aliases
+  security: {
+    ssl: "sslStatus",
+    encryption: "encryptionStatus",
+    firewall: "firewallStatus",
+    privileges: "userPrivileges",
+    password: "passwordValidate",
+    mask: "maskData",
+    sensitive: "sensitiveTables",
+  },
+  // Cluster: intuitive aliases
+  cluster: {
+    status: "clusterStatus",
+    instances: "clusterInstances",
+    topology: "clusterTopology",
+    switchover: "clusterSwitchover",
+    routerStatus: "clusterRouterStatus",
+    grStatus: "grStatus",
+    grMembers: "grMembers",
+    grPrimary: "grPrimary",
+    grFlowControl: "grFlowControl",
+    grTransactions: "grTransactions",
+  },
+  // Roles: shorter aliases
+  roles: {
+    create: "roleCreate",
+    drop: "roleDrop",
+    list: "roleList",
+    assign: "roleAssign",
+    grant: "roleGrant",
+    revoke: "roleRevoke",
+    grants: "roleGrants",
+    userRoles: "userRoles",
+  },
+  // DocStore: shorter aliases
+  docstore: {
+    add: "docAdd",
+    find: "docFind",
+    modify: "docModify",
+    remove: "docRemove",
+    createCollection: "docCreateCollection",
+    dropCollection: "docDropCollection",
+    listCollections: "docListCollections",
+    collectionInfo: "docCollectionInfo",
+    createIndex: "docCreateIndex",
+  },
+  // SysSchema: shorter aliases
+  sysschema: {
+    schemaStats: "sysSchemaStats",
+    lockWaits: "sysInnodbLockWaits",
+    memory: "sysMemorySummary",
+    statements: "sysStatementSummary",
+    waits: "sysWaitSummary",
+    io: "sysIoSummary",
+    users: "sysUserSummary",
+    hosts: "sysHostSummary",
+  },
+  // Router: shorter aliases
+  router: {
+    metadata: "metadataStatus",
+    pool: "poolStatus",
+    connections: "routeConnections",
+    destinations: "routeDestinations",
+    blocked: "routeBlockedHosts",
+  },
+  // Shell: shorter aliases
+  shell: {
+    run: "runScript",
+    script: "runScript",
+    upgrade: "checkUpgrade",
+    dump: "dumpInstance",
+    load: "loadDump",
+    export: "exportTable",
+    import: "importTable",
+  },
+};
+
+/**
+ * Usage examples for each group's help() output.
+ * Provides quick-reference examples for common operations.
+ */
+const GROUP_EXAMPLES: Record<string, string[]> = {
+  core: [
+    'mysql.core.readQuery("SELECT * FROM users LIMIT 10")',
+    'mysql.core.describeTable("users")',
+    'mysql.core.createTable("orders", { columns: [{ name: "id", type: "INT AUTO_INCREMENT PRIMARY KEY" }] })',
+    "mysql.core.listTables()",
+  ],
+  transactions: [
+    "const { transactionId } = await mysql.transactions.begin()",
+    'await mysql.transactions.savepoint({ transactionId, name: "sp1" })',
+    'await mysql.transactions.rollbackTo({ transactionId, name: "sp1" })',
+    "await mysql.transactions.commit({ transactionId })",
+    'await mysql.transactions.execute({ statements: [{ sql: "INSERT..." }, { sql: "UPDATE..." }] })',
+  ],
+  json: [
+    'mysql.json.extract({ table: "docs", column: "data", path: "$.user.name" })',
+    'mysql.json.set({ table: "docs", column: "data", path: "$.status", value: "active", where: "id=1" })',
+    'mysql.json.contains({ table: "docs", column: "data", value: \'{"type": "admin"}\' })',
+    "mysql.json.merge({ json1: '{\"a\": 1}', json2: '{\"b\": 2}' })",
+    'mysql.json.search({ table: "docs", column: "data", searchValue: "active" })',
+  ],
+  text: [
+    'mysql.text.regexpMatch({ table: "users", column: "email", pattern: "^admin@" })',
+    'mysql.text.likeSearch({ table: "products", column: "name", pattern: "%widget%" })',
+    'mysql.text.soundex({ table: "users", column: "name", value: "Smith" })',
+  ],
+  fulltext: [
+    'mysql.fulltext.fulltextSearch({ table: "articles", columns: ["title", "content"], query: "database" })',
+    'mysql.fulltext.fulltextCreate({ table: "articles", columns: ["title", "content"] })',
+    'mysql.fulltext.fulltextBoolean({ table: "articles", columns: ["content"], query: "+MySQL -Oracle" })',
+  ],
+  performance: [
+    "mysql.performance.explain({ sql: 'SELECT * FROM orders WHERE status = ?', params: ['active'] })",
+    "mysql.performance.slowQueries({ limit: 10 })",
+    "mysql.performance.bufferPoolStats()",
+    "mysql.performance.innodbStatus()",
+    "mysql.performance.tableStats({ table: 'orders' })",
+  ],
+  optimization: [
+    "mysql.optimization.indexRecommendation({ table: 'orders' })",
+    "mysql.optimization.queryRewrite({ query: 'SELECT * FROM orders WHERE status = ?' })",
+    'mysql.optimization.forceIndex({ table: "orders", query: "SELECT * FROM orders WHERE status = ?", indexName: "idx_status" })',
+  ],
+  admin: [
+    "mysql.admin.optimizeTable({ table: 'orders' })",
+    "mysql.admin.checkTable({ table: 'orders' })",
+    "mysql.admin.analyzeTable({ table: 'orders' })",
+    "mysql.admin.flushTables()",
+    "mysql.admin.killQuery({ processId: 12345 })",
+  ],
+  monitoring: [
+    "mysql.monitoring.showStatus({ pattern: 'Threads%' })",
+    "mysql.monitoring.showVariables({ pattern: 'max_connections' })",
+    "mysql.monitoring.showProcesslist()",
+    "mysql.monitoring.queryStats()",
+  ],
+  backup: [
+    "mysql.backup.createDump({ tables: ['users', 'orders'] })",
+    "mysql.backup.exportTable({ table: 'users', format: 'csv' })",
+    "mysql.backup.importData({ table: 'users', data: [{ name: 'Alice', email: 'alice@test.com' }] })",
+    "mysql.backup.restoreDump({ filename: 'backup.sql' })",
+  ],
+  replication: [
+    "mysql.replication.slaveStatus()",
+    "mysql.replication.lag()",
+    "mysql.replication.masterStatus()",
+    "mysql.replication.binlogEvents({ limit: 20 })",
+  ],
+  partitioning: [
+    "mysql.partitioning.partitionInfo({ table: 'events' })",
+    "mysql.partitioning.addPartition({ table: 'events', partitionName: 'p2024q1', partitionType: 'RANGE', value: '2024040100' })",
+    "mysql.partitioning.dropPartition({ table: 'events', partitionName: 'p2023q1' })",
+  ],
+  schema: [
+    "mysql.schema.listViews()",
+    "mysql.schema.createView({ name: 'active_users', sql: 'SELECT * FROM users WHERE active = 1' })",
+    "mysql.schema.listFunctions()",
+    "mysql.schema.listTriggers({ table: 'orders' })",
+  ],
+  events: [
+    "mysql.events.eventCreate({ name: 'cleanup', schedule: { type: 'RECURRING', interval: 1, intervalUnit: 'DAY' }, body: 'DELETE FROM logs WHERE created_at < DATE_SUB(NOW(), INTERVAL 30 DAY)' })",
+    "mysql.events.eventList()",
+    "mysql.events.schedulerStatus()",
+  ],
+  sysschema: [
+    "mysql.sysschema.sysSchemaStats({ schema: 'testdb' })",
+    "mysql.sysschema.sysStatementSummary({ limit: 10 })",
+    "mysql.sysschema.sysInnodbLockWaits()",
+    "mysql.sysschema.sysMemorySummary()",
+  ],
+  stats: [
+    "mysql.stats.descriptive({ table: 'orders', column: 'amount' })",
+    "mysql.stats.percentiles({ table: 'orders', column: 'amount', percentiles: [50, 95, 99] })",
+    "mysql.stats.timeSeries({ table: 'metrics', timeColumn: 'ts', valueColumn: 'value', interval: 'hour' })",
+    "mysql.stats.histogram({ table: 'orders', column: 'amount', buckets: 10 })",
+  ],
+  spatial: [
+    "mysql.spatial.distance({ table: 'locations', spatialColumn: 'geom', point: { longitude: -74, latitude: 40.7 } })",
+    "mysql.spatial.distanceSphere({ table: 'locations', spatialColumn: 'geom', point: { longitude: -74, latitude: 40.7 } })",
+    "mysql.spatial.point({ longitude: -74, latitude: 40.7 })",
+    "mysql.spatial.buffer({ geometry: 'POINT(-74 40.7)', distance: 1000 })",
+  ],
+  security: [
+    "mysql.security.sslStatus()",
+    "mysql.security.userPrivileges({ user: 'app_user' })",
+    "mysql.security.audit()",
+    "mysql.security.sensitiveTables()",
+    "mysql.security.passwordValidate({ password: 'test123' })",
+  ],
+  cluster: [
+    "mysql.cluster.clusterStatus({ summary: true })",
+    "mysql.cluster.clusterRouterStatus({ summary: true })",
+    "mysql.cluster.clusterSwitchover()",
+    "mysql.cluster.grMembers()",
+    "mysql.cluster.clusterTopology()",
+  ],
+  roles: [
+    "mysql.roles.roleCreate({ name: 'app_reader' })",
+    "mysql.roles.roleGrant({ role: 'app_reader', privileges: ['SELECT'], database: 'mydb' })",
+    "mysql.roles.roleAssign({ role: 'app_reader', user: 'app_user' })",
+    "mysql.roles.roleList()",
+  ],
+  docstore: [
+    "mysql.docstore.docCreateCollection({ name: 'products', schema: 'mydb' })",
+    "mysql.docstore.docAdd({ collection: 'products', documents: [{ name: 'Widget', price: 9.99 }] })",
+    "mysql.docstore.docFind({ collection: 'products', filter: '$.name' })",
+  ],
+  router: [
+    "mysql.router.status()",
+    "mysql.router.routes()",
+    "mysql.router.routeHealth({ routeName: 'myroute' })",
+  ],
+  proxysql: [
+    "// ProxySQL requires external ProxySQL admin connection",
+    "// See tool descriptions for connection requirements",
+  ],
+  shell: [
+    "mysql.shell.version()",
+    'mysql.shell.runScript({ script: \'print("hello")\', language: "js" })',
+    "mysql.shell.exportTable({ schema: 'mydb', table: 'users', outputPath: '/tmp/users.csv', format: 'csv' })",
+    "mysql.shell.dumpSchemas({ schemas: ['mydb'], outputDir: '/backup/mydb', dryRun: true })",
+  ],
+};
+
+/**
+ * Mapping of method names to their parameter names for positional argument support.
+ * Single string = first positional arg maps to this key
+ * Array = multiple positional args map to these keys in order
+ *
+ * Enables:
+ * - `mysql.core.readQuery("SELECT...")` → `{ sql: "SELECT..." }`
+ * - `mysql.core.describeTable("users")` → `{ table: "users" }`
+ */
+const POSITIONAL_PARAM_MAP: Record<string, string | string[]> = {
+  // ============ CORE GROUP ============
+  readQuery: "sql",
+  writeQuery: "sql",
+  describeTable: "table",
+  dropTable: "table",
+  listTables: "database",
+  getIndexes: "table",
+  dropIndex: "name",
+  createTable: ["name", "columns"],
+  createIndex: ["table", "columns"],
+
+  // ============ SCHEMA GROUP ============
+  createSchema: "name",
+  dropSchema: "name",
+  listSchemas: "pattern",
+  listViews: "database",
+  listFunctions: "database",
+  listStoredProcedures: "database",
+  listTriggers: "table",
+  listConstraints: "table",
+  createView: ["name", "sql"],
+
+  // ============ JSON GROUP ============
+  extract: ["table", "column", "path", "where"],
+  set: ["table", "column", "path", "value", "where"],
+  insert: ["table", "column", "path", "value", "where"],
+  remove: ["table", "column", "path", "where"],
+  contains: ["table", "column", "value"],
+  keys: ["table", "column", "where"],
+  replace: ["table", "column", "path", "value", "where"],
+  get: ["table", "column", "path"],
+  search: ["table", "column", "searchValue"],
+  update: ["table", "column", "path", "value", "where"],
+  validate: ["table", "column"],
+  stats: ["table", "column"],
+  indexSuggest: ["table", "column"],
+  normalize: ["table", "column"],
+  merge: ["json1", "json2"],
+  diff: ["json1", "json2"],
+  arrayAppend: ["table", "column", "path", "value"],
+
+  // ============ TEXT GROUP ============
+  regexpMatch: ["table", "column", "pattern"],
+  likeSearch: ["table", "column", "pattern"],
+  soundex: ["table", "column", "value"],
+  substring: ["table", "column"],
+  concat: ["table", "columns"],
+  collationConvert: ["table", "column", "collation"],
+
+  // ============ FULLTEXT GROUP ============
+  fulltextCreate: ["table", "columns"],
+  fulltextDrop: ["table", "indexName"],
+  fulltextSearch: ["table", "columns", "query"],
+  fulltextBoolean: ["table", "columns", "query"],
+  fulltextExpand: ["table", "columns", "query"],
+
+  // ============ TRANSACTION GROUP ============
+  transactionCommit: "transactionId",
+  transactionRollback: "transactionId",
+  transactionSavepoint: ["transactionId", "name"],
+  transactionRelease: ["transactionId", "name"],
+  transactionRollbackTo: ["transactionId", "name"],
+  // Short aliases
+  commit: "transactionId",
+  rollback: "transactionId",
+  savepoint: ["transactionId", "name"],
+  release: ["transactionId", "name"],
+  rollbackTo: ["transactionId", "name"],
+
+  // ============ PERFORMANCE GROUP ============
+  explain: "sql",
+  explainAnalyze: "sql",
+
+  // ============ ADMIN GROUP ============
+  checkTable: "table",
+  repairTable: "table",
+  optimizeTable: "table",
+  analyzeTable: "table",
+
+  // ============ BACKUP GROUP ============
+  createDump: "tables",
+  exportTable: "table",
+  importData: "table",
+  restoreDump: "filename",
+
+  // ============ STATS GROUP ============
+  descriptive: ["table", "column"],
+  percentiles: ["table", "column", "percentiles"],
+  distribution: ["table", "column"],
+  histogram: ["table", "column", "buckets"],
+  correlation: ["table", "column1", "column2"],
+  regression: ["table", "xColumn", "yColumn"],
+  sampling: ["table", "sampleSize"],
+  timeSeries: ["table", "timeColumn", "valueColumn"],
+  // Stats prefixed aliases
+  statsTimeSeries: ["table", "timeColumn", "valueColumn"],
+  statsDescriptive: ["table", "column"],
+  statsPercentiles: ["table", "column", "percentiles"],
+  statsDistribution: ["table", "column"],
+  statsCorrelation: ["table", "column1", "column2"],
+  statsHistogram: ["table", "column", "buckets"],
+  statsSampling: ["table", "sampleSize"],
+  statsRegression: ["table", "xColumn", "yColumn"],
+
+  // ============ PARTITIONING GROUP ============
+  addPartition: ["table", "partitionName", "partitionType", "value"],
+  dropPartition: ["table", "partitionName"],
+  reorganizePartition: ["table", "partitions"],
+  partitionInfo: "table",
+
+  // ============ SPATIAL GROUP ============
+  distance: ["table", "spatialColumn"],
+  distanceSphere: ["table", "spatialColumn"],
+  point: ["longitude", "latitude"],
+  polygon: "coordinates",
+
+  // ============ SHELL GROUP ============
+  // Note: exportTable omitted — conflicts with backup group's exportTable
+  checkUpgrade: "targetVersion",
+  runScript: ["script", "language"],
+  importTable: ["inputPath", "schema", "table"],
+  importJson: ["inputPath", "schema", "collection"],
+  dumpInstance: "outputDir",
+  dumpSchemas: ["schemas", "outputDir"],
+  dumpTables: ["schema", "tables", "outputDir"],
+  loadDump: "inputDir",
+
+  // ============ SECURITY GROUP ============
+  passwordValidate: "password",
+};
+
+/**
+ * Methods where a single array arg should be wrapped in a specific key
+ */
+const ARRAY_WRAP_MAP: Record<string, string> = {
+  transactionExecute: "statements",
+  execute: "statements",
+};
+
+/**
+ * Normalize parameters to support positional arguments.
+ * Handles both single positional args and multiple positional args.
+ */
+function normalizeParams(methodName: string, args: unknown[]): unknown {
+  // No args - pass through
+  if (args.length === 0) return undefined;
+
+  // Single arg handling
+  if (args.length === 1) {
+    const arg = args[0];
+
+    // Object arg - pass through
+    if (typeof arg === "object" && arg !== null && !Array.isArray(arg)) {
+      return arg;
+    }
+
+    // Array arg - check if we should wrap it
+    if (Array.isArray(arg)) {
+      const wrapKey = ARRAY_WRAP_MAP[methodName];
+      if (wrapKey !== undefined) {
+        return { [wrapKey]: arg };
+      }
+      return arg;
+    }
+
+    // String arg - use positional mapping
+    if (typeof arg === "string") {
+      const paramMapping = POSITIONAL_PARAM_MAP[methodName];
+      if (typeof paramMapping === "string") {
+        return { [paramMapping]: arg };
+      }
+      if (Array.isArray(paramMapping) && paramMapping[0] !== undefined) {
+        return { [paramMapping[0]]: arg };
+      }
+      // Fallback: try common parameter names
+      return { sql: arg, query: arg, table: arg, name: arg };
+    }
+
+    return arg;
+  }
+
+  // Multi-arg: check for array+options pattern first
+  if (args.length >= 1 && Array.isArray(args[0])) {
+    const wrapKey = ARRAY_WRAP_MAP[methodName];
+    if (wrapKey !== undefined) {
+      const result: Record<string, unknown> = { [wrapKey]: args[0] };
+      if (args.length > 1) {
+        const lastArg = args[args.length - 1];
+        if (
+          typeof lastArg === "object" &&
+          lastArg !== null &&
+          !Array.isArray(lastArg)
+        ) {
+          Object.assign(result, lastArg);
+        }
+      }
+      return result;
+    }
+  }
+
+  // Look up positional parameter mapping
+  const paramMapping = POSITIONAL_PARAM_MAP[methodName];
+
+  if (paramMapping === undefined) {
+    return args[0];
+  }
+
+  // Single param mapping - merge trailing options if present
+  if (typeof paramMapping === "string") {
+    const result: Record<string, unknown> = { [paramMapping]: args[0] };
+    if (args.length > 1) {
+      const lastArg = args[args.length - 1];
+      if (
+        typeof lastArg === "object" &&
+        lastArg !== null &&
+        !Array.isArray(lastArg)
+      ) {
+        Object.assign(result, lastArg);
+      }
+    }
+    return result;
+  }
+
+  // Multi-param mapping (array)
+  const result: Record<string, unknown> = {};
+
+  // Check if last arg is an options object that should be merged
+  const lastArg = args[args.length - 1];
+  const lastArgIsOptionsObject =
+    typeof lastArg === "object" &&
+    lastArg !== null &&
+    !Array.isArray(lastArg) &&
+    Object.keys(lastArg as Record<string, unknown>).some((k) =>
+      paramMapping.includes(k),
+    );
+
+  // Map positional args to their keys
+  const argsToMap = lastArgIsOptionsObject ? args.length - 1 : args.length;
+  for (let i = 0; i < paramMapping.length && i < argsToMap; i++) {
+    const key = paramMapping[i];
+    const arg = args[i];
+    if (key !== undefined) {
+      result[key] = arg;
+    }
+  }
+
+  // Merge trailing options object
+  if (args.length > paramMapping.length || lastArgIsOptionsObject) {
+    if (
+      typeof lastArg === "object" &&
+      lastArg !== null &&
+      !Array.isArray(lastArg)
+    ) {
+      Object.assign(result, lastArg);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Dynamic API generator for tool groups
+ * Creates methods for each tool in the group
+ */
+function createGroupApi(
+  adapter: MySQLAdapter,
+  groupName: string,
+  tools: ToolDefinition[],
+): Record<string, (...args: unknown[]) => Promise<unknown>> {
+  const api: Record<string, (...args: unknown[]) => Promise<unknown>> = {};
+
+  for (const tool of tools) {
+    // Convert tool name to method name
+    // e.g., mysql_read_query -> readQuery, mysql_json_extract -> extract
+    const methodName = toolNameToMethodName(tool.name, groupName);
+
+    api[methodName] = async (...args: unknown[]) => {
+      // Normalize positional arguments to object parameters
+      const normalizedParams = normalizeParams(methodName, args) ?? {};
+      const context = adapter.createContext();
+      return tool.handler(normalizedParams, context);
+    };
+  }
+
+  // Add method aliases for this group
+  const aliases = METHOD_ALIASES[groupName];
+  if (aliases !== undefined) {
+    for (const [aliasName, canonicalName] of Object.entries(aliases)) {
+      if (api[canonicalName] !== undefined) {
+        api[aliasName] = api[canonicalName];
+      }
+    }
+  }
+
+  return api;
+}
+
+/**
+ * Convert tool name to camelCase method name
+ * Examples:
+ *   mysql_read_query (core) -> readQuery
+ *   mysql_json_extract (json) -> extract
+ *   mysql_fulltext_search (fulltext) -> fulltextSearch
+ *   mysql_sys_schema_stats (sysschema) -> sysSchemaStats
+ */
+function toolNameToMethodName(toolName: string, groupName: string): string {
+  // Remove mysql_ prefix
+  let name = toolName.replace(/^mysql_/, "");
+
+  // Map group name to its tool name prefix
+  // Some groups use different prefixes in tool names
+  const groupPrefixMap: Record<string, string> = {
+    sysschema: "sys_",
+    fulltext: "fulltext_",
+    docstore: "doc_",
+    transactions: "transaction_",
+    shell: "mysqlsh_",
+    // Default: use groupName + "_"
+  };
+
+  const groupPrefix = groupPrefixMap[groupName] ?? groupName + "_";
+
+  // For certain groups, keep the prefix as part of the method name
+  // because the tool names use a prefix that differs from the group
+  const keepPrefix = new Set([
+    "fulltext",
+    "sysschema",
+    "docstore",
+    "transactions",
+    "cluster",
+
+    "roles",
+    "events",
+  ]);
+
+  if (!keepPrefix.has(groupName) && name.startsWith(groupPrefix)) {
+    name = name.substring(groupPrefix.length);
+  }
+
+  // Convert snake_case to camelCase
+  return name.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+// Type alias for group API record
+type GroupApiRecord = Record<string, (...args: unknown[]) => Promise<unknown>>;
+
+/**
+ * Main API class exposing all tool groups
+ */
+export class MysqlApi {
+  // Core groups (15 original)
+  readonly core: GroupApiRecord;
+  readonly transactions: GroupApiRecord;
+  readonly json: GroupApiRecord;
+  readonly text: GroupApiRecord;
+  readonly fulltext: GroupApiRecord;
+  readonly performance: GroupApiRecord;
+  readonly optimization: GroupApiRecord;
+  readonly admin: GroupApiRecord;
+  readonly monitoring: GroupApiRecord;
+  readonly backup: GroupApiRecord;
+  readonly replication: GroupApiRecord;
+  readonly partitioning: GroupApiRecord;
+  readonly router: GroupApiRecord;
+  readonly proxysql: GroupApiRecord;
+  readonly shell: GroupApiRecord;
+  // New groups (9 added in v2.0.0)
+  readonly schema: GroupApiRecord;
+  readonly events: GroupApiRecord;
+  readonly sysschema: GroupApiRecord;
+  readonly stats: GroupApiRecord;
+  readonly spatial: GroupApiRecord;
+  readonly security: GroupApiRecord;
+  readonly cluster: GroupApiRecord;
+  readonly roles: GroupApiRecord;
+  readonly docstore: GroupApiRecord;
+
+  private readonly toolsByGroup: Map<string, ToolDefinition[]>;
+
+  constructor(adapter: MySQLAdapter) {
+    // Get all tool definitions and group them
+    const allTools = adapter.getToolDefinitions();
+    this.toolsByGroup = this.groupTools(allTools);
+
+    // Create group-specific APIs - 24 groups
+    this.core = createGroupApi(
+      adapter,
+      "core",
+      this.toolsByGroup.get("core") ?? [],
+    );
+    this.transactions = createGroupApi(
+      adapter,
+      "transactions",
+      this.toolsByGroup.get("transactions") ?? [],
+    );
+    this.json = createGroupApi(
+      adapter,
+      "json",
+      this.toolsByGroup.get("json") ?? [],
+    );
+    this.text = createGroupApi(
+      adapter,
+      "text",
+      this.toolsByGroup.get("text") ?? [],
+    );
+    this.fulltext = createGroupApi(
+      adapter,
+      "fulltext",
+      this.toolsByGroup.get("fulltext") ?? [],
+    );
+    this.performance = createGroupApi(
+      adapter,
+      "performance",
+      this.toolsByGroup.get("performance") ?? [],
+    );
+    this.optimization = createGroupApi(
+      adapter,
+      "optimization",
+      this.toolsByGroup.get("optimization") ?? [],
+    );
+    this.admin = createGroupApi(
+      adapter,
+      "admin",
+      this.toolsByGroup.get("admin") ?? [],
+    );
+    this.monitoring = createGroupApi(
+      adapter,
+      "monitoring",
+      this.toolsByGroup.get("monitoring") ?? [],
+    );
+    this.backup = createGroupApi(
+      adapter,
+      "backup",
+      this.toolsByGroup.get("backup") ?? [],
+    );
+    this.replication = createGroupApi(
+      adapter,
+      "replication",
+      this.toolsByGroup.get("replication") ?? [],
+    );
+    this.partitioning = createGroupApi(
+      adapter,
+      "partitioning",
+      this.toolsByGroup.get("partitioning") ?? [],
+    );
+    this.router = createGroupApi(
+      adapter,
+      "router",
+      this.toolsByGroup.get("router") ?? [],
+    );
+    this.proxysql = createGroupApi(
+      adapter,
+      "proxysql",
+      this.toolsByGroup.get("proxysql") ?? [],
+    );
+    this.shell = createGroupApi(
+      adapter,
+      "shell",
+      this.toolsByGroup.get("shell") ?? [],
+    );
+    // New groups (9)
+    this.schema = createGroupApi(
+      adapter,
+      "schema",
+      this.toolsByGroup.get("schema") ?? [],
+    );
+    this.events = createGroupApi(
+      adapter,
+      "events",
+      this.toolsByGroup.get("events") ?? [],
+    );
+    this.sysschema = createGroupApi(
+      adapter,
+      "sysschema",
+      this.toolsByGroup.get("sysschema") ?? [],
+    );
+    this.stats = createGroupApi(
+      adapter,
+      "stats",
+      this.toolsByGroup.get("stats") ?? [],
+    );
+    this.spatial = createGroupApi(
+      adapter,
+      "spatial",
+      this.toolsByGroup.get("spatial") ?? [],
+    );
+    this.security = createGroupApi(
+      adapter,
+      "security",
+      this.toolsByGroup.get("security") ?? [],
+    );
+    this.cluster = createGroupApi(
+      adapter,
+      "cluster",
+      this.toolsByGroup.get("cluster") ?? [],
+    );
+    this.roles = createGroupApi(
+      adapter,
+      "roles",
+      this.toolsByGroup.get("roles") ?? [],
+    );
+    this.docstore = createGroupApi(
+      adapter,
+      "docstore",
+      this.toolsByGroup.get("docstore") ?? [],
+    );
+  }
+
+  /**
+   * Group tools by their tool group
+   */
+  private groupTools(tools: ToolDefinition[]): Map<string, ToolDefinition[]> {
+    const grouped = new Map<string, ToolDefinition[]>();
+
+    for (const tool of tools) {
+      const group = tool.group;
+      const existing = grouped.get(group);
+      if (existing) {
+        existing.push(tool);
+      } else {
+        grouped.set(group, [tool]);
+      }
+    }
+
+    return grouped;
+  }
+
+  /**
+   * Get list of available groups and their method counts
+   */
+  getAvailableGroups(): Record<string, number> {
+    const groups: Record<string, number> = {};
+    for (const [group, tools] of this.toolsByGroup) {
+      groups[group] = tools.length;
+    }
+    return groups;
+  }
+
+  /**
+   * Get list of methods available in a group
+   */
+  getGroupMethods(groupName: string): string[] {
+    const groupApi = this[groupName as keyof MysqlApi];
+    if (typeof groupApi === "object" && groupApi !== null) {
+      return Object.keys(groupApi as Record<string, unknown>);
+    }
+    return [];
+  }
+
+  /**
+   * Get help information listing all groups and their methods.
+   * Call mysql.help() in code mode to discover available APIs.
+   *
+   * @returns Object with group names as keys and arrays of method names as values
+   */
+  help(): Record<string, string[]> {
+    const result: Record<string, string[]> = {};
+    for (const [group, tools] of this.toolsByGroup) {
+      // Skip codemode group itself
+      if (group === "codemode") continue;
+      result[group] = tools.map((t) => toolNameToMethodName(t.name, group));
+    }
+    return result;
+  }
+
+  /**
+   * Create a serializable API binding for the sandbox
+   * This creates references that can be called from the vm context
+   */
+  createSandboxBindings(): Record<string, unknown> {
+    const bindings: Record<string, unknown> = {};
+
+    const groupNames = [
+      "core",
+      "transactions",
+      "json",
+      "text",
+      "fulltext",
+      "performance",
+      "optimization",
+      "admin",
+      "monitoring",
+      "backup",
+      "replication",
+      "partitioning",
+      "router",
+      "proxysql",
+      "shell",
+      "schema",
+      "events",
+      "sysschema",
+      "stats",
+      "spatial",
+      "security",
+      "cluster",
+      "roles",
+      "docstore",
+    ] as const;
+
+    for (const groupName of groupNames) {
+      const groupApi = this[groupName];
+      const allMethodNames = Object.keys(groupApi);
+
+      // Separate canonical methods from aliases for structured help output
+      const aliases = METHOD_ALIASES[groupName] ?? {};
+      const aliasNames = new Set(Object.keys(aliases));
+      const canonicalMethodNames = allMethodNames.filter(
+        (name) => !aliasNames.has(name),
+      );
+
+      // Filter aliases to only show useful shorthand aliases in help output
+      const usefulAliases = allMethodNames.filter((name) => {
+        if (!aliasNames.has(name)) return false;
+        const lowerGroupName = groupName.toLowerCase();
+        const lowerAlias = name.toLowerCase();
+        return !lowerAlias.startsWith(lowerGroupName);
+      });
+
+      // Add all methods plus a 'help' property that lists them
+      bindings[groupName] = {
+        ...groupApi,
+        help: () => ({
+          methods: canonicalMethodNames,
+          methodAliases: usefulAliases,
+          examples: GROUP_EXAMPLES[groupName],
+        }),
+      };
+    }
+
+    // Add top-level help as directly callable mysql.help()
+    bindings["help"] = () => this.help();
+
+    // =========================================================================
+    // Top-level convenience aliases
+    // =========================================================================
+
+    // Core aliases: mysql.readQuery() → mysql.core.readQuery()
+    const coreApi = bindings["core"] as GroupApiRecord | undefined;
+    if (coreApi !== undefined) {
+      // Query tools
+      if (coreApi["readQuery"] !== undefined) {
+        bindings["readQuery"] = coreApi["readQuery"];
+      }
+      if (coreApi["writeQuery"] !== undefined) {
+        bindings["writeQuery"] = coreApi["writeQuery"];
+      }
+      // Table metadata
+      if (coreApi["listTables"] !== undefined) {
+        bindings["listTables"] = coreApi["listTables"];
+      }
+      if (coreApi["describeTable"] !== undefined) {
+        bindings["describeTable"] = coreApi["describeTable"];
+      }
+      // Table DDL
+      if (coreApi["createTable"] !== undefined) {
+        bindings["createTable"] = coreApi["createTable"];
+      }
+      if (coreApi["dropTable"] !== undefined) {
+        bindings["dropTable"] = coreApi["dropTable"];
+      }
+      // Index tools
+      if (coreApi["createIndex"] !== undefined) {
+        bindings["createIndex"] = coreApi["createIndex"];
+      }
+      if (coreApi["getIndexes"] !== undefined) {
+        bindings["getIndexes"] = coreApi["getIndexes"];
+      }
+    }
+
+    // Transaction aliases: mysql.transactionBegin() → mysql.transactions.transactionBegin()
+    const transactionsApi = bindings["transactions"] as
+      | GroupApiRecord
+      | undefined;
+    if (transactionsApi !== undefined) {
+      for (const method of [
+        "transactionBegin",
+        "transactionCommit",
+        "transactionRollback",
+        "transactionSavepoint",
+        "transactionRelease",
+        "transactionRollbackTo",
+        "transactionExecute",
+      ]) {
+        if (transactionsApi[method] !== undefined) {
+          bindings[method] = transactionsApi[method];
+        }
+      }
+    }
+
+    // JSON aliases: mysql.jsonExtract() → mysql.json.extract()
+    const jsonApi = bindings["json"] as GroupApiRecord | undefined;
+    if (jsonApi !== undefined) {
+      for (const method of [
+        "extract",
+        "set",
+        "insert",
+        "remove",
+        "contains",
+        "keys",
+        "replace",
+        "get",
+        "search",
+        "update",
+        "validate",
+        "merge",
+        "diff",
+        "stats",
+        "indexSuggest",
+        "normalize",
+        "arrayAppend",
+      ]) {
+        if (jsonApi[method] !== undefined) {
+          bindings[`json${method.charAt(0).toUpperCase()}${method.slice(1)}`] =
+            jsonApi[method];
+        }
+      }
+    }
+
+    // Performance aliases: mysql.explain() → mysql.performance.explain()
+    const performanceApi = bindings["performance"] as
+      | GroupApiRecord
+      | undefined;
+    if (performanceApi !== undefined) {
+      for (const method of [
+        "explain",
+        "explainAnalyze",
+        "slowQueries",
+        "bufferPoolStats",
+        "innodbStatus",
+        "tableStats",
+        "threadStats",
+        "serverHealth",
+      ]) {
+        if (performanceApi[method] !== undefined) {
+          bindings[method] = performanceApi[method];
+        }
+      }
+    }
+
+    // Admin aliases: mysql.optimizeTable() → mysql.admin.optimizeTable()
+    const adminApi = bindings["admin"] as GroupApiRecord | undefined;
+    if (adminApi !== undefined) {
+      for (const method of [
+        "checkTable",
+        "repairTable",
+        "optimizeTable",
+        "analyzeTable",
+        "flushTables",
+        "killQuery",
+      ]) {
+        if (adminApi[method] !== undefined) {
+          bindings[method] = adminApi[method];
+        }
+      }
+    }
+
+    // Monitoring aliases: mysql.showStatus() → mysql.monitoring.showStatus()
+    const monitoringApi = bindings["monitoring"] as GroupApiRecord | undefined;
+    if (monitoringApi !== undefined) {
+      for (const method of [
+        "showStatus",
+        "showVariables",
+        "showProcesslist",
+        "queryStats",
+      ]) {
+        if (monitoringApi[method] !== undefined) {
+          bindings[method] = monitoringApi[method];
+        }
+      }
+    }
+
+    // Backup aliases: mysql.createDump() → mysql.backup.createDump()
+    const backupApi = bindings["backup"] as GroupApiRecord | undefined;
+    if (backupApi !== undefined) {
+      for (const method of [
+        "createDump",
+        "exportTable",
+        "importData",
+        "restoreDump",
+      ]) {
+        if (backupApi[method] !== undefined) {
+          bindings[method] = backupApi[method];
+        }
+      }
+    }
+
+    // Stats aliases: mysql.descriptive() → mysql.stats.descriptive()
+    const statsApi = bindings["stats"] as GroupApiRecord | undefined;
+    if (statsApi !== undefined) {
+      for (const method of [
+        "descriptive",
+        "percentiles",
+        "correlation",
+        "regression",
+        "timeSeries",
+        "distribution",
+        "histogram",
+        "sampling",
+      ]) {
+        if (statsApi[method] !== undefined) {
+          bindings[method] = statsApi[method];
+        }
+      }
+    }
+
+    return bindings;
+  }
+}
+
+/**
+ * Create a MysqlApi instance for an adapter
+ */
+export function createMysqlApi(adapter: MySQLAdapter): MysqlApi {
+  return new MysqlApi(adapter);
+}