@neverinfamous/postgres-mcp 1.2.0 → 2.0.0

package/dist/adapters/postgresql/tools/text.js

@@ -4,9 +4,10 @@
  * Text processing, FTS, trigrams, and fuzzy matching.
  * 14 tools total.
  */
-import { z } from "zod";
+import { z, ZodError } from "zod";
 import { readOnly, write } from "../../../utils/annotations.js";
 import { getToolIcons } from "../../../utils/icons.js";
+import { formatPostgresError } from "./core/error-helpers.js";
 import { sanitizeIdentifier, sanitizeIdentifiers, sanitizeTableName, } from "../../../utils/identifiers.js";
 import { sanitizeFtsConfig } from "../../../utils/fts-config.js";
 import { sanitizeWhereClause } from "../../../utils/where-clause.js";
@@ -43,43 +44,80 @@ function createTextSearchTool(adapter) {
         annotations: readOnly("Full-Text Search"),
         icons: getToolIcons("text", readOnly("Full-Text Search")),
         handler: async (params, _context) => {
-            const parsed = TextSearchSchema.parse(params);
-            const cfg = sanitizeFtsConfig(parsed.config ?? "english");
-            // Handle both column (string) and columns (array) parameters
-            // The preprocessor converts column → columns, but we handle both for safety
-            let cols;
-            if (parsed.columns !== undefined && parsed.columns.length > 0) {
-                cols = parsed.columns;
-            }
-            else if (parsed.column !== undefined) {
-                cols = [parsed.column];
-            }
-            else {
-                throw new Error("Either 'columns' (array) or 'column' (string) is required");
-            }
-            // Build qualified table name with schema support
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
-            }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const sanitizedCols = sanitizeIdentifiers(cols);
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ")
-                : "*";
-            const tsvector = sanitizedCols
-                .map((c) => `coalesce(${c}, '')`)
-                .join(" || ' ' || ");
-            const limitClause = parsed.limit !== undefined && parsed.limit > 0
-                ? ` LIMIT ${String(parsed.limit)}`
-                : "";
-            const sql = `SELECT ${selectCols}, ts_rank_cd(to_tsvector('${cfg}', ${tsvector}), plainto_tsquery('${cfg}', $1)) as rank
+            try {
+                const parsed = TextSearchSchema.parse(params);
+                const cfg = sanitizeFtsConfig(parsed.config ?? "english");
+                // Handle both column (string) and columns (array) parameters
+                // The preprocessor converts column → columns, but we handle both for safety
+                let cols;
+                if (parsed.columns !== undefined && parsed.columns.length > 0) {
+                    cols = parsed.columns;
+                }
+                else if (parsed.column !== undefined) {
+                    cols = [parsed.column];
+                }
+                else {
+                    return {
+                        success: false,
+                        error: "Either 'columns' (array) or 'column' (string) is required",
+                    };
+                }
+                // Build qualified table name with schema support
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const sanitizedCols = sanitizeIdentifiers(cols);
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ")
+                    : "*";
+                const tsvector = sanitizedCols
+                    .map((c) => `coalesce(${c}, '')`)
+                    .join(" || ' ' || ");
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                const sql = `SELECT ${selectCols}, ts_rank_cd(to_tsvector('${cfg}', ${tsvector}), plainto_tsquery('${cfg}', $1)) as rank
                         FROM ${tableName}
                         WHERE to_tsvector('${cfg}', ${tsvector}) @@ plainto_tsquery('${cfg}', $1)
                         ORDER BY rank DESC${limitClause}`;
-            const result = await adapter.executeQuery(sql, [parsed.query]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
+                const result = await adapter.executeQuery(sql, [parsed.query]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_text_search validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_search",
+                    }),
+                };
+            }
         },
     };
 }
@@ -115,42 +153,79 @@ function createTextRankTool(adapter) {
         annotations: readOnly("Text Rank"),
         icons: getToolIcons("text", readOnly("Text Rank")),
         handler: async (params, _context) => {
-            const parsed = TextRankSchema.parse(params);
-            const cfg = sanitizeFtsConfig(parsed.config ?? "english");
-            const norm = parsed.normalization ?? 0;
-            // Handle both column (string) and columns (array) parameters
-            let cols;
-            if (parsed.columns !== undefined && parsed.columns.length > 0) {
-                cols = parsed.columns;
-            }
-            else if (parsed.column !== undefined) {
-                cols = [parsed.column];
-            }
-            else {
-                throw new Error("Either column or columns parameter is required");
-            }
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
-            }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const sanitizedCols = sanitizeIdentifiers(cols);
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ")
-                : "*";
-            const tsvector = sanitizedCols
-                .map((c) => `coalesce(${c}, '')`)
-                .join(" || ' ' || ");
-            const limitClause = parsed.limit !== undefined && parsed.limit > 0
-                ? ` LIMIT ${String(parsed.limit)}`
-                : "";
-            const sql = `SELECT ${selectCols}, ts_rank_cd(to_tsvector('${cfg}', ${tsvector}), plainto_tsquery('${cfg}', $1), ${String(norm)}) as rank
+            try {
+                const parsed = TextRankSchema.parse(params);
+                const cfg = sanitizeFtsConfig(parsed.config ?? "english");
+                const norm = parsed.normalization ?? 0;
+                // Handle both column (string) and columns (array) parameters
+                let cols;
+                if (parsed.columns !== undefined && parsed.columns.length > 0) {
+                    cols = parsed.columns;
+                }
+                else if (parsed.column !== undefined) {
+                    cols = [parsed.column];
+                }
+                else {
+                    return {
+                        success: false,
+                        error: "Either column or columns parameter is required",
+                    };
+                }
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const sanitizedCols = sanitizeIdentifiers(cols);
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ")
+                    : "*";
+                const tsvector = sanitizedCols
+                    .map((c) => `coalesce(${c}, '')`)
+                    .join(" || ' ' || ");
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                const sql = `SELECT ${selectCols}, ts_rank_cd(to_tsvector('${cfg}', ${tsvector}), plainto_tsquery('${cfg}', $1), ${String(norm)}) as rank
                         FROM ${tableName}
                         WHERE to_tsvector('${cfg}', ${tsvector}) @@ plainto_tsquery('${cfg}', $1)
                         ORDER BY rank DESC${limitClause}`;
-            const result = await adapter.executeQuery(sql, [parsed.query]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
+                const result = await adapter.executeQuery(sql, [parsed.query]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_text_rank validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_rank",
+                    }),
+                };
+            }
         },
     };
 }
