@neverinfamous/mysql-mcp 2.3.0 → 3.0.0

package/src/adapters/mysql/tools/sysschema/resources.ts

@@ -5,13 +5,22 @@
  * 3 tools: schema_stats, innodb_lock_waits, memory_summary.
  */
 
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import type { MySQLAdapter } from "../../MySQLAdapter.js";
 import type {
   ToolDefinition,
   RequestContext,
 } from "../../../../types/index.js";
 
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Extract human-readable messages from a ZodError instead of raw JSON array */
+function formatZodError(error: ZodError): string {
+  return error.issues.map((i) => i.message).join("; ");
+}
+
 // =============================================================================
 // Zod Schemas
 // =============================================================================
@@ -45,35 +54,41 @@ export function createSysSchemaStatsTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { schema, limit } = z
-        .object({
-          schema: z.string().optional(),
-          limit: z.number().default(10),
-        })
-        .parse(params);
+      try {
+        const { schema, limit } = z
+          .object({
+            schema: z.string().optional(),
+            limit: z.number().default(10),
+          })
+          .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 };
+        // 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 {
+              success: false,
+              error: `Schema '${schema}' does not exist`,
+            };
+          }
         }
-      }
 
-      // Resolve actual database name for response
-      let resolvedSchema = schema;
-      if (!resolvedSchema) {
-        const dbResult = await adapter.executeQuery("SELECT DATABASE() as db");
-        const rows = dbResult.rows ?? [];
-        const dbRow = rows[0] as Record<string, unknown> | undefined;
-        resolvedSchema = (dbRow?.["db"] as string) ?? "unknown";
-      }
+        // Resolve actual database name for response
+        let resolvedSchema = schema;
+        if (!resolvedSchema) {
+          const dbResult = await adapter.executeQuery(
+            "SELECT DATABASE() as db",
+          );
+          const rows = dbResult.rows ?? [];
+          const dbRow = rows[0] as Record<string, unknown> | undefined;
+          resolvedSchema = (dbRow?.["db"] as string) ?? "unknown";
+        }
 
-      // Get table statistics
-      const tableStatsQuery = `
+        // Get table statistics
+        const tableStatsQuery = `
                 SELECT 
                     table_schema,
                     table_name,
@@ -97,8 +112,8 @@ export function createSysSchemaStatsTool(
                 LIMIT ${String(limit)}
             `;
 
-      // Get index statistics
-      const indexStatsQuery = `
+        // Get index statistics
+        const indexStatsQuery = `
                 SELECT 
                     table_schema,
                     table_name,
@@ -117,8 +132,8 @@ export function createSysSchemaStatsTool(
                 LIMIT ${String(limit)}
             `;
 
-      // Get auto-increment status
-      const autoIncQuery = `
+        // Get auto-increment status
+        const autoIncQuery = `
                 SELECT 
                     table_schema,
                     table_name,
@@ -132,21 +147,28 @@ export function createSysSchemaStatsTool(
                 LIMIT ${String(limit)}
             `;
 
-      const [tableStats, indexStats, autoIncStats] = await Promise.all([
-        adapter.executeQuery(tableStatsQuery, [schema ?? null]),
-        adapter.executeQuery(indexStatsQuery, [schema ?? null]),
-        adapter.executeQuery(autoIncQuery, [schema ?? null]),
-      ]);
+        const [tableStats, indexStats, autoIncStats] = await Promise.all([
+          adapter.executeQuery(tableStatsQuery, [schema ?? null]),
+          adapter.executeQuery(indexStatsQuery, [schema ?? null]),
+          adapter.executeQuery(autoIncQuery, [schema ?? null]),
+        ]);
 
-      return {
-        tableStatistics: tableStats.rows ?? [],
-        indexStatistics: indexStats.rows ?? [],
-        autoIncrementStatus: autoIncStats.rows ?? [],
-        tableStatisticsCount: (tableStats.rows ?? []).length,
-        indexStatisticsCount: (indexStats.rows ?? []).length,
-        autoIncrementStatusCount: (autoIncStats.rows ?? []).length,
-        schemaName: resolvedSchema,
-      };
+        return {
+          tableStatistics: tableStats.rows ?? [],
+          indexStatistics: indexStats.rows ?? [],
+          autoIncrementStatus: autoIncStats.rows ?? [],
+          tableStatisticsCount: (tableStats.rows ?? []).length,
+          indexStatisticsCount: (indexStats.rows ?? []).length,
+          autoIncrementStatusCount: (autoIncStats.rows ?? []).length,
+          schemaName: resolvedSchema,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+      }
     },
   };
 }
@@ -170,9 +192,10 @@ export function createSysInnoDBLockWaitsTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { limit } = LimitSchema.parse(params);
+      try {
+        const { limit } = LimitSchema.parse(params);
 
-      const query = `
+        const query = `
                 SELECT 
                     wait_started,
                     wait_age,
@@ -198,12 +221,19 @@ export function createSysInnoDBLockWaitsTool(
                 LIMIT ${String(limit)}
             `;
 
-      const result = await adapter.executeQuery(query);
-      return {
-        lockWaits: result.rows,
-        count: result.rows?.length ?? 0,
-        hasContention: (result.rows?.length ?? 0) > 0,
-      };
+        const result = await adapter.executeQuery(query);
+        return {
+          lockWaits: result.rows,
+          count: result.rows?.length ?? 0,
+          hasContention: (result.rows?.length ?? 0) > 0,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+      }
     },
   };
 }
