@neverinfamous/mysql-mcp 2.3.0 → 3.0.0

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

@@ -15,6 +15,7 @@ import type {
 } from "../../../types/index.js";
 import type { MySQLAdapter } from "../MySQLAdapter.js";
 import https from "node:https";
+import { ZodError } from "zod";
 import {
   RouterBaseInputSchema,
   RouteNameInputSchema,
@@ -22,6 +23,15 @@ import {
   ConnectionPoolNameInputSchema,
 } from "../types/router-types.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("; ");
+}
+
 // =============================================================================
 // Router HTTP Client Helper
 // =============================================================================
@@ -31,7 +41,7 @@ import {
  */
 interface RouterUnavailableResponse {
   available: false;
-  reason: string;
+  error: string;
 }
 
 /**
@@ -120,11 +130,11 @@ async function routerFetch(
             reject(new Error(`Invalid JSON response: ${data}`));
           }
         } else {
-          reject(
-            new Error(
-              `Router API error: ${statusCode} ${res.statusMessage ?? "Unknown"}`,
-            ),
+          const err = new Error(
+            `Router API error: ${statusCode} ${res.statusMessage ?? "Unknown"}`,
           );
+          (err as Error & { statusCode: number }).statusCode = statusCode;
+          reject(err);
         }
       });
     });
@@ -166,22 +176,38 @@ async function routerFetch(
 
 /**
  * Safe wrapper for routerFetch that returns graceful responses instead of throwing.
- * Returns { success: true, data } on success or { success: false, response: { available: false, reason } } on failure.
+ * Returns { success: true, data } on success or { success: false, response: { available: false, error } } on failure.
+ * 404 responses (nonexistent route/metadata/pool) return { success: false, error } matching the standard error convention.
  */
 async function safeRouterFetch<T>(path: string): Promise<SafeRouterResult<T>> {
   try {
     const data = (await routerFetch(path)) as T;
     return { success: true, data };
   } catch (error) {
-    const reason =
+    const msg =
       error instanceof Error
         ? error.message
         : "Unknown error connecting to Router API";
+    // 404 = valid Router response for nonexistent route/metadata/pool
+    // Return { success: false, error } instead of { available: false } to
+    // distinguish "not found" from "Router is down"
+    if (
+      error instanceof Error &&
+      (error as Error & { statusCode?: number }).statusCode === 404
+    ) {
+      return {
+        success: false,
+        response: {
+          success: false,
+          error: msg,
+        } as unknown as RouterUnavailableResponse,
+      };
+    }
     return {
       success: false,
       response: {
         available: false,
-        reason,
+        error: msg,
       },
     };
   }
@@ -294,18 +320,28 @@ function createRouterRouteStatusTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { routeName } = RouteNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/routes/${encodeURIComponent(routeName)}/status`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { routeName } = RouteNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/routes/${encodeURIComponent(routeName)}/status`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          routeName,
+          status: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        routeName,
-        status: result.data,
-      };
     },
   };
 }
@@ -328,18 +364,28 @@ function createRouterRouteHealthTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { routeName } = RouteNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/routes/${encodeURIComponent(routeName)}/health`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { routeName } = RouteNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/routes/${encodeURIComponent(routeName)}/health`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          routeName,
+          health: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        routeName,
-        health: result.data,
-      };
     },
   };
 }
@@ -362,18 +408,28 @@ function createRouterRouteConnectionsTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { routeName } = RouteNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/routes/${encodeURIComponent(routeName)}/connections`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { routeName } = RouteNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/routes/${encodeURIComponent(routeName)}/connections`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          routeName,
+          connections: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        routeName,
-        connections: result.data,
-      };
     },
   };
 }
@@ -396,18 +452,28 @@ function createRouterRouteDestinationsTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { routeName } = RouteNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/routes/${encodeURIComponent(routeName)}/destinations`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { routeName } = RouteNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/routes/${encodeURIComponent(routeName)}/destinations`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          routeName,
+          destinations: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        routeName,
-        destinations: result.data,
-      };
     },
   };
 }
@@ -430,18 +496,28 @@ function createRouterRouteBlockedHostsTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { routeName } = RouteNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/routes/${encodeURIComponent(routeName)}/blockedHosts`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { routeName } = RouteNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/routes/${encodeURIComponent(routeName)}/blockedHosts`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          routeName,
+          blockedHosts: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        routeName,
-        blockedHosts: result.data,
-      };
     },
   };
 }
@@ -468,18 +544,28 @@ function createRouterMetadataStatusTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { metadataName } = MetadataNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/metadata/${encodeURIComponent(metadataName)}/status`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { metadataName } = MetadataNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/metadata/${encodeURIComponent(metadataName)}/status`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          metadataName,
+          status: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        metadataName,
-        status: result.data,
-      };
     },
   };
 }