@@ -164,29 +239,64 @@ function createTrigramSimilarityTool(adapter) {
         annotations: readOnly("Trigram Similarity"),
         icons: getToolIcons("text", readOnly("Trigram Similarity")),
         handler: async (params, _context) => {
-            const parsed = TrigramSimilaritySchema.parse(params);
-            const thresh = parsed.threshold ?? 0.3;
-            // Default limit to 100 to prevent large payloads
-            const limitVal = parsed.limit !== undefined && parsed.limit > 0 ? parsed.limit : 100;
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
-            }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const columnName = sanitizeIdentifier(parsed.column);
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ")
-                : "*";
-            const additionalWhere = parsed.where
-                ? ` AND (${sanitizeWhereClause(parsed.where)})`
-                : "";
-            const sql = `SELECT ${selectCols}, similarity(${columnName}, $1) as similarity
+            try {
+                const parsed = TrigramSimilaritySchema.parse(params);
+                const thresh = parsed.threshold ?? 0.3;
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const columnName = sanitizeIdentifier(parsed.column);
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ")
+                    : "*";
+                const additionalWhere = parsed.where
+                    ? ` AND (${sanitizeWhereClause(parsed.where)})`
+                    : "";
+                const sql = `SELECT ${selectCols}, similarity(${columnName}, $1) as similarity
                         FROM ${tableName}
                         WHERE similarity(${columnName}, $1) > ${String(thresh)}${additionalWhere}
-                        ORDER BY similarity DESC LIMIT ${String(limitVal)}`;
-            const result = await adapter.executeQuery(sql, [parsed.value]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
+                        ORDER BY similarity DESC${limitClause}`;
+                const result = await adapter.executeQuery(sql, [parsed.value]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_trigram_similarity validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_trigram_similarity",
+                    }),
+                };
+            }
         },
     };
 }
@@ -198,7 +308,10 @@ function createFuzzyMatchTool(adapter) {
         tableName: z.string().optional().describe("Table name (alias for table)"),
         column: z.string(),
         value: z.string(),
-        method: z.enum(["soundex", "levenshtein", "metaphone"]).optional(),
+        method: z
+            .string()
+            .optional()
+            .describe("Fuzzy match method (default: levenshtein). Valid: soundex, levenshtein, metaphone"),
         maxDistance: z
             .number()
             .optional()
@@ -225,37 +338,84 @@ function createFuzzyMatchTool(adapter) {
         annotations: readOnly("Fuzzy Match"),
         icons: getToolIcons("text", readOnly("Fuzzy Match")),
         handler: async (params, _context) => {
-            const parsed = FuzzyMatchSchema.parse(params);
-            // Method is already validated by zod enum, default to levenshtein if not provided
-            const method = parsed.method ?? "levenshtein";
-            const maxDist = parsed.maxDistance ?? 3;
-            // Default limit to 100 to prevent large payloads
-            const limitVal = parsed.limit !== undefined && parsed.limit > 0 ? parsed.limit : 100;
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
+            try {
+                const parsed = FuzzyMatchSchema.parse(params);
+                // Validate method (moved from z.enum to handler for structured error)
+                const VALID_METHODS = [
+                    "levenshtein",
+                    "soundex",
+                    "metaphone",
+                ];
+                const rawMethod = parsed.method ?? "levenshtein";
+                if (!VALID_METHODS.includes(rawMethod)) {
+                    return {
+                        success: false,
+                        error: `Invalid method "${rawMethod}". Valid methods: ${VALID_METHODS.join(", ")}`,
+                    };
+                }
+                const method = rawMethod;
+                const maxDist = parsed.maxDistance ?? 3;
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const columnName = sanitizeIdentifier(parsed.column);
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ")
+                    : "*";
+                const additionalWhere = parsed.where
+                    ? ` AND (${sanitizeWhereClause(parsed.where)})`
+                    : "";
+                let sql;
+                if (method === "soundex") {
+                    sql = `SELECT ${selectCols}, soundex(${columnName}) as code FROM ${tableName} WHERE soundex(${columnName}) = soundex($1)${additionalWhere}${limitClause}`;
+                }
+                else if (method === "metaphone") {
+                    sql = `SELECT ${selectCols}, metaphone(${columnName}, 10) as code FROM ${tableName} WHERE metaphone(${columnName}, 10) = metaphone($1, 10)${additionalWhere}${limitClause}`;
+                }
+                else {
+                    sql = `SELECT ${selectCols}, levenshtein(${columnName}, $1) as distance FROM ${tableName} WHERE levenshtein(${columnName}, $1) <= ${String(maxDist)}${additionalWhere} ORDER BY distance${limitClause}`;
+                }
+                const result = await adapter.executeQuery(sql, [parsed.value]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
             }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const columnName = sanitizeIdentifier(parsed.column);
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ")
-                : "*";
-            const additionalWhere = parsed.where
-                ? ` AND (${sanitizeWhereClause(parsed.where)})`
-                : "";
-            let sql;
-            if (method === "soundex") {
-                sql = `SELECT ${selectCols}, soundex(${columnName}) as code FROM ${tableName} WHERE soundex(${columnName}) = soundex($1)${additionalWhere} LIMIT ${String(limitVal)}`;
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_fuzzy_match validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_fuzzy_match",
+                    }),
+                };
             }
-            else if (method === "metaphone") {
-                sql = `SELECT ${selectCols}, metaphone(${columnName}, 10) as code FROM ${tableName} WHERE metaphone(${columnName}, 10) = metaphone($1, 10)${additionalWhere} LIMIT ${String(limitVal)}`;
-            }
-            else {
-                sql = `SELECT ${selectCols}, levenshtein(${columnName}, $1) as distance FROM ${tableName} WHERE levenshtein(${columnName}, $1) <= ${String(maxDist)}${additionalWhere} ORDER BY distance LIMIT ${String(limitVal)}`;
-            }
-            const result = await adapter.executeQuery(sql, [parsed.value]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
         },
     };
 }
@@ -269,27 +429,61 @@ function createRegexpMatchTool(adapter) {
         annotations: readOnly("Regexp Match"),
         icons: getToolIcons("text", readOnly("Regexp Match")),
         handler: async (params, _context) => {
-            const parsed = RegexpMatchSchema.parse(params);
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
+            try {
+                const parsed = RegexpMatchSchema.parse(params);
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const columnName = sanitizeIdentifier(parsed.column);
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ")
+                    : "*";
+                const op = parsed.flags?.includes("i") ? "~*" : "~";
+                const additionalWhere = parsed.where
+                    ? ` AND (${sanitizeWhereClause(parsed.where)})`
+                    : "";
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                const sql = `SELECT ${selectCols} FROM ${tableName} WHERE ${columnName} ${op} $1${additionalWhere}${limitClause}`;
+                const result = await adapter.executeQuery(sql, [parsed.pattern]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_regexp_match validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_regexp_match",
+                    }),
+                };
             }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const columnName = sanitizeIdentifier(parsed.column);
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ")
-                : "*";
-            const op = parsed.flags?.includes("i") ? "~*" : "~";
-            const additionalWhere = parsed.where
-                ? ` AND (${sanitizeWhereClause(parsed.where)})`
-                : "";
-            // Default limit to 100 to prevent large payloads
-            const limitVal = parsed.limit !== undefined && parsed.limit > 0 ? parsed.limit : 100;
-            const limitClause = ` LIMIT ${String(limitVal)}`;
-            const sql = `SELECT ${selectCols} FROM ${tableName} WHERE ${columnName} ${op} $1${additionalWhere}${limitClause}`;
-            const result = await adapter.executeQuery(sql, [parsed.pattern]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
         },
     };
 }
@@ -327,27 +521,61 @@ function createLikeSearchTool(adapter) {
         annotations: readOnly("LIKE Search"),
         icons: getToolIcons("text", readOnly("LIKE Search")),
         handler: async (params, _context) => {
-            const parsed = LikeSearchSchema.parse(params);
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
+            try {
+                const parsed = LikeSearchSchema.parse(params);
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const columnName = sanitizeIdentifier(parsed.column);
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ")
+                    : "*";
+                const op = parsed.caseSensitive === true ? "LIKE" : "ILIKE";
+                const additionalWhere = parsed.where
+                    ? ` AND (${sanitizeWhereClause(parsed.where)})`
+                    : "";
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                const sql = `SELECT ${selectCols} FROM ${tableName} WHERE ${columnName} ${op} $1${additionalWhere}${limitClause}`;
+                const result = await adapter.executeQuery(sql, [parsed.pattern]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_like_search validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_like_search",
+                    }),
+                };
             }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const columnName = sanitizeIdentifier(parsed.column);
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ")
-                : "*";
-            const op = parsed.caseSensitive === true ? "LIKE" : "ILIKE";
-            const additionalWhere = parsed.where
-                ? ` AND (${sanitizeWhereClause(parsed.where)})`
-                : "";
-            // Default limit to 100 to prevent large payloads
-            const limitVal = parsed.limit !== undefined && parsed.limit > 0 ? parsed.limit : 100;
-            const limitClause = ` LIMIT ${String(limitVal)}`;
-            const sql = `SELECT ${selectCols} FROM ${tableName} WHERE ${columnName} ${op} $1${additionalWhere}${limitClause}`;
-            const result = await adapter.executeQuery(sql, [parsed.pattern]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
         },
     };
 }
@@ -395,40 +623,74 @@ function createTextHeadlineTool(adapter) {
         annotations: readOnly("Text Headline"),
         icons: getToolIcons("text", readOnly("Text Headline")),
         handler: async (params, _context) => {
-            const parsed = HeadlineSchema.parse(params);
-            const cfg = sanitizeFtsConfig(parsed.config ?? "english");
-            // Build options string from individual params or use provided options
-            let opts;
-            if (parsed.options) {
-                opts = parsed.options;
-            }
-            else {
-                const optParts = [];
-                optParts.push(`StartSel=${parsed.startSel ?? "<b>"}`);
-                optParts.push(`StopSel=${parsed.stopSel ?? "</b>"}`);
-                optParts.push(`MaxWords=${String(parsed.maxWords ?? 35)}`);
-                optParts.push(`MinWords=${String(parsed.minWords ?? 15)}`);
-                opts = optParts.join(", ");
-            }
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
-            }
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const columnName = sanitizeIdentifier(parsed.column);
-            // Use provided select columns, or default to * (user should specify PK for stable identification)
-            const selectCols = parsed.select !== undefined && parsed.select.length > 0
-                ? sanitizeIdentifiers(parsed.select).join(", ") + ", "
-                : "";
-            const limitClause = parsed.limit !== undefined && parsed.limit > 0
-                ? ` LIMIT ${String(parsed.limit)}`
-                : "";
-            const sql = `SELECT ${selectCols}ts_headline('${cfg}', ${columnName}, plainto_tsquery('${cfg}', $1), '${opts}') as headline
+            try {
+                const parsed = HeadlineSchema.parse(params);
+                const cfg = sanitizeFtsConfig(parsed.config ?? "english");
+                // Build options string from individual params or use provided options
+                let opts;
+                if (parsed.options) {
+                    opts = parsed.options;
+                }
+                else {
+                    const optParts = [];
+                    optParts.push(`StartSel=${parsed.startSel ?? "<b>"}`);
+                    optParts.push(`StopSel=${parsed.stopSel ?? "</b>"}`);
+                    optParts.push(`MaxWords=${String(parsed.maxWords ?? 35)}`);
+                    optParts.push(`MinWords=${String(parsed.minWords ?? 15)}`);
+                    opts = optParts.join(", ");
+                }
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const columnName = sanitizeIdentifier(parsed.column);
+                // Use provided select columns, or default to * (user should specify PK for stable identification)
+                const selectCols = parsed.select !== undefined && parsed.select.length > 0
+                    ? sanitizeIdentifiers(parsed.select).join(", ") + ", "
+                    : "";
+                // Default limit to 100 to prevent large payloads; limit: 0 means no limit
+                const limitVal = parsed.limit === 0
+                    ? null
+                    : parsed.limit !== undefined && parsed.limit > 0
+                        ? parsed.limit
+                        : 100;
+                const limitClause = limitVal !== null ? ` LIMIT ${String(limitVal)}` : "";
+                const sql = `SELECT ${selectCols}ts_headline('${cfg}', ${columnName}, plainto_tsquery('${cfg}', $1), '${opts}') as headline
                         FROM ${tableName}
                         WHERE to_tsvector('${cfg}', ${columnName}) @@ plainto_tsquery('${cfg}', $1)${limitClause}`;
-            const result = await adapter.executeQuery(sql, [parsed.query]);
-            return { rows: result.rows, count: result.rows?.length ?? 0 };
+                const result = await adapter.executeQuery(sql, [parsed.query]);
+                const count = result.rows?.length ?? 0;
+                const truncated = limitVal !== null && count === limitVal;
+                return {
+                    rows: result.rows,
+                    count,
+                    ...(truncated
+                        ? {
+                            truncated: true,
+                            hint: `Results limited to ${String(limitVal)}. Use limit: 0 for all rows.`,
+                        }
+                        : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_text_headline validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_headline",
+                    }),
+                };
+            }
         },
     };
 }
@@ -461,36 +723,55 @@ function createFtsIndexTool(adapter) {
         annotations: write("Create FTS Index"),
         icons: getToolIcons("text", write("Create FTS Index")),
         handler: async (params, _context) => {
-            const parsed = FtsIndexSchema.parse(params);
-            const cfg = sanitizeFtsConfig(parsed.config ?? "english");
-            // The preprocessor guarantees table is set (converts tableName → table)
-            const resolvedTable = parsed.table ?? parsed.tableName;
-            if (!resolvedTable) {
-                throw new Error("Either 'table' or 'tableName' is required");
+            try {
+                const parsed = FtsIndexSchema.parse(params);
+                const cfg = sanitizeFtsConfig(parsed.config ?? "english");
+                // The preprocessor guarantees table is set (converts tableName → table)
+                const resolvedTable = parsed.table ?? parsed.tableName;
+                if (!resolvedTable) {
+                    return {
+                        success: false,
+                        error: "Either 'table' or 'tableName' is required",
+                    };
+                }
+                const defaultIndexName = `idx_${resolvedTable}_${parsed.column}_fts`;
+                const resolvedIndexName = parsed.name ?? defaultIndexName;
+                const indexName = sanitizeIdentifier(resolvedIndexName);
+                // Default to IF NOT EXISTS for safer operation (skip existing indexes)
+                const useIfNotExists = parsed.ifNotExists !== false;
+                const ifNotExists = useIfNotExists ? "IF NOT EXISTS " : "";
+                // Build qualified table name with schema support
+                const tableName = sanitizeTableName(resolvedTable, parsed.schema);
+                const columnName = sanitizeIdentifier(parsed.column);
+                // Check if index exists before creation (to accurately report 'skipped')
+                let existedBefore = false;
+                if (useIfNotExists) {
+                    const checkResult = await adapter.executeQuery(`SELECT 1 FROM pg_indexes WHERE indexname = $1 LIMIT 1`, [resolvedIndexName]);
+                    existedBefore = (checkResult.rows?.length ?? 0) > 0;
+                }
+                const sql = `CREATE INDEX ${ifNotExists}${indexName} ON ${tableName} USING gin(to_tsvector('${cfg}', ${columnName}))`;
+                await adapter.executeQuery(sql);
+                return {
+                    success: true,
+                    index: resolvedIndexName,
+                    config: cfg,
+                    skipped: existedBefore,
+                };
             }
-            const defaultIndexName = `idx_${resolvedTable}_${parsed.column}_fts`;
-            const resolvedIndexName = parsed.name ?? defaultIndexName;
-            const indexName = sanitizeIdentifier(resolvedIndexName);
-            // Default to IF NOT EXISTS for safer operation (skip existing indexes)
-            const useIfNotExists = parsed.ifNotExists !== false;
-            const ifNotExists = useIfNotExists ? "IF NOT EXISTS " : "";
-            // Build qualified table name with schema support
-            const tableName = sanitizeTableName(resolvedTable, parsed.schema);
-            const columnName = sanitizeIdentifier(parsed.column);
-            // Check if index exists before creation (to accurately report 'skipped')
-            let existedBefore = false;
-            if (useIfNotExists) {
-                const checkResult = await adapter.executeQuery(`SELECT 1 FROM pg_indexes WHERE indexname = $1 LIMIT 1`, [resolvedIndexName]);
-                existedBefore = (checkResult.rows?.length ?? 0) > 0;
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_create_fts_index validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_create_fts_index",
+                    }),
+                };
             }
-            const sql = `CREATE INDEX ${ifNotExists}${indexName} ON ${tableName} USING gin(to_tsvector('${cfg}', ${columnName}))`;
-            await adapter.executeQuery(sql);
-            return {
-                success: true,
-                index: resolvedIndexName,
-                config: cfg,
-                skipped: existedBefore,
-            };
         },
     };
 }
@@ -507,11 +788,27 @@ function createTextNormalizeTool(adapter) {
         annotations: readOnly("Text Normalize"),
         icons: getToolIcons("text", readOnly("Text Normalize")),
         handler: async (params, _context) => {
-            const parsed = NormalizeSchema.parse(params ?? {});
-            // Ensure unaccent extension is available
-            await adapter.executeQuery("CREATE EXTENSION IF NOT EXISTS unaccent");
-            const result = await adapter.executeQuery(`SELECT unaccent($1) as normalized`, [parsed.text]);
-            return { normalized: result.rows?.[0]?.["normalized"] };
+            try {
+                const parsed = NormalizeSchema.parse(params ?? {});
+                // Ensure unaccent extension is available
+                await adapter.executeQuery("CREATE EXTENSION IF NOT EXISTS unaccent");
+                const result = await adapter.executeQuery(`SELECT unaccent($1) as normalized`, [parsed.text]);
+                return { normalized: result.rows?.[0]?.["normalized"] };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_text_normalize validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_normalize",
+                    }),
+                };
+            }
         },
     };
 }
@@ -535,95 +832,109 @@ function createTextSentimentTool(_adapter) {
         annotations: readOnly("Text Sentiment"),
         icons: getToolIcons("text", readOnly("Text Sentiment")),
         handler: (params, _context) => {
-            const parsed = SentimentSchema.parse(params ?? {});
-            const text = parsed.text.toLowerCase();
-            const positiveWords = [
-                "good",
-                "great",
-                "excellent",
-                "amazing",
-                "wonderful",
-                "fantastic",
-                "love",
-                "happy",
-                "positive",
-                "best",
-                "beautiful",
-                "awesome",
-                "perfect",
-                "nice",
-                "helpful",
-                "thank",
-                "thanks",
-                "pleased",
-                "satisfied",
-                "recommend",
-                "enjoy",
-                "impressive",
-                "brilliant",
-            ];
-            const negativeWords = [
-                "bad",
-                "terrible",
-                "awful",
-                "horrible",
-                "worst",
-                "hate",
-                "angry",
-                "disappointed",
-                "poor",
-                "wrong",
-                "problem",
-                "issue",
-                "fail",
-                "failed",
-                "broken",
-                "useless",
-                "waste",
-                "frustrating",
-                "annoyed",
-                "unhappy",
-                "negative",
-                "complaint",
-                "slow",
-            ];
-            const words = text.split(/\s+/);
-            const matchedPositive = words
-                .map((w) => w.replace(/[^a-z]/g, ""))
-                .filter((w) => positiveWords.includes(w));
-            const matchedNegative = words
-                .map((w) => w.replace(/[^a-z]/g, ""))
-                .filter((w) => negativeWords.includes(w));
-            const positiveScore = matchedPositive.length;
-            const negativeScore = matchedNegative.length;
-            const totalScore = positiveScore - negativeScore;
-            let sentiment;
-            if (totalScore > 2)
-                sentiment = "very_positive";
-            else if (totalScore > 0)
-                sentiment = "positive";
-            else if (totalScore < -2)
-                sentiment = "very_negative";
-            else if (totalScore < 0)
-                sentiment = "negative";
-            else
-                sentiment = "neutral";
-            const result = {
-                sentiment,
-                score: totalScore,
-                positiveCount: positiveScore,
-                negativeCount: negativeScore,
-                confidence: positiveScore + negativeScore > 3
-                    ? "high"
-                    : positiveScore + negativeScore > 1
-                        ? "medium"
-                        : "low",
-            };
-            if (parsed.returnWords) {
-                result.matchedPositive = matchedPositive;
-                result.matchedNegative = matchedNegative;
+            try {
+                const parsed = SentimentSchema.parse(params ?? {});
+                const text = parsed.text.toLowerCase();
+                const positiveWords = [
+                    "good",
+                    "great",
+                    "excellent",
+                    "amazing",
+                    "wonderful",
+                    "fantastic",
+                    "love",
+                    "happy",
+                    "positive",
+                    "best",
+                    "beautiful",
+                    "awesome",
+                    "perfect",
+                    "nice",
+                    "helpful",
+                    "thank",
+                    "thanks",
+                    "pleased",
+                    "satisfied",
+                    "recommend",
+                    "enjoy",
+                    "impressive",
+                    "brilliant",
+                ];
+                const negativeWords = [
+                    "bad",
+                    "terrible",
+                    "awful",
+                    "horrible",
+                    "worst",
+                    "hate",
+                    "angry",
+                    "disappointed",
+                    "poor",
+                    "wrong",
+                    "problem",
+                    "issue",
+                    "fail",
+                    "failed",
+                    "broken",
+                    "useless",
+                    "waste",
+                    "frustrating",
+                    "annoyed",
+                    "unhappy",
+                    "negative",
+                    "complaint",
+                    "slow",
+                ];
+                const words = text.split(/\s+/);
+                const matchedPositive = words
+                    .map((w) => w.replace(/[^a-z]/g, ""))
+                    .filter((w) => positiveWords.includes(w));
+                const matchedNegative = words
+                    .map((w) => w.replace(/[^a-z]/g, ""))
+                    .filter((w) => negativeWords.includes(w));
+                const positiveScore = matchedPositive.length;
+                const negativeScore = matchedNegative.length;
+                const totalScore = positiveScore - negativeScore;
+                let sentiment;
+                if (totalScore > 2)
+                    sentiment = "very_positive";
+                else if (totalScore > 0)
+                    sentiment = "positive";
+                else if (totalScore < -2)
+                    sentiment = "very_negative";
+                else if (totalScore < 0)
+                    sentiment = "negative";
+                else
+                    sentiment = "neutral";
+                const result = {
+                    sentiment,
+                    score: totalScore,
+                    positiveCount: positiveScore,
+                    negativeCount: negativeScore,
+                    confidence: positiveScore + negativeScore > 3
+                        ? "high"
+                        : positiveScore + negativeScore > 1
+                            ? "medium"
+                            : "low",
+                };
+                if (parsed.returnWords) {
+                    result.matchedPositive = matchedPositive;
+                    result.matchedNegative = matchedNegative;
+                }
+                return Promise.resolve(result);
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return Promise.resolve({
+                        success: false,
+                        error: `pg_text_sentiment validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    });
+                }
+                return Promise.resolve({
+                    success: false,
+                    error: error instanceof Error ? error.message : "Unknown error occurred",
+                });
             }
-            return Promise.resolve(result);
         },
     };
 }
@@ -647,10 +958,26 @@ function createTextToVectorTool(adapter) {
         annotations: readOnly("Text to Vector"),
         icons: getToolIcons("text", readOnly("Text to Vector")),
         handler: async (params, _context) => {
-            const parsed = ToVectorSchema.parse(params ?? {});
-            const cfg = parsed.config ?? "english";
-            const result = await adapter.executeQuery(`SELECT to_tsvector($1, $2) as vector`, [cfg, parsed.text]);
-            return { vector: result.rows?.[0]?.["vector"] };
+            try {
+                const parsed = ToVectorSchema.parse(params ?? {});
+                const cfg = parsed.config ?? "english";
+                const result = await adapter.executeQuery(`SELECT to_tsvector($1, $2) as vector`, [cfg, parsed.text]);
+                return { vector: result.rows?.[0]?.["vector"] };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_text_to_vector validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_to_vector",
+                    }),
+                };
+            }
         },
     };
 }
@@ -678,22 +1005,38 @@ function createTextToQueryTool(adapter) {
         annotations: readOnly("Text to Query"),
         icons: getToolIcons("text", readOnly("Text to Query")),
         handler: async (params, _context) => {
-            const parsed = ToQuerySchema.parse(params ?? {});
-            const cfg = parsed.config ?? "english";
-            const mode = parsed.mode ?? "plain";
-            let fn;
-            switch (mode) {
-                case "phrase":
-                    fn = "phraseto_tsquery";
-                    break;
-                case "websearch":
-                    fn = "websearch_to_tsquery";
-                    break;
-                default:
-                    fn = "plainto_tsquery";
+            try {
+                const parsed = ToQuerySchema.parse(params ?? {});
+                const cfg = parsed.config ?? "english";
+                const mode = parsed.mode ?? "plain";
+                let fn;
+                switch (mode) {
+                    case "phrase":
+                        fn = "phraseto_tsquery";
+                        break;
+                    case "websearch":
+                        fn = "websearch_to_tsquery";
+                        break;
+                    default:
+                        fn = "plainto_tsquery";
+                }
+                const result = await adapter.executeQuery(`SELECT ${fn}($1, $2) as query`, [cfg, parsed.text]);
+                return { query: result.rows?.[0]?.["query"], mode };
+            }
+            catch (error) {
+                if (error instanceof ZodError) {
+                    return {
+                        success: false,
+                        error: `pg_text_to_query validation error: ${error.issues.map((e) => e.message).join(", ")}`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_to_query",
+                    }),
+                };
             }
-            const result = await adapter.executeQuery(`SELECT ${fn}($1, $2) as query`, [cfg, parsed.text]);
-            return { query: result.rows?.[0]?.["query"], mode };
         },
     };
 }
@@ -710,8 +1053,9 @@ function createTextSearchConfigTool(adapter) {
         annotations: readOnly("Search Configurations"),
         icons: getToolIcons("text", readOnly("Search Configurations")),
         handler: async (_params, _context) => {
-            const result = await adapter.executeQuery(`
-                SELECT 
+            try {
+                const result = await adapter.executeQuery(`
+                SELECT
                     c.cfgname as name,
                     n.nspname as schema,
                     obj_description(c.oid, 'pg_ts_config') as description
@@ -719,10 +1063,19 @@ function createTextSearchConfigTool(adapter) {
                 JOIN pg_namespace n ON n.oid = c.cfgnamespace
                 ORDER BY c.cfgname
             `);
-            return {
-                configs: result.rows ?? [],
-                count: result.rows?.length ?? 0,
-            };
+                return {
+                    configs: result.rows ?? [],
+                    count: result.rows?.length ?? 0,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_text_search_config",
+                    }),
+                };
+            }
         },
     };
 }