@neverinfamous/mysql-mcp 2.2.0 → 2.3.0

package/dist/codemode/api.js

@@ -0,0 +1,1035 @@
+/**
+ * mysql-mcp - Code Mode API
+ *
+ * Exposes all MySQL tools organized by their 24 groups
+ * for use within the sandboxed execution environment.
+ */
+/**
+ * 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 = {
+    // 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 = {
+    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 = {
+    // ============ 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 = {
+    transactionExecute: "statements",
+    execute: "statements",
+};
+/**
+ * Normalize parameters to support positional arguments.
+ * Handles both single positional args and multiple positional args.
+ */
+function normalizeParams(methodName, args) {
+    // 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 = { [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 = { [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 = {};
+    // 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).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, groupName, tools) {
+    const api = {};
+    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) => {
+            // 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, groupName) {
+    // 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 = {
+        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) => letter.toUpperCase());
+}
+/**
+ * Main API class exposing all tool groups
+ */
+export class MysqlApi {
+    // Core groups (15 original)
+    core;
+    transactions;
+    json;
+    text;
+    fulltext;
+    performance;
+    optimization;
+    admin;
+    monitoring;
+    backup;
+    replication;
+    partitioning;
+    router;
+    proxysql;
+    shell;
+    // New groups (9 added in v2.0.0)
+    schema;
+    events;
+    sysschema;
+    stats;
+    spatial;
+    security;
+    cluster;
+    roles;
+    docstore;
+    toolsByGroup;
+    constructor(adapter) {
+        // 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
+     */
+    groupTools(tools) {
+        const grouped = new Map();
+        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() {
+        const groups = {};
+        for (const [group, tools] of this.toolsByGroup) {
+            groups[group] = tools.length;
+        }
+        return groups;
+    }
+    /**
+     * Get list of methods available in a group
+     */
+    getGroupMethods(groupName) {
+        const groupApi = this[groupName];
+        if (typeof groupApi === "object" && groupApi !== null) {
+            return Object.keys(groupApi);
+        }
+        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() {
+        const result = {};
+        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() {
+        const bindings = {};
+        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",
+        ];
+        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"];
+        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"];
+        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"];
+        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"];
+        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"];
+        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"];
+        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"];
+        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"];
+        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) {
+    return new MysqlApi(adapter);
+}
+//# sourceMappingURL=api.js.map