fdic-mcp-server 1.1.0 → 1.1.2

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.1.0" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.1.2" : 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 = {
@@ -55,12 +55,23 @@ var apiClient = import_axios.default.create({
   }
 });
 var QUERY_CACHE_TTL_MS = 6e4;
+var QUERY_CACHE_MAX_ENTRIES = 500;
 var queryCache = /* @__PURE__ */ new Map();
 function pruneExpiredQueryCache(now) {
   for (const [key, entry] of queryCache.entries()) {
-    if (entry.expiresAt <= now) {
-      queryCache.delete(key);
+    if (entry.expiresAt > now) {
+      break;
     }
+    queryCache.delete(key);
+  }
+}
+function evictOverflowQueryCache() {
+  while (queryCache.size > QUERY_CACHE_MAX_ENTRIES) {
+    const oldestKey = queryCache.keys().next().value;
+    if (oldestKey === void 0) {
+      break;
+    }
+    queryCache.delete(oldestKey);
   }
 }
 function getCacheKey(endpoint, params) {
@@ -74,6 +85,38 @@ function getCacheKey(endpoint, params) {
     params.sort_order ?? null
   ]);
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function validateFdicResponseShape(endpoint, payload) {
+  if (!isRecord(payload)) {
+    throw new Error(
+      `Unexpected FDIC API response shape for endpoint ${endpoint}: expected an object payload.`
+    );
+  }
+  const { data, meta } = payload;
+  if (!Array.isArray(data)) {
+    throw new Error(
+      `Unexpected FDIC API response shape for endpoint ${endpoint}: expected 'data' to be an array.`
+    );
+  }
+  if (!isRecord(meta) || typeof meta.total !== "number") {
+    throw new Error(
+      `Unexpected FDIC API response shape for endpoint ${endpoint}: expected 'meta.total' to be a number.`
+    );
+  }
+  return {
+    data: data.map((item, index) => {
+      if (!isRecord(item) || !isRecord(item.data)) {
+        throw new Error(
+          `Unexpected FDIC API response shape for endpoint ${endpoint}: expected data[${index}] to contain an object 'data' property.`
+        );
+      }
+      return { data: item.data };
+    }),
+    meta: { total: meta.total }
+  };
+}
 async function queryEndpoint(endpoint, params, options = {}) {
   if (options.signal?.aborted) {
     throw new Error("FDIC API request was canceled before it started.");
@@ -101,7 +144,7 @@ async function queryEndpoint(endpoint, params, options = {}) {
         params: queryParams,
         signal: options.signal
       });
-      return response.data;
+      return validateFdicResponseShape(endpoint, 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.");
@@ -133,6 +176,7 @@ async function queryEndpoint(endpoint, params, options = {}) {
       expiresAt: now + QUERY_CACHE_TTL_MS,
       value: requestPromise
     });
+    evictOverflowQueryCache();
   }
   try {
     return await requestPromise;
@@ -144,7 +188,14 @@ async function queryEndpoint(endpoint, params, options = {}) {
   }
 }
 function extractRecords(response) {
-  return response.data.map((item) => item.data);
+  return response.data.map((item, index) => {
+    if (!isRecord(item) || !isRecord(item.data)) {
+      throw new Error(
+        `Unexpected FDIC API response shape: expected data[${index}] to contain an object 'data' property.`
+      );
+    }
+    return item.data;
+  });
 }
 function buildPaginationInfo(total, offset, count) {
   const has_more = total > offset + count;
@@ -156,6 +207,10 @@ function buildPaginationInfo(total, offset, count) {
     ...has_more ? { next_offset: offset + count } : {}
   };
 }
+function buildTruncationWarning(label, total, count, guidance) {
+  if (total <= count) return void 0;
+  return `${label} truncated to ${count.toLocaleString()} records out of ${total.toLocaleString()} matched rows. ${guidance}`;
+}
 function truncateIfNeeded(text, charLimit) {
   if (text.length <= charLimit) return text;
   return text.slice(0, charLimit) + `
@@ -1073,9 +1128,40 @@ Prefer concise human-readable summaries or tables when answering users. Structur
 
 // src/tools/analysis.ts
 var import_zod7 = require("zod");
+
+// src/tools/shared/queryUtils.ts
 var CHUNK_SIZE = 25;
 var MAX_CONCURRENCY = 4;
 var ANALYSIS_TIMEOUT_MS = 9e4;
+function asNumber(value) {
+  return typeof value === "number" ? value : null;
+}
+function buildCertFilters(certs) {
+  const filters = [];
+  for (let i = 0; i < certs.length; i += CHUNK_SIZE) {
+    const chunk = certs.slice(i, i + CHUNK_SIZE);
+    filters.push(chunk.map((cert) => `CERT:${cert}`).join(" OR "));
+  }
+  return filters;
+}
+async function mapWithConcurrency(values, limit, mapper) {
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (true) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+      if (currentIndex >= values.length) return;
+      results[currentIndex] = await mapper(values[currentIndex], currentIndex);
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(limit, values.length) }, () => worker())
+  );
+  return results;
+}
+
+// src/tools/analysis.ts
 var SortFieldSchema = import_zod7.z.enum([
   "asset_growth",
   "asset_growth_pct",
@@ -1124,32 +1210,9 @@ var SnapshotAnalysisSchema = import_zod7.z.object({
     });
   }
 });
-function asNumber(value) {
-  return typeof value === "number" ? value : null;
-}
-function buildCertFilters(certs) {
-  const filters = [];
-  for (let i = 0; i < certs.length; i += CHUNK_SIZE) {
-    const chunk = certs.slice(i, i + CHUNK_SIZE);
-    filters.push(chunk.map((cert) => `CERT:${cert}`).join(" OR "));
-  }
-  return filters;
-}
-async function mapWithConcurrency(values, limit, mapper) {
-  const results = new Array(values.length);
-  let nextIndex = 0;
-  async function worker() {
-    while (true) {
-      const currentIndex = nextIndex;
-      nextIndex += 1;
-      if (currentIndex >= values.length) return;
-      results[currentIndex] = await mapper(values[currentIndex], currentIndex);
-    }
-  }
-  await Promise.all(
-    Array.from({ length: Math.min(limit, values.length) }, () => worker())
-  );
-  return results;
+function maxOrNull(values) {
+  const nonNullValues = values.filter((value) => value !== null);
+  return nonNullValues.length > 0 ? Math.max(...nonNullValues) : null;
 }
 function ratio(numerator, denominator) {
   if (numerator === null || denominator === null || denominator === 0) {
@@ -1333,7 +1396,7 @@ function summarizeTimeSeries(records, demographicsByDate, institution) {
   const depositsPerOfficeEnd = ratio(depEnd, officesEnd);
   const depositsToAssetsStart = ratio(depStart, assetStart);
   const depositsToAssetsEnd = ratio(depEnd, assetEnd);
-  const peakAsset = Math.max(...assetSeries.filter((value) => value !== null));
+  const peakAsset = maxOrNull(assetSeries);
   const troughRoaValues = roaSeries.filter((value) => value !== null);
   const troughRoa = troughRoaValues.length > 0 ? Math.min(...troughRoaValues) : null;
   const comparison = {
@@ -1456,29 +1519,46 @@ async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, field
       certFilter
     }))
   );
-  const responses = await mapWithConcurrency(tasks, MAX_CONCURRENCY, async (task) => {
-    const response = await queryEndpoint(endpoint, {
-      filters: `(${task.certFilter}) AND ${task.repdteFilter}`,
-      fields,
-      limit: 1e4,
-      offset: 0,
-      sort_by: "CERT",
-      sort_order: "ASC"
-    }, { signal });
-    return { repdteFilter: task.repdteFilter, response };
-  });
+  const responses = await mapWithConcurrency(
+    tasks,
+    MAX_CONCURRENCY,
+    async (task) => {
+      const response = await queryEndpoint(
+        endpoint,
+        {
+          filters: `(${task.certFilter}) AND ${task.repdteFilter}`,
+          fields,
+          limit: 1e4,
+          offset: 0,
+          sort_by: "CERT",
+          sort_order: "ASC"
+        },
+        { signal }
+      );
+      return { repdteFilter: task.repdteFilter, response };
+    }
+  );
   const byDate = /* @__PURE__ */ new Map();
+  const warnings = /* @__PURE__ */ new Set();
   for (const { repdteFilter, response } of responses) {
     if (!byDate.has(repdteFilter)) {
       byDate.set(repdteFilter, /* @__PURE__ */ new Map());
     }
+    const records = extractRecords(response);
+    const warning = buildTruncationWarning(
+      `${endpoint} batch for ${repdteFilter}`,
+      response.meta.total,
+      records.length,
+      "Narrow the comparison set with institution_filters or certs for complete analysis."
+    );
+    if (warning) warnings.add(warning);
     const target = byDate.get(repdteFilter);
-    for (const record of extractRecords(response)) {
+    for (const record of records) {
       const cert = asNumber(record.CERT);
       if (cert !== null) target.set(cert, record);
     }
   }
-  return byDate;
+  return { byDate, warnings: [...warnings] };
 }
 async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, fields, signal) {
   const certFilters = buildCertFilters(certs);
@@ -1495,15 +1575,24 @@ async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, field
     }, { signal })
   );
   const grouped = /* @__PURE__ */ new Map();
+  const warnings = /* @__PURE__ */ new Set();
   for (const response of responses) {
-    for (const record of extractRecords(response)) {
+    const records = extractRecords(response);
+    const warning = buildTruncationWarning(
+      `${endpoint} batch for REPDTE:[${startRepdte} TO ${endRepdte}]`,
+      response.meta.total,
+      records.length,
+      "Narrow the comparison set with certs or a shorter date range for complete analysis."
+    );
+    if (warning) warnings.add(warning);
+    for (const record of records) {
       const cert = asNumber(record.CERT);
       if (cert === null) continue;
       if (!grouped.has(cert)) grouped.set(cert, []);
       grouped.get(cert).push(record);
     }
   }
-  return grouped;
+  return { grouped, warnings: [...warnings] };
 }
 function buildSnapshotComparison(cert, institution, startFinancial, endFinancial, startDemo, endDemo, startRepdte, endRepdte) {
   const assetStart = asNumber(startFinancial.ASSET);
@@ -1660,8 +1749,9 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
           )
         );
         let comparisons = [];
+        const warnings = rosterResult.warning ? [rosterResult.warning] : [];
         if (analysis_mode === "timeseries") {
-          const [financialSeries, demographicsSeries] = await Promise.all([
+          const [financialSeriesResult, demographicsSeriesResult] = await Promise.all([
             fetchSeriesRecords(
               ENDPOINTS.FINANCIALS,
               candidateCerts,
@@ -1677,8 +1767,17 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
               end_repdte,
               "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME",
               controller.signal
-            ) : Promise.resolve(/* @__PURE__ */ new Map())
+            ) : Promise.resolve({
+              grouped: /* @__PURE__ */ new Map(),
+              warnings: []
+            })
           ]);
+          warnings.push(
+            ...financialSeriesResult.warnings,
+            ...demographicsSeriesResult.warnings
+          );
+          const financialSeries = financialSeriesResult.grouped;
+          const demographicsSeries = demographicsSeriesResult.grouped;
           comparisons = candidateCerts.map(
             (cert) => summarizeTimeSeries(
               financialSeries.get(cert) ?? [],
@@ -1692,7 +1791,7 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
             )
           ).filter((comparison) => comparison !== null);
         } else {
-          const [financialSnapshots, demographicSnapshots] = await Promise.all([
+          const [financialSnapshotsResult, demographicSnapshotsResult] = await Promise.all([
             fetchBatchedRecordsForDates(
               ENDPOINTS.FINANCIALS,
               candidateCerts,
@@ -1706,8 +1805,17 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
               [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
               "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME",
               controller.signal
-            ) : Promise.resolve(/* @__PURE__ */ new Map())
+            ) : Promise.resolve({
+              byDate: /* @__PURE__ */ new Map(),
+              warnings: []
+            })
           ]);
+          warnings.push(
+            ...financialSnapshotsResult.warnings,
+            ...demographicSnapshotsResult.warnings
+          );
+          const financialSnapshots = financialSnapshotsResult.byDate;
+          const demographicSnapshots = demographicSnapshotsResult.byDate;
           const startFinancials = financialSnapshots.get(`REPDTE:${start_repdte}`) ?? /* @__PURE__ */ new Map();
           const endFinancials = financialSnapshots.get(`REPDTE:${end_repdte}`) ?? /* @__PURE__ */ new Map();
           const startDemographics = demographicSnapshots.get(`REPDTE:${start_repdte}`) ?? /* @__PURE__ */ new Map();
@@ -1743,14 +1851,14 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
           analysis_mode,
           sort_by,
           sort_order,
-          warnings: rosterResult.warning ? [rosterResult.warning] : [],
+          warnings,
           insights: buildTopLevelInsights(sortedComparisons),
           ...pagination,
           comparisons: ranked
         };
         const text = truncateIfNeeded(
           [
-            rosterResult.warning ? `Warning: ${rosterResult.warning}` : null,
+            ...warnings.map((warning) => `Warning: ${warning}`),
             formatComparisonText(output)
           ].filter((value) => value !== null).join("\n\n"),
           CHARACTER_LIMIT
@@ -1777,9 +1885,8 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
 
 // src/tools/peerGroup.ts
 var import_zod8 = require("zod");
-function asNumber2(value) {
-  return typeof value === "number" ? value : null;
-}
+
+// src/tools/shared/financialMetrics.ts
 function safeRatio(numerator, denominator) {
   if (numerator === null || denominator === null || denominator === 0) {
     return null;
@@ -1793,14 +1900,14 @@ function safeRatioPositiveDenom(numerator, denominator) {
   return numerator / denominator;
 }
 function deriveMetrics(raw) {
-  const asset = asNumber2(raw.ASSET);
-  const dep = asNumber2(raw.DEP);
-  const eqtot = asNumber2(raw.EQTOT);
-  const lnlsnet = asNumber2(raw.LNLSNET);
-  const intinc = asNumber2(raw.INTINC);
-  const eintexp = asNumber2(raw.EINTEXP);
-  const nonii = asNumber2(raw.NONII);
-  const nonix = asNumber2(raw.NONIX);
+  const asset = asNumber(raw.ASSET);
+  const dep = asNumber(raw.DEP);
+  const eqtot = asNumber(raw.EQTOT);
+  const lnlsnet = asNumber(raw.LNLSNET);
+  const intinc = asNumber(raw.INTINC);
+  const eintexp = asNumber(raw.EINTEXP);
+  const nonii = asNumber(raw.NONII);
+  const nonix = asNumber(raw.NONIX);
   const netInterestIncome = intinc !== null && eintexp !== null ? intinc - eintexp : null;
   const revenueDenominator = netInterestIncome !== null && nonii !== null ? netInterestIncome + nonii : null;
   const equityRatioRaw = safeRatio(eqtot, asset);
@@ -1808,9 +1915,9 @@ function deriveMetrics(raw) {
   return {
     asset,
     dep,
-    roa: asNumber2(raw.ROA),
-    roe: asNumber2(raw.ROE),
-    netnim: asNumber2(raw.NETNIM),
+    roa: asNumber(raw.ROA),
+    roe: asNumber(raw.ROE),
+    netnim: asNumber(raw.NETNIM),
     equity_ratio: equityRatioRaw !== null ? equityRatioRaw * 100 : null,
     efficiency_ratio: efficiencyRatioRaw !== null ? efficiencyRatioRaw * 100 : null,
     loan_to_deposit: safeRatio(lnlsnet, dep),
@@ -1825,6 +1932,8 @@ function computeMedian(values) {
   if (sorted.length % 2 === 1) return sorted[mid];
   return (sorted[mid - 1] + sorted[mid]) / 2;
 }
+
+// src/tools/peerGroup.ts
 function computeCompetitionRank(subjectValue, peerValues, higherIsBetter) {
   if (peerValues.length === 0) return null;
   const ascending = higherIsBetter === false;
@@ -1839,7 +1948,7 @@ function computeCompetitionRank(subjectValue, peerValues, higherIsBetter) {
     }
   }
   const rank = ranks.get(subjectValue);
-  const of = peerValues.length;
+  const of = all.length;
   const percentile = Math.round((1 - (rank - 1) / of) * 100);
   return { rank, of, percentile };
 }
@@ -1950,34 +2059,7 @@ var PeerGroupInputSchema = import_zod8.z.object({
     });
   }
 });
-var CHUNK_SIZE2 = 25;
-var MAX_CONCURRENCY2 = 4;
-var ANALYSIS_TIMEOUT_MS2 = 9e4;
 var FINANCIAL_FIELDS = "CERT,ASSET,DEP,NETINC,ROA,ROE,NETNIM,EQTOT,LNLSNET,INTINC,EINTEXP,NONII,NONIX";
-function buildCertFilters2(certs) {
-  const filters = [];
-  for (let i = 0; i < certs.length; i += CHUNK_SIZE2) {
-    const chunk = certs.slice(i, i + CHUNK_SIZE2);
-    filters.push(chunk.map((cert) => `CERT:${cert}`).join(" OR "));
-  }
-  return filters;
-}
-async function mapWithConcurrency2(values, limit, mapper) {
-  const results = new Array(values.length);
-  let nextIndex = 0;
-  async function worker() {
-    while (true) {
-      const currentIndex = nextIndex;
-      nextIndex += 1;
-      if (currentIndex >= values.length) return;
-      results[currentIndex] = await mapper(values[currentIndex], currentIndex);
-    }
-  }
-  await Promise.all(
-    Array.from({ length: Math.min(limit, values.length) }, () => worker())
-  );
-  return results;
-}
 function formatMetricValue(key, value) {
   if (value === null) return "n/a";
   const def = METRIC_DEFINITIONS[key];
@@ -2060,7 +2142,7 @@ Metrics ranked (fixed order):
   - Equity Capital Ratio, Efficiency Ratio, Loan-to-Deposit Ratio
   - Deposits-to-Assets Ratio, Non-Interest Income Share
 
-Rankings use competition rank (1, 2, 2, 4) with metric-specific denominators. Subject is excluded from peer set.
+Rankings use competition rank (1, 2, 2, 4). Rank, denominator, and percentile all use the same comparison set: matched peers plus the subject institution.
 
 Output includes:
   - Subject rankings and percentiles (when cert provided)
@@ -2079,7 +2161,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
     },
     async (params) => {
       const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS2);
+      const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       try {
         const warnings = [];
         let subjectProfile = null;
@@ -2164,7 +2246,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
         }
         if (params.cert) {
           rosterRecords = rosterRecords.filter(
-            (r) => asNumber2(r.CERT) !== params.cert
+            (r) => asNumber(r.CERT) !== params.cert
           );
         }
         const criteriaUsed = {
@@ -2216,12 +2298,12 @@ Override precedence: cert derives defaults, then explicit params override them.`
             structuredContent: output2
           };
         }
-        const peerCerts = rosterRecords.map((r) => asNumber2(r.CERT)).filter((c) => c !== null);
-        const certFilters = buildCertFilters2(peerCerts);
+        const peerCerts = rosterRecords.map((r) => asNumber(r.CERT)).filter((c) => c !== null);
+        const certFilters = buildCertFilters(peerCerts);
         const extraFieldsCsv = params.extra_fields && params.extra_fields.length > 0 ? "," + params.extra_fields.join(",") : "";
-        const financialResponses = await mapWithConcurrency2(
+        const financialResponses = await mapWithConcurrency(
           certFilters,
-          MAX_CONCURRENCY2,
+          MAX_CONCURRENCY,
           async (certFilter) => queryEndpoint(
             ENDPOINTS.FINANCIALS,
             {
@@ -2237,13 +2319,21 @@ Override precedence: cert derives defaults, then explicit params override them.`
         );
         const peerFinancialsByCert = /* @__PURE__ */ new Map();
         for (const response of financialResponses) {
-          for (const record of extractRecords(response)) {
-            const cert = asNumber2(record.CERT);
+          const records = extractRecords(response);
+          const warning = buildTruncationWarning(
+            `financials batch for REPDTE:${params.repdte}`,
+            response.meta.total,
+            records.length,
+            "Narrow the peer group criteria for complete analysis."
+          );
+          if (warning && !warnings.includes(warning)) warnings.push(warning);
+          for (const record of records) {
+            const cert = asNumber(record.CERT);
             if (cert !== null) peerFinancialsByCert.set(cert, record);
           }
         }
         const rosterByCert = new Map(
-          rosterRecords.map((r) => [asNumber2(r.CERT), r]).filter(
+          rosterRecords.map((r) => [asNumber(r.CERT), r]).filter(
             (e) => e[0] !== null
           )
         );
@@ -2340,7 +2430,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
         if (controller.signal.aborted) {
           return formatToolError(
             new Error(
-              `Peer group analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS2 / 1e3)} seconds. Narrow the peer group criteria and try again.`
+              `Peer group analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Narrow the peer group criteria and try again.`
             )
           );
         }
@@ -2375,6 +2465,16 @@ async function runStdio() {
   await server.connect(transport);
   console.error("FDIC BankFind MCP server running on stdio");
 }
+function parseHttpPort(rawPort) {
+  const port = Number.parseInt(rawPort ?? "3000", 10);
+  if (Number.isNaN(port)) {
+    throw new Error(`Invalid PORT value: ${rawPort ?? ""}`);
+  }
+  if (port < 0 || port > 65535) {
+    throw new Error(`PORT must be between 0 and 65535. Received: ${port}`);
+  }
+  return port;
+}
 function createApp() {
   const app = (0, import_express.default)();
   app.use(import_express.default.json());
@@ -2418,7 +2518,7 @@ function createApp() {
 }
 async function runHTTP() {
   const app = createApp();
-  const port = parseInt(process.env.PORT ?? "3000");
+  const port = parseHttpPort(process.env.PORT);
   app.listen(port, () => {
     console.error(
       `FDIC BankFind MCP server running on http://localhost:${port}/mcp`