@neverinfamous/mysql-mcp 2.3.0 → 3.0.0

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

@@ -5,12 +5,45 @@
  * 4 tools: distance, distance_sphere, contains, within.
  */
 
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import type { MySQLAdapter } from "../../MySQLAdapter.js";
 import type {
   ToolDefinition,
   RequestContext,
 } from "../../../../types/index.js";
+import {
+  validateQualifiedIdentifier,
+  escapeQualifiedTable,
+} from "../../../../utils/validators.js";
+import { ValidationError } from "../../../../utils/validators.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("; ");
+}
+
+/** Strip verbose adapter prefixes from MySQL error messages */
+function stripErrorPrefix(msg: string): string {
+  return msg.replace(/^(Query failed:\s*)?(Execute failed:\s*)?/i, "");
+}
+
+/** Safely extract a string field from raw params for error context */
+function paramStr(params: unknown, key: string): string {
+  if (
+    params !== null &&
+    params !== undefined &&
+    typeof params === "object" &&
+    key in params
+  ) {
+    const val = (params as Record<string, unknown>)[key];
+    return typeof val === "string" ? val : "";
+  }
+  return "";
+}
 
 // =============================================================================
 // Zod Schemas
@@ -71,25 +104,24 @@ export function createSpatialDistanceTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, spatialColumn, point, maxDistance, limit, srid } =
-        DistanceSchema.parse(params);
+      try {
+        const { table, spatialColumn, point, maxDistance, limit, srid } =
+          DistanceSchema.parse(params);
 
-      // Validate identifiers
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-        throw new Error("Invalid table name");
-      }
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
-        throw new Error("Invalid column name");
-      }
+        // Validate identifiers
+        validateQualifiedIdentifier(table, "table");
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
+          return { success: false, error: "Invalid column name" };
+        }
 
-      try {
         // Use 'axis-order=long-lat' to accept natural longitude-latitude order
         const pointWkt = `POINT(${String(point.longitude)} ${String(point.latitude)})`;
+        const escapedTable = escapeQualifiedTable(table);
 
         let query = `
-                SELECT *,
+                SELECT *, ST_AsText(\`${spatialColumn}\`) as ${spatialColumn}_wkt,
                        ST_Distance(\`${spatialColumn}\`, ST_GeomFromText(?, ${String(srid)}, 'axis-order=long-lat')) as distance
-                FROM \`${table}\`
+                FROM ${escapedTable}
             `;
 
         const queryParams: unknown[] = [pointWkt];
@@ -102,17 +134,29 @@ export function createSpatialDistanceTool(
         query += ` ORDER BY distance LIMIT ${String(limit)}`;
 
         const result = await adapter.executeQuery(query, queryParams);
+        // Strip raw binary spatial column from each row
+        const rows = (result.rows ?? []).map((row: Record<string, unknown>) =>
+          Object.fromEntries(
+            Object.entries(row).filter(([key]) => key !== spatialColumn),
+          ),
+        );
         return {
-          results: result.rows ?? [],
-          count: result.rows?.length ?? 0,
+          results: rows,
+          count: rows.length,
           referencePoint: point,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        if (error instanceof ValidationError) {
+          return { success: false, error: error.message };
+        }
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("doesn't exist")) {
-          return { exists: false, table };
+          return { exists: false, table: paramStr(params, "table") };
         }
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -137,25 +181,24 @@ export function createSpatialDistanceSphereTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, spatialColumn, point, maxDistance, limit, srid } =
-        DistanceSchema.parse(params);
+      try {
+        const { table, spatialColumn, point, maxDistance, limit, srid } =
+          DistanceSchema.parse(params);
 
-      // Validate identifiers
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-        throw new Error("Invalid table name");
-      }
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
-        throw new Error("Invalid column name");
-      }
+        // Validate identifiers
+        validateQualifiedIdentifier(table, "table");
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
+          return { success: false, error: "Invalid column name" };
+        }
 