@@ -226,10 +256,11 @@ export function createSysMemorySummaryTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { limit } = LimitSchema.parse(params);
+      try {
+        const { limit } = LimitSchema.parse(params);
 
-      // Global memory summary
-      const globalQuery = `
+        // Global memory summary
+        const globalQuery = `
                 SELECT 
                     event_name,
                     current_count,
@@ -243,8 +274,8 @@ export function createSysMemorySummaryTool(
                 LIMIT ${String(limit)}
             `;
 
-      // Memory by user
-      const userQuery = `
+        // Memory by user
+        const userQuery = `
                 SELECT 
                     user,
                     current_count_used,
@@ -257,17 +288,24 @@ export function createSysMemorySummaryTool(
                 LIMIT ${String(limit)}
             `;
 
-      const [globalStats, userStats] = await Promise.all([
-        adapter.executeQuery(globalQuery),
-        adapter.executeQuery(userQuery),
-      ]);
+        const [globalStats, userStats] = await Promise.all([
+          adapter.executeQuery(globalQuery),
+          adapter.executeQuery(userQuery),
+        ]);
 
-      return {
-        globalMemory: globalStats.rows ?? [],
-        memoryByUser: userStats.rows ?? [],
-        globalMemoryCount: (globalStats.rows ?? []).length,
-        memoryByUserCount: (userStats.rows ?? []).length,
-      };
+        return {
+          globalMemory: globalStats.rows ?? [],
+          memoryByUser: userStats.rows ?? [],
+          globalMemoryCount: (globalStats.rows ?? []).length,
+          memoryByUserCount: (userStats.rows ?? []).length,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+      }
     },
   };
 }

package/src/adapters/mysql/tools/text/__tests__/fulltext.test.ts

@@ -93,14 +93,14 @@ describe("Text Fulltext Tools", () => {
           indexName: "ft_idx",
         },
         mockContext,
-      )) as { success: boolean; reason: string };
+      )) as { success: boolean; error: string };
 
       expect(result.success).toBe(false);
-      expect(result.reason).toContain("already exists");
-      expect(result.reason).toContain("ft_idx");
+      expect(result.error).toContain("already exists");
+      expect(result.error).toContain("ft_idx");
     });
 
