fdic-mcp-server 1.0.7 → 1.0.8

package/dist/index.js

@@ -30,7 +30,7 @@ var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamable
 var import_express = __toESM(require("express"));
 
 // src/constants.ts
-var VERSION = true ? "1.0.7" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.0.8" : process.env.npm_package_version ?? "0.0.0-dev";
 var FDIC_API_BASE_URL = "https://banks.data.fdic.gov/api";
 var CHARACTER_LIMIT = 5e4;
 var ENDPOINTS = {
@@ -56,6 +56,13 @@ var apiClient = import_axios.default.create({
 });
 var QUERY_CACHE_TTL_MS = 6e4;
 var queryCache = /* @__PURE__ */ new Map();
+function pruneExpiredQueryCache(now) {
+  for (const [key, entry] of queryCache.entries()) {
+    if (entry.expiresAt <= now) {
+      queryCache.delete(key);
+    }
+  }
+}
 function getCacheKey(endpoint, params) {
   return JSON.stringify([
     endpoint,
@@ -67,10 +74,15 @@ function getCacheKey(endpoint, params) {
     params.sort_order ?? null
   ]);
 }
-async function queryEndpoint(endpoint, params) {
-  const cacheKey = getCacheKey(endpoint, params);
+async function queryEndpoint(endpoint, params, options = {}) {
+  if (options.signal?.aborted) {
+    throw new Error("FDIC API request was canceled before it started.");
+  }
+  const shouldUseCache = !options.signal;
   const now = Date.now();
-  const cached = queryCache.get(cacheKey);
+  pruneExpiredQueryCache(now);
+  const cacheKey = getCacheKey(endpoint, params);
+  const cached = shouldUseCache ? queryCache.get(cacheKey) : void 0;
   if (cached && cached.expiresAt > now) {
     return cached.value;
   }
@@ -86,10 +98,14 @@ async function queryEndpoint(endpoint, params) {
       if (params.sort_by) queryParams.sort_by = params.sort_by;
       if (params.sort_order) queryParams.sort_order = params.sort_order;
       const response = await apiClient.get(`/${endpoint}`, {
-        params: queryParams
+        params: queryParams,
+        signal: options.signal
       });
       return response.data;
     } catch (err) {
+      if (options.signal?.aborted || typeof err === "object" && err !== null && "code" in err && err.code === "ERR_CANCELED" || err instanceof DOMException && err.name === "AbortError") {
+        throw new Error("FDIC API request was canceled.");
+      }
       if (err instanceof import_axios.AxiosError) {
         const status = err.response?.status;
         const detail = err.response?.data?.message ?? err.message;
@@ -112,14 +128,18 @@ async function queryEndpoint(endpoint, params) {
       throw new Error(`Unexpected error calling FDIC API: ${String(err)}`);
     }
   })();
-  queryCache.set(cacheKey, {
-    expiresAt: now + QUERY_CACHE_TTL_MS,
-    value: requestPromise
-  });
+  if (shouldUseCache) {
+    queryCache.set(cacheKey, {
+      expiresAt: now + QUERY_CACHE_TTL_MS,
+      value: requestPromise
+    });
+  }
   try {
     return await requestPromise;
   } catch (error) {
-    queryCache.delete(cacheKey);
+    if (shouldUseCache) {
+      queryCache.delete(cacheKey);
+    }
     throw error;
   }
 }
@@ -1055,6 +1075,7 @@ Prefer concise human-readable summaries or tables when answering users. Structur
 var import_zod7 = require("zod");
 var CHUNK_SIZE = 25;
 var MAX_CONCURRENCY = 4;
+var ANALYSIS_TIMEOUT_MS = 9e4;
 var SortFieldSchema = import_zod7.z.enum([
   "asset_growth",
   "asset_growth_pct",
@@ -1144,14 +1165,31 @@ function change(start, end) {
   if (start === null || end === null) return null;
   return end - start;
 }
+function getQuarterIndex(repdte) {
+  const year = Number.parseInt(repdte.slice(0, 4), 10);
+  const month = Number.parseInt(repdte.slice(4, 6), 10);
+  const quarter = month / 3;
+  if (!Number.isInteger(quarter) || quarter < 1 || quarter > 4) {
+    return null;
+  }
+  return year * 4 + quarter;
+}
 function yearsBetween(startRepdte, endRepdte) {
+  const startQuarterIndex = getQuarterIndex(startRepdte);
+  const endQuarterIndex = getQuarterIndex(endRepdte);
+  if (startQuarterIndex !== null && endQuarterIndex !== null) {
+    return Math.max((endQuarterIndex - startQuarterIndex) / 4, 0);
+  }
   const start = /* @__PURE__ */ new Date(
-    `${startRepdte.slice(0, 4)}-${startRepdte.slice(4, 6)}-${startRepdte.slice(6, 8)}`
+    `${startRepdte.slice(0, 4)}-${startRepdte.slice(4, 6)}-${startRepdte.slice(6, 8)}T00:00:00Z`
   );
   const end = /* @__PURE__ */ new Date(
-    `${endRepdte.slice(0, 4)}-${endRepdte.slice(4, 6)}-${endRepdte.slice(6, 8)}`
+    `${endRepdte.slice(0, 4)}-${endRepdte.slice(4, 6)}-${endRepdte.slice(6, 8)}T00:00:00Z`
+  );
+  return Math.max(
+    (end.getTime() - start.getTime()) / (365.25 * 24 * 60 * 60 * 1e3),
+    0
   );
-  return Math.max((end.getTime() - start.getTime()) / (365.25 * 24 * 60 * 60 * 1e3), 0);
 }
 function cagr(start, end, years) {
   if (start === null || end === null || start <= 0 || end <= 0 || years <= 0) {
@@ -1223,6 +1261,21 @@ function buildTopLevelInsights(comparisons) {
       (comparison) => comparison.insights?.includes(
         "growth_with_branch_consolidation"
       )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    deposit_mix_softening: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "deposit_mix_softening"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    sustained_asset_growth: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "sustained_asset_growth"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    multi_quarter_roa_decline: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "multi_quarter_roa_decline"
+      )
     ).slice(0, 5).map((comparison) => String(comparison.name))
   };
 }
@@ -1378,7 +1431,7 @@ Insights
 ${insights}` : `${header}
 ${rows.join("\n")}`;
 }
-async function fetchInstitutionRoster(state, institutionFilters, activeOnly) {
+async function fetchInstitutionRoster(state, institutionFilters, activeOnly, signal) {
   const filterParts = [];
   if (state) filterParts.push(`STNAME:"${state}"`);
   if (activeOnly) filterParts.push("ACTIVE:1");
@@ -1390,10 +1443,12 @@ async function fetchInstitutionRoster(state, institutionFilters, activeOnly) {
     offset: 0,
     sort_by: "CERT",
     sort_order: "ASC"
-  });
-  return extractRecords(response);
+  }, { signal });
+  const records = extractRecords(response);
+  const warning = response.meta.total > records.length ? `Institution roster truncated to ${records.length.toLocaleString()} records out of ${response.meta.total.toLocaleString()} matched institutions. Narrow the comparison set with institution_filters or certs for complete analysis.` : void 0;
+  return { records, warning };
 }
-async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, fields) {
+async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, fields, signal) {
   const certFilters = buildCertFilters(certs);
   const tasks = repdteFilters.flatMap(
     (repdteFilter) => certFilters.map((certFilter) => ({
@@ -1409,7 +1464,7 @@ async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, field
       offset: 0,
       sort_by: "CERT",
       sort_order: "ASC"
-    });
+    }, { signal });
     return { repdteFilter: task.repdteFilter, response };
   });
   const byDate = /* @__PURE__ */ new Map();
@@ -1425,7 +1480,7 @@ async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, field
   }
   return byDate;
 }
-async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, fields) {
+async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, fields, signal) {
   const certFilters = buildCertFilters(certs);
   const responses = await mapWithConcurrency(
     certFilters,
@@ -1437,7 +1492,7 @@ async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, field
       offset: 0,
       sort_by: "REPDTE",
       sort_order: "ASC"
-    })
+    }, { signal })
   );
   const grouped = /* @__PURE__ */ new Map();
   for (const response of responses) {
@@ -1567,12 +1622,19 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
       sort_by,
       sort_order
     }) => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       try {
-        const roster = certs && certs.length > 0 ? certs.map((cert) => ({ CERT: cert })) : await fetchInstitutionRoster(
+        const rosterResult = certs && certs.length > 0 ? {
+          records: certs.map((cert) => ({ CERT: cert })),
+          warning: void 0
+        } : await fetchInstitutionRoster(
           state,
           institution_filters,
-          active_only
+          active_only,
+          controller.signal
         );
+        const roster = rosterResult.records;
         const candidateCerts = roster.map((record) => asNumber(record.CERT)).filter((cert) => cert !== null);
         if (candidateCerts.length === 0) {
           const output2 = {
@@ -1605,14 +1667,16 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
               candidateCerts,
               start_repdte,
               end_repdte,
-              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE"
+              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE",
+              controller.signal
             ),
             include_demographics ? fetchSeriesRecords(
               ENDPOINTS.DEMOGRAPHICS,
               candidateCerts,
               start_repdte,
               end_repdte,
-              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME"
+              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME",
+              controller.signal
             ) : Promise.resolve(/* @__PURE__ */ new Map())
           ]);
           comparisons = candidateCerts.map(
@@ -1633,13 +1697,15 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
               ENDPOINTS.FINANCIALS,
               candidateCerts,
               [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
-              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE"
+              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE",
+              controller.signal
             ),
             include_demographics ? fetchBatchedRecordsForDates(
               ENDPOINTS.DEMOGRAPHICS,
               candidateCerts,
               [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
-              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME"
+              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME",
+              controller.signal
             ) : Promise.resolve(/* @__PURE__ */ new Map())
           ]);
           const startFinancials = financialSnapshots.get(`REPDTE:${start_repdte}`) ?? /* @__PURE__ */ new Map();
@@ -1662,10 +1728,12 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
             );
           }).filter((comparison) => comparison !== null);
         }
-        const ranked = sortComparisons(comparisons, sort_by, sort_order).slice(
-          0,
-          limit
+        const sortedComparisons = sortComparisons(
+          comparisons,
+          sort_by,
+          sort_order
         );
+        const ranked = sortedComparisons.slice(0, limit);
         const pagination = buildPaginationInfo(comparisons.length, 0, ranked.length);
         const output = {
           total_candidates: candidateCerts.length,
@@ -1675,12 +1743,16 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
           analysis_mode,
           sort_by,
           sort_order,
-          insights: buildTopLevelInsights(comparisons),
+          warnings: rosterResult.warning ? [rosterResult.warning] : [],
+          insights: buildTopLevelInsights(sortedComparisons),
           ...pagination,
           comparisons: ranked
         };
         const text = truncateIfNeeded(
-          formatComparisonText(output),
+          [
+            rosterResult.warning ? `Warning: ${rosterResult.warning}` : null,
+            formatComparisonText(output)
+          ].filter((value) => value !== null).join("\n\n"),
           CHARACTER_LIMIT
         );
         return {
@@ -1688,7 +1760,16 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
           structuredContent: output
         };
       } catch (err) {
+        if (controller.signal.aborted) {
+          return formatToolError(
+            new Error(
+              `Analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Narrow the comparison set with certs or institution_filters and try again.`
+            )
+          );
+        }
         return formatToolError(err);
+      } finally {
+        clearTimeout(timeoutId);
       }
     }
   );

package/dist/server.js

@@ -41,7 +41,7 @@ var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamable
 var import_express = __toESM(require("express"));
 
 // src/constants.ts
-var VERSION = true ? "1.0.7" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.0.8" : process.env.npm_package_version ?? "0.0.0-dev";
 var FDIC_API_BASE_URL = "https://banks.data.fdic.gov/api";
 var CHARACTER_LIMIT = 5e4;
 var ENDPOINTS = {
@@ -67,6 +67,13 @@ var apiClient = import_axios.default.create({
 });
 var QUERY_CACHE_TTL_MS = 6e4;
 var queryCache = /* @__PURE__ */ new Map();
+function pruneExpiredQueryCache(now) {
+  for (const [key, entry] of queryCache.entries()) {
+    if (entry.expiresAt <= now) {
+      queryCache.delete(key);
+    }
+  }
+}
 function getCacheKey(endpoint, params) {
   return JSON.stringify([
     endpoint,
@@ -78,10 +85,15 @@ function getCacheKey(endpoint, params) {
     params.sort_order ?? null
   ]);
 }
-async function queryEndpoint(endpoint, params) {
-  const cacheKey = getCacheKey(endpoint, params);
+async function queryEndpoint(endpoint, params, options = {}) {
+  if (options.signal?.aborted) {
+    throw new Error("FDIC API request was canceled before it started.");
+  }
+  const shouldUseCache = !options.signal;
   const now = Date.now();
-  const cached = queryCache.get(cacheKey);
+  pruneExpiredQueryCache(now);
+  const cacheKey = getCacheKey(endpoint, params);
+  const cached = shouldUseCache ? queryCache.get(cacheKey) : void 0;
   if (cached && cached.expiresAt > now) {
     return cached.value;
   }
@@ -97,10 +109,14 @@ async function queryEndpoint(endpoint, params) {
       if (params.sort_by) queryParams.sort_by = params.sort_by;
       if (params.sort_order) queryParams.sort_order = params.sort_order;
       const response = await apiClient.get(`/${endpoint}`, {
-        params: queryParams
+        params: queryParams,
+        signal: options.signal
       });
       return response.data;
     } catch (err) {
+      if (options.signal?.aborted || typeof err === "object" && err !== null && "code" in err && err.code === "ERR_CANCELED" || err instanceof DOMException && err.name === "AbortError") {
+        throw new Error("FDIC API request was canceled.");
+      }
       if (err instanceof import_axios.AxiosError) {
         const status = err.response?.status;
         const detail = err.response?.data?.message ?? err.message;
@@ -123,14 +139,18 @@ async function queryEndpoint(endpoint, params) {
       throw new Error(`Unexpected error calling FDIC API: ${String(err)}`);
     }
   })();
-  queryCache.set(cacheKey, {
-    expiresAt: now + QUERY_CACHE_TTL_MS,
-    value: requestPromise
-  });
+  if (shouldUseCache) {
+    queryCache.set(cacheKey, {
+      expiresAt: now + QUERY_CACHE_TTL_MS,
+      value: requestPromise
+    });
+  }
   try {
     return await requestPromise;
   } catch (error) {
-    queryCache.delete(cacheKey);
+    if (shouldUseCache) {
+      queryCache.delete(cacheKey);
+    }
     throw error;
   }
 }
@@ -1066,6 +1086,7 @@ Prefer concise human-readable summaries or tables when answering users. Structur
 var import_zod7 = require("zod");
 var CHUNK_SIZE = 25;
 var MAX_CONCURRENCY = 4;
+var ANALYSIS_TIMEOUT_MS = 9e4;
 var SortFieldSchema = import_zod7.z.enum([
   "asset_growth",
   "asset_growth_pct",
@@ -1155,14 +1176,31 @@ function change(start, end) {
   if (start === null || end === null) return null;
   return end - start;
 }
+function getQuarterIndex(repdte) {
+  const year = Number.parseInt(repdte.slice(0, 4), 10);
+  const month = Number.parseInt(repdte.slice(4, 6), 10);
+  const quarter = month / 3;
+  if (!Number.isInteger(quarter) || quarter < 1 || quarter > 4) {
+    return null;
+  }
+  return year * 4 + quarter;
+}
 function yearsBetween(startRepdte, endRepdte) {
+  const startQuarterIndex = getQuarterIndex(startRepdte);
+  const endQuarterIndex = getQuarterIndex(endRepdte);
+  if (startQuarterIndex !== null && endQuarterIndex !== null) {
+    return Math.max((endQuarterIndex - startQuarterIndex) / 4, 0);
+  }
   const start = /* @__PURE__ */ new Date(
-    `${startRepdte.slice(0, 4)}-${startRepdte.slice(4, 6)}-${startRepdte.slice(6, 8)}`
+    `${startRepdte.slice(0, 4)}-${startRepdte.slice(4, 6)}-${startRepdte.slice(6, 8)}T00:00:00Z`
   );
   const end = /* @__PURE__ */ new Date(
-    `${endRepdte.slice(0, 4)}-${endRepdte.slice(4, 6)}-${endRepdte.slice(6, 8)}`
+    `${endRepdte.slice(0, 4)}-${endRepdte.slice(4, 6)}-${endRepdte.slice(6, 8)}T00:00:00Z`
+  );
+  return Math.max(
+    (end.getTime() - start.getTime()) / (365.25 * 24 * 60 * 60 * 1e3),
+    0
   );
-  return Math.max((end.getTime() - start.getTime()) / (365.25 * 24 * 60 * 60 * 1e3), 0);
 }
 function cagr(start, end, years) {
   if (start === null || end === null || start <= 0 || end <= 0 || years <= 0) {
@@ -1234,6 +1272,21 @@ function buildTopLevelInsights(comparisons) {
       (comparison) => comparison.insights?.includes(
         "growth_with_branch_consolidation"
       )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    deposit_mix_softening: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "deposit_mix_softening"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    sustained_asset_growth: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "sustained_asset_growth"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    multi_quarter_roa_decline: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "multi_quarter_roa_decline"
+      )
     ).slice(0, 5).map((comparison) => String(comparison.name))
   };
 }
@@ -1389,7 +1442,7 @@ Insights
 ${insights}` : `${header}
 ${rows.join("\n")}`;
 }
-async function fetchInstitutionRoster(state, institutionFilters, activeOnly) {
+async function fetchInstitutionRoster(state, institutionFilters, activeOnly, signal) {
   const filterParts = [];
   if (state) filterParts.push(`STNAME:"${state}"`);
   if (activeOnly) filterParts.push("ACTIVE:1");
@@ -1401,10 +1454,12 @@ async function fetchInstitutionRoster(state, institutionFilters, activeOnly) {
     offset: 0,
     sort_by: "CERT",
     sort_order: "ASC"
-  });
-  return extractRecords(response);
+  }, { signal });
+  const records = extractRecords(response);
+  const warning = response.meta.total > records.length ? `Institution roster truncated to ${records.length.toLocaleString()} records out of ${response.meta.total.toLocaleString()} matched institutions. Narrow the comparison set with institution_filters or certs for complete analysis.` : void 0;
+  return { records, warning };
 }
-async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, fields) {
+async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, fields, signal) {
   const certFilters = buildCertFilters(certs);
   const tasks = repdteFilters.flatMap(
     (repdteFilter) => certFilters.map((certFilter) => ({
@@ -1420,7 +1475,7 @@ async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, field
       offset: 0,
       sort_by: "CERT",
       sort_order: "ASC"
-    });
+    }, { signal });
     return { repdteFilter: task.repdteFilter, response };
   });
   const byDate = /* @__PURE__ */ new Map();
@@ -1436,7 +1491,7 @@ async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, field
   }
   return byDate;
 }
-async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, fields) {
+async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, fields, signal) {
   const certFilters = buildCertFilters(certs);
   const responses = await mapWithConcurrency(
     certFilters,
@@ -1448,7 +1503,7 @@ async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, field
       offset: 0,
       sort_by: "REPDTE",
       sort_order: "ASC"
-    })
+    }, { signal })
   );
   const grouped = /* @__PURE__ */ new Map();
   for (const response of responses) {
@@ -1578,12 +1633,19 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
       sort_by,
       sort_order
     }) => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       try {
-        const roster = certs && certs.length > 0 ? certs.map((cert) => ({ CERT: cert })) : await fetchInstitutionRoster(
+        const rosterResult = certs && certs.length > 0 ? {
+          records: certs.map((cert) => ({ CERT: cert })),
+          warning: void 0
+        } : await fetchInstitutionRoster(
           state,
           institution_filters,
-          active_only
+          active_only,
+          controller.signal
         );
+        const roster = rosterResult.records;
         const candidateCerts = roster.map((record) => asNumber(record.CERT)).filter((cert) => cert !== null);
         if (candidateCerts.length === 0) {
           const output2 = {
@@ -1616,14 +1678,16 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
               candidateCerts,
               start_repdte,
               end_repdte,
-              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE"
+              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE",
+              controller.signal
             ),
             include_demographics ? fetchSeriesRecords(
               ENDPOINTS.DEMOGRAPHICS,
               candidateCerts,
               start_repdte,
               end_repdte,
-              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME"
+              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME",
+              controller.signal
             ) : Promise.resolve(/* @__PURE__ */ new Map())
           ]);
           comparisons = candidateCerts.map(
@@ -1644,13 +1708,15 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
               ENDPOINTS.FINANCIALS,
               candidateCerts,
               [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
-              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE"
+              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE",
+              controller.signal
             ),
             include_demographics ? fetchBatchedRecordsForDates(
               ENDPOINTS.DEMOGRAPHICS,
               candidateCerts,
               [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
-              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME"
+              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME",
+              controller.signal
             ) : Promise.resolve(/* @__PURE__ */ new Map())
           ]);
           const startFinancials = financialSnapshots.get(`REPDTE:${start_repdte}`) ?? /* @__PURE__ */ new Map();
@@ -1673,10 +1739,12 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
             );
           }).filter((comparison) => comparison !== null);
         }
