fdic-mcp-server 1.0.8 → 1.1.0

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.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 = {
@@ -1775,6 +1775,583 @@ 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;
+}
+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);
+      }
+    }
+  );
+}
+
 // src/index.ts
 function createServer() {
   const server = new import_mcp.McpServer({
@@ -1789,6 +2366,7 @@ function createServer() {
   registerSodTools(server);
   registerDemographicsTools(server);
   registerAnalysisTools(server);
+  registerPeerGroupTools(server);
   return server;
 }
 async function runStdio() {