@neverinfamous/postgres-mcp 1.2.0 → 2.0.0

package/dist/adapters/postgresql/tools/postgis/advanced.js

@@ -3,9 +3,12 @@
  *
  * Advanced spatial tools: geocode, geo_transform, geo_index_optimize, geo_cluster.
  */
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import { readOnly } from "../../../../utils/annotations.js";
 import { getToolIcons } from "../../../../utils/icons.js";
+import { formatPostgresError } from "../core/error-helpers.js";
+import { sanitizeIdentifier, sanitizeTableName, } from "../../../../utils/identifiers.js";
+import { sanitizeWhereClause } from "../../../../utils/where-clause.js";
 import { GeocodeSchemaBase, GeocodeSchema, GeoTransformSchemaBase, GeoTransformSchema, GeoClusterSchemaBase, GeoClusterSchema, 
 // Output schemas
 GeocodeOutputSchema, GeoTransformOutputSchema, GeoIndexOptimizeOutputSchema, GeoClusterOutputSchema, } from "../../schemas/index.js";
@@ -19,27 +22,41 @@ export function createGeocodeTool(adapter) {
         annotations: readOnly("Geocode"),
         icons: getToolIcons("postgis", readOnly("Geocode")),
         handler: async (params, _context) => {
-            const parsed = GeocodeSchema.parse(params ?? {});
-            const srid = parsed.srid ?? 4326;
-            const sql = `SELECT 
+            try {
+                const parsed = GeocodeSchema.parse(params ?? {});
+                const srid = parsed.srid ?? 4326;
+                const sql = `SELECT
                         ST_AsGeoJSON(ST_SetSRID(ST_MakePoint($1, $2), $3)) as geojson,
                         ST_AsText(ST_SetSRID(ST_MakePoint($1, $2), $3)) as wkt`;
-            const result = await adapter.executeQuery(sql, [
-                parsed.lng,
-                parsed.lat,
-                srid,
-            ]);
-            // Add note about SRID for non-4326 cases
-            const row = result.rows?.[0];
-            if (row === undefined) {
-                return {};
+                const result = await adapter.executeQuery(sql, [
+                    parsed.lng,
+                    parsed.lat,
+                    srid,
+                ]);
+                // Add note about SRID for non-4326 cases
+                const row = result.rows?.[0];
+                if (row === undefined) {
+                    return {};
+                }
+                const response = { ...row };
+                if (srid !== 4326) {
+                    response["note"] =
+                        `Coordinates are WGS84 lat/lng with SRID ${String(srid)} metadata. Use pg_geo_transform to convert to target CRS.`;
+                }
+                return response;
             }
-            const response = { ...row };
-            if (srid !== 4326) {
-                response["note"] =
-                    `Coordinates are WGS84 lat/lng with SRID ${String(srid)} metadata. Use pg_geo_transform to convert to target CRS.`;
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: error.issues.map((i) => i.message).join("; "),
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, { tool: "pg_geocode" }),
+                };
             }
-            return response;
         },
     };
 }
@@ -56,84 +73,114 @@ export function createGeoTransformTool(adapter) {
         annotations: readOnly("Transform Geometry"),
         icons: getToolIcons("postgis", readOnly("Transform Geometry")),
         handler: async (params, _context) => {
-            const parsed = GeoTransformSchema.parse(params ?? {});
-            const schemaName = parsed.schema ?? "public";
-            const qualifiedTable = schemaName !== "public"
-                ? `"${schemaName}"."${parsed.table}"`
-                : `"${parsed.table}"`;
-            const columnName = `"${parsed.column}"`;
-            // Auto-detect fromSrid from column metadata if not provided
-            let fromSrid = parsed.fromSrid;
-            if (fromSrid === 0) {
-                const sridQuery = `
-          SELECT srid FROM geometry_columns 
-          WHERE f_table_schema = $1 AND f_table_name = $2 AND f_geometry_column = $3
-          UNION
-          SELECT srid FROM geography_columns 
-          WHERE f_table_schema = $1 AND f_table_name = $2 AND f_geography_column = $3
-          LIMIT 1
+            try {
+                const parsed = GeoTransformSchema.parse(params ?? {});
+                const schemaName = parsed.schema ?? "public";
+                const qualifiedTable = sanitizeTableName(parsed.table, schemaName !== "public" ? schemaName : undefined);
+                const columnName = sanitizeIdentifier(parsed.column);
+                // Auto-detect fromSrid from column metadata if not provided
+                let fromSrid = parsed.fromSrid;
+                if (fromSrid === 0) {
+                    // Check if table exists before attempting SRID auto-detection
+                    const tableCheckSql = `SELECT 1 FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2`;
+                    const tableCheckResult = await adapter.executeQuery(tableCheckSql, [
+                        schemaName,
+                        parsed.table,
+                    ]);
+                    if ((tableCheckResult.rows?.length ?? 0) === 0) {
+                        return {
+                            success: false,
+                            error: `Table or view '${parsed.table}' not found. Use pg_list_tables to see available tables.`,
+                        };
+                    }
+                    const sridQuery = `
+            SELECT srid FROM geometry_columns
+            WHERE f_table_schema = $1 AND f_table_name = $2 AND f_geometry_column = $3
+            UNION
+            SELECT srid FROM geography_columns
+            WHERE f_table_schema = $1 AND f_table_name = $2 AND f_geography_column = $3
+            LIMIT 1
+          `;
+                    const sridResult = await adapter.executeQuery(sridQuery, [
+                        schemaName,
+                        parsed.table,
+                        parsed.column,
+                    ]);
+                    const sridValue = sridResult.rows?.[0]?.["srid"];
+                    if (sridValue !== undefined && sridValue !== null) {
+                        fromSrid = Number(sridValue);
+                    }
+                    else {
+                        return {
+                            success: false,
+                            error: `Could not auto-detect SRID for column "${parsed.column}" on table "${parsed.table}". Provide fromSrid (or sourceSrid) explicitly.`,
+                            suggestion: `Use fromSrid: 4326 for WGS84/GPS coordinates, or fromSrid: 3857 for Web Mercator`,
+                        };
+                    }
+                }
+                const whereClause = parsed.where !== undefined
+                    ? `WHERE ${sanitizeWhereClause(parsed.where)}`
+                    : "";
+                // Default limit of 50 to prevent large payloads, use limit: 0 for all
+                const effectiveLimit = parsed.limit ?? 50;
+                const limitClause = effectiveLimit > 0 ? `LIMIT ${String(effectiveLimit)}` : "";
+                // Get non-geometry columns to avoid returning raw WKB
+                const colQuery = `
+          SELECT column_name FROM information_schema.columns
+          WHERE table_schema = $1 AND table_name = $2
+          AND udt_name NOT IN ('geometry', 'geography')
+          ORDER BY ordinal_position
         `;
-                const sridResult = await adapter.executeQuery(sridQuery, [
+                const colResult = await adapter.executeQuery(colQuery, [
                     schemaName,
                     parsed.table,
-                    parsed.column,
                 ]);
-                const sridValue = sridResult.rows?.[0]?.["srid"];
-                if (sridValue !== undefined && sridValue !== null) {
-                    fromSrid = Number(sridValue);
+                const nonGeomCols = (colResult.rows ?? [])
+                    .map((row) => `"${String(row["column_name"])}"`)
+                    .join(", ");
+                // Select non-geometry columns + transformed geometry representations
+                const selectCols = nonGeomCols.length > 0
+                    ? `${nonGeomCols}, ST_AsGeoJSON(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_geojson, ST_AsText(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_wkt, ${String(parsed.toSrid)} as output_srid`
+                    : `ST_AsGeoJSON(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_geojson, ST_AsText(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_wkt, ${String(parsed.toSrid)} as output_srid`;
+                const sql = `SELECT ${selectCols} FROM ${qualifiedTable} ${whereClause} ${limitClause}`;
+                const result = await adapter.executeQuery(sql);
+                // Build response with truncation indicators if default limit was applied
+                const response = {
+                    results: result.rows,
+                    count: result.rows?.length ?? 0,
+                    fromSrid: fromSrid,
+                    toSrid: parsed.toSrid,
+                    ...(parsed.fromSrid === 0 && { autoDetectedSrid: true }),
+                };
+                // Check if results were truncated (works for both default and explicit limits)
+                if (effectiveLimit > 0) {
+                    const countSql = `SELECT COUNT(*) as cnt FROM ${qualifiedTable} ${whereClause}`;
+                    const countResult = await adapter.executeQuery(countSql);
+                    const totalCount = Number(countResult.rows?.[0]?.["cnt"] ?? 0);
+                    if (totalCount > effectiveLimit) {
+                        response["truncated"] = true;
+                        response["totalCount"] = totalCount;
+                        response["limit"] = effectiveLimit;
+                    }
                 }
-                else {
+                return response;
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
                     return {
                         success: false,
-                        error: `Could not auto-detect SRID for column "${parsed.column}" on table "${parsed.table}". Provide fromSrid (or sourceSrid) explicitly.`,
-                        suggestion: `Use fromSrid: 4326 for WGS84/GPS coordinates, or fromSrid: 3857 for Web Mercator`,
+                        error: error.issues.map((i) => i.message).join("; "),
                     };
                 }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_geo_transform",
+                        table: params?.["table"] ??
+                            undefined,
+                    }),
+                };
             }
-            const whereClause = parsed.where !== undefined ? `WHERE ${parsed.where}` : "";
-            // Default limit of 50 to prevent large payloads, use limit: 0 for all
-            const effectiveLimit = parsed.limit ?? 50;
-            const limitClause = effectiveLimit > 0 ? `LIMIT ${String(effectiveLimit)}` : "";
-            // Get non-geometry columns to avoid returning raw WKB
-            const colQuery = `
-        SELECT column_name FROM information_schema.columns 
-        WHERE table_schema = $1 AND table_name = $2 
-        AND udt_name NOT IN ('geometry', 'geography')
-        ORDER BY ordinal_position
-      `;
-            const colResult = await adapter.executeQuery(colQuery, [
-                schemaName,
-                parsed.table,
-            ]);
-            const nonGeomCols = (colResult.rows ?? [])
-                .map((row) => `"${String(row["column_name"])}"`)
-                .join(", ");
-            // Select non-geometry columns + transformed geometry representations
-            const selectCols = nonGeomCols.length > 0
-                ? `${nonGeomCols}, ST_AsGeoJSON(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_geojson, ST_AsText(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_wkt, ${String(parsed.toSrid)} as output_srid`
-                : `ST_AsGeoJSON(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_geojson, ST_AsText(ST_Transform(ST_SetSRID(${columnName}, ${String(fromSrid)}), ${String(parsed.toSrid)})) as transformed_wkt, ${String(parsed.toSrid)} as output_srid`;
-            const sql = `SELECT ${selectCols} FROM ${qualifiedTable} ${whereClause} ${limitClause}`;
-            const result = await adapter.executeQuery(sql);
-            // Build response with truncation indicators if default limit was applied
-            const response = {
-                results: result.rows,
-                count: result.rows?.length ?? 0,
-                fromSrid: fromSrid,
-                toSrid: parsed.toSrid,
-                ...(parsed.fromSrid === 0 && { autoDetectedSrid: true }),
-            };
-            // Check if results were truncated (works for both default and explicit limits)
-            if (effectiveLimit > 0) {
-                const countSql = `SELECT COUNT(*) as cnt FROM ${qualifiedTable} ${whereClause}`;
-                const countResult = await adapter.executeQuery(countSql);
-                const totalCount = Number(countResult.rows?.[0]?.["cnt"] ?? 0);
-                if (totalCount > effectiveLimit) {
-                    response["truncated"] = true;
-                    response["totalCount"] = totalCount;
-                    response["limit"] = effectiveLimit;
-                }
-            }
-            return response;
         },
     };
 }