-      try {
         // Use 'axis-order=long-lat' to accept natural longitude-latitude order
         const pointWkt = `POINT(${String(point.longitude)} ${String(point.latitude)})`;
+        const escapedTable = escapeQualifiedTable(table);
 
         let query = `
-                SELECT *,
+                SELECT *, ST_AsText(\`${spatialColumn}\`) as ${spatialColumn}_wkt,
                        ST_Distance_Sphere(\`${spatialColumn}\`, ST_GeomFromText(?, ${String(srid)}, 'axis-order=long-lat')) as distance_meters
-                FROM \`${table}\`
+                FROM ${escapedTable}
             `;
 
         const queryParams: unknown[] = [pointWkt];
@@ -168,18 +211,30 @@ export function createSpatialDistanceSphereTool(
         query += ` ORDER BY distance_meters LIMIT ${String(limit)}`;
 
         const result = await adapter.executeQuery(query, queryParams);
+        // Strip raw binary spatial column from each row
+        const rows = (result.rows ?? []).map((row: Record<string, unknown>) =>
+          Object.fromEntries(
+            Object.entries(row).filter(([key]) => key !== spatialColumn),
+          ),
+        );
         return {
-          results: result.rows ?? [],
-          count: result.rows?.length ?? 0,
+          results: rows,
+          count: rows.length,
           referencePoint: point,
           unit: "meters",
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        if (error instanceof ValidationError) {
+          return { success: false, error: error.message };
+        }
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("doesn't exist")) {
-          return { exists: false, table };
+          return { exists: false, table: paramStr(params, "table") };
         }
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -204,36 +259,47 @@ export function createSpatialContainsTool(
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, spatialColumn, polygon, limit, srid } =
-        ContainsSchema.parse(params);
+      try {
+        const { table, spatialColumn, polygon, limit, srid } =
+          ContainsSchema.parse(params);
 
-      // Validate identifiers
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-        throw new Error("Invalid table name");
-      }
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
-        throw new Error("Invalid column name");
-      }
+        // Validate identifiers
+        validateQualifiedIdentifier(table, "table");
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
+          return { success: false, error: "Invalid column name" };
+        }
 
-      try {
+        const escapedTable = escapeQualifiedTable(table);
         const query = `
-                SELECT *
-                FROM \`${table}\`
+                SELECT *, ST_AsText(\`${spatialColumn}\`) as ${spatialColumn}_wkt
+                FROM ${escapedTable}
                 WHERE ST_Contains(ST_GeomFromText(?, ${String(srid)}, 'axis-order=long-lat'), \`${spatialColumn}\`)
                 LIMIT ${String(limit)}
             `;
 
         const result = await adapter.executeQuery(query, [polygon]);
+        // Strip raw binary spatial column from each row
+        const rows = (result.rows ?? []).map((row: Record<string, unknown>) =>
+          Object.fromEntries(
+            Object.entries(row).filter(([key]) => key !== spatialColumn),
+          ),
+        );
         return {
-          results: result.rows ?? [],
-          count: result.rows?.length ?? 0,
+          results: rows,
+          count: rows.length,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        if (error instanceof ValidationError) {
+          return { success: false, error: error.message };
+        }
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("doesn't exist")) {
-          return { exists: false, table };
+          return { exists: false, table: paramStr(params, "table") };
         }
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -255,36 +321,47 @@ export function createSpatialWithinTool(adapter: MySQLAdapter): ToolDefinition {
       idempotentHint: true,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, spatialColumn, geometry, limit, srid } =
-        WithinSchema.parse(params);
+      try {
+        const { table, spatialColumn, geometry, limit, srid } =
+          WithinSchema.parse(params);
 
-      // Validate identifiers
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-        throw new Error("Invalid table name");
-      }
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
-        throw new Error("Invalid column name");
-      }
+        // Validate identifiers
+        validateQualifiedIdentifier(table, "table");
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(spatialColumn)) {
+          return { success: false, error: "Invalid column name" };
+        }
 
