fdic-mcp-server 1.0.8 → 1.1.1

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.8" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.1.1" : 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
@@ -1775,6 +1883,565 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
   );
 }
 
+// src/tools/peerGroup.ts
+var import_zod8 = require("zod");
+
+// src/tools/shared/financialMetrics.ts
+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 = 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);
+  const efficiencyRatioRaw = safeRatioPositiveDenom(nonix, revenueDenominator);
+  return {
+    asset,
+    dep,
+    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),
+    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;
+}
+
+// src/tools/peerGroup.ts
+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 = all.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 FINANCIAL_FIELDS = "CERT,ASSET,DEP,NETINC,ROA,ROE,NETNIM,EQTOT,LNLSNET,INTINC,EINTEXP,NONII,NONIX";
+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). 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)
+  - 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_MS);
+      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) => asNumber(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) => 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 mapWithConcurrency(
+          certFilters,
+          MAX_CONCURRENCY,
+          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) {
+          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) => [asNumber(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_MS / 1e3)} seconds. Narrow the peer group criteria and try again.`
+            )
+          );
+        }
+        return formatToolError(err);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+  );
+}
+
 // src/index.ts
 function createServer() {
   const server = new import_mcp.McpServer({
@@ -1789,6 +2456,7 @@ function createServer() {
   registerSodTools(server);
   registerDemographicsTools(server);
   registerAnalysisTools(server);
+  registerPeerGroupTools(server);
   return server;
 }
 async function runStdio() {
@@ -1797,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());
@@ -1840,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`