@neverinfamous/mysql-mcp 2.3.0 → 3.0.0

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

@@ -5,6 +5,9 @@
  * 9 tools total.
  */
 import { z } from "zod";
+const IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+// Valid JSON path: $, $.field, $.field.sub, $.field[0], $[0], $[*]
+const JSON_PATH_RE = /^(\$)((\.([a-zA-Z_][a-zA-Z0-9_]*))|((\[\d+\])|(\[\*\])))*$/;
 const ListCollectionsSchema = z.object({
     schema: z.string().optional().describe("Schema name (defaults to current)"),
 });
@@ -33,6 +36,7 @@ const DropCollectionSchema = z.object({
 });
 const FindSchema = z.object({
     collection: z.string(),
+    schema: z.string().optional(),
     filter: z.string().optional().describe("JSON path expression filter"),
     fields: z.array(z.string()).optional(),
     limit: z.number().default(100),
@@ -40,12 +44,14 @@ const FindSchema = z.object({
 });
 const AddDocSchema = z.object({
     collection: z.string(),
+    schema: z.string().optional(),
     documents: z
         .array(z.record(z.string(), z.unknown()))
         .describe("Documents to add"),
 });
 const ModifyDocSchema = z.object({
     collection: z.string(),
+    schema: z.string().optional(),
     filter: z
         .string()
         .describe("Filter: JSON path for existence ($.name) OR _id value for specific document"),
@@ -54,6 +60,7 @@ const ModifyDocSchema = z.object({
 });
 const RemoveDocSchema = z.object({
     collection: z.string(),
+    schema: z.string().optional(),
     filter: z
         .string()
         .describe("Filter: JSON path for existence ($.name) OR _id value for specific document"),
@@ -73,7 +80,12 @@ function parseDocFilter(filter) {
     // Check for simple field=value pattern
     const eqMatch = /^([a-zA-Z_][a-zA-Z0-9_]*)=(.+)$/.exec(filter);
     if (eqMatch) {
-        const [, field, value] = eqMatch;
+        const field = eqMatch[1] ?? "";
+        const value = eqMatch[2] ?? "";
+        // Defense-in-depth: validate field name against identifier regex
+        if (!IDENTIFIER_RE.test(field)) {
+            throw new Error(`Invalid field name in filter: "${field}". Field names must be valid identifiers.`);
+        }
         // Try to parse as number
         const numVal = Number(value);
         if (!isNaN(numVal)) {
@@ -95,6 +107,7 @@ function parseDocFilter(filter) {
 }
 const CreateDocIndexSchema = z.object({
     collection: z.string(),
+    schema: z.string().optional(),
     name: z.string(),
     fields: z.array(z.object({
         path: z.string(),
@@ -110,12 +123,35 @@ const CollectionInfoSchema = z.object({
     schema: z.string().optional(),
 });
 /**
- * Check if a collection (table) exists in the current database.
+ * Check if a collection (table) exists in the specified (or current) database.
+ * Returns a discriminated result distinguishing schema-not-found from collection-not-found.
  */
-async function checkCollectionExists(adapter, collection) {
+async function checkCollectionExists(adapter, collection, schema) {
+    // When schema is explicitly provided, check schema existence first
+    if (schema) {
+        const schemaCheck = await adapter.executeQuery("SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [schema]);
+        if (!schemaCheck.rows || schemaCheck.rows.length === 0) {
+            return { exists: false, reason: "schema", name: schema };
+        }
+    }
     const result = await adapter.executeQuery(`SELECT 1 FROM information_schema.TABLES
-     WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`, [collection]);
-    return (result.rows?.length ?? 0) > 0;
+     WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?`, [schema ?? null, collection]);
+    if ((result.rows?.length ?? 0) > 0) {
+        return { exists: true };
+    }
+    return { exists: false, reason: "collection", name: collection };
+}
+/**
+ * Build a backtick-escaped qualified table reference.
+ */
+function escapeTableRef(name, schema) {
+    return schema ? `\`${schema}\`.\`${name}\`` : `\`${name}\``;
+}
+/**
+ * Format a ZodError into a human-readable string.
+ */
+function formatZodError(err) {
+    return err.issues.map((i) => i.message).join("; ");
 }
 export function getDocStoreTools(adapter) {
     return [
@@ -128,31 +164,43 @@ export function getDocStoreTools(adapter) {
             requiredScopes: ["read"],
             annotations: { readOnlyHint: true, idempotentHint: true },
             handler: async (params, _context) => {
-                const { schema } = ListCollectionsSchema.parse(params);
-                // P154: Schema existence check when explicitly provided
-                if (schema) {
-                    const schemaCheck = await adapter.executeQuery("SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [schema]);
-                    if (!schemaCheck.rows || schemaCheck.rows.length === 0) {
-                        return { exists: false, schema };
+                try {
+                    const { schema } = ListCollectionsSchema.parse(params);
+                    // P154: Schema existence check when explicitly provided
+                    if (schema) {
+                        const schemaCheck = await adapter.executeQuery("SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [schema]);
+                        if (!schemaCheck.rows || schemaCheck.rows.length === 0) {
+                            return { exists: false, schema };
+                        }
                     }
-                }
-                const query = `
+                    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())
+                          SELECT c1.TABLE_NAME FROM information_schema.COLUMNS c1
+                          JOIN information_schema.COLUMNS c2
+                            ON c1.TABLE_SCHEMA = c2.TABLE_SCHEMA AND c1.TABLE_NAME = c2.TABLE_NAME
+                          WHERE c1.COLUMN_NAME = 'doc' AND c1.DATA_TYPE = 'json'
+                            AND c2.COLUMN_NAME = '_id'
+                            AND c1.TABLE_SCHEMA = COALESCE(?, DATABASE())
                       )`;
-                const result = await adapter.executeQuery(query, [
-                    schema ?? null,
-                    schema ?? null,
-                ]);
-                return {
-                    collections: result.rows ?? [],
-                    count: result.rows?.length ?? 0,
-                };
+                    const result = await adapter.executeQuery(query, [
+                        schema ?? null,
+                        schema ?? null,
+                    ]);
+                    return {
+                        collections: result.rows ?? [],
+                        count: result.rows?.length ?? 0,
+                    };
+                }
+                catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { success: false, error: message };
+                }
             },
         },
         {
@@ -164,38 +212,67 @@ export function getDocStoreTools(adapter) {
             requiredScopes: ["write"],
             annotations: { readOnlyHint: false },
             handler: async (params, _context) => {
-                const { name, ifNotExists, validation } = CreateCollectionSchema.parse(params);
-                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
-                    throw new Error("Invalid collection name");
-                const createClause = ifNotExists
-                    ? "CREATE TABLE IF NOT EXISTS"
-                    : "CREATE TABLE";
-                let sql = `${createClause} \`${name}\` (
+                try {
+                    const { name, schema, ifNotExists, validation } = CreateCollectionSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(name))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    const tableRef = escapeTableRef(name, schema);
+                    // Pre-check existence when ifNotExists is true so we can report accurately
+                    if (ifNotExists) {
+                        const check = await checkCollectionExists(adapter, name, schema);
+                        if (check.exists) {
+                            return {
+                                success: true,
+                                skipped: true,
+                                collection: name,
+                                reason: "Collection already exists",
+                            };
+                        }
+                        // If schema doesn't exist, report it even with ifNotExists
+                        if (check.reason === "schema") {
+                            return { exists: false, schema: check.name };
+                        }
+                    }
+                    const createClause = ifNotExists
+                        ? "CREATE TABLE IF NOT EXISTS"
+                        : "CREATE TABLE";
+                    let sql = `${createClause} ${tableRef} (
                     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 = `${createClause} \`${name}\` (
+                    if (validation?.level && validation.level !== "OFF") {
+                        const schemaJson = JSON.stringify(validation.schema ?? {});
+                        sql = `${createClause} ${tableRef} (
                         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`;
-                }
-                try {
+                    }
                     await adapter.executeQuery(sql);
+                    adapter.clearSchemaCache();
                     return { success: true, collection: name };
                 }
                 catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
                     const message = error instanceof Error ? error.message : String(error);
+                    if (message.toLowerCase().includes("unknown database")) {
+                        return {
+                            exists: false,
+                            schema: params?.schema ?? "unknown",
+                        };
+                    }
                     if (message.toLowerCase().includes("already exists")) {
                         return {
                             success: false,
-                            reason: `Collection '${name}' already exists`,
+                            error: `Collection '${params?.name ?? "unknown"}' already exists`,
                         };
                     }
-                    throw error;
+                    return { success: false, error: message };
                 }
             },
         },
@@ -208,33 +285,47 @@ export function getDocStoreTools(adapter) {
             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");
-                // Pre-check existence when ifExists is true so we can report accurately
-                if (ifExists) {
-                    const exists = await checkCollectionExists(adapter, name);
-                    if (!exists) {
-                        return {
-                            success: true,
-                            collection: name,
-                            message: "Collection did not exist",
-                        };
-                    }
-                }
                 try {
-                    await adapter.executeQuery(`DROP TABLE ${ifExists ? "IF EXISTS " : ""}\`${name}\``);
+                    const { name, schema, ifExists } = DropCollectionSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(name))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    const tableRef = escapeTableRef(name, schema);
+                    // P154: Schema existence check when explicitly provided
+                    if (schema) {
+                        const schemaCheck = await adapter.executeQuery("SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [schema]);
+                        if (!schemaCheck.rows || schemaCheck.rows.length === 0) {
+                            return { exists: false, schema };
+                        }
+                    }
+                    // Pre-check existence when ifExists is true so we can report accurately
+                    if (ifExists) {
+                        const check = await checkCollectionExists(adapter, name, schema);
+                        if (!check.exists) {
+                            return {
+                                success: true,
+                                collection: name,
+                                message: "Collection did not exist",
+                            };
+                        }
+                    }
+                    await adapter.executeQuery(`DROP TABLE ${ifExists ? "IF EXISTS " : ""}${tableRef}`);
+                    adapter.clearSchemaCache();
                     return { success: true, collection: name };
                 }
                 catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
                     const message = error instanceof Error ? error.message : String(error);
                     if (message.toLowerCase().includes("unknown table")) {
                         return {
                             success: false,
-                            reason: `Collection '${name}' does not exist`,
+                            error: `Collection '${params?.name ?? "unknown"}' does not exist`,
                         };
                     }
-                    throw error;
+                    return { success: false, error: message };
                 }
             },
         },
@@ -247,42 +338,63 @@ export function getDocStoreTools(adapter) {
             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");
-                // Check if collection exists
-                const tableCheck = await adapter.executeQuery(`SELECT 1 FROM information_schema.TABLES 
-           WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`, [collection]);
-                if (!tableCheck.rows || tableCheck.rows.length === 0) {
-                    return {
-                        exists: false,
-                        collection,
-                        documents: [],
-                        count: 0,
-                    };
+                try {
+                    const { collection, schema, filter, fields, limit, offset } = FindSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(collection))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    // Check if collection exists (with schema detection)
+                    const findCheck = await checkCollectionExists(adapter, collection, schema);
+                    if (!findCheck.exists) {
+                        if (findCheck.reason === "schema") {
+                            return { exists: false, schema: findCheck.name };
+                        }
+                        return {
+                            exists: false,
+                            collection,
+                            documents: [],
+                            count: 0,
+                        };
+                    }
+                    let selectClause = "doc";
+                    if (fields && fields.length > 0) {
+                        selectClause =
+                            "JSON_OBJECT(" +
+                                fields
+                                    .map((f) => `'${f}', JSON_EXTRACT(doc, '$.${f}')`)
+                                    .join(", ") +
+                                ") as doc";
+                    }
+                    const tableRef = escapeTableRef(collection, schema);
+                    let query = `SELECT ${selectClause} FROM ${tableRef}`;
+                    if (filter) {
+                        if (!JSON_PATH_RE.test(filter)) {
+                            return {
+                                success: false,
+                                error: `Invalid JSON path filter: "${filter}". Use a valid JSON path like $.field or $.field.sub`,
+                            };
+                        }
+                        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 };
                 }
-                let selectClause = "doc";
-                if (fields && fields.length > 0) {
-                    selectClause =
-                        "JSON_OBJECT(" +
-                            fields
-                                .map((f) => `'${f}', JSON_EXTRACT(doc, '$.${f}')`)
-                                .join(", ") +
-                            ") as doc";
+                catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { success: false, error: message };
                 }
-                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 };
             },
         },
         {
@@ -294,19 +406,34 @@ export function getDocStoreTools(adapter) {
             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");
-                if (!(await checkCollectionExists(adapter, collection))) {
-                    return { exists: false, collection };
+                try {
+                    const { collection, schema, documents } = AddDocSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(collection))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    const addCheck = await checkCollectionExists(adapter, collection, schema);
+                    if (!addCheck.exists) {
+                        return addCheck.reason === "schema"
+                            ? { exists: false, schema: addCheck.name }
+                            : { exists: false, collection };
+                    }
+                    const tableRef = escapeTableRef(collection, schema);
+                    let inserted = 0;
+                    for (const doc of documents) {
+                        doc["_id"] ??= crypto.randomUUID().replace(/-/g, "");
+                        await adapter.executeQuery(`INSERT INTO ${tableRef} (doc) VALUES (?)`, [JSON.stringify(doc)]);
+                        inserted++;
+                    }
+                    return { success: true, inserted };
                 }
-                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++;
+                catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { success: false, error: message };
                 }
-                return { success: true, inserted };
             },
         },
         {
@@ -318,29 +445,44 @@ export function getDocStoreTools(adapter) {
             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");
-                if (!(await checkCollectionExists(adapter, collection))) {
-                    return { exists: false, collection };
-                }
-                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))`);
+                try {
+                    const { collection, schema, filter, set, unset } = ModifyDocSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(collection))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    const modCheck = await checkCollectionExists(adapter, collection, schema);
+                    if (!modCheck.exists) {
+                        return modCheck.reason === "schema"
+                            ? { exists: false, schema: modCheck.name }
+                            : { exists: false, collection };
+                    }
+                    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)
+                        return { success: false, error: "No modifications specified" };
+                    const { where, params: whereParams } = parseDocFilter(filter);
+                    const tableRef = escapeTableRef(collection, schema);
+                    const query = `UPDATE ${tableRef} SET ${updates.join(", ")} WHERE ${where}`;
+                    const result = await adapter.executeQuery(query, whereParams);
+                    return { success: true, modified: result.rowsAffected ?? 0 };
                 }
-                if (unset) {
-                    for (const path of unset) {
-                        updates.push(`doc = JSON_REMOVE(doc, '$.${path}')`);
+                catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
                     }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { success: false, error: message };
                 }
-                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 };
             },
         },
         {
@@ -352,16 +494,31 @@ export function getDocStoreTools(adapter) {
             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");
-                if (!(await checkCollectionExists(adapter, collection))) {
-                    return { exists: false, collection };
+                try {
+                    const { collection, schema, filter } = RemoveDocSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(collection))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    const rmCheck = await checkCollectionExists(adapter, collection, schema);
+                    if (!rmCheck.exists) {
+                        return rmCheck.reason === "schema"
+                            ? { exists: false, schema: rmCheck.name }
+                            : { exists: false, collection };
+                    }
+                    const { where, params: whereParams } = parseDocFilter(filter);
+                    const tableRef = escapeTableRef(collection, schema);
+                    const query = `DELETE FROM ${tableRef} WHERE ${where}`;
+                    const result = await adapter.executeQuery(query, whereParams);
+                    return { success: true, removed: result.rowsAffected ?? 0 };
+                }
+                catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { success: false, error: message };
                 }
-                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 };
             },
         },
         {
@@ -373,38 +530,48 @@ export function getDocStoreTools(adapter) {
             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");
-                if (!(await checkCollectionExists(adapter, collection))) {
-                    return { exists: false, collection };
-                }
                 try {
+                    const { collection, schema, name, fields, unique } = CreateDocIndexSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(collection))
+                        return { success: false, error: "Invalid collection name" };
+                    if (schema && !IDENTIFIER_RE.test(schema))
+                        return { success: false, error: "Invalid schema name" };
+                    if (!IDENTIFIER_RE.test(name))
+                        return { success: false, error: "Invalid index name" };
+                    const idxCheck = await checkCollectionExists(adapter, collection, schema);
+                    if (!idxCheck.exists) {
+                        return idxCheck.reason === "schema"
+                            ? { exists: false, schema: idxCheck.name }
+                            : { exists: false, collection };
+                    }
+                    const tableRef = escapeTableRef(collection, schema);
                     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} 
+                        await adapter.executeQuery(`ALTER TABLE ${tableRef} 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})`);
+                    await adapter.executeQuery(`CREATE ${uniqueClause}INDEX \`${name}\` ON ${tableRef} (${cols})`);
+                    adapter.clearSchemaCache();
                     return { success: true, index: name };
                 }
                 catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
                     const message = error instanceof Error ? error.message : String(error);
                     if (message.toLowerCase().includes("duplicate column") ||
                         message.toLowerCase().includes("duplicate key")) {
                         return {
                             success: false,
-                            reason: `Index '${name}' or its generated columns already exist on '${collection}'`,
+                            error: `Index '${params?.name ?? "unknown"}' or its generated columns already exist on '${params?.collection ?? "unknown"}'`,
                         };
                     }
-                    throw error;
+                    return { success: false, error: message };
                 }
             },
         },
@@ -417,37 +584,47 @@ export function getDocStoreTools(adapter) {
             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");
-                // Check if collection exists
-                const existsCheck = await adapter.executeQuery(`SELECT 1 FROM information_schema.TABLES
-           WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?`, [schema ?? null, collection]);
-                if (!existsCheck.rows || existsCheck.rows.length === 0) {
-                    return { exists: false, collection };
-                }
-                // Get accurate row count using COUNT(*) instead of INFORMATION_SCHEMA estimate
-                const schemaClause = schema
-                    ? `\`${schema}\`.\`${collection}\``
-                    : `\`${collection}\``;
-                const countResult = await adapter.executeQuery(`SELECT COUNT(*) as rowCount FROM ${schemaClause}`);
-                const rowCount = countResult.rows?.[0]?.rowCount ?? 0;
-                const tableInfo = await adapter.executeQuery(`
+                try {
+                    const { collection, schema } = CollectionInfoSchema.parse(params);
+                    if (!IDENTIFIER_RE.test(collection))
+                        return { success: false, error: "Invalid collection name" };
+                    // Check collection existence (with schema detection)
+                    const infoCheck = await checkCollectionExists(adapter, collection, schema);
+                    if (!infoCheck.exists) {
+                        return infoCheck.reason === "schema"
+                            ? { exists: false, schema: infoCheck.name }
+                            : { exists: false, collection };
+                    }
+                    // Get accurate row count using COUNT(*) instead of INFORMATION_SCHEMA estimate
+                    const schemaClause = schema
+                        ? `\`${schema}\`.\`${collection}\``
+                        : `\`${collection}\``;
+                    const countResult = await adapter.executeQuery(`SELECT COUNT(*) as rowCount FROM ${schemaClause}`);
+                    const rowCount = countResult.rows?.[0]?.rowCount ?? 0;
+                    const tableInfo = await adapter.executeQuery(`
                     SELECT 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(`
+                    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]);
-                const stats = tableInfo.rows?.[0] ?? {};
-                return {
-                    collection,
-                    stats: { rowCount, ...stats },
-                    indexes: indexInfo.rows ?? [],
-                };
+                    const stats = tableInfo.rows?.[0] ?? {};
+                    return {
+                        collection,
+                        stats: { rowCount, ...stats },
+                        indexes: indexInfo.rows ?? [],
+                    };
+                }
+                catch (error) {
+                    if (error instanceof z.ZodError) {
+                        return { success: false, error: formatZodError(error) };
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { success: false, error: message };
+                }
             },
         },
     ];