@neverinfamous/mysql-mcp 2.1.0

package/dist/adapters/mysql/tools/core.js

@@ -0,0 +1,308 @@
+/**
+ * MySQL Core Database Tools
+ *
+ * Fundamental database operations: read, write, table management, indexes.
+ * 8 tools total.
+ */
+import { ReadQuerySchema, WriteQuerySchema, CreateTableSchema, DescribeTableSchema, DropTableSchema, CreateIndexSchema, GetIndexesSchema, ListTablesSchema } from '../types.js';
+/**
+ * Helper to escape table/schema identifiers
+ * Handles "table" -> "`table`" and "db.table" -> "`db`.`table`"
+ */
+function escapeId(id) {
+    return id.split('.').map(part => `\`${part}\``).join('.');
+}
+/**
+ * Helper to validate table/schema identifiers
+ * Allows "table" and "db.table" formats
+ */
+function isValidId(id) {
+    return /^[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)?$/.test(id);
+}
+/**
+ * Get all core database tools
+ */
+export function getCoreTools(adapter) {
+    return [
+        createReadQueryTool(adapter),
+        createWriteQueryTool(adapter),
+        createListTablesTool(adapter),
+        createDescribeTableTool(adapter),
+        createCreateTableTool(adapter),
+        createDropTableTool(adapter),
+        createGetIndexesTool(adapter),
+        createCreateIndexTool(adapter)
+    ];
+}
+/**
+ * Execute a read-only SQL query
+ */
+function createReadQueryTool(adapter) {
+    return {
+        name: 'mysql_read_query',
+        title: 'MySQL Read Query',
+        description: 'Execute a read-only SQL query (SELECT). Uses prepared statements for safety.',
+        group: 'core',
+        inputSchema: ReadQuerySchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params, _context) => {
+            const { query, params: queryParams, transactionId } = ReadQuerySchema.parse(params);
+            const result = await adapter.executeReadQuery(query, queryParams, transactionId);
+            return {
+                rows: result.rows,
+                rowCount: result.rows?.length ?? 0,
+                executionTimeMs: result.executionTimeMs
+            };
+        }
+    };
+}
+/**
+ * Execute a write SQL query
+ */
+function createWriteQueryTool(adapter) {
+    return {
+        name: 'mysql_write_query',
+        title: 'MySQL Write Query',
+        description: 'Execute a write SQL query (INSERT, UPDATE, DELETE). Uses prepared statements for safety.',
+        group: 'core',
+        inputSchema: WriteQuerySchema,
+        requiredScopes: ['write'],
+        annotations: {
+            readOnlyHint: false
+        },
+        handler: async (params, _context) => {
+            const { query, params: queryParams, transactionId } = WriteQuerySchema.parse(params);
+            const result = await adapter.executeWriteQuery(query, queryParams, transactionId);
+            return {
+                rowsAffected: result.rowsAffected,
+                lastInsertId: result.lastInsertId?.toString(),
+                executionTimeMs: result.executionTimeMs
+            };
+        }
+    };
+}
+/**
+ * List all tables in the database
+ */
+function createListTablesTool(adapter) {
+    return {
+        name: 'mysql_list_tables',
+        title: 'MySQL List Tables',
+        description: 'List all tables and views in the database with metadata.',
+        group: 'core',
+        inputSchema: ListTablesSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params, _context) => {
+            const { database } = ListTablesSchema.parse(params);
+            const tables = await adapter.listTables(database);
+            return {
+                tables: tables.map(t => ({
+                    name: t.name,
+                    type: t.type,
+                    engine: t.engine,
+                    rowCount: t.rowCount,
+                    comment: t.comment
+                })),
+                count: tables.length
+            };
+        }
+    };
+}
+/**
+ * Describe a table's structure
+ */
+function createDescribeTableTool(adapter) {
+    return {
+        name: 'mysql_describe_table',
+        title: 'MySQL Describe Table',
+        description: 'Get detailed information about a table\'s structure including columns, types, and constraints.',
+        group: 'core',
+        inputSchema: DescribeTableSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params, _context) => {
+            const { table } = DescribeTableSchema.parse(params);
+            const tableInfo = await adapter.describeTable(table);
+            return tableInfo;
+        }
+    };
+}
+/**
+ * Create a new table
+ */
+function createCreateTableTool(adapter) {
+    return {
+        name: 'mysql_create_table',
+        title: 'MySQL Create Table',
+        description: 'Create a new table with specified columns, engine, and charset.',
+        group: 'core',
+        inputSchema: CreateTableSchema,
+        requiredScopes: ['write'],
+        annotations: {
+            readOnlyHint: false
+        },
+        handler: async (params, _context) => {
+            const { name, columns, engine, charset, collate, comment, ifNotExists } = CreateTableSchema.parse(params);
+            // Build column definitions
+            const columnDefs = columns.map(col => {
+                let def = `\`${col.name}\` ${col.type}`;
+                if (!col.nullable) {
+                    def += ' NOT NULL';
+                }
+                if (col.autoIncrement) {
+                    def += ' AUTO_INCREMENT';
+                }
+                if (col.default !== undefined) {
+                    const defaultVal = col.default;
+                    // Check if default is a SQL function/expression that should not be quoted
+                    const defaultValue = String(defaultVal).toUpperCase().trim();
+                    const sqlFunctions = [
+                        'CURRENT_TIMESTAMP', 'CURRENT_DATE', 'CURRENT_TIME',
+                        'NOW()', 'UUID()', 'NULL'
+                    ];
+                    const isSqlFunction = sqlFunctions.some(fn => defaultValue.startsWith(fn)) ||
+                        /^[A-Z_]+\(.*\)$/.test(defaultValue); // Matches FUNCTION(...) pattern
+                    if (isSqlFunction || typeof defaultVal === 'number') {
+                        def += ` DEFAULT ${String(defaultVal)}`;
+                    }
+                    else {
+                        def += ` DEFAULT '${String(defaultVal).replace(/'/g, "''")}'`;
+                    }
+                }
+                if (col.unique) {
+                    def += ' UNIQUE';
+                }
+                if (col.comment) {
+                    def += ` COMMENT '${col.comment.replace(/'/g, "''")}'`;
+                }
+                return def;
+            });
+            // Add primary key
+            const pkCols = columns.filter(c => c.primaryKey).map(c => `\`${c.name}\``);
+            if (pkCols.length > 0) {
+                columnDefs.push(`PRIMARY KEY (${pkCols.join(', ')})`);
+            }
+            // Build SQL
+            const ifNotExistsClause = ifNotExists ? 'IF NOT EXISTS ' : '';
+            // Handle qualified names (e.g. schema.table)
+            const tableName = escapeId(name);
+            let sql = `CREATE TABLE ${ifNotExistsClause}${tableName} (\n  ${columnDefs.join(',\n  ')}\n)`;
+            sql += ` ENGINE=${engine}`;
+            sql += ` DEFAULT CHARSET=${charset}`;
+            sql += ` COLLATE=${collate}`;
+            if (comment) {
+                sql += ` COMMENT='${comment.replace(/'/g, "''")}'`;
+            }
+            // If schema-qualified name, switch to that database first
+            if (name.includes('.')) {
+                const [schemaName] = name.split('.');
+                await adapter.executeQuery(`USE \`${schemaName}\``);
+            }
+            await adapter.executeQuery(sql);
+            return { success: true, tableName: name };
+        }
+    };
+}
+/**
+ * Drop a table
+ */
+function createDropTableTool(adapter) {
+    return {
+        name: 'mysql_drop_table',
+        title: 'MySQL Drop Table',
+        description: 'Drop (delete) a table from the database.',
+        group: 'core',
+        inputSchema: DropTableSchema,
+        requiredScopes: ['admin'],
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true
+        },
+        handler: async (params, _context) => {
+            const { table, ifExists } = DropTableSchema.parse(params);
+            // Validate table name
+            if (!isValidId(table)) {
+                throw new Error('Invalid table name');
+            }
+            const ifExistsClause = ifExists ? 'IF EXISTS ' : '';
+            const tableName = escapeId(table);
+            await adapter.executeQuery(`DROP TABLE ${ifExistsClause}${tableName}`);
+            return { success: true, tableName: table };
+        }
+    };
+}
+/**
+ * Get indexes for a table
+ */
+function createGetIndexesTool(adapter) {
+    return {
+        name: 'mysql_get_indexes',
+        title: 'MySQL Get Indexes',
+        description: 'Get all indexes for a table including type, columns, and cardinality.',
+        group: 'core',
+        inputSchema: GetIndexesSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params, _context) => {
+            const { table } = GetIndexesSchema.parse(params);
+            const indexes = await adapter.getTableIndexes(table);
+            return { indexes };
+        }
+    };
+}
+/**
+ * Create an index
+ */
+function createCreateIndexTool(adapter) {
+    return {
+        name: 'mysql_create_index',
+        title: 'MySQL Create Index',
+        description: 'Create an index on a table. Supports BTREE, HASH, FULLTEXT, and SPATIAL index types.',
+        group: 'core',
+        inputSchema: CreateIndexSchema,
+        requiredScopes: ['write'],
+        annotations: {
+            readOnlyHint: false
+        },
+        handler: async (params, _context) => {
+            const { name, table, columns, unique, type, ifNotExists } = CreateIndexSchema.parse(params);
+            // Validate names
+            if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+                // Index names usually don't have schema prefix
+                throw new Error('Invalid index name');
+            }
+            if (!isValidId(table)) {
+                throw new Error('Invalid table name');
+            }
+            const columnList = columns.map(c => `\`${c}\``).join(', ');
+            const uniqueClause = unique ? 'UNIQUE ' : '';
+            const typeClause = type ? `USING ${type} ` : '';
+            const tableName = escapeId(table);
+            // Note: IF NOT EXISTS not supported for indexes in MySQL
+            // We'll check if it exists first
+            if (ifNotExists) {
+                const existing = await adapter.getTableIndexes(table); // Pass original unescaped name to getTableIndexes (it expects string)
+                if (existing.some(idx => idx.name === name)) {
+                    return { success: true, skipped: true, indexName: name, reason: 'Index already exists' };
+                }
+            }
+            await adapter.executeQuery(`CREATE ${uniqueClause}INDEX \`${name}\` ${typeClause}ON ${tableName} (${columnList})`);
+            return { success: true, indexName: name };
+        }
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/adapters/mysql/tools/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../src/adapters/mysql/tools/core.ts"],"names":[],"mappings":"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"}

package/dist/adapters/mysql/tools/docstore.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MySQL Document Store / X DevAPI Tools
+ *
+ * Tools for working with JSON document collections.
+ * 9 tools total.
+ */
+import type { MySQLAdapter } from '../MySQLAdapter.js';
+import type { ToolDefinition } from '../../../types/index.js';
+export declare function getDocStoreTools(adapter: MySQLAdapter): ToolDefinition[];
+//# sourceMappingURL=docstore.d.ts.map

package/dist/adapters/mysql/tools/docstore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docstore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/mysql/tools/docstore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,yBAAyB,CAAC;AAoG9E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,EAAE,CA4OxE"}

package/dist/adapters/mysql/tools/docstore.js

@@ -0,0 +1,320 @@
+/**
+ * MySQL Document Store / X DevAPI Tools
+ *
+ * Tools for working with JSON document collections.
+ * 9 tools total.
+ */
+import { z } from 'zod';
+const ListCollectionsSchema = z.object({
+    schema: z.string().optional().describe('Schema name (defaults to current)')
+});
+const CreateCollectionSchema = z.object({
+    name: z.string().describe('Collection name'),
+    schema: z.string().optional(),
+    validation: z.object({
+        schema: z.record(z.string(), z.unknown()).optional().describe('JSON schema'),
+        level: z.enum(['OFF', 'STRICT', 'MODERATE']).default('OFF').describe('Validation level')
+    }).optional().describe('Validation config')
+});
+const DropCollectionSchema = z.object({
+    name: z.string(),
+    schema: z.string().optional(),
+    ifExists: z.boolean().default(true)
+});
+const FindSchema = z.object({
+    collection: z.string(),
+    filter: z.string().optional().describe('JSON path expression filter'),
+    fields: z.array(z.string()).optional(),
+    limit: z.number().default(100),
+    offset: z.number().default(0)
+});
+const AddDocSchema = z.object({
+    collection: z.string(),
+    documents: z.array(z.record(z.string(), z.unknown())).describe('Documents to add')
+});
+const ModifyDocSchema = z.object({
+    collection: z.string(),
+    filter: z.string().describe('Filter: JSON path for existence ($.name) OR _id value for specific document'),
+    set: z.record(z.string(), z.unknown()).optional().describe('Fields to set'),
+    unset: z.array(z.string()).optional()
+});
+const RemoveDocSchema = z.object({
+    collection: z.string(),
+    filter: z.string().describe('Filter: JSON path for existence ($.name) OR _id value for specific document')
+});
+/**
+ * Parse filter string into a WHERE clause.
+ * Supports:
+ * - JSON path existence: $.name, $.address.city
+ * - _id match: direct _id value (32-char hex string)
+ * - Field equality: name=Alice, age=30
+ */
+function parseDocFilter(filter) {
+    // Check if it's a direct _id (32-char hex)
+    if (/^[a-f0-9]{32}$/i.test(filter)) {
+        return { where: '_id = ?', params: [filter] };
+    }
+    // Check for simple field=value pattern
+    const eqMatch = /^([a-zA-Z_][a-zA-Z0-9_]*)=(.+)$/.exec(filter);
+    if (eqMatch) {
+        const [, field, value] = eqMatch;
+        // Try to parse as number
+        const numVal = Number(value);
+        if (!isNaN(numVal)) {
+            return {
+                where: `JSON_UNQUOTE(JSON_EXTRACT(doc, '$.${field}')) = ?`,
+                params: [String(numVal)]
+            };
+        }
+        return {
+            where: `JSON_UNQUOTE(JSON_EXTRACT(doc, '$.${field}')) = ?`,
+            params: [value]
+        };
+    }
+    // Default: treat as JSON path existence check
+    if (!filter.startsWith('$')) {
+        throw new Error(`Invalid filter: "${filter}". Use JSON path ($.field), _id value, or field=value format.`);
+    }
+    return { where: `JSON_EXTRACT(doc, '${filter}') IS NOT NULL`, params: [] };
+}
+const CreateDocIndexSchema = z.object({
+    collection: z.string(),
+    name: z.string(),
+    fields: z.array(z.object({
+        path: z.string(),
+        type: z.enum(['TEXT', 'INT', 'DOUBLE', 'DATE', 'DATETIME', 'GEOJSON']).default('TEXT'),
+        required: z.boolean().default(false)
+    })),
+    unique: z.boolean().default(false)
+});
+const CollectionInfoSchema = z.object({
+    collection: z.string(),
+    schema: z.string().optional()
+});
+export function getDocStoreTools(adapter) {
+    return [
+        {
+            name: 'mysql_doc_list_collections',
+            title: 'MySQL List Collections',
+            description: 'List JSON document collections in a schema.',
+            group: 'docstore',
+            inputSchema: ListCollectionsSchema,
+            requiredScopes: ['read'],
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: async (params, _context) => {
+                const { schema } = ListCollectionsSchema.parse(params);
+                const query = `
+                    SELECT TABLE_NAME as name, TABLE_COMMENT as comment, TABLE_ROWS as rowCount
+                    FROM information_schema.TABLES
+                    WHERE TABLE_SCHEMA = COALESCE(?, DATABASE())
+                      AND TABLE_NAME IN (
+                          SELECT TABLE_NAME FROM information_schema.COLUMNS
+                          WHERE COLUMN_NAME = 'doc' AND DATA_TYPE = 'json'
+                            AND TABLE_SCHEMA = COALESCE(?, DATABASE())
+                      )`;
+                const result = await adapter.executeQuery(query, [schema ?? null, schema ?? null]);
+                return { collections: result.rows ?? [], count: result.rows?.length ?? 0 };
+            }
+        },
+        {
+            name: 'mysql_doc_create_collection',
+            title: 'MySQL Create Collection',
+            description: 'Create a new JSON document collection.',
+            group: 'docstore',
+            inputSchema: CreateCollectionSchema,
+            requiredScopes: ['write'],
+            annotations: { readOnlyHint: false },
+            handler: async (params, _context) => {
+                const { name, validation } = CreateCollectionSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
+                    throw new Error('Invalid collection name');
+                let sql = `CREATE TABLE \`${name}\` (
+                    doc JSON,
+                    _id VARBINARY(32) GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(doc, '$._id'))) STORED PRIMARY KEY,
+                    _json_schema JSON GENERATED ALWAYS AS ('{}') VIRTUAL
+                ) ENGINE=InnoDB`;
+                if (validation?.level && validation.level !== 'OFF') {
+                    const schemaJson = JSON.stringify(validation.schema ?? {});
+                    sql = `CREATE TABLE \`${name}\` (
+                        doc JSON,
+                        _id VARBINARY(32) GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(doc, '$._id'))) STORED PRIMARY KEY,
+                        CONSTRAINT chk_schema CHECK (JSON_SCHEMA_VALID('${schemaJson}', doc))
+                    ) ENGINE=InnoDB`;
+                }
+                await adapter.executeQuery(sql);
+                return { success: true, collection: name };
+            }
+        },
+        {
+            name: 'mysql_doc_drop_collection',
+            title: 'MySQL Drop Collection',
+            description: 'Drop a document collection.',
+            group: 'docstore',
+            inputSchema: DropCollectionSchema,
+            requiredScopes: ['admin'],
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            handler: async (params, _context) => {
+                const { name, ifExists } = DropCollectionSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
+                    throw new Error('Invalid collection name');
+                await adapter.executeQuery(`DROP TABLE ${ifExists ? 'IF EXISTS ' : ''}\`${name}\``);
+                return { success: true, collection: name };
+            }
+        },
+        {
+            name: 'mysql_doc_find',
+            title: 'MySQL Find Documents',
+            description: 'Query documents in a collection.',
+            group: 'docstore',
+            inputSchema: FindSchema,
+            requiredScopes: ['read'],
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: async (params, _context) => {
+                const { collection, filter, fields, limit, offset } = FindSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(collection))
+                    throw new Error('Invalid collection name');
+                let selectClause = 'doc';
+                if (fields && fields.length > 0) {
+                    selectClause = 'JSON_OBJECT(' + fields.map(f => `'${f}', JSON_EXTRACT(doc, '$.${f}')`).join(', ') + ') as doc';
+                }
+                let query = `SELECT ${selectClause} FROM \`${collection}\``;
+                if (filter)
+                    query += ` WHERE JSON_EXTRACT(doc, '${filter}') IS NOT NULL`;
+                query += ` LIMIT ${String(limit)} OFFSET ${String(offset)}`;
+                const result = await adapter.executeQuery(query);
+                const docs = (result.rows ?? []).map(r => {
+                    const row = r;
+                    const docValue = row['doc'];
+                    return typeof docValue === 'string' ? JSON.parse(docValue) : docValue;
+                });
+                return { documents: docs, count: docs.length };
+            }
+        },
+        {
+            name: 'mysql_doc_add',
+            title: 'MySQL Add Documents',
+            description: 'Add documents to a collection.',
+            group: 'docstore',
+            inputSchema: AddDocSchema,
+            requiredScopes: ['write'],
+            annotations: { readOnlyHint: false },
+            handler: async (params, _context) => {
+                const { collection, documents } = AddDocSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(collection))
+                    throw new Error('Invalid collection name');
+                let inserted = 0;
+                for (const doc of documents) {
+                    doc['_id'] ??= crypto.randomUUID().replace(/-/g, '');
+                    await adapter.executeQuery(`INSERT INTO \`${collection}\` (doc) VALUES (?)`, [JSON.stringify(doc)]);
+                    inserted++;
+                }
+                return { success: true, inserted };
+            }
+        },
+        {
+            name: 'mysql_doc_modify',
+            title: 'MySQL Modify Documents',
+            description: 'Update documents in a collection.',
+            group: 'docstore',
+            inputSchema: ModifyDocSchema,
+            requiredScopes: ['write'],
+            annotations: { readOnlyHint: false },
+            handler: async (params, _context) => {
+                const { collection, filter, set, unset } = ModifyDocSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(collection))
+                    throw new Error('Invalid collection name');
+                const updates = [];
+                if (set) {
+                    for (const [path, value] of Object.entries(set)) {
+                        updates.push(`doc = JSON_SET(doc, '$.${path}', CAST('${JSON.stringify(value)}' AS JSON))`);
+                    }
+                }
+                if (unset) {
+                    for (const path of unset) {
+                        updates.push(`doc = JSON_REMOVE(doc, '$.${path}')`);
+                    }
+                }
+                if (updates.length === 0)
+                    throw new Error('No modifications specified');
+                const { where, params: whereParams } = parseDocFilter(filter);
+                const query = `UPDATE \`${collection}\` SET ${updates.join(', ')} WHERE ${where}`;
+                const result = await adapter.executeQuery(query, whereParams);
+                return { success: true, modified: result.rowsAffected ?? 0 };
+            }
+        },
+        {
+            name: 'mysql_doc_remove',
+            title: 'MySQL Remove Documents',
+            description: 'Remove documents from a collection.',
+            group: 'docstore',
+            inputSchema: RemoveDocSchema,
+            requiredScopes: ['write'],
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            handler: async (params, _context) => {
+                const { collection, filter } = RemoveDocSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(collection))
+                    throw new Error('Invalid collection name');
+                const { where, params: whereParams } = parseDocFilter(filter);
+                const query = `DELETE FROM \`${collection}\` WHERE ${where}`;
+                const result = await adapter.executeQuery(query, whereParams);
+                return { success: true, removed: result.rowsAffected ?? 0 };
+            }
+        },
+        {
+            name: 'mysql_doc_create_index',
+            title: 'MySQL Create Doc Index',
+            description: 'Create an index on document fields.',
+            group: 'docstore',
+            inputSchema: CreateDocIndexSchema,
+            requiredScopes: ['write'],
+            annotations: { readOnlyHint: false },
+            handler: async (params, _context) => {
+                const { collection, name, fields, unique } = CreateDocIndexSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(collection))
+                    throw new Error('Invalid collection name');
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
+                    throw new Error('Invalid index name');
+                for (const field of fields) {
+                    const colName = `_idx_${field.path.replace(/\./g, '_')}`;
+                    const cast = field.type === 'TEXT' ? 'CHAR(255)' : field.type;
+                    await adapter.executeQuery(`ALTER TABLE \`${collection}\` ADD COLUMN \`${colName}\` ${cast} 
+                         GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(doc, '$.${field.path}'))) STORED`);
+                }
+                const cols = fields.map(f => `\`_idx_${f.path.replace(/\./g, '_')}\``).join(', ');
+                const uniqueClause = unique ? 'UNIQUE ' : '';
+                await adapter.executeQuery(`CREATE ${uniqueClause}INDEX \`${name}\` ON \`${collection}\` (${cols})`);
+                return { success: true, index: name };
+            }
+        },
+        {
+            name: 'mysql_doc_collection_info',
+            title: 'MySQL Collection Info',
+            description: 'Get collection statistics.',
+            group: 'docstore',
+            inputSchema: CollectionInfoSchema,
+            requiredScopes: ['read'],
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: async (params, _context) => {
+                const { collection, schema } = CollectionInfoSchema.parse(params);
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(collection))
+                    throw new Error('Invalid collection name');
+                const tableInfo = await adapter.executeQuery(`
+                    SELECT TABLE_ROWS as rowCount, DATA_LENGTH as dataSize, INDEX_LENGTH as indexSize
+                    FROM information_schema.TABLES
+                    WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?
+                `, [schema ?? null, collection]);
+                const indexInfo = await adapter.executeQuery(`
+                    SELECT INDEX_NAME, COLUMN_NAME, SEQ_IN_INDEX, NON_UNIQUE
+                    FROM information_schema.STATISTICS
+                    WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?
+                `, [schema ?? null, collection]);
+                return {
+                    collection,
+                    stats: tableInfo.rows?.[0] ?? {},
+                    indexes: indexInfo.rows ?? []
+                };
+            }
+        }
+    ];
+}
+//# sourceMappingURL=docstore.js.map