@neverinfamous/postgres-mcp 1.1.0 → 1.3.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,65 @@ 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(" || ' ' || ");
+                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
                         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]);
+                return { rows: result.rows, count: result.rows?.length ?? 0 };
+            }
+            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 +138,64 @@ 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(" || ' ' || ");
+                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
                         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]);
+                return { rows: result.rows, count: result.rows?.length ?? 0 };
+            }
+            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 +209,48 @@ 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
+                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) {
+                    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 };
+                const result = await adapter.executeQuery(sql, [parsed.value]);
+                return { rows: result.rows, count: result.rows?.length ?? 0 };
+            }
+            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 +262,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 +292,68 @@ 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
+                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) {
+                    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} LIMIT ${String(limitVal)}`;
+                }
+                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 };
             }
-            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,25 +367,46 @@ 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
+                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 };
+            }
+            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)})`
-                : "";
-            const limitClause = parsed.limit !== undefined ? ` LIMIT ${String(parsed.limit)}` : "";
-            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 };
         },
     };
 }
@@ -304,7 +423,10 @@ function createLikeSearchTool(adapter) {
             .optional()
             .describe("Use case-sensitive LIKE (default: false, uses ILIKE)"),
         select: z.array(z.string()).optional(),
-        limit: z.number().optional(),
+        limit: z
+            .number()
+            .optional()
+            .describe("Max results (default: 100 to prevent large payloads)"),
         where: z.string().optional().describe("Additional WHERE clause filter"),
         schema: z.string().optional().describe("Schema name (default: public)"),
     })
@@ -322,27 +444,46 @@ 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
+                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 };
+            }
+            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)})`
-                : "";
-            const limitClause = parsed.limit !== undefined && parsed.limit > 0
-                ? ` LIMIT ${String(parsed.limit)}`
-                : "";
-            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 };
         },
     };
 }
@@ -390,40 +531,59 @@ 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(", ") + ", "
+                    : "";
+                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
                         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]);
+                return { rows: result.rows, count: result.rows?.length ?? 0 };
+            }
+            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",
+                    }),
+                };
+            }
         },
     };
 }
@@ -456,36 +616,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,
-            };
         },
     };
 }
@@ -529,8 +708,7 @@ function createTextSentimentTool(_adapter) {
         outputSchema: TextSentimentOutputSchema,
         annotations: readOnly("Text Sentiment"),
         icons: getToolIcons("text", readOnly("Text Sentiment")),
-        // eslint-disable-next-line @typescript-eslint/require-await
-        handler: async (params, _context) => {
+        handler: (params, _context) => {
             const parsed = SentimentSchema.parse(params ?? {});
             const text = parsed.text.toLowerCase();
             const positiveWords = [
@@ -619,7 +797,7 @@ function createTextSentimentTool(_adapter) {
                 result.matchedPositive = matchedPositive;
                 result.matchedNegative = matchedNegative;
             }
-            return result;
+            return Promise.resolve(result);
         },
     };
 }