@neverinfamous/mysql-mcp 2.3.0 → 3.0.0

package/src/adapters/mysql/tools/shell/restore.ts

@@ -7,6 +7,7 @@
 import { promises as fs } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+import { ZodError } from "zod";
 import type {
   ToolDefinition,
   RequestContext,
@@ -17,6 +18,11 @@ import {
 } from "../../types/shell-types.js";
 import { getShellConfig, execShellJS, execMySQLShell } from "./common.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("; ");
+}
+
 /**
  * Load dump to instance
  */
@@ -210,59 +216,67 @@ export function createShellRunScriptTool(): ToolDefinition {
       openWorldHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { script, language, timeout } =
-        ShellRunScriptInputSchema.parse(params);
-      const config = getShellConfig();
+      try {
+        const { script, language, timeout } =
+          ShellRunScriptInputSchema.parse(params);
+        const config = getShellConfig();
 
-      // Build command based on language
-      let langFlag: string;
-      switch (language) {
-        case "js":
-          langFlag = "--js";
-          break;
-        case "py":
-          langFlag = "--py";
-          break;
-        case "sql":
-          langFlag = "--sql";
-          break;
-      }
+        // Build command based on language
+        let langFlag: string;
+        switch (language) {
+          case "js":
+            langFlag = "--js";
+            break;
+          case "py":
+            langFlag = "--py";
+            break;
+          case "sql":
+            langFlag = "--sql";
+            break;
+        }
 
-      let result;
-      // SQL scripts with comments or multi-line content break when passed via -e
-      // Use --file approach for SQL to properly handle all syntax
-      if (language === "sql") {
-        // Create a secure temp directory via mkdtemp (restrictive permissions,
-        // unique path) to avoid CodeQL js/insecure-temporary-file alert.
-        const tempDir = await fs.mkdtemp(join(tmpdir(), `mysqlsh_script_`));
-        const tempFile = join(tempDir, "script.sql");
-        try {
-          await fs.writeFile(tempFile, script, "utf8");
-          const args = [
-            "--uri",
-            config.connectionUri,
-            langFlag,
-            "--file",
-            tempFile,
-          ];
+        let result;
+        // SQL scripts with comments or multi-line content break when passed via -e
+        // Use --file approach for SQL to properly handle all syntax
+        if (language === "sql") {
+          // Create a secure temp directory via mkdtemp (restrictive permissions,
+          // unique path) to avoid CodeQL js/insecure-temporary-file alert.
+          const tempDir = await fs.mkdtemp(join(tmpdir(), `mysqlsh_script_`));
+          const tempFile = join(tempDir, "script.sql");
+          try {
+            await fs.writeFile(tempFile, script, "utf8");
+            const args = [
+              "--uri",
+              config.connectionUri,
+              langFlag,
+              "--file",
+              tempFile,
+            ];
+            result = await execMySQLShell(args, { timeout });
+          } finally {
+            // Cleanup temp directory and its contents
+            await fs.rm(tempDir, { recursive: true }).catch(() => void 0);
+          }
+        } else {
+          // JS and Python work fine with -e
+          const args = ["--uri", config.connectionUri, langFlag, "-e", script];
           result = await execMySQLShell(args, { timeout });
-        } finally {
-          // Cleanup temp directory and its contents
-          await fs.rm(tempDir, { recursive: true }).catch(() => void 0);
         }
-      } else {
-        // JS and Python work fine with -e
-        const args = ["--uri", config.connectionUri, langFlag, "-e", script];
-        result = await execMySQLShell(args, { timeout });
-      }
 
-      return {
-        success: result.exitCode === 0,
-        language,
-        exitCode: result.exitCode,
-        stdout: result.stdout,
-        stderr: result.stderr,
-      };
+        return {
+          success: result.exitCode === 0,
+          language,
+          exitCode: result.exitCode,
+          stdout: result.stdout,
+          stderr: result.stderr,
+        };
+      } 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/spatial/__tests__/operations.test.ts

@@ -272,29 +272,37 @@ describe("Spatial Operations Tools", () => {
       expect(result.wkt).toBe("POINT(10 20)");
     });
 
-    it("should throw if neither geometry nor geoJson provided", async () => {
+    it("should return structured error if neither geometry nor geoJson provided", async () => {
       const tool = createSpatialGeoJSONTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      // Use type assertion or casting to bypass TS error for invalid input in test
-      // Zod parser will catch it, or refiner.
-      // Wait, Zod schema has refine check.
-      await expect(tool.handler({}, mockContext)).rejects.toThrow();
+      const result = await tool.handler({}, mockContext);
+      expect(result).toEqual({
+        success: false,
+        error: expect.stringContaining(
+          "Either geometry or geoJson must be provided",
+        ),
+      });
     });
 
-    it("should throw if both geometry and geoJson provided", async () => {
+    it("should return structured error if both geometry and geoJson provided", async () => {
       const tool = createSpatialGeoJSONTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          {
-            geometry: "POINT(0 0)",
-            geoJson: "{}",
-          },
-          mockContext,
+      const result = await tool.handler(
+        {
+          geometry: "POINT(0 0)",
+          geoJson: "{}",
+        },
+        mockContext,
+      );
+
+      expect(result).toEqual({
+        success: false,
+        error: expect.stringContaining(
+          "Either geometry or geoJson must be provided",
         ),
-      ).rejects.toThrow();
+      });
     });
   });
 });

package/src/adapters/mysql/tools/spatial/__tests__/queries.test.ts

@@ -97,32 +97,38 @@ describe("Spatial Queries Tools", () => {
       const tool = createSpatialDistanceTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          {
-            table: "invalid; drop table",
-            spatialColumn: "geom",
-            point: { longitude: 0, latitude: 0 },
-          },
-          mockContext,
-        ),
-      ).rejects.toThrow("Invalid table name");
+      const result = await tool.handler(
+        {
+          table: "invalid; drop table",
+          spatialColumn: "geom",
+          point: { longitude: 0, latitude: 0 },
+        },
+        mockContext,
+      );
+
+      expect(result).toEqual({
+        success: false,
+        error: expect.stringContaining("Invalid table name"),
+      });
     });
 
     it("should validate column name", async () => {
       const tool = createSpatialDistanceTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          {
-            table: "valid_table",
-            spatialColumn: "invalid column",
-            point: { longitude: 0, latitude: 0 },
-          },
-          mockContext,
-        ),
-      ).rejects.toThrow("Invalid column name");
+      const result = await tool.handler(
+        {
+          table: "valid_table",
+          spatialColumn: "invalid column",
+          point: { longitude: 0, latitude: 0 },
+        },
+        mockContext,
+      );
+
+      expect(result).toEqual({
+        success: false,
+        error: "Invalid column name",
+      });
     });
 
     it("should handle undefined rows result", async () => {
@@ -200,17 +206,19 @@ describe("Spatial Queries Tools", () => {
       const tool = createSpatialDistanceSphereTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          {
-            table: "invalid",
-            spatialColumn: "bad-column", // Hyphens not allowed by simple regex maybe?
-            // Regex is /^[a-zA-Z_][a-zA-Z0-9_]*$/ so hyphen is invalid
-            point: { longitude: 0, latitude: 0 },
-          },
-          mockContext,
-        ),
-      ).rejects.toThrow("Invalid column name");
+      const result = await tool.handler(
+        {
+          table: "invalid",
+          spatialColumn: "bad-column",
+          point: { longitude: 0, latitude: 0 },
+        },
+        mockContext,
+      );
+
+      expect(result).toEqual({
+        success: false,
+        error: "Invalid column name",
+      });
     });
   });
 