@@ -506,18 +592,28 @@ function createRouterPoolStatusTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { poolName } = ConnectionPoolNameInputSchema.parse(params);
-      const result = await safeRouterFetch<unknown>(
-        `/connection_pool/${encodeURIComponent(poolName)}/status`,
-      );
-      if (!result.success) {
-        return result.response;
+      try {
+        const { poolName } = ConnectionPoolNameInputSchema.parse(params);
+        const result = await safeRouterFetch<unknown>(
+          `/connection_pool/${encodeURIComponent(poolName)}/status`,
+        );
+        if (!result.success) {
+          return result.response;
+        }
+        return {
+          success: true,
+          poolName,
+          status: result.data,
+        };
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
       }
-      return {
-        success: true,
-        poolName,
-        status: result.data,
-      };
     },
   };
 }

package/src/adapters/mysql/tools/schema/__tests__/constraints.test.ts

@@ -162,5 +162,18 @@ describe("Schema Constraint Tools", () => {
       // Should only call once (existence check), not the main query
       expect(mockAdapter.executeQuery).toHaveBeenCalledTimes(1);
     });
+    it("should return structured error for invalid constraint type", async () => {
+      const tool = createListConstraintsTool(
+        mockAdapter as unknown as MySQLAdapter,
+      );
+      const result = (await tool.handler(
+        { table: "users", type: "INVALID_TYPE" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+      expect(mockAdapter.executeQuery).not.toHaveBeenCalled();
+    });
   });
 });

package/src/adapters/mysql/tools/schema/__tests__/management.test.ts

@@ -78,13 +78,43 @@ describe("Schema Management Tools", () => {
       expect(result).toHaveProperty("success", true);
     });
 
-    it("should reject invalid schema names", async () => {
+    it("should return structured error for invalid schema names", async () => {
       const tool = createCreateSchemaTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler({ name: "invalid-name" }, mockContext),
-      ).rejects.toThrow("Invalid schema name");
+      const result = (await tool.handler(
+        { name: "invalid-name" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Invalid schema name");
+    });
+
+    it("should return structured error for invalid charset", async () => {
+      const tool = createCreateSchemaTool(
+        mockAdapter as unknown as MySQLAdapter,
+      );
+      const result = (await tool.handler(
+        { name: "valid_db", charset: "bad; DROP DATABASE" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Invalid charset");
+    });
+
+    it("should return structured error for invalid collation", async () => {
+      const tool = createCreateSchemaTool(
+        mockAdapter as unknown as MySQLAdapter,
+      );
+      const result = (await tool.handler(
+        { name: "valid_db", collation: "bad; DROP DATABASE" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Invalid collation");
     });
 
     it("should use custom charset and collation", async () => {
@@ -120,10 +150,10 @@ describe("Schema Management Tools", () => {
       const result = (await tool.handler(
         { name: "existing_db", ifNotExists: false },
         mockContext,
-      )) as { success: boolean; reason: string };
+      )) as { success: boolean; error: string };
 
       expect(result.success).toBe(false);
-      expect(result.reason).toContain("already exists");
+      expect(result.error).toContain("already exists");
     });
 
     it("should return skipped when schema already exists with ifNotExists", async () => {
@@ -172,28 +202,33 @@ describe("Schema Management Tools", () => {
       expect(result).toHaveProperty("success", true);
     });
 
-    it("should fail if attempting to drop system schema", async () => {
+    it("should return structured error for system schemas", async () => {
       const tool = createDropSchemaTool(mockAdapter as unknown as MySQLAdapter);
 
-      await expect(
-        tool.handler({ name: "mysql" }, mockContext),
-      ).rejects.toThrow("Cannot drop system schema");
-      await expect(
-        tool.handler({ name: "information_schema" }, mockContext),
-      ).rejects.toThrow("Cannot drop system schema");
-      await expect(
-        tool.handler({ name: "performance_schema" }, mockContext),
-      ).rejects.toThrow("Cannot drop system schema");
-      await expect(tool.handler({ name: "sys" }, mockContext)).rejects.toThrow(
-        "Cannot drop system schema",
-      );
+      for (const name of [
+        "mysql",
+        "information_schema",
+        "performance_schema",
+        "sys",
+      ]) {
+        const result = (await tool.handler({ name }, mockContext)) as {
+          success: boolean;
+          error: string;
+        };
+        expect(result.success).toBe(false);
+        expect(result.error).toBe("Cannot drop system schema");
+      }
     });
 
-    it("should reject invalid schema names", async () => {
+    it("should return structured error for invalid schema names", async () => {
       const tool = createDropSchemaTool(mockAdapter as unknown as MySQLAdapter);
-      await expect(
-        tool.handler({ name: "invalid-db" }, mockContext),
-      ).rejects.toThrow("Invalid schema name");
+      const result = (await tool.handler(
+        { name: "invalid-db" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Invalid schema name");
     });
 
     it("should drop schema without IF EXISTS if requested", async () => {
@@ -215,10 +250,10 @@ describe("Schema Management Tools", () => {
       const result = (await tool.handler(
         { name: "gone_db", ifExists: false },
         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.error).toContain("does not exist");
     });
 
     it("should return skipped when schema does not exist with ifExists", async () => {

package/src/adapters/mysql/tools/schema/__tests__/scheduled_events.test.ts

@@ -59,5 +59,16 @@ describe("Schema Event Tools", () => {
       const params = mockAdapter.executeQuery.mock.calls[0][1] as unknown[];
       expect(params).toContain("ENABLED");
     });
+    it("should return structured error for invalid status", async () => {
+      const tool = createListEventsTool(mockAdapter as unknown as MySQLAdapter);
+      const result = (await tool.handler(
+        { status: "INVALID_STATUS" },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+      expect(mockAdapter.executeQuery).not.toHaveBeenCalled();
+    });
   });
 });

package/src/adapters/mysql/tools/schema/__tests__/triggers.test.ts

@@ -51,18 +51,39 @@ describe("Schema Trigger Tools", () => {
       expect(result.schema).toBe("nonexistent_db");
     });
 
+    it("should return exists false for nonexistent table", async () => {
+      // Table existence check returns empty
+      mockAdapter.executeQuery.mockResolvedValueOnce(createMockQueryResult([]));
+
+      const tool = createListTriggersTool(
+        mockAdapter as unknown as MySQLAdapter,
+      );
+      const result = (await tool.handler(
+        { table: "nonexistent_table" },
+        mockContext,
+      )) as { exists: boolean; table: string };
+
+      expect(result.exists).toBe(false);
+      expect(result.table).toBe("nonexistent_table");
+    });
+
     it("should filter by table when provided", async () => {
-      mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+      // Table existence check returns a row
+      mockAdapter.executeQuery.mockResolvedValueOnce(
+        createMockQueryResult([{ TABLE_NAME: "users" }]),
+      );
+      // Triggers query returns empty
+      mockAdapter.executeQuery.mockResolvedValueOnce(createMockQueryResult([]));
 
       const tool = createListTriggersTool(
         mockAdapter as unknown as MySQLAdapter,
       );
       await tool.handler({ table: "users" }, mockContext);
 
-      expect(mockAdapter.executeQuery).toHaveBeenCalled();
-      const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+      expect(mockAdapter.executeQuery).toHaveBeenCalledTimes(2);
+      const call = mockAdapter.executeQuery.mock.calls[1][0] as string;
       expect(call).toContain("EVENT_OBJECT_TABLE = ?");
-      const params = mockAdapter.executeQuery.mock.calls[0][1] as unknown[];
+      const params = mockAdapter.executeQuery.mock.calls[1][1] as unknown[];
       expect(params).toContain("users");
     });
   });

package/src/adapters/mysql/tools/schema/__tests__/views.test.ts

@@ -85,17 +85,18 @@ describe("Schema View Tools", () => {
       expect(call).toContain("OR REPLACE");
     });
 
-    it("should validate view name", async () => {
+    it("should return structured error for invalid view name", async () => {
       const tool = createCreateViewTool(mockAdapter as unknown as MySQLAdapter);
-      await expect(
-        tool.handler(
-          {
-            name: "invalid-name",
-            definition: "SELECT 1",
-          },
-          mockContext,
-        ),
-      ).rejects.toThrow("Invalid view name");
+      const result = (await tool.handler(
+        {
+          name: "invalid-name",
+          definition: "SELECT 1",
+        },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Invalid view name");
     });
 
     it("should include WITH CHECK OPTION when specified", async () => {
@@ -127,10 +128,10 @@ describe("Schema View Tools", () => {
           definition: "SELECT 1",
         },
         mockContext,
-      )) as { success: boolean; reason: string };
+      )) as { success: boolean; error: string };
 
       expect(result.success).toBe(false);
-      expect(result.reason).toContain("already exists");
+      expect(result.error).toContain("already exists");
     });
 
     it("should return success false for invalid SQL definition", async () => {
@@ -145,10 +146,41 @@ describe("Schema View Tools", () => {
           definition: "SELECT * FROM nonexistent_table",
         },
         mockContext,
-      )) as { success: boolean; reason: string };
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("doesn't exist");
+    });
+    it("should return structured error for invalid algorithm", async () => {
+      const tool = createCreateViewTool(mockAdapter as unknown as MySQLAdapter);
+      const result = (await tool.handler(
+        {
+          name: "test_view",
+          definition: "SELECT 1",
+          algorithm: "INVALID",
+        },
+        mockContext,
+      )) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+      expect(mockAdapter.executeQuery).not.toHaveBeenCalled();
+    });
+
+    it("should return structured error for invalid checkOption", async () => {
+      const tool = createCreateViewTool(mockAdapter as unknown as MySQLAdapter);
+      const result = (await tool.handler(
+        {
+          name: "test_view",
+          definition: "SELECT 1",
+          checkOption: "BAD",
+        },
+        mockContext,
+      )) as { success: boolean; error: string };
 
       expect(result.success).toBe(false);
-      expect(result.reason).toContain("doesn't exist");
+      expect(result.error).toBeDefined();
+      expect(mockAdapter.executeQuery).not.toHaveBeenCalled();
     });
   });
 });