fdic-mcp-server 1.0.7 → 1.1.0

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.1.0" : 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,593 @@ 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);
+      }
+    }
+  );
+}
+
+// src/tools/peerGroup.ts
+var import_zod8 = require("zod");
+function asNumber2(value) {
+  return typeof value === "number" ? value : null;
+}
+function safeRatio(numerator, denominator) {
+  if (numerator === null || denominator === null || denominator === 0) {
+    return null;
+  }
+  return numerator / denominator;
+}
+function safeRatioPositiveDenom(numerator, denominator) {
+  if (numerator === null || denominator === null || denominator <= 0) {
+    return null;
+  }
+  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 netInterestIncome = intinc !== null && eintexp !== null ? intinc - eintexp : null;
+  const revenueDenominator = netInterestIncome !== null && nonii !== null ? netInterestIncome + nonii : null;
+  const equityRatioRaw = safeRatio(eqtot, asset);
+  const efficiencyRatioRaw = safeRatioPositiveDenom(nonix, revenueDenominator);
+  return {
+    asset,
+    dep,
+    roa: asNumber2(raw.ROA),
+    roe: asNumber2(raw.ROE),
+    netnim: asNumber2(raw.NETNIM),
+    equity_ratio: equityRatioRaw !== null ? equityRatioRaw * 100 : null,
+    efficiency_ratio: efficiencyRatioRaw !== null ? efficiencyRatioRaw * 100 : null,
+    loan_to_deposit: safeRatio(lnlsnet, dep),
+    deposits_to_assets: safeRatio(dep, asset),
+    noninterest_income_share: safeRatioPositiveDenom(nonii, revenueDenominator)
+  };
+}
+function computeMedian(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 1) return sorted[mid];
+  return (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function computeCompetitionRank(subjectValue, peerValues, higherIsBetter) {
+  if (peerValues.length === 0) return null;
+  const ascending = higherIsBetter === false;
+  const all = [...peerValues, subjectValue];
+  const sorted = [...all].sort(
+    (a, b) => ascending ? a - b : b - a
+  );
+  const ranks = /* @__PURE__ */ new Map();
+  for (let i = 0; i < sorted.length; i++) {
+    if (!ranks.has(sorted[i])) {
+      ranks.set(sorted[i], i + 1);
+    }
+  }
+  const rank = ranks.get(subjectValue);
+  const of = peerValues.length;
+  const percentile = Math.round((1 - (rank - 1) / of) * 100);
+  return { rank, of, percentile };
+}
+function formatRepdteHuman(repdte) {
+  if (repdte.length !== 8) return repdte;
+  const year = repdte.slice(0, 4);
+  const month = repdte.slice(4, 6);
+  const day = repdte.slice(6, 8);
+  const date = /* @__PURE__ */ new Date(`${year}-${month}-${day}T00:00:00Z`);
+  if (Number.isNaN(date.getTime())) return repdte;
+  return date.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC"
+  });
+}
+var METRIC_KEYS = [
+  "asset",
+  "dep",
+  "roa",
+  "roe",
+  "netnim",
+  "equity_ratio",
+  "efficiency_ratio",
+  "loan_to_deposit",
+  "deposits_to_assets",
+  "noninterest_income_share"
+];
+var METRIC_DEFINITIONS = {
+  asset: { higher_is_better: true, unit: "$thousands", label: "Total Assets" },
+  dep: { higher_is_better: true, unit: "$thousands", label: "Total Deposits" },
+  roa: { higher_is_better: true, unit: "%", label: "Return on Assets" },
+  roe: { higher_is_better: true, unit: "%", label: "Return on Equity" },
+  netnim: {
+    higher_is_better: true,
+    unit: "%",
+    label: "Net Interest Margin"
+  },
+  equity_ratio: {
+    higher_is_better: true,
+    unit: "%",
+    label: "Equity Capital Ratio"
+  },
+  efficiency_ratio: {
+    higher_is_better: false,
+    unit: "%",
+    label: "Efficiency Ratio"
+  },
+  loan_to_deposit: {
+    higher_is_better: null,
+    unit: "ratio",
+    label: "Loan-to-Deposit Ratio",
+    ranking_note: "Rank and percentile reflect position by value (1 = highest). Directionality is context-dependent."
+  },
+  deposits_to_assets: {
+    higher_is_better: null,
+    unit: "ratio",
+    label: "Deposits-to-Assets Ratio",
+    ranking_note: "Rank and percentile reflect position by value (1 = highest). Directionality is context-dependent."
+  },
+  noninterest_income_share: {
+    higher_is_better: true,
+    unit: "ratio",
+    label: "Non-Interest Income Share"
+  }
+};
+var PeerGroupInputSchema = import_zod8.z.object({
+  cert: import_zod8.z.number().int().positive().optional().describe(
+    "Subject institution CERT number. When provided, auto-derives peer criteria and ranks this bank against peers."
+  ),
+  repdte: import_zod8.z.string().regex(/^\d{8}$/).describe("Report date in YYYYMMDD format."),
+  asset_min: import_zod8.z.number().positive().optional().describe(
+    "Minimum total assets ($thousands) for peer selection. Defaults to 50% of subject's report-date assets when cert is provided."
+  ),
+  asset_max: import_zod8.z.number().positive().optional().describe(
+    "Maximum total assets ($thousands) for peer selection. Defaults to 200% of subject's report-date assets when cert is provided."
+  ),
+  charter_classes: import_zod8.z.array(import_zod8.z.string()).optional().describe(
+    `Charter class codes to include (e.g., ["N", "SM"]). Defaults to the subject's charter class when cert is provided.`
+  ),
+  state: import_zod8.z.string().regex(/^[A-Z]{2}$/).optional().describe('Two-letter state code (e.g., "NC", "TX").'),
+  raw_filter: import_zod8.z.string().optional().describe(
+    "Advanced: raw ElasticSearch query string appended to peer selection criteria with AND."
+  ),
+  active_only: import_zod8.z.boolean().default(true).describe(
+    "Limit to institutions where ACTIVE:1 (currently operating, FDIC-insured)."
+  ),
+  extra_fields: import_zod8.z.array(import_zod8.z.string()).optional().describe(
+    "Additional FDIC field names to include as raw values in the response. Does not affect peer selection."
+  ),
+  limit: import_zod8.z.number().int().min(1).max(500).default(50).describe(
+    "Max peer records returned in the response. All matched peers are used for ranking regardless of this limit."
+  )
+}).superRefine((value, ctx) => {
+  if (!value.cert && value.asset_min === void 0 && value.asset_max === void 0 && !value.charter_classes && !value.state && !value.raw_filter) {
+    ctx.addIssue({
+      code: import_zod8.z.ZodIssueCode.custom,
+      message: "At least one peer-group constructor is required: cert, asset_min, asset_max, charter_classes, state, or raw_filter.",
+      path: ["cert"]
+    });
+  }
+  if (value.asset_min !== void 0 && value.asset_max !== void 0 && value.asset_min > value.asset_max) {
+    ctx.addIssue({
+      code: import_zod8.z.ZodIssueCode.custom,
+      message: "asset_min must be <= asset_max.",
+      path: ["asset_min"]
+    });
+  }
+});
+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];
+  if (def.unit === "$thousands")
+    return `$${Math.round(value).toLocaleString()}k`;
+  if (def.unit === "%") return `${value.toFixed(4)}%`;
+  return value.toFixed(4);
+}
+function ordinalSuffix(n) {
+  const mod100 = n % 100;
+  if (mod100 >= 11 && mod100 <= 13) return `${n}th`;
+  const mod10 = n % 10;
+  if (mod10 === 1) return `${n}st`;
+  if (mod10 === 2) return `${n}nd`;
+  if (mod10 === 3) return `${n}rd`;
+  return `${n}th`;
+}
+function formatPeerGroupText(repdte, subjectProfile, subjectMetrics, rankings, medians, returnedPeers, peerCount, warnings) {
+  const parts = [];
+  for (const warning of warnings) {
+    parts.push(`Warning: ${warning}`);
+  }
+  const dateStr = formatRepdteHuman(repdte);
+  const subjectLabel = subjectProfile ? ` for ${subjectProfile.NAME} (CERT ${subjectProfile.CERT ?? ""})` : "";
+  parts.push(`Peer group analysis${subjectLabel} as of ${dateStr}.`);
+  parts.push(`${peerCount} peers matched.`);
+  if (subjectMetrics && subjectProfile) {
+    parts.push("");
+    parts.push("Subject rankings:");
+    for (const key of METRIC_KEYS) {
+      const def = METRIC_DEFINITIONS[key];
+      const ranking = rankings[key];
+      const value = formatMetricValue(key, subjectMetrics[key]);
+      const medianValue = formatMetricValue(key, medians[key] ?? null);
+      if (ranking) {
+        const pctLabel = `${ordinalSuffix(ranking.percentile)} percentile`;
+        parts.push(
+          `  ${def.label.padEnd(28)} rank ${String(ranking.rank).padStart(2)} of ${String(ranking.of).padEnd(4)} (${pctLabel.padEnd(18)})  ${value.padStart(16)}  median: ${medianValue}`
+        );
+      } else {
+        parts.push(`  ${def.label.padEnd(28)} n/a`);
+      }
+    }
+  } else if (peerCount > 0) {
+    parts.push("");
+    parts.push("Peer group medians:");
+    const medianParts = METRIC_KEYS.filter((k) => medians[k] !== null).map(
+      (k) => `${METRIC_DEFINITIONS[k].label}: ${formatMetricValue(k, medians[k] ?? null)}`
+    );
+    parts.push(`  ${medianParts.join(" | ")}`);
+  }
+  if (returnedPeers.length > 0) {
+    parts.push("");
+    parts.push(`Peers (${returnedPeers.length} returned):`);
+    for (let i = 0; i < returnedPeers.length; i++) {
+      const p = returnedPeers[i];
+      const location = [p.city, p.stalp].filter(Boolean).join(" ");
+      const locationStr = location ? `, ${location}` : "";
+      parts.push(
+        `${i + 1}. ${p.name}${locationStr} (CERT ${p.cert}) | Asset: ${formatMetricValue("asset", p.metrics.asset)} | ROA: ${formatMetricValue("roa", p.metrics.roa)} | ROE: ${formatMetricValue("roe", p.metrics.roe)}`
+      );
+    }
+  }
+  return parts.join("\n");
+}
+function registerPeerGroupTools(server) {
+  server.registerTool(
+    "fdic_peer_group_analysis",
+    {
+      title: "Peer Group Analysis",
+      description: `Build a peer group for an FDIC-insured institution and rank it against peers on financial and efficiency metrics at a single report date.
+
+Three usage modes:
+  - Subject-driven: provide cert and repdte \u2014 auto-derives peer criteria from the subject's asset size and charter class
+  - Explicit criteria: provide repdte plus asset_min/asset_max, charter_classes, state, or raw_filter
+  - Subject with overrides: provide cert plus explicit criteria to override auto-derived defaults
+
+Metrics ranked (fixed order):
+  - Total Assets, Total Deposits, ROA, ROE, Net Interest Margin
+  - 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.
+
+Output includes:
+  - Subject rankings and percentiles (when cert provided)
+  - Peer group medians
+  - Peer list with CERTs (pass to fdic_compare_bank_snapshots for trend analysis)
+  - Metric definitions with directionality metadata
+
+Override precedence: cert derives defaults, then explicit params override them.`,
+      inputSchema: PeerGroupInputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS2);
+      try {
+        const warnings = [];
+        let subjectProfile = null;
+        let subjectFinancials = null;
+        if (params.cert) {
+          const [profileResponse, financialsResponse] = await Promise.all([
+            queryEndpoint(
+              ENDPOINTS.INSTITUTIONS,
+              {
+                filters: `CERT:${params.cert}`,
+                fields: "CERT,NAME,CITY,STALP,BKCLASS",
+                limit: 1
+              },
+              { signal: controller.signal }
+            ),
+            queryEndpoint(
+              ENDPOINTS.FINANCIALS,
+              {
+                filters: `CERT:${params.cert} AND REPDTE:${params.repdte}`,
+                fields: FINANCIAL_FIELDS,
+                limit: 1
+              },
+              { signal: controller.signal }
+            )
+          ]);
+          const profileRecords = extractRecords(profileResponse);
+          if (profileRecords.length === 0) {
+            return formatToolError(
+              new Error(
+                `No institution found with CERT number ${params.cert}.`
+              )
+            );
+          }
+          subjectProfile = profileRecords[0];
+          const financialRecords = extractRecords(financialsResponse);
+          if (financialRecords.length === 0) {
+            return formatToolError(
+              new Error(
+                `No financial data for CERT ${params.cert} at report date ${params.repdte}. Auto-derivation of peer criteria requires asset data at the specified report date.`
+              )
+            );
+          }
+          subjectFinancials = financialRecords[0];
+        }
+        const subjectAsset = subjectFinancials && typeof subjectFinancials.ASSET === "number" ? subjectFinancials.ASSET : null;
+        const assetMin = params.asset_min ?? (subjectAsset !== null ? subjectAsset * 0.5 : void 0);
+        const assetMax = params.asset_max ?? (subjectAsset !== null ? subjectAsset * 2 : void 0);
+        const charterClasses = params.charter_classes ?? (subjectProfile && typeof subjectProfile.BKCLASS === "string" ? [subjectProfile.BKCLASS] : void 0);
+        const { state, active_only, raw_filter } = params;
+        const filterParts = [];
+        if (assetMin !== void 0 || assetMax !== void 0) {
+          const min = assetMin ?? 0;
+          const max = assetMax ?? "*";
+          filterParts.push(`ASSET:[${min} TO ${max}]`);
+        }
+        if (charterClasses && charterClasses.length > 0) {
+          const classFilter = charterClasses.map((cls) => `BKCLASS:${cls}`).join(" OR ");
+          filterParts.push(
+            charterClasses.length > 1 ? `(${classFilter})` : classFilter
+          );
+        }
+        if (state) filterParts.push(`STALP:${state}`);
+        if (active_only) filterParts.push("ACTIVE:1");
+        if (raw_filter) filterParts.push(`(${raw_filter})`);
+        const rosterResponse = await queryEndpoint(
+          ENDPOINTS.INSTITUTIONS,
+          {
+            filters: filterParts.join(" AND "),
+            fields: "CERT,NAME,CITY,STALP,BKCLASS",
+            limit: 1e4,
+            offset: 0,
+            sort_by: "CERT",
+            sort_order: "ASC"
+          },
+          { signal: controller.signal }
+        );
+        let rosterRecords = extractRecords(rosterResponse);
+        if (rosterResponse.meta.total > rosterRecords.length) {
+          warnings.push(
+            `Institution roster truncated to ${rosterRecords.length.toLocaleString()} records out of ${rosterResponse.meta.total.toLocaleString()} matched institutions. Narrow the peer group criteria for complete analysis.`
+          );
+        }
+        if (params.cert) {
+          rosterRecords = rosterRecords.filter(
+            (r) => asNumber2(r.CERT) !== params.cert
+          );
+        }
+        const criteriaUsed = {
+          asset_min: assetMin ?? null,
+          asset_max: assetMax ?? null,
+          charter_classes: charterClasses ?? null,
+          state: state ?? null,
+          active_only,
+          raw_filter: raw_filter ?? null
+        };
+        if (rosterRecords.length === 0) {
+          const subjectMetrics2 = subjectFinancials ? deriveMetrics(subjectFinancials) : null;
+          const output2 = {};
+          if (subjectProfile) {
+            output2.subject = {
+              cert: params.cert,
+              name: subjectProfile.NAME,
+              city: subjectProfile.CITY,
+              stalp: subjectProfile.STALP,
+              bkclass: subjectProfile.BKCLASS,
+              metrics: subjectMetrics2,
+              rankings: null
+            };
+          }
+          output2.peer_group = {
+            repdte: params.repdte,
+            criteria_used: criteriaUsed,
+            medians: {}
+          };
+          output2.metric_definitions = METRIC_DEFINITIONS;
+          output2.peers = [];
+          output2.peer_count = 0;
+          output2.returned_count = 0;
+          output2.has_more = false;
+          output2.message = "No peers matched the specified criteria.";
+          output2.warnings = warnings;
+          const text2 = formatPeerGroupText(
+            params.repdte,
+            subjectProfile,
+            subjectMetrics2,
+            {},
+            {},
+            [],
+            0,
+            warnings
+          );
+          return {
+            content: [{ type: "text", text: text2 }],
+            structuredContent: output2
+          };
+        }
+        const peerCerts = rosterRecords.map((r) => asNumber2(r.CERT)).filter((c) => c !== null);
+        const certFilters = buildCertFilters2(peerCerts);
+        const extraFieldsCsv = params.extra_fields && params.extra_fields.length > 0 ? "," + params.extra_fields.join(",") : "";
+        const financialResponses = await mapWithConcurrency2(
+          certFilters,
+          MAX_CONCURRENCY2,
+          async (certFilter) => queryEndpoint(
+            ENDPOINTS.FINANCIALS,
+            {
+              filters: `(${certFilter}) AND REPDTE:${params.repdte}`,
+              fields: FINANCIAL_FIELDS + extraFieldsCsv,
+              limit: 1e4,
+              offset: 0,
+              sort_by: "CERT",
+              sort_order: "ASC"
+            },
+            { signal: controller.signal }
+          )
+        );
+        const peerFinancialsByCert = /* @__PURE__ */ new Map();
+        for (const response of financialResponses) {
+          for (const record of extractRecords(response)) {
+            const cert = asNumber2(record.CERT);
+            if (cert !== null) peerFinancialsByCert.set(cert, record);
+          }
+        }
+        const rosterByCert = new Map(
+          rosterRecords.map((r) => [asNumber2(r.CERT), r]).filter(
+            (e) => e[0] !== null
+          )
+        );
+        const peers = [];
+        for (const [cert, financials] of peerFinancialsByCert) {
+          const roster = rosterByCert.get(cert);
+          const metrics = deriveMetrics(financials);
+          const extraFields = {};
+          if (params.extra_fields) {
+            for (const field of params.extra_fields) {
+              extraFields[field] = financials[field] ?? null;
+            }
+          }
+          peers.push({
+            cert,
+            name: String(roster?.NAME ?? financials.NAME ?? cert),
+            city: roster?.CITY != null ? String(roster.CITY) : null,
+            stalp: roster?.STALP != null ? String(roster.STALP) : null,
+            bkclass: roster?.BKCLASS != null ? String(roster.BKCLASS) : null,
+            metrics,
+            extraFields
+          });
+        }
+        const peerCount = peers.length;
+        const subjectMetrics = subjectFinancials ? deriveMetrics(subjectFinancials) : null;
+        const rankings = {};
+        const medians = {};
+        for (const key of METRIC_KEYS) {
+          const peerValues = peers.map((p) => p.metrics[key]).filter((v) => v !== null);
+          medians[key] = computeMedian(peerValues);
+          if (subjectMetrics && subjectMetrics[key] !== null) {
+            rankings[key] = computeCompetitionRank(
+              subjectMetrics[key],
+              peerValues,
+              METRIC_DEFINITIONS[key].higher_is_better
+            );
+          } else {
+            rankings[key] = null;
+          }
+        }
+        peers.sort((a, b) => (b.metrics.asset ?? 0) - (a.metrics.asset ?? 0));
+        const returnedPeers = peers.slice(0, params.limit);
+        const returnedCount = returnedPeers.length;
+        const hasMore = peerCount > returnedCount;
+        const output = {};
+        if (subjectProfile && subjectMetrics) {
+          output.subject = {
+            cert: params.cert,
+            name: subjectProfile.NAME,
+            city: subjectProfile.CITY,
+            stalp: subjectProfile.STALP,
+            bkclass: subjectProfile.BKCLASS,
+            metrics: subjectMetrics,
+            rankings
+          };
+        }
+        output.peer_group = {
+          repdte: params.repdte,
+          criteria_used: criteriaUsed,
+          medians
+        };
+        output.metric_definitions = METRIC_DEFINITIONS;
+        output.peers = returnedPeers.map((p) => ({
+          cert: p.cert,
+          name: p.name,
+          city: p.city,
+          stalp: p.stalp,
+          metrics: p.metrics,
+          ...p.extraFields
+        }));
+        output.peer_count = peerCount;
+        output.returned_count = returnedCount;
+        output.has_more = hasMore;
+        output.message = null;
+        output.warnings = warnings;
+        const text = truncateIfNeeded(
+          formatPeerGroupText(
+            params.repdte,
+            subjectProfile,
+            subjectMetrics,
+            rankings,
+            medians,
+            returnedPeers,
+            peerCount,
+            warnings
+          ),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        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.`
+            )
+          );
+        }
         return formatToolError(err);
+      } finally {
+        clearTimeout(timeoutId);
       }
     }
   );
@@ -1719,6 +2377,7 @@ function createServer() {
   registerSodTools(server);
   registerDemographicsTools(server);
   registerAnalysisTools(server);
+  registerPeerGroupTools(server);
   return server;
 }
 async function runStdio() {