@@ -267,16 +275,19 @@ describe("Spatial Queries Tools", () => {
       const tool = createSpatialContainsTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          {
-            table: "bad-table",
-            spatialColumn: "boundary",
-            polygon: "P",
-          },
-          mockContext,
-        ),
-      ).rejects.toThrow("Invalid table name");
+      const result = await tool.handler(
+        {
+          table: "bad-table",
+          spatialColumn: "boundary",
+          polygon: "P",
+        },
+        mockContext,
+      );
+
+      expect(result).toEqual({
+        success: false,
+        error: expect.stringContaining("Invalid table name"),
+      });
     });
   });
 
@@ -333,16 +344,19 @@ describe("Spatial Queries Tools", () => {
       const tool = createSpatialWithinTool(
         mockAdapter as unknown as MySQLAdapter,
       );
-      await expect(
-        tool.handler(
-          {
-            table: "t",
-            spatialColumn: "bad col",
-            geometry: "P",
-          },
-          mockContext,
-        ),
-      ).rejects.toThrow("Invalid column name");
+      const result = await tool.handler(
+        {
+          table: "t",
+          spatialColumn: "bad col",
+          geometry: "P",
+        },
+        mockContext,
+      );
+
+      expect(result).toEqual({
+        success: false,
+        error: "Invalid column name",
+      });
     });
   });
 });

package/src/adapters/mysql/tools/spatial/geometry.ts

@@ -5,7 +5,7 @@
  * 2 tools: point and polygon creation.
  */
 
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import type { MySQLAdapter } from "../../MySQLAdapter.js";
 import type {
   ToolDefinition,
@@ -16,6 +16,16 @@ import type {
 // 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("; ");
+}
+
+/** Strip verbose adapter prefixes from MySQL error messages */
+function stripErrorPrefix(msg: string): string {
+  return msg.replace(/^(Query failed:\s*)?(Execute failed:\s*)?/i, "");
+}
+
 /**
  * Parse GeoJSON result from MySQL.
  * MySQL returns ST_AsGeoJSON as a string, but mysql2 driver may auto-parse JSON.
@@ -73,9 +83,9 @@ export function createSpatialPointTool(adapter: MySQLAdapter): ToolDefinition {
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { longitude, latitude, srid } = PointSchema.parse(params);
-
       try {
+        const { longitude, latitude, srid } = PointSchema.parse(params);
+
         const result = await adapter.executeQuery(
           `SELECT ST_AsText(ST_SRID(ST_GeomFromText('POINT(${String(longitude)} ${String(latitude)})', ${String(srid)}, 'axis-order=long-lat'), ${String(srid)})) as wkt,
                         ST_AsGeoJSON(ST_SRID(ST_GeomFromText('POINT(${String(longitude)} ${String(latitude)})', ${String(srid)}, 'axis-order=long-lat'), ${String(srid)})) as geoJson`,
@@ -90,8 +100,11 @@ export function createSpatialPointTool(adapter: MySQLAdapter): ToolDefinition {
           latitude,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
         const msg = error instanceof Error ? error.message : String(error);
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -115,9 +128,9 @@ export function createSpatialPolygonTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { coordinates, srid } = PolygonSchema.parse(params);
-
       try {
+        const { coordinates, srid } = PolygonSchema.parse(params);
+
         // Build WKT polygon
         const rings = coordinates.map(
           (ring) =>
@@ -144,8 +157,11 @@ export function createSpatialPolygonTool(
           srid,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
         const msg = error instanceof Error ? error.message : String(error);
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };

package/src/adapters/mysql/tools/spatial/operations.ts

@@ -5,7 +5,7 @@
  * 4 tools: intersection, buffer, transform, geojson.
  */
 
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import type { MySQLAdapter } from "../../MySQLAdapter.js";
 import type {
   ToolDefinition,
@@ -16,6 +16,16 @@ import type {
 // 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("; ");
+}
+
+/** Strip verbose adapter prefixes from MySQL error messages */
+function stripErrorPrefix(msg: string): string {
+  return msg.replace(/^(Query failed:\s*)?(Execute failed:\s*)?/i, "");
+}
+
 /**
  * Parse GeoJSON result from MySQL.
  * MySQL returns ST_AsGeoJSON as a string, but mysql2 driver may auto-parse JSON.
@@ -55,10 +65,9 @@ const BufferSchema = z.object({
   segments: z
     .number()
     .int()
-    .min(1)
     .default(8)
     .describe(
-      "Number of segments per quarter-circle for buffer polygon approximation (default: 8, MySQL default: 32). Lower values produce simpler polygons with smaller payloads. Only effective with Cartesian geometries (SRID 0); geographic SRIDs use MySQL's internal algorithm.",
+      "Number of segments per quarter-circle for buffer polygon approximation (default: 8, MySQL default: 32). Must be >= 1. Lower values produce simpler polygons with smaller payloads. Only effective with Cartesian geometries (SRID 0); geographic SRIDs use MySQL's internal algorithm.",
     ),
   precision: z
     .number()
@@ -77,19 +86,19 @@ const TransformSchema = z.object({
   toSrid: z.number().describe("Target SRID"),
 });
 
-const GeoJSONSchema = z
-  .object({
-    geometry: z
-      .string()
-      .optional()
-      .describe("WKT geometry to convert to GeoJSON"),
-    geoJson: z.string().optional().describe("GeoJSON to convert to WKT"),
-    srid: z.number().default(4326).describe("SRID for conversion"),
-  })
-  .refine(
-    (data) => (data.geometry !== undefined) !== (data.geoJson !== undefined),
-    "Either geometry or geoJson must be provided, but not both",
-  );
+const GeoJSONSchemaBase = z.object({
+  geometry: z
+    .string()
+    .optional()
+    .describe("WKT geometry to convert to GeoJSON"),
+  geoJson: z.string().optional().describe("GeoJSON to convert to WKT"),
+  srid: z.number().default(4326).describe("SRID for conversion"),
+});
+
+const GeoJSONSchema = GeoJSONSchemaBase.refine(
+  (data) => (data.geometry !== undefined) !== (data.geoJson !== undefined),
+  "Either geometry or geoJson must be provided, but not both",
+);
 
 /**
  * Calculate intersection of two geometries
@@ -109,9 +118,9 @@ export function createSpatialIntersectionTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { geometry1, geometry2, srid } = IntersectionSchema.parse(params);
-
       try {
+        const { geometry1, geometry2, srid } = IntersectionSchema.parse(params);
+
         const result = await adapter.executeQuery(
           `SELECT 
                     ST_Intersects(
@@ -138,8 +147,11 @@ export function createSpatialIntersectionTool(
           ),
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
         const msg = error instanceof Error ? error.message : String(error);
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -161,10 +173,15 @@ export function createSpatialBufferTool(adapter: MySQLAdapter): ToolDefinition {
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { geometry, distance, srid, segments, precision } =
-        BufferSchema.parse(params);
-
       try {
+        const { geometry, distance, srid, segments, precision } =
+          BufferSchema.parse(params);
+
+        // Handler-level validation for segments (replaces schema .min(1))
+        if (segments < 1) {
+          return { success: false, error: "segments must be >= 1" };
+        }
+
         // ST_Buffer_Strategy only works with Cartesian (non-geographic) SRIDs.
         // Geographic SRIDs (e.g., 4326) use MySQL's internal geographic buffer algorithm.
         const isGeographic = srid !== 0;
@@ -189,8 +206,11 @@ export function createSpatialBufferTool(adapter: MySQLAdapter): ToolDefinition {
           srid,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
         const msg = error instanceof Error ? error.message : String(error);
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -215,9 +235,9 @@ export function createSpatialTransformTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { geometry, fromSrid, toSrid } = TransformSchema.parse(params);
-
       try {
+        const { geometry, fromSrid, toSrid } = TransformSchema.parse(params);
+
         const result = await adapter.executeQuery(
           `SELECT 
                     ST_AsText(ST_Transform(ST_GeomFromText(?, ${String(fromSrid)}, 'axis-order=long-lat'), ${String(toSrid)})) as transformed_wkt,
@@ -234,8 +254,11 @@ export function createSpatialTransformTool(
           toSrid,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
         const msg = error instanceof Error ? error.message : String(error);
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -252,16 +275,16 @@ export function createSpatialGeoJSONTool(
     title: "MySQL GeoJSON Conversion",
     description: "Convert geometry between WKT and GeoJSON formats.",
     group: "spatial",
-    inputSchema: GeoJSONSchema,
+    inputSchema: GeoJSONSchemaBase,
     requiredScopes: ["read"],
     annotations: {
       readOnlyHint: true,
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { geometry, geoJson, srid } = GeoJSONSchema.parse(params);
-
       try {
+        const { geometry, geoJson, srid } = GeoJSONSchema.parse(params);
+
         if (geometry) {
           // Convert WKT to GeoJSON
           const result = await adapter.executeQuery(
@@ -290,10 +313,16 @@ export function createSpatialGeoJSONTool(
           };
         }
 
-        throw new Error("Either geometry or geoJson must be provided");
+        return {
+          success: false,
+          error: "Either geometry or geoJson must be provided",
+        };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
         const msg = error instanceof Error ? error.message : String(error);
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };