@neverinfamous/postgres-mcp 1.1.0 → 1.3.0

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

@@ -14,11 +14,10 @@
 import { z } from "zod";
 import { readOnly, write, destructive } from "../../../utils/annotations.js";
 import { getToolIcons } from "../../../utils/icons.js";
-import { KcacheQueryStatsSchema, KcacheDatabaseStatsSchema, KcacheResourceAnalysisSchema, 
+import { formatPostgresError } from "./core/error-helpers.js";
+import { KcacheQueryStatsSchemaBase, KcacheQueryStatsSchema, KcacheTopCpuSchemaBase, KcacheTopIoSchemaBase, KcacheDatabaseStatsSchemaBase, KcacheDatabaseStatsSchema, KcacheResourceAnalysisSchemaBase, KcacheResourceAnalysisSchema, 
 // Output schemas
 KcacheCreateExtensionOutputSchema, KcacheQueryStatsOutputSchema, KcacheTopCpuOutputSchema, KcacheTopIoOutputSchema, KcacheDatabaseStatsOutputSchema, KcacheResourceAnalysisOutputSchema, KcacheResetOutputSchema, } from "../schemas/index.js";
-// Helper to handle undefined params (allows tools to be called without {})
-const defaultToEmpty = (val) => val ?? {};
 async function getKcacheColumnNames(adapter) {
     const result = await adapter.executeQuery(`
         SELECT column_name FROM information_schema.columns 
@@ -105,37 +104,52 @@ Joins pg_stat_statements with pg_stat_kcache to show what SQL did AND what syste
 
 orderBy options: 'total_time' (default), 'cpu_time', 'reads', 'writes'. Use minCalls parameter to filter by call count.`,
         group: "kcache",
-        inputSchema: KcacheQueryStatsSchema,
+        inputSchema: KcacheQueryStatsSchemaBase,
         outputSchema: KcacheQueryStatsOutputSchema,
         annotations: readOnly("Kcache Query Stats"),
         icons: getToolIcons("kcache", readOnly("Kcache Query Stats")),
         handler: async (params, _context) => {
-            const { limit, orderBy, minCalls, queryPreviewLength } = KcacheQueryStatsSchema.parse(params);
-            const cols = await getKcacheColumnNames(adapter);
-            const DEFAULT_LIMIT = 50;
-            // limit: 0 means "no limit" (return all rows), undefined means use default
-            const limitVal = limit === 0 ? null : (limit ?? DEFAULT_LIMIT);
-            // Bound queryPreviewLength: 0 = full query, default 100, max 500
-            const previewLen = queryPreviewLength === 0
-                ? 10000
-                : Math.min(queryPreviewLength ?? 100, 500);
-            const orderColumn = orderBy === "cpu_time"
-                ? `(k.${cols.userTime} + k.${cols.systemTime})`
-                : orderBy === "reads"
-                    ? `k.${cols.reads}`
-                    : orderBy === "writes"
-                        ? `k.${cols.writes}`
-                        : "s.total_exec_time";
-            const conditions = [];
-            const queryParams = [];
-            let paramIndex = 1;
-            if (minCalls !== undefined) {
-                conditions.push(`s.calls >= $${String(paramIndex++)}`);
-                queryParams.push(minCalls);
-            }
-            const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-            // Get total count first for truncation indicator
-            const countSql = `
+            try {
+                const { limit, orderBy, minCalls, queryPreviewLength } = KcacheQueryStatsSchema.parse(params);
+                // Validate orderBy inside handler for structured error response
+                const VALID_ORDER_BY = [
+                    "total_time",
+                    "cpu_time",
+                    "reads",
+                    "writes",
+                ];
+                if (orderBy !== undefined &&
+                    !VALID_ORDER_BY.includes(orderBy)) {
+                    return {
+                        success: false,
+                        error: `Invalid orderBy value "${orderBy}". Valid options: ${VALID_ORDER_BY.join(", ")}`,
+                    };
+                }
+                const cols = await getKcacheColumnNames(adapter);
+                const DEFAULT_LIMIT = 20;
+                // limit: 0 means "no limit" (return all rows), undefined means use default
+                const limitVal = limit === 0 ? null : (limit ?? DEFAULT_LIMIT);
+                // Bound queryPreviewLength: 0 = full query, default 100, max 500
+                const previewLen = queryPreviewLength === 0
+                    ? 10000
+                    : Math.min(queryPreviewLength ?? 100, 500);
+                const orderColumn = orderBy === "cpu_time"
+                    ? `(k.${cols.userTime} + k.${cols.systemTime})`
+                    : orderBy === "reads"
+                        ? `k.${cols.reads}`
+                        : orderBy === "writes"
+                            ? `k.${cols.writes}`
+                            : "s.total_exec_time";
+                const conditions = [];
+                const queryParams = [];
+                const paramIndex = 1;
+                if (minCalls !== undefined) {
+                    conditions.push(`s.calls >= $${String(paramIndex)}`);
+                    queryParams.push(minCalls);
+                }
+                const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+                // Get total count first for truncation indicator
+                const countSql = `
                 SELECT COUNT(*) as total
                 FROM pg_stat_statements s
                 JOIN pg_stat_kcache() k ON s.queryid = k.queryid 
@@ -143,10 +157,10 @@ orderBy options: 'total_time' (default), 'cpu_time', 'reads', 'writes'. Use minC
                     AND s.dbid = k.dbid
                 ${whereClause}
             `;
-            const countResult = await adapter.executeQuery(countSql, queryParams);
-            const totalRaw = countResult.rows?.[0]?.["total"];
-            const totalCount = Number(totalRaw) || 0;
-            const sql = `
+                const countResult = await adapter.executeQuery(countSql, queryParams);
+                const totalRaw = countResult.rows?.[0]?.["total"];
+                const totalCount = Number(totalRaw) || 0;
+                const sql = `
                 SELECT 
                     s.queryid,
                     LEFT(s.query, ${String(previewLen)}) as query_preview,
@@ -170,17 +184,25 @@ orderBy options: 'total_time' (default), 'cpu_time', 'reads', 'writes'. Use minC
                 ORDER BY ${orderColumn} DESC
                 ${limitVal !== null ? `LIMIT ${String(limitVal)}` : ""}
             `;
-            const result = await adapter.executeQuery(sql, queryParams);
-            const rowCount = result.rows?.length ?? 0;
-            const truncated = rowCount < totalCount;
-            const response = {
-                queries: result.rows ?? [],
-                count: rowCount,
-                orderBy: orderBy ?? "total_time",
-                truncated,
-                totalCount,
-            };
-            return response;
+                const result = await adapter.executeQuery(sql, queryParams);
+                const rowCount = result.rows?.length ?? 0;
+                const effectiveTotalCount = Math.max(totalCount, rowCount);
+                const truncated = rowCount < effectiveTotalCount;
+                const response = {
+                    queries: result.rows ?? [],
+                    count: rowCount,
+                    orderBy: orderBy ?? "total_time",
+                    truncated,
+                    totalCount: effectiveTotalCount,
+                };
+                return response;
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, { tool: "pg_kcache_query_stats" }),
+                };
+            }
         },
     };
 }
@@ -193,25 +215,28 @@ function createKcacheTopCpuTool(adapter) {
         description: `Get top CPU-consuming queries. Shows which queries spend the most time 
 in user CPU (application code) vs system CPU (kernel operations).`,
         group: "kcache",
-        inputSchema: z.preprocess(defaultToEmpty, z.object({
-            limit: z
-                .number()
-                .optional()
-                .describe("Number of top queries to return (default: 10)"),
-        })),
+        inputSchema: KcacheTopCpuSchemaBase,
         outputSchema: KcacheTopCpuOutputSchema,
         annotations: readOnly("Kcache Top CPU"),
         icons: getToolIcons("kcache", readOnly("Kcache Top CPU")),
         handler: async (params, _context) => {
-            const parsed = z
-                .object({ limit: z.number().optional() })
-                .parse(params ?? {});
-            const DEFAULT_LIMIT = 10;
-            // limit: 0 means "no limit" (return all rows), undefined means use default
-            const limitVal = parsed.limit === 0 ? null : (parsed.limit ?? DEFAULT_LIMIT);
-            const cols = await getKcacheColumnNames(adapter);
-            // Get total count first for truncation indicator
-            const countSql = `
+            try {
+                const parsed = z
+                    .object({
+                    limit: z.number().optional(),
+                    queryPreviewLength: z.number().optional(),
+                })
+                    .parse(params ?? {});
+                const DEFAULT_LIMIT = 10;
+                // limit: 0 means "no limit" (return all rows), undefined means use default
+                const limitVal = parsed.limit === 0 ? null : (parsed.limit ?? DEFAULT_LIMIT);
+                // Bound queryPreviewLength: 0 = full query, default 100, max 500
+                const previewLen = parsed.queryPreviewLength === 0
+                    ? 10000
+                    : Math.min(parsed.queryPreviewLength ?? 100, 500);
+                const cols = await getKcacheColumnNames(adapter);
+                // Get total count first for truncation indicator
+                const countSql = `
                 SELECT COUNT(*) as total
                 FROM pg_stat_statements s
                 JOIN pg_stat_kcache() k ON s.queryid = k.queryid 
@@ -219,13 +244,13 @@ in user CPU (application code) vs system CPU (kernel operations).`,
                     AND s.dbid = k.dbid
                 WHERE (k.${cols.userTime} + k.${cols.systemTime}) > 0
             `;
-            const countResult = await adapter.executeQuery(countSql);
-            const totalRaw = countResult.rows?.[0]?.["total"];
-            const totalCount = Number(totalRaw) || 0;
-            const sql = `
+                const countResult = await adapter.executeQuery(countSql);
+                const totalRaw = countResult.rows?.[0]?.["total"];
+                const totalCount = Number(totalRaw) || 0;
+                const sql = `
                 SELECT 
                     s.queryid,
-                    LEFT(s.query, 100) as query_preview,
+                    LEFT(s.query, ${String(previewLen)}) as query_preview,
                     s.calls,
                     k.${cols.userTime} as user_time,
                     k.${cols.systemTime} as system_time,
@@ -249,17 +274,25 @@ in user CPU (application code) vs system CPU (kernel operations).`,
                 ORDER BY (k.${cols.userTime} + k.${cols.systemTime}) DESC
                 ${limitVal !== null ? `LIMIT ${String(limitVal)}` : ""}
             `;
-            const result = await adapter.executeQuery(sql);
-            const rowCount = result.rows?.length ?? 0;
-            const truncated = rowCount < totalCount;
-            const response = {
-                topCpuQueries: result.rows ?? [],
-                count: rowCount,
-                description: "Queries ranked by total CPU time (user + system)",
-                truncated,
-                totalCount,
-            };
-            return response;
+                const result = await adapter.executeQuery(sql);
+                const rowCount = result.rows?.length ?? 0;
+                const effectiveTotalCount = Math.max(totalCount, rowCount);
+                const truncated = rowCount < effectiveTotalCount;
+                const response = {
+                    topCpuQueries: result.rows ?? [],
+                    count: rowCount,
+                    description: "Queries ranked by total CPU time (user + system)",
+                    truncated,
+                    totalCount: effectiveTotalCount,
+                };
+                return response;
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, { tool: "pg_kcache_top_cpu" }),
+                };
+            }
         },
     };
 }
@@ -272,71 +305,63 @@ function createKcacheTopIoTool(adapter) {
         description: `Get top I/O-consuming queries. Shows filesystem-level reads and writes, 
 which represent actual disk access (not just shared buffer hits).`,
         group: "kcache",
-        inputSchema: z.preprocess((input) => {
-            const obj = defaultToEmpty(input);
-            // Alias: ioType -> type
-            if (obj["ioType"] !== undefined && obj["type"] === undefined) {
-                obj["type"] = obj["ioType"];
-            }
-            return obj;
-        }, z.object({
-            type: z
-                .enum(["reads", "writes", "both"])
-                .optional()
-                .describe("I/O type to rank by (default: both)"),
-            ioType: z
-                .enum(["reads", "writes", "both"])
-                .optional()
-                .describe("Alias for type"),
-            limit: z
-                .number()
-                .optional()
-                .describe("Number of top queries to return (default: 10)"),
-        })),
+        inputSchema: KcacheTopIoSchemaBase,
         outputSchema: KcacheTopIoOutputSchema,
         annotations: readOnly("Kcache Top IO"),
         icons: getToolIcons("kcache", readOnly("Kcache Top IO")),
         handler: async (params, _context) => {
-            // Apply the same preprocessing as inputSchema
-            const preprocessed = (() => {
-                const obj = (params ?? {});
-                if (obj["ioType"] !== undefined && obj["type"] === undefined) {
-                    return { ...obj, type: obj["ioType"] };
-                }
-                return obj;
-            })();
-            const parsed = z
-                .object({
-                type: z.enum(["reads", "writes", "both"]).optional(),
-                limit: z.number().optional(),
-            })
-                .parse(preprocessed);
-            const ioType = parsed.type ?? "both";
-            const DEFAULT_LIMIT = 10;
-            // limit: 0 means "no limit" (return all rows), undefined means use default
-            const limitVal = parsed.limit === 0 ? null : (parsed.limit ?? DEFAULT_LIMIT);
-            const cols = await getKcacheColumnNames(adapter);
-            const orderColumn = ioType === "reads"
-                ? `k.${cols.reads}`
-                : ioType === "writes"
-                    ? `k.${cols.writes}`
-                    : `(k.${cols.reads} + k.${cols.writes})`;
-            // Get total count first for truncation indicator
-            const countSql = `
+            try {
+                // Apply the same preprocessing as inputSchema
+                const preprocessed = (() => {
+                    const obj = (params ?? {});
+                    if (obj["ioType"] !== undefined && obj["type"] === undefined) {
+                        return { ...obj, type: obj["ioType"] };
+                    }
+                    return obj;
+                })();
+                const parsed = z
+                    .object({
+                    type: z.enum(["reads", "writes", "both"]).optional(),
+                    limit: z.number().optional(),
+                    queryPreviewLength: z.number().optional(),
+                })
+                    .parse(preprocessed);
+                const ioType = parsed.type ?? "both";
+                const DEFAULT_LIMIT = 10;
+                // limit: 0 means "no limit" (return all rows), undefined means use default
+                const limitVal = parsed.limit === 0 ? null : (parsed.limit ?? DEFAULT_LIMIT);
+                // Bound queryPreviewLength: 0 = full query, default 100, max 500
+                const previewLen = parsed.queryPreviewLength === 0
+                    ? 10000
+                    : Math.min(parsed.queryPreviewLength ?? 100, 500);
+                const cols = await getKcacheColumnNames(adapter);
+                const orderColumn = ioType === "reads"
+                    ? `k.${cols.reads}`
+                    : ioType === "writes"
+                        ? `k.${cols.writes}`
+                        : `(k.${cols.reads} + k.${cols.writes})`;
+                // Filter by the type-specific IO column so 'reads' excludes write-only queries
+                const ioFilter = ioType === "reads"
+                    ? `k.${cols.reads} > 0`
+                    : ioType === "writes"
+                        ? `k.${cols.writes} > 0`
+                        : `(k.${cols.reads} + k.${cols.writes}) > 0`;
+                // Get total count first for truncation indicator
+                const countSql = `
                 SELECT COUNT(*) as total
                 FROM pg_stat_statements s
                 JOIN pg_stat_kcache() k ON s.queryid = k.queryid 
                     AND s.userid = k.userid 
                     AND s.dbid = k.dbid
-                WHERE (k.${cols.reads} + k.${cols.writes}) > 0
+                WHERE ${ioFilter}
             `;
-            const countResult = await adapter.executeQuery(countSql);
-            const totalRaw = countResult.rows?.[0]?.["total"];
-            const totalCount = Number(totalRaw) || 0;
-            const sql = `
+                const countResult = await adapter.executeQuery(countSql);
+                const totalRaw = countResult.rows?.[0]?.["total"];
+                const totalCount = Number(totalRaw) || 0;
+                const sql = `
                 SELECT 
                     s.queryid,
-                    LEFT(s.query, 100) as query_preview,
+                    LEFT(s.query, ${String(previewLen)}) as query_preview,
                     s.calls,
                     k.${cols.reads} as read_bytes,
                     k.${cols.writes} as write_bytes,
@@ -348,22 +373,30 @@ which represent actual disk access (not just shared buffer hits).`,
                 JOIN pg_stat_kcache() k ON s.queryid = k.queryid 
                     AND s.userid = k.userid 
                     AND s.dbid = k.dbid
-                WHERE (k.${cols.reads} + k.${cols.writes}) > 0
+                WHERE ${ioFilter}
                 ORDER BY ${orderColumn} DESC
                 ${limitVal !== null ? `LIMIT ${String(limitVal)}` : ""}
             `;
-            const result = await adapter.executeQuery(sql);
-            const rowCount = result.rows?.length ?? 0;
-            const truncated = rowCount < totalCount;
-            const response = {
-                topIoQueries: result.rows ?? [],
-                count: rowCount,
-                ioType,
-                description: `Queries ranked by ${ioType === "both" ? "total I/O" : ioType}`,
-                truncated,
-                totalCount,
-            };
-            return response;
+                const result = await adapter.executeQuery(sql);
+                const rowCount = result.rows?.length ?? 0;
+                const effectiveTotalCount = Math.max(totalCount, rowCount);
+                const truncated = rowCount < effectiveTotalCount;
+                const response = {
+                    topIoQueries: result.rows ?? [],
+                    count: rowCount,
+                    ioType,
+                    description: `Queries ranked by ${ioType === "both" ? "total I/O" : ioType}`,
+                    truncated,
+                    totalCount: effectiveTotalCount,
+                };
+                return response;
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, { tool: "pg_kcache_top_io" }),
+                };
+            }
         },
     };
 }
@@ -376,17 +409,18 @@ function createKcacheDatabaseStatsTool(adapter) {
         description: `Get aggregated OS-level statistics for a database. 
 Shows total CPU time, I/O, and page faults across all queries.`,
         group: "kcache",
-        inputSchema: KcacheDatabaseStatsSchema,
+        inputSchema: KcacheDatabaseStatsSchemaBase,
         outputSchema: KcacheDatabaseStatsOutputSchema,
         annotations: readOnly("Kcache Database Stats"),
         icons: getToolIcons("kcache", readOnly("Kcache Database Stats")),
         handler: async (params, _context) => {
-            const { database } = KcacheDatabaseStatsSchema.parse(params);
-            const cols = await getKcacheColumnNames(adapter);
-            let sql;
-            const queryParams = [];
-            if (database !== undefined) {
-                sql = `
+            try {
+                const { database } = KcacheDatabaseStatsSchema.parse(params);
+                const cols = await getKcacheColumnNames(adapter);
+                let sql;
+                const queryParams = [];
+                if (database !== undefined) {
+                    sql = `
                     SELECT 
                         d.datname as database,
                         SUM(k.${cols.userTime}) as total_user_time,
@@ -404,10 +438,10 @@ Shows total CPU time, I/O, and page faults across all queries.`,
                     WHERE d.datname = $1
                     GROUP BY d.datname
                 `;
-                queryParams.push(database);
-            }
-            else {
-                sql = `
+                    queryParams.push(database);
+                }
+                else {
+                    sql = `
                     SELECT 
                         datname as database,
                         SUM(${cols.userTime}) as total_user_time,
@@ -424,12 +458,21 @@ Shows total CPU time, I/O, and page faults across all queries.`,
                     GROUP BY datname
                     ORDER BY SUM(${cols.userTime} + ${cols.systemTime}) DESC
                 `;
+                }
+                const result = await adapter.executeQuery(sql, queryParams);
+                return {
+                    databaseStats: result.rows ?? [],
+                    count: result.rows?.length ?? 0,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_kcache_database_stats",
+                    }),
+                };
             }
-            const result = await adapter.executeQuery(sql, queryParams);
-            return {
-                databaseStats: result.rows ?? [],
-                count: result.rows?.length ?? 0,
-            };
         },
     };
 }
@@ -442,36 +485,37 @@ function createKcacheResourceAnalysisTool(adapter) {
         description: `Analyze queries to classify them as CPU-bound, I/O-bound, or balanced.
 Helps identify the root cause of performance issues - is the query computation-heavy or disk-heavy?`,
         group: "kcache",
-        inputSchema: KcacheResourceAnalysisSchema,
+        inputSchema: KcacheResourceAnalysisSchemaBase,
         outputSchema: KcacheResourceAnalysisOutputSchema,
         annotations: readOnly("Kcache Resource Analysis"),
         icons: getToolIcons("kcache", readOnly("Kcache Resource Analysis")),
         handler: async (params, _context) => {
-            const { queryId, threshold, limit, minCalls, queryPreviewLength } = KcacheResourceAnalysisSchema.parse(params);
-            const thresholdVal = threshold ?? 0.5;
-            const DEFAULT_LIMIT = 50;
-            // limit: 0 means "no limit" (return all rows), undefined means use default
-            const limitVal = limit === 0 ? null : (limit ?? DEFAULT_LIMIT);
-            // Bound queryPreviewLength: 0 = full query, default 100, max 500
-            const previewLen = queryPreviewLength === 0
-                ? 10000
-                : Math.min(queryPreviewLength ?? 100, 500);
-            const cols = await getKcacheColumnNames(adapter);
-            const conditions = [];
-            const queryParams = [];
-            let paramIndex = 1;
-            if (queryId !== undefined) {
-                conditions.push(`s.queryid::text = $${String(paramIndex++)}`);
-                queryParams.push(queryId);
-            }
-            if (minCalls !== undefined) {
-                conditions.push(`s.calls >= $${String(paramIndex++)}`);
-                queryParams.push(minCalls);
-            }
-            conditions.push(`(k.${cols.userTime} + k.${cols.systemTime} + k.${cols.reads} + k.${cols.writes}) > 0`);
-            const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-            // Get total count first for truncation indicator
-            const countSql = `
+            try {
+                const { queryId, threshold, limit, minCalls, queryPreviewLength } = KcacheResourceAnalysisSchema.parse(params);
+                const thresholdVal = threshold ?? 0.5;
+                const DEFAULT_LIMIT = 20;
+                // limit: 0 means "no limit" (return all rows), undefined means use default
+                const limitVal = limit === 0 ? null : (limit ?? DEFAULT_LIMIT);
+                // Bound queryPreviewLength: 0 = full query, default 100, max 500
+                const previewLen = queryPreviewLength === 0
+                    ? 10000
+                    : Math.min(queryPreviewLength ?? 100, 500);
+                const cols = await getKcacheColumnNames(adapter);
+                const conditions = [];
+                const queryParams = [];
+                let paramIndex = 1;
+                if (queryId !== undefined) {
+                    conditions.push(`s.queryid::text = $${String(paramIndex++)}`);
+                    queryParams.push(queryId);
+                }
+                if (minCalls !== undefined) {
+                    conditions.push(`s.calls >= $${String(paramIndex)}`);
+                    queryParams.push(minCalls);
+                }
+                conditions.push(`(k.${cols.userTime} + k.${cols.systemTime} + k.${cols.reads} + k.${cols.writes}) > 0`);
+                const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+                // Get total count first for truncation indicator
+                const countSql = `
                 SELECT COUNT(*) as total
                 FROM pg_stat_statements s
                 JOIN pg_stat_kcache() k ON s.queryid = k.queryid 
@@ -479,10 +523,10 @@ Helps identify the root cause of performance issues - is the query computation-h
                     AND s.dbid = k.dbid
                 ${whereClause}
             `;
-            const countResult = await adapter.executeQuery(countSql, queryParams);
-            const totalRaw = countResult.rows?.[0]?.["total"];
-            const totalCount = Number(totalRaw) || 0;
-            const sql = `
+                const countResult = await adapter.executeQuery(countSql, queryParams);
+                const totalRaw = countResult.rows?.[0]?.["total"];
+                const totalCount = Number(totalRaw) || 0;
+                const sql = `
                 WITH query_metrics AS (
                     SELECT 
                         s.queryid,
@@ -528,32 +572,42 @@ Helps identify the root cause of performance issues - is the query computation-h
                 ORDER BY total_time_ms DESC
                 ${limitVal !== null ? `LIMIT ${String(limitVal)}` : ""}
             `;
-            const result = await adapter.executeQuery(sql, queryParams);
-            const rows = result.rows ?? [];
-            const truncated = rows.length < totalCount;
-            const cpuBound = rows.filter((r) => r["resource_classification"] === "CPU-bound").length;
-            const ioBound = rows.filter((r) => r["resource_classification"] === "I/O-bound").length;
-            const balanced = rows.filter((r) => r["resource_classification"] === "Balanced").length;
-            const response = {
-                queries: rows,
-                count: rows.length,
-                summary: {
-                    cpuBound,
-                    ioBound,
-                    balanced,
-                    threshold: thresholdVal,
-                },
-                recommendations: [
-                    cpuBound > ioBound
-                        ? "Most resource-intensive queries are CPU-bound. Consider query optimization or more CPU resources."
-                        : ioBound > cpuBound
-                            ? "Most resource-intensive queries are I/O-bound. Consider more memory, faster storage, or better indexing."
-                            : "Resource usage is balanced between CPU and I/O.",
-                ],
-                truncated,
-                totalCount,
-            };
-            return response;
+                const result = await adapter.executeQuery(sql, queryParams);
+                const rows = result.rows ?? [];
+                const effectiveTotalCount = Math.max(totalCount, rows.length);
+                const truncated = rows.length < effectiveTotalCount;
+                const cpuBound = rows.filter((r) => r["resource_classification"] === "CPU-bound").length;
+                const ioBound = rows.filter((r) => r["resource_classification"] === "I/O-bound").length;
+                const balanced = rows.filter((r) => r["resource_classification"] === "Balanced").length;
+                const response = {
+                    queries: rows,
+                    count: rows.length,
+                    summary: {
+                        cpuBound,
+                        ioBound,
+                        balanced,
+                        threshold: thresholdVal,
+                    },
+                    recommendations: [
+                        cpuBound > ioBound
+                            ? "Most resource-intensive queries are CPU-bound. Consider query optimization or more CPU resources."
+                            : ioBound > cpuBound
+                                ? "Most resource-intensive queries are I/O-bound. Consider more memory, faster storage, or better indexing."
+                                : "Resource usage is balanced between CPU and I/O.",
+                    ],
+                    truncated,
+                    totalCount: effectiveTotalCount,
+                };
+                return response;
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_kcache_resource_analysis",
+                    }),
+                };
+            }
         },
     };
 }
@@ -571,12 +625,20 @@ Note: This also resets pg_stat_statements statistics.`,
         annotations: destructive("Reset Kcache Stats"),
         icons: getToolIcons("kcache", destructive("Reset Kcache Stats")),
         handler: async (_params, _context) => {
-            await adapter.executeQuery("SELECT pg_stat_kcache_reset()");
-            return {
-                success: true,
-                message: "pg_stat_kcache statistics reset",
-                note: "pg_stat_statements statistics were also reset",
-            };
+            try {
+                await adapter.executeQuery("SELECT pg_stat_kcache_reset()");
+                return {
+                    success: true,
+                    message: "pg_stat_kcache statistics reset",
+                    note: "pg_stat_statements statistics were also reset",
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, { tool: "pg_kcache_reset" }),
+                };
+            }
         },
     };
 }