-        const ranked = sortComparisons(comparisons, sort_by, sort_order).slice(
-          0,
-          limit
+        const sortedComparisons = sortComparisons(
+          comparisons,
+          sort_by,
+          sort_order
         );
+        const ranked = sortedComparisons.slice(0, limit);
         const pagination = buildPaginationInfo(comparisons.length, 0, ranked.length);
         const output = {
           total_candidates: candidateCerts.length,
@@ -1686,12 +1754,16 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
           analysis_mode,
           sort_by,
           sort_order,
-          insights: buildTopLevelInsights(comparisons),
+          warnings: rosterResult.warning ? [rosterResult.warning] : [],
+          insights: buildTopLevelInsights(sortedComparisons),
           ...pagination,
           comparisons: ranked
         };
         const text = truncateIfNeeded(
-          formatComparisonText(output),
+          [
+            rosterResult.warning ? `Warning: ${rosterResult.warning}` : null,
+            formatComparisonText(output)
+          ].filter((value) => value !== null).join("\n\n"),
           CHARACTER_LIMIT
         );
         return {
@@ -1699,7 +1771,16 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
           structuredContent: output
         };
       } catch (err) {
+        if (controller.signal.aborted) {
+          return formatToolError(
+            new Error(
+              `Analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Narrow the comparison set with certs or institution_filters and try again.`
+            )
+          );
+        }
         return formatToolError(err);
+      } finally {
+        clearTimeout(timeoutId);
       }
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdic-mcp-server",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "MCP server for the FDIC BankFind Suite API",
   "main": "dist/server.js",
   "files": [