-      try {
+        const escapedTable = escapeQualifiedTable(table);
         const query = `
-                SELECT *
-                FROM \`${table}\`
+                SELECT *, ST_AsText(\`${spatialColumn}\`) as ${spatialColumn}_wkt
+                FROM ${escapedTable}
                 WHERE ST_Within(\`${spatialColumn}\`, ST_GeomFromText(?, ${String(srid)}, 'axis-order=long-lat'))
                 LIMIT ${String(limit)}
             `;
 
         const result = await adapter.executeQuery(query, [geometry]);
+        // Strip raw binary spatial column from each row
+        const rows = (result.rows ?? []).map((row: Record<string, unknown>) =>
+          Object.fromEntries(
+            Object.entries(row).filter(([key]) => key !== spatialColumn),
+          ),
+        );
         return {
-          results: result.rows ?? [],
-          count: result.rows?.length ?? 0,
+          results: rows,
+          count: rows.length,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        if (error instanceof ValidationError) {
+          return { success: false, error: error.message };
+        }
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("doesn't exist")) {
-          return { exists: false, table };
+          return { exists: false, table: paramStr(params, "table") };
         }
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };

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

@@ -5,33 +5,65 @@
  * 2 tools: column creation and index creation.
  */
 
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import type { MySQLAdapter } from "../../MySQLAdapter.js";
 import type {
   ToolDefinition,
   RequestContext,
 } from "../../../../types/index.js";
+import {
+  validateQualifiedIdentifier,
+  escapeQualifiedTable,
+} from "../../../../utils/validators.js";
+import { ValidationError } from "../../../../utils/validators.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("; ");
+}
+
+/** Strip verbose adapter prefixes from MySQL error messages */
+function stripErrorPrefix(msg: string): string {
+  return msg.replace(/^(Query failed:\s*)?(Execute failed:\s*)?/i, "");
+}
+
+/** Safely extract a string field from raw params for error context */
+function paramStr(params: unknown, key: string): string {
+  if (
+    params !== null &&
+    params !== undefined &&
+    typeof params === "object" &&
+    key in params
+  ) {
+    const val = (params as Record<string, unknown>)[key];
+    return typeof val === "string" ? val : "";
+  }
+  return "";
+}
 
 // =============================================================================
 // Zod Schemas
 // =============================================================================
 
+const VALID_GEOMETRY_TYPES = new Set([
+  "POINT",
+  "LINESTRING",
+  "POLYGON",
+  "GEOMETRY",
+  "MULTIPOINT",
+  "MULTILINESTRING",
+  "MULTIPOLYGON",
+  "GEOMETRYCOLLECTION",
+]);
+
 const SpatialColumnSchema = z.object({
   table: z.string().describe("Table name"),
   column: z.string().describe("Column name"),
-  type: z
-    .enum([
-      "POINT",
-      "LINESTRING",
-      "POLYGON",
-      "GEOMETRY",
-      "MULTIPOINT",
-      "MULTILINESTRING",
-      "MULTIPOLYGON",
-      "GEOMETRYCOLLECTION",
-    ])
-    .default("GEOMETRY")
-    .describe("Geometry type"),
+  type: z.string().default("GEOMETRY").describe("Geometry type"),
   srid: z
     .number()
     .default(4326)
@@ -65,25 +97,33 @@ export function createSpatialCreateColumnTool(
       readOnlyHint: false,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, column, type, srid, nullable } =
-        SpatialColumnSchema.parse(params);
+      try {
+        const { table, column, type, srid, nullable } =
+          SpatialColumnSchema.parse(params);
 
-      // Validate identifiers
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-        throw new Error("Invalid table name");
-      }
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(column)) {
-        throw new Error("Invalid column name");
-      }
+        // Validate identifiers
+        validateQualifiedIdentifier(table, "table");
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(column)) {
+          return { success: false, error: "Invalid column name" };
+        }
+
+        // Validate geometry type
+        const upperType = type.toUpperCase();
+        if (!VALID_GEOMETRY_TYPES.has(upperType)) {
+          return {
+            success: false,
+            error: `Invalid type: '${type}' — expected one of: ${[...VALID_GEOMETRY_TYPES].join(", ")}`,
+          };
+        }
 