-    it("should rethrow non-duplicate errors", async () => {
+    it("should return structured error for non-duplicate errors", async () => {
       mockAdapter.executeQuery.mockRejectedValue(
         new Error("Connection refused"),
       );
@@ -108,12 +108,36 @@ describe("Text Fulltext Tools", () => {
       const tool = createFulltextCreateTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          { table: "articles", columns: ["title"], indexName: "ft_idx" },
-          mockContext,
-        ),
-      ).rejects.toThrow("Connection refused");
+      const result = (await tool.handler(
+        { table: "articles", columns: ["title"], indexName: "ft_idx" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Connection refused");
+    });
+
+    it("should return structured error for nonexistent column", async () => {
+      const colError = new Error(
+        "Key column 'nonexistent_col' doesn't exist in table",
+      );
+      (colError as Error & { errno?: number }).errno = 1072;
+      mockAdapter.executeQuery.mockRejectedValue(colError);
+
+      const tool = createFulltextCreateTool(
+        mockAdapter as unknown as MySQLAdapter,
+      );
+      const result = (await tool.handler(
+        {
+          table: "articles",
+          columns: ["nonexistent_col"],
+          indexName: "ft_idx",
+        },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Key column");
     });
 
     it("should return exists:false for nonexistent table", async () => {
@@ -170,22 +194,26 @@ describe("Text Fulltext Tools", () => {
       const result = (await tool.handler(
         { table: "articles", indexName: "ft_nonexistent" },
         mockContext,
-      )) as { success: boolean; reason: string };
+      )) as { success: boolean; error: string };
 
       expect(result.success).toBe(false);
-      expect(result.reason).toContain("does not exist");
-      expect(result.reason).toContain("ft_nonexistent");
+      expect(result.error).toContain("does not exist");
+      expect(result.error).toContain("ft_nonexistent");
     });
 
-    it("should rethrow non-drop errors", async () => {
+    it("should return structured error for non-drop errors", async () => {
       mockAdapter.executeQuery.mockRejectedValue(new Error("Access denied"));
 
       const tool = createFulltextDropTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler({ table: "articles", indexName: "ft_idx" }, mockContext),
-      ).rejects.toThrow("Access denied");
+      const result = (await tool.handler(
+        { table: "articles", indexName: "ft_idx" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Access denied");
     });
 
     it("should return exists:false for nonexistent table", async () => {

package/src/adapters/mysql/tools/text/fulltext.ts

@@ -15,6 +15,12 @@ import {
   FulltextCreateSchemaBase,
   FulltextSearchSchema,
   FulltextSearchSchemaBase,
+  FulltextDropSchema,
+  FulltextDropSchemaBase,
+  FulltextBooleanSchema,
+  FulltextBooleanSchemaBase,
+  FulltextExpandSchema,
+  FulltextExpandSchemaBase,
 } from "../../types.js";
 import { z } from "zod";
 import {
@@ -99,33 +105,37 @@ export function createFulltextCreateTool(
         if (isDuplicateKeyError(err)) {
           return {
             success: false,
-            reason: `Index '${name}' already exists on table '${table}'`,
+            error: `Index '${name}' already exists on table '${table}'`,
           };
         }
         const msg = err instanceof Error ? err.message : String(err);
+        // Distinguish column-not-found (errno 1072) from table-not-found
+        if (
+          (err as Error & { errno?: number }).errno === 1072 ||
+          msg.includes("Key column") ||
+          msg.includes("Column '")
+        ) {
+          return { success: false, error: msg };
+        }
         if (msg.includes("doesn't exist")) {
           return { exists: false, table };
         }
-        throw err;
+        return { success: false, error: msg };
       }
 
+      adapter.clearSchemaCache();
       return { success: true, indexName: name, columns };
     },
   };
 }
 
-const FulltextDropSchema = z.object({
-  table: z.string().describe("Table containing the index"),
-  indexName: z.string().describe("Name of the FULLTEXT index to drop"),
-});
-
 export function createFulltextDropTool(adapter: MySQLAdapter): ToolDefinition {
   return {
     name: "mysql_fulltext_drop",
     title: "MySQL Drop FULLTEXT Index",
     description: "Drop a FULLTEXT index from a table.",
     group: "fulltext",
-    inputSchema: FulltextDropSchema,
+    inputSchema: FulltextDropSchemaBase,
     requiredScopes: ["write"],
     annotations: {
       readOnlyHint: false,
@@ -146,16 +156,17 @@ export function createFulltextDropTool(adapter: MySQLAdapter): ToolDefinition {
         if (isCantDropKeyError(err)) {
           return {
             success: false,
-            reason: `Index '${indexName}' does not exist on table '${table}'`,
+            error: `Index '${indexName}' does not exist on table '${table}'`,
           };
         }
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.includes("doesn't exist")) {
           return { exists: false, table };
         }
-        throw err;
+        return { success: false, error: msg };
       }
 
+      adapter.clearSchemaCache();
       return { success: true, indexName, table };
     },
   };
@@ -232,32 +243,21 @@ export function createFulltextSearchTool(
 export function createFulltextBooleanTool(
   adapter: MySQLAdapter,
 ): ToolDefinition {
-  const schema = z.object({
-    table: z.string(),
-    columns: z.array(z.string()),
-    query: z.string().describe("Boolean search query with +, -, *, etc."),
-    maxLength: z
-      .number()
-      .optional()
-      .describe(
-        "Optional max characters per text column in results. Truncates with '...' if exceeded.",
-      ),
-  });
-
   return {
     name: "mysql_fulltext_boolean",
     title: "MySQL FULLTEXT Boolean",
     description:
       "Perform FULLTEXT search in BOOLEAN MODE with operators (+, -, *, etc.).",
     group: "fulltext",
-    inputSchema: schema,
+    inputSchema: FulltextBooleanSchemaBase,
     requiredScopes: ["read"],
     annotations: {
       readOnlyHint: true,
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, columns, query, maxLength } = schema.parse(params);
+      const { table, columns, query, maxLength } =
+        FulltextBooleanSchema.parse(params);
 
       // Validate inputs
       validateQualifiedIdentifier(table, "table");
@@ -289,32 +289,21 @@ export function createFulltextBooleanTool(
 export function createFulltextExpandTool(
   adapter: MySQLAdapter,
 ): ToolDefinition {
-  const schema = z.object({
-    table: z.string(),
-    columns: z.array(z.string()),
-    query: z.string().describe("Search query to expand"),
-    maxLength: z
-      .number()
-      .optional()
-      .describe(
-        "Optional max characters per text column in results. Truncates with '...' if exceeded.",
-      ),
-  });
-
   return {
     name: "mysql_fulltext_expand",
     title: "MySQL FULLTEXT Expand",
     description:
       "Perform FULLTEXT search WITH QUERY EXPANSION for finding related terms.",
     group: "fulltext",
-    inputSchema: schema,
+    inputSchema: FulltextExpandSchemaBase,
     requiredScopes: ["read"],
     annotations: {
       readOnlyHint: true,
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, columns, query, maxLength } = schema.parse(params);
+      const { table, columns, query, maxLength } =
+        FulltextExpandSchema.parse(params);
 
       // Validate inputs
       validateQualifiedIdentifier(table, "table");

package/src/adapters/mysql/tools/transactions.ts

@@ -7,8 +7,10 @@
 
 import type { MySQLAdapter } from "../MySQLAdapter.js";
 import type { ToolDefinition, RequestContext } from "../../../types/index.js";
+import { ZodError } from "zod";
 import {
   TransactionBeginSchema,
+  TransactionBeginSchemaBase,
   TransactionIdSchema,
   TransactionIdSchemaBase,
   TransactionSavepointSchema,
@@ -17,6 +19,11 @@ import {
   TransactionExecuteSchemaBase,
 } from "../types.js";
 
+/** Extract human-readable messages from a ZodError instead of raw JSON array */
+function formatZodError(error: ZodError): string {
+  return error.issues.map((i) => i.message).join("; ");
+}
+
 /**
  * Get all transaction tools
  */
@@ -42,20 +49,28 @@ function createTransactionBeginTool(adapter: MySQLAdapter): ToolDefinition {
     description:
       "Begin a new transaction with optional isolation level. Returns a transaction ID for subsequent operations.",
     group: "transactions",
-    inputSchema: TransactionBeginSchema,
+    inputSchema: TransactionBeginSchemaBase,
     requiredScopes: ["write"],
     annotations: {
       readOnlyHint: false,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { isolationLevel } = TransactionBeginSchema.parse(params);
-      const transactionId = await adapter.beginTransaction(isolationLevel);
-      return {
-        transactionId,
-        isolationLevel: isolationLevel ?? "REPEATABLE READ (default)",
-        message:
-          "Transaction started. Use transactionId for commit/rollback operations.",
-      };
+      try {
+        const { isolationLevel } = TransactionBeginSchema.parse(params);
+        const transactionId = await adapter.beginTransaction(isolationLevel);
+        return {
+          transactionId,
+          isolationLevel: isolationLevel ?? "REPEATABLE READ (default)",
+          message:
+            "Transaction started. Use transactionId for commit/rollback operations.",
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        const msg = String(error instanceof Error ? error.message : error);
+        return { success: false, error: msg };
+      }
     },
   };
 }
@@ -85,7 +100,7 @@ function createTransactionCommitTool(adapter: MySQLAdapter): ToolDefinition {
         };
       } catch (error) {
         const msg = String(error instanceof Error ? error.message : error);
-        return { success: false, reason: msg };
+        return { success: false, error: msg };
       }
     },
   };
@@ -116,7 +131,7 @@ function createTransactionRollbackTool(adapter: MySQLAdapter): ToolDefinition {
         };
       } catch (error) {
         const msg = String(error instanceof Error ? error.message : error);
-        return { success: false, reason: msg };
+        return { success: false, error: msg };
       }
     },
   };
@@ -145,13 +160,13 @@ function createTransactionSavepointTool(adapter: MySQLAdapter): ToolDefinition {
       if (!connection) {
         return {
           success: false,
-          reason: `Transaction not found: ${transactionId}`,
+          error: `Transaction not found: ${transactionId}`,
         };
       }
 
       // Validate savepoint name
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(savepoint)) {
-        return { success: false, reason: "Invalid savepoint name" };
+        return { success: false, error: "Invalid savepoint name" };
       }
 
       try {
@@ -160,7 +175,7 @@ function createTransactionSavepointTool(adapter: MySQLAdapter): ToolDefinition {
         return { success: true, transactionId, savepoint };
       } catch (error) {
         const msg = String(error instanceof Error ? error.message : error);
-        return { success: false, reason: msg };
+        return { success: false, error: msg };
       }
     },
   };
@@ -188,12 +203,12 @@ function createTransactionReleaseTool(adapter: MySQLAdapter): ToolDefinition {
       if (!connection) {
         return {
           success: false,
-          reason: `Transaction not found: ${transactionId}`,
+          error: `Transaction not found: ${transactionId}`,
         };
       }
 
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(savepoint)) {
-        return { success: false, reason: "Invalid savepoint name" };
+        return { success: false, error: "Invalid savepoint name" };
       }
 
       try {
@@ -207,7 +222,7 @@ function createTransactionReleaseTool(adapter: MySQLAdapter): ToolDefinition {
         };
       } catch (error) {
         const msg = String(error instanceof Error ? error.message : error);
-        return { success: false, reason: msg };
+        return { success: false, error: msg };
       }
     },
   };
@@ -237,12 +252,12 @@ function createTransactionRollbackToTool(
       if (!connection) {
         return {
           success: false,
-          reason: `Transaction not found: ${transactionId}`,
+          error: `Transaction not found: ${transactionId}`,
         };
       }
 
       if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(savepoint)) {
-        return { success: false, reason: "Invalid savepoint name" };
+        return { success: false, error: "Invalid savepoint name" };
       }
 
       try {
@@ -256,7 +271,7 @@ function createTransactionRollbackToTool(
         };
       } catch (error) {
         const msg = String(error instanceof Error ? error.message : error);
-        return { success: false, reason: msg };
+        return { success: false, error: msg };
       }
     },
   };
@@ -278,13 +293,23 @@ function createTransactionExecuteTool(adapter: MySQLAdapter): ToolDefinition {
       readOnlyHint: false,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { statements, isolationLevel } =
-        TransactionExecuteSchema.parse(params);
+      let parsedParams;
+      try {
+        parsedParams = TransactionExecuteSchema.parse(params);
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        const msg = String(error instanceof Error ? error.message : error);
+        return { success: false, error: msg };
+      }
+
+      const { statements, isolationLevel } = parsedParams;
 
       if (statements.length === 0) {
         return {
           success: false,
-          reason:
+          error:
             "No statements provided. Pass at least one SQL statement in statements (or queries alias).",
         };
       }
@@ -334,7 +359,7 @@ function createTransactionExecuteTool(adapter: MySQLAdapter): ToolDefinition {
         const msg = String(error instanceof Error ? error.message : error);
         return {
           success: false,
-          reason: `Transaction failed and was rolled back: ${msg}`,
+          error: `Transaction failed and was rolled back: ${msg}`,
           rolledBack: true,
         };
       }