@@ -159,7 +206,7 @@ export function createGeoIndexOptimizeTool(adapter) {
             const parsed = params;
             const schemaName = parsed.schema ?? "public";
             const indexQuery = `
-                SELECT 
+                SELECT
                     c.relname as table_name,
                     i.relname as index_name,
                     a.attname as column_name,
@@ -178,13 +225,16 @@ export function createGeoIndexOptimizeTool(adapter) {
                 WHERE n.nspname = $1
                 AND (pg_get_indexdef(i.oid) LIKE '%gist%' OR pg_get_indexdef(i.oid) LIKE '%spgist%')
                 AND t.typname IN ('geometry', 'geography')
-                ${parsed.table !== undefined ? `AND c.relname = '${parsed.table}'` : ""}
+                ${parsed.table !== undefined ? `AND c.relname = $2` : ""}
                 ORDER BY index_size_bytes DESC
             `;
+            const indexParams = [schemaName];
+            if (parsed.table !== undefined)
+                indexParams.push(parsed.table);
             const [indexes, tableStats] = await Promise.all([
-                adapter.executeQuery(indexQuery, [schemaName]),
+                adapter.executeQuery(indexQuery, indexParams),
                 adapter.executeQuery(`
-                    SELECT 
+                    SELECT
                         c.relname as table_name,
                         n_live_tup as row_count,
                         pg_size_pretty(pg_table_size(c.oid)) as table_size
@@ -192,14 +242,14 @@ export function createGeoIndexOptimizeTool(adapter) {
                     JOIN pg_class c ON c.relname = t.relname
                     JOIN pg_namespace n ON n.oid = c.relnamespace
                     WHERE n.nspname = $1
-                    ${parsed.table !== undefined ? `AND c.relname = '${parsed.table}'` : ""}
+                    ${parsed.table !== undefined ? `AND c.relname = $${String(parsed.table !== undefined ? 2 : 1)}` : ""}
                     AND EXISTS (
                         SELECT 1 FROM information_schema.columns ic
-                        WHERE ic.table_schema = n.nspname 
-                        AND ic.table_name = c.relname 
+                        WHERE ic.table_schema = n.nspname
+                        AND ic.table_name = c.relname
                         AND ic.udt_name IN ('geometry', 'geography')
                     )
-                `, [schemaName]),
+                `, indexParams),
             ]);
             const recommendations = [];
             for (const idx of indexes.rows ?? []) {
@@ -267,151 +317,169 @@ export function createGeoClusterTool(adapter) {
         annotations: readOnly("Geo Cluster"),
         icons: getToolIcons("postgis", readOnly("Geo Cluster")),
         handler: async (params, _context) => {
-            const parsed = GeoClusterSchema.parse(params ?? {});
-            const method = parsed.method ?? "dbscan";
-            const schemaName = parsed.schema ?? "public";
-            const qualifiedTable = schemaName !== "public"
-                ? `"${schemaName}"."${parsed.table}"`
-                : `"${parsed.table}"`;
-            const whereClause = parsed.where !== undefined ? `WHERE ${parsed.where}` : "";
-            const limitClause = parsed.limit !== undefined && parsed.limit > 0
-                ? `LIMIT ${String(parsed.limit)}`
-                : "";
-            // Track warning if K > N
-            let warning;
-            // For K-Means, validate and adjust numClusters
-            let effectiveNumClusters = parsed.numClusters ?? 5;
-            let rowCount = 0;
-            if (method === "kmeans") {
-                // Validate numClusters > 0
-                if (effectiveNumClusters <= 0) {
-                    return {
-                        error: `numClusters must be greater than 0 (received: ${String(effectiveNumClusters)}).`,
-                        method,
-                        table: parsed.table,
-                        numClusters: effectiveNumClusters,
-                        suggestion: "Provide a positive integer for numClusters (e.g., numClusters: 3)",
-                    };
+            try {
+                const parsed = GeoClusterSchema.parse(params ?? {});
+                const method = parsed.method ?? "dbscan";
+                const schemaName = parsed.schema ?? "public";
+                const qualifiedTable = sanitizeTableName(parsed.table, schemaName !== "public" ? schemaName : undefined);
+                const whereClause = parsed.where !== undefined
+                    ? `WHERE ${sanitizeWhereClause(parsed.where)}`
+                    : "";
+                const limitClause = parsed.limit !== undefined && parsed.limit > 0
+                    ? `LIMIT ${String(parsed.limit)}`
+                    : "";
+                // Track warning if K > N
+                let warning;
+                // For K-Means, validate and adjust numClusters
+                let effectiveNumClusters = parsed.numClusters ?? 5;
+                let rowCount;
+                if (method === "kmeans") {
+                    // Validate numClusters > 0
+                    if (effectiveNumClusters <= 0) {
+                        return {
+                            error: `numClusters must be greater than 0 (received: ${String(effectiveNumClusters)}).`,
+                            method,
+                            table: parsed.table,
+                            numClusters: effectiveNumClusters,
+                            suggestion: "Provide a positive integer for numClusters (e.g., numClusters: 3)",
+                        };
+                    }
+                    const countResult = await adapter.executeQuery(`SELECT COUNT(*) as cnt FROM ${qualifiedTable} ${whereClause}`);
+                    rowCount = Number(countResult.rows?.[0]?.["cnt"] ?? 0);
+                    if (rowCount === 0) {
+                        return {
+                            error: `No rows found in table ${parsed.table}${whereClause !== "" ? " matching filter" : ""}. K-Means requires at least 1 row.`,
+                            method,
+                            table: parsed.table,
+                            rowCount: 0,
+                        };
+                    }
+                    // Clamp K to row count and warn if exceeded
+                    if (effectiveNumClusters > rowCount) {
+                        warning = `Requested ${String(parsed.numClusters)} clusters but only ${String(rowCount)} rows available. Using ${String(rowCount)} clusters instead.`;
+                        effectiveNumClusters = rowCount;
+                    }
                 }
-                const countResult = await adapter.executeQuery(`SELECT COUNT(*) as cnt FROM ${qualifiedTable} ${whereClause}`);
-                rowCount = Number(countResult.rows?.[0]?.["cnt"] ?? 0);
-                if (rowCount === 0) {
-                    return {
-                        error: `No rows found in table ${parsed.table}${whereClause !== "" ? " matching filter" : ""}. K-Means requires at least 1 row.`,
-                        method,
-                        table: parsed.table,
-                        rowCount: 0,
-                    };
+                let clusterFunction;
+                if (method === "kmeans") {
+                    clusterFunction = `ST_ClusterKMeans("${parsed.column}", ${String(effectiveNumClusters)}) OVER ()`;
                 }
-                // Clamp K to row count and warn if exceeded
-                if (effectiveNumClusters > rowCount) {
-                    warning = `Requested ${String(parsed.numClusters)} clusters but only ${String(rowCount)} rows available. Using ${String(rowCount)} clusters instead.`;
-                    effectiveNumClusters = rowCount;
+                else {
+                    const eps = parsed.eps ?? 100;
+                    const minPoints = parsed.minPoints ?? 3;
+                    clusterFunction = `ST_ClusterDBSCAN("${parsed.column}", ${String(eps)}, ${String(minPoints)}) OVER ()`;
                 }
-            }
-            let clusterFunction;
-            if (method === "kmeans") {
-                clusterFunction = `ST_ClusterKMeans("${parsed.column}", ${String(effectiveNumClusters)}) OVER ()`;
-            }
-            else {
-                const eps = parsed.eps ?? 100;
-                const minPoints = parsed.minPoints ?? 3;
-                clusterFunction = `ST_ClusterDBSCAN("${parsed.column}", ${String(eps)}, ${String(minPoints)}) OVER ()`;
-            }
-            const sql = `
-                WITH clustered AS (
-                    SELECT 
-                        *,
-                        ${clusterFunction} as cluster_id
-                    FROM ${qualifiedTable}
-                    ${whereClause}
-                )
-                SELECT 
-                    cluster_id,
-                    COUNT(*) as point_count,
-                    ST_AsGeoJSON(ST_Centroid(ST_Collect("${parsed.column}"))) as centroid,
-                    ST_AsGeoJSON(ST_ConvexHull(ST_Collect("${parsed.column}"))) as hull
-                FROM clustered
-                WHERE cluster_id IS NOT NULL
-                GROUP BY cluster_id
-                ORDER BY point_count DESC
-                ${limitClause}
-            `;
-            const [clustersResult, summaryResult] = await Promise.all([
-                adapter.executeQuery(sql),
-                adapter.executeQuery(`
-                    WITH clustered AS (
-                        SELECT ${clusterFunction} as cluster_id
-                        FROM ${qualifiedTable}
-                        ${whereClause}
-                    )
-                    SELECT 
-                        COUNT(DISTINCT cluster_id) as num_clusters,
-                        COUNT(*) FILTER (WHERE cluster_id IS NULL) as noise_points,
-                        COUNT(*) as total_points
-                    FROM clustered
-                `),
-            ]);
-            // Normalize cluster point_count to numbers
-            const normalizedClusters = (clustersResult.rows ?? []).map((row) => ({
-                ...row,
-                point_count: Number(row["point_count"]),
-            }));
-            // Normalize summary values to numbers for consistency
-            const rawSummary = summaryResult.rows?.[0] ?? {};
-            const normalizedSummary = {
-                num_clusters: Number(rawSummary["num_clusters"] ?? 0),
-                noise_points: Number(rawSummary["noise_points"] ?? 0),
-                total_points: Number(rawSummary["total_points"] ?? 0),
-            };
-            // Build response
-            const response = {
-                method,
-                parameters: method === "kmeans"
-                    ? { numClusters: effectiveNumClusters }
-                    : { eps: parsed.eps ?? 100, minPoints: parsed.minPoints ?? 3 },
-                summary: normalizedSummary,
-                clusters: normalizedClusters,
-            };
-            // Add warning if K was clamped
-            if (warning !== undefined) {
-                response["warning"] = warning;
-                response["requestedClusters"] = parsed.numClusters;
-                response["actualClusters"] = effectiveNumClusters;
-            }
-            // Add contextual hints based on method and results
-            const numClusters = normalizedSummary.num_clusters;
-            const noisePoints = normalizedSummary.noise_points;
-            const totalPoints = normalizedSummary.total_points;
-            if (method === "dbscan") {
-                const eps = parsed.eps ?? 100;
-                const minPoints = parsed.minPoints ?? 3;
-                // Provide hints about DBSCAN parameter trade-offs
-                const hints = [];
-                if (numClusters === 1 && totalPoints > 1) {
-                    hints.push(`All ${String(totalPoints)} points formed a single cluster. Consider decreasing eps (currently ${String(eps)}m) to create more distinct clusters.`);
+                const sql = `
+                  WITH clustered AS (
+                      SELECT
+                          *,
+                          ${clusterFunction} as cluster_id
+                      FROM ${qualifiedTable}
+                      ${whereClause}
+                  )
+                  SELECT
+                      cluster_id,
+                      COUNT(*) as point_count,
+                      ST_AsGeoJSON(ST_Centroid(ST_Collect("${parsed.column}"))) as centroid,
+                      ST_AsGeoJSON(ST_ConvexHull(ST_Collect("${parsed.column}"))) as hull
+                  FROM clustered
+                  WHERE cluster_id IS NOT NULL
+                  GROUP BY cluster_id
+                  ORDER BY point_count DESC
+                  ${limitClause}
+              `;
+                const [clustersResult, summaryResult] = await Promise.all([
+                    adapter.executeQuery(sql),
+                    adapter.executeQuery(`
+                      WITH clustered AS (
+                          SELECT ${clusterFunction} as cluster_id
+                          FROM ${qualifiedTable}
+                          ${whereClause}
+                      )
+                      SELECT
+                          COUNT(DISTINCT cluster_id) as num_clusters,
+                          COUNT(*) FILTER (WHERE cluster_id IS NULL) as noise_points,
+                          COUNT(*) as total_points
+                      FROM clustered
+                  `),
+                ]);
+                // Normalize cluster point_count to numbers
+                const normalizedClusters = (clustersResult.rows ?? []).map((row) => ({
+                    ...row,
+                    point_count: Number(row["point_count"]),
+                }));
+                // Normalize summary values to numbers for consistency
+                const rawSummary = summaryResult.rows?.[0] ?? {};
+                const normalizedSummary = {
+                    num_clusters: Number(rawSummary["num_clusters"] ?? 0),
+                    noise_points: Number(rawSummary["noise_points"] ?? 0),
+                    total_points: Number(rawSummary["total_points"] ?? 0),
+                };
+                // Build response
+                const response = {
+                    method,
+                    parameters: method === "kmeans"
+                        ? { numClusters: effectiveNumClusters }
+                        : { eps: parsed.eps ?? 100, minPoints: parsed.minPoints ?? 3 },
+                    summary: normalizedSummary,
+                    clusters: normalizedClusters,
+                };
+                // Add warning if K was clamped
+                if (warning !== undefined) {
+                    response["warning"] = warning;
+                    response["requestedClusters"] = parsed.numClusters;
+                    response["actualClusters"] = effectiveNumClusters;
                 }
-                if (noisePoints > 0 && noisePoints > totalPoints * 0.5) {
-                    hints.push(`${String(noisePoints)} of ${String(totalPoints)} points (${String(Math.round((noisePoints / totalPoints) * 100))}%) are noise. Consider increasing eps or decreasing minPoints (currently ${String(minPoints)}).`);
+                // Add contextual hints based on method and results
+                const numClusters = normalizedSummary.num_clusters;
+                const noisePoints = normalizedSummary.noise_points;
+                const totalPoints = normalizedSummary.total_points;
+                if (method === "dbscan") {
+                    const eps = parsed.eps ?? 100;
+                    const minPoints = parsed.minPoints ?? 3;
+                    // Provide hints about DBSCAN parameter trade-offs
+                    const hints = [];
+                    if (numClusters === 1 && totalPoints > 1) {
+                        hints.push(`All ${String(totalPoints)} points formed a single cluster. Consider decreasing eps (currently ${String(eps)}m) to create more distinct clusters.`);
+                    }
+                    if (noisePoints > 0 && noisePoints > totalPoints * 0.5) {
+                        hints.push(`${String(noisePoints)} of ${String(totalPoints)} points (${String(Math.round((noisePoints / totalPoints) * 100))}%) are noise. Consider increasing eps or decreasing minPoints (currently ${String(minPoints)}).`);
+                    }
+                    if (numClusters === 0 && totalPoints > 0) {
+                        hints.push(`No clusters formed - all points are noise. Try increasing eps (currently ${String(eps)}m) or decreasing minPoints (currently ${String(minPoints)}).`);
+                    }
+                    response["notes"] =
+                        "Noise points (cluster_id = NULL) are points not belonging to any cluster";
+                    if (hints.length > 0) {
+                        response["hints"] = hints;
+                    }
+                    response["parameterGuide"] = {
+                        eps: `Distance threshold in meters. Larger values group more distant points together.`,
+                        minPoints: `Minimum points required to form a cluster. Higher values create fewer, denser clusters.`,
+                    };
                 }
-                if (numClusters === 0 && totalPoints > 0) {
-                    hints.push(`No clusters formed - all points are noise. Try increasing eps (currently ${String(eps)}m) or decreasing minPoints (currently ${String(minPoints)}).`);
+                else {
+                    response["notes"] =
+                        "K-Means will always assign all points to a cluster";
                 }
-                response["notes"] =
-                    "Noise points (cluster_id = NULL) are points not belonging to any cluster";
-                if (hints.length > 0) {
-                    response["hints"] = hints;
+                return response;
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: error.issues.map((i) => i.message).join("; "),
+                    };
                 }
-                response["parameterGuide"] = {
-                    eps: `Distance threshold in meters. Larger values group more distant points together.`,
-                    minPoints: `Minimum points required to form a cluster. Higher values create fewer, denser clusters.`,
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_geo_cluster",
+                        table: params?.["table"] ??
+                            undefined,
+                    }),
                 };
             }
-            else {
-                response["notes"] =
-                    "K-Means will always assign all points to a cluster";
-            }
-            return response;
         },
     };
 }