-      try {
         const nullClause = nullable ? "" : " NOT NULL";
         const sridClause = srid ? ` SRID ${String(srid)}` : "";
 
         await adapter.executeQuery(
-          `ALTER TABLE \`${table}\` ADD COLUMN \`${column}\` ${type}${sridClause}${nullClause}`,
+          `ALTER TABLE ${escapeQualifiedTable(table)} ADD COLUMN \`${column}\` ${upperType}${sridClause}${nullClause}`,
         );
 
+        adapter.clearSchemaCache();
         return {
           success: true,
           table,
@@ -93,17 +133,25 @@ export function createSpatialCreateColumnTool(
           nullable,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        if (error instanceof ValidationError) {
+          return { success: false, error: error.message };
+        }
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("doesn't exist")) {
-          return { exists: false, table };
+          return { exists: false, table: paramStr(params, "table") };
         }
         if (msg.includes("Duplicate column name")) {
+          const col = paramStr(params, "column");
+          const tbl = paramStr(params, "table");
           return {
             success: false,
-            reason: `Column '${column}' already exists on table '${table}'`,
+            error: `Column '${col}' already exists on table '${tbl}'`,
           };
         }
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };
@@ -127,27 +175,32 @@ export function createSpatialCreateIndexTool(
       readOnlyHint: false,
     },
     handler: async (params: unknown, _context: RequestContext) => {
-      const { table, column, indexName } = SpatialIndexSchema.parse(params);
+      try {
+        const { table, column, indexName } = SpatialIndexSchema.parse(params);
 
-      // Validate identifiers
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-        throw new Error("Invalid table name");
-      }
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(column)) {
-        throw new Error("Invalid column name");
-      }
+        // Validate identifiers
+        validateQualifiedIdentifier(table, "table");
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(column)) {
+          return { success: false, error: "Invalid column name" };
+        }
 
-      const idxName = indexName ?? `idx_spatial_${table}_${column}`;
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(idxName)) {
-        throw new Error("Invalid index name");
-      }
+        // For qualified names (schema.table), split for information_schema queries
+        const parts = table.split(".");
+        const bareTable = parts.length > 1 ? parts[1] : parts[0];
+        const schemaClause =
+          parts.length > 1 ? "TABLE_SCHEMA = ?" : "TABLE_SCHEMA = DATABASE()";
+        const schemaParams = parts.length > 1 ? [parts[0]] : [];
+
+        const idxName = indexName ?? `idx_spatial_${bareTable}_${column}`;
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(idxName)) {
+          return { success: false, error: "Invalid index name" };
+        }
 
-      try {
         // Check if column is nullable - SPATIAL indexes require NOT NULL
         const colInfo = await adapter.executeQuery(
           `SELECT IS_NULLABLE, DATA_TYPE FROM information_schema.COLUMNS
-           WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?`,
-          [table, column],
+           WHERE ${schemaClause} AND TABLE_NAME = ? AND COLUMN_NAME = ?`,
+          [...schemaParams, bareTable, column],
         );
 
         const colRow = colInfo.rows?.[0];
@@ -155,20 +208,22 @@ export function createSpatialCreateIndexTool(
           const isNullable = colRow["IS_NULLABLE"] === "YES";
           const dataType = String(colRow["DATA_TYPE"]).toUpperCase();
           if (isNullable) {
-            throw new Error(
-              `Cannot create SPATIAL index on nullable column '${column}'. ` +
+            return {
+              success: false,
+              error:
+                `Cannot create SPATIAL index on nullable column '${column}'. ` +
                 `Alter the column to NOT NULL first: ` +
-                `ALTER TABLE \`${table}\` MODIFY \`${column}\` ${dataType} NOT NULL`,
-            );
+                `ALTER TABLE ${escapeQualifiedTable(table)} MODIFY \`${column}\` ${dataType} NOT NULL`,
+            };
           }
         }
 
         // Check if a SPATIAL index already exists on this column (any name)
         const existingIdx = await adapter.executeQuery(
           `SELECT INDEX_NAME FROM information_schema.STATISTICS
-           WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ? AND INDEX_TYPE = 'SPATIAL'
+           WHERE ${schemaClause} AND TABLE_NAME = ? AND COLUMN_NAME = ? AND INDEX_TYPE = 'SPATIAL'
            LIMIT 1`,
-          [table, column],
+          [...schemaParams, bareTable, column],
         );
 
         const existingRow = existingIdx.rows?.[0];
@@ -176,14 +231,15 @@ export function createSpatialCreateIndexTool(
           const existingName = String(existingRow["INDEX_NAME"]);
           return {
             success: false,
-            reason: `Spatial index '${existingName}' already exists on column '${column}' of table '${table}'`,
+            error: `Spatial index '${existingName}' already exists on column '${column}' of table '${table}'`,
           };
         }
 
         await adapter.executeQuery(
-          `CREATE SPATIAL INDEX \`${idxName}\` ON \`${table}\`(\`${column}\`)`,
+          `CREATE SPATIAL INDEX \`${idxName}\` ON ${escapeQualifiedTable(table)}(\`${column}\`)`,
         );
 
+        adapter.clearSchemaCache();
         return {
           success: true,
           table,
@@ -191,20 +247,30 @@ export function createSpatialCreateIndexTool(
           indexName: idxName,
         };
       } catch (error) {
+        if (error instanceof ZodError) {
+          return { success: false, error: formatZodError(error) };
+        }
+        if (error instanceof ValidationError) {
+          return { success: false, error: error.message };
+        }
         const msg = error instanceof Error ? error.message : String(error);
+        const tbl = paramStr(params, "table");
         if (msg.includes("doesn't exist")) {
-          return { exists: false, table };
+          return { exists: false, table: tbl };
         }
         if (msg.includes("Cannot create SPATIAL index on nullable column")) {
-          return { success: false, reason: msg };
+          return { success: false, error: stripErrorPrefix(msg) };
         }
+        const idxFromParams = paramStr(params, "indexName");
+        const idx =
+          idxFromParams || `idx_spatial_${tbl}_${paramStr(params, "column")}`;
         if (msg.includes("Duplicate key name")) {
           return {
             success: false,
-            reason: `Index '${idxName}' already exists on table '${table}'`,
+            error: `Index '${idx}' already exists on table '${tbl}'`,
           };
         }
-        return { success: false, error: msg };
+        return { success: false, error: stripErrorPrefix(msg) };
       }
     },
   };

package/src/adapters/mysql/tools/stats/__tests__/comparative.test.ts

@@ -67,16 +67,17 @@ describe("Comparative Stats Tools", () => {
     });
 
     it("should validate inputs", async () => {
-      await expect(
-        correlationTool.handler(
-          {
-            table: "bad;table",
-            column1: "x",
-            column2: "y",
-          },
-          {} as any,
-        ),
-      ).rejects.toThrow("Invalid table name");
+      const result: any = await correlationTool.handler(
+        {
+          table: "bad;table",
+          column1: "x",
+          column2: "y",
+        },
+        {} as any,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Invalid table name");
     });
   });
 
@@ -95,6 +96,7 @@ describe("Comparative Stats Tools", () => {
         {} as any,
       );
 
+      expect(result.success).toBe(false);
       expect(result.error).toContain("Insufficient data");
     });