fdic-mcp-server 1.25.1 → 1.26.0

package/dist/index.js

@@ -32,7 +32,7 @@ var import_types = require("@modelcontextprotocol/sdk/types.js");
 var import_express2 = __toESM(require("express"));
 
 // src/constants.ts
-var VERSION = true ? "1.25.1" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.26.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 DEFAULT_FDIC_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -32043,6 +32043,62 @@ var FdicBankDeepDiveOutputSchema = import_zod2.z.object({
   warnings: import_zod2.z.array(import_zod2.z.string()),
   sources: import_zod2.z.array(Source)
 });
+var PeerStatsSchema = import_zod2.z.object({
+  peer_count: import_zod2.z.number().int(),
+  peer_median: import_zod2.z.number(),
+  peer_mean: import_zod2.z.number(),
+  subject_value: import_zod2.z.number(),
+  subject_percentile: import_zod2.z.number(),
+  robust_z_score: import_zod2.z.number(),
+  is_outlier: import_zod2.z.boolean(),
+  outlier_direction: import_zod2.z.enum(["high", "low"]).optional()
+});
+var PeerHealthMetricRowSchema = import_zod2.z.object({
+  name: import_zod2.z.string(),
+  label: import_zod2.z.string(),
+  subject: import_zod2.z.number().nullable(),
+  peer_median: import_zod2.z.number().nullable(),
+  peer_weighted_avg: import_zod2.z.number().nullable(),
+  percentile: import_zod2.z.number().nullable(),
+  higher_is_better: import_zod2.z.boolean(),
+  is_outlier: import_zod2.z.boolean(),
+  outlier_direction: import_zod2.z.enum(["high", "low"]).nullable()
+});
+var PeerHealthInstitutionSchema = import_zod2.z.object({
+  cert: import_zod2.z.number().int(),
+  name: import_zod2.z.string(),
+  name_source: import_zod2.z.enum(["fdic_institution_profile", "cert_fallback"]),
+  city: import_zod2.z.string().nullable(),
+  state: import_zod2.z.string().nullable(),
+  total_assets: import_zod2.z.number().nullable(),
+  proxy_score: import_zod2.z.number(),
+  proxy_band: import_zod2.z.string(),
+  composite_rating: import_zod2.z.number(),
+  composite_label: import_zod2.z.string(),
+  component_ratings: import_zod2.z.record(import_zod2.z.number()),
+  flags: import_zod2.z.array(import_zod2.z.string())
+});
+var FdicPeerHealthOutputSchema = import_zod2.z.object({
+  model: import_zod2.z.literal("public_camels_proxy_v1"),
+  official_status: import_zod2.z.literal("public off-site proxy, not official CAMELS"),
+  proxy: import_zod2.z.unknown().nullable(),
+  report_date: import_zod2.z.string(),
+  sort_by: import_zod2.z.string(),
+  total_institutions: import_zod2.z.number().int(),
+  returned_count: import_zod2.z.number().int(),
+  subject_cert: import_zod2.z.number().int().nullable(),
+  subject_rank: import_zod2.z.number().int().nullable(),
+  metrics: import_zod2.z.array(PeerHealthMetricRowSchema),
+  institutions: import_zod2.z.array(PeerHealthInstitutionSchema),
+  peer_context: import_zod2.z.object({
+    peer_count: import_zod2.z.number().int(),
+    peer_definition: import_zod2.z.string(),
+    broadening_steps: import_zod2.z.array(import_zod2.z.string()),
+    subject_rank: import_zod2.z.number().int().nullable(),
+    subject_percentiles: import_zod2.z.record(PeerStatsSchema),
+    weighted_peer_averages: import_zod2.z.record(import_zod2.z.number())
+  }).nullable()
+}).passthrough();
 var FdicAnalysisOutputSchema = import_zod2.z.object({}).passthrough();
 
 // src/tools/institutions.ts
@@ -35819,6 +35875,15 @@ function computePeerStats(subjectValue, peerValues, options) {
 }
 
 // src/tools/peerHealth.ts
+var PEER_METRICS = [
+  // legacyKey preserves the original camelCase peer_context map keys for backward compatibility.
+  // New UI consumers should bind to the flat metrics[].name snake_case values instead.
+  { key: "roaPct", legacyKey: "roaPct", name: "roa_pct", label: "Return on assets", higherIsBetter: true },
+  { key: "equityCapitalRatioPct", legacyKey: "equityCapitalRatioPct", name: "equity_capital_ratio_pct", label: "Equity capital ratio", higherIsBetter: true },
+  { key: "netInterestMarginPct", legacyKey: "netInterestMarginPct", name: "net_interest_margin_pct", label: "Net interest margin", higherIsBetter: true },
+  { key: "efficiencyRatioPct", legacyKey: "efficiencyRatioPct", name: "efficiency_ratio_pct", label: "Efficiency ratio", higherIsBetter: false },
+  { key: "loanToDepositPct", legacyKey: "loanToDepositPct", name: "loan_to_deposit_pct", label: "Loan-to-deposit ratio", higherIsBetter: false }
+];
 var PeerHealthInputSchema = import_zod11.z.object({
   cert: import_zod11.z.number().int().positive().optional().describe("Subject institution CERT to highlight in the ranking. Optional."),
   certs: import_zod11.z.array(import_zod11.z.number().int().positive()).max(50).optional().describe("Explicit list of CERTs to compare (max 50)."),
@@ -35853,11 +35918,11 @@ Three usage modes:
 
 Optionally provide cert to highlight a subject institution's position in the ranking.
 
-Output: Ranked list with per-institution proxy_score (1-4 scale) and proxy_band, sorted by composite or any individual component. When a subject cert is provided, includes peer percentile context, asset-weighted peer averages, and the subject's full proxy assessment. Auto-peer selection derives asset bands from report-date financials and broadens the cohort if fewer than 10 peers match.
+Output: structuredContent includes {model, official_status, report_date, institutions, metrics, peer_context, proxy}. Institutions include proxy scores and name_source. When a subject cert is provided, metrics is a flat subject-vs-peer array for UI binding while peer_context preserves the legacy nested percentiles and weighted averages. Auto-peer selection derives asset bands from report-date financials and broadens the cohort if fewer than 10 peers match.
 
 NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`,
       inputSchema: PeerHealthInputSchema,
-      outputSchema: FdicAnalysisOutputSchema,
+      outputSchema: FdicPeerHealthOutputSchema,
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -36031,6 +36096,33 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
           const c = asNumber(r.CERT);
           if (c !== null) profileMap.set(c, r);
         }
+        const financialCerts = allFinancials.map((r) => asNumber(r.CERT)).filter((cert) => cert !== null);
+        const missingProfileCerts = financialCerts.filter((cert) => {
+          const profile = profileMap.get(cert);
+          return !profile || typeof profile.NAME !== "string" || profile.NAME.length === 0;
+        });
+        if (missingProfileCerts.length > 0) {
+          const missingProfileFilters = buildCertFilters(missingProfileCerts);
+          const missingProfileResponses = await mapWithConcurrency(
+            missingProfileFilters,
+            MAX_CONCURRENCY,
+            async (certFilter) => queryEndpoint(
+              ENDPOINTS.INSTITUTIONS,
+              {
+                filters: certFilter,
+                fields: "CERT,NAME,CITY,STALP",
+                limit: 1e4,
+                sort_by: "CERT",
+                sort_order: "ASC"
+              },
+              { signal: controller.signal }
+            )
+          );
+          for (const r of missingProfileResponses.flatMap(extractRecords)) {
+            const c = asNumber(r.CERT);
+            if (c !== null) profileMap.set(c, r);
+          }
+        }
         await sendProgressNotification(server.server, progressToken, 0.7, "Computing proxy assessments");
         const subjectHistory = params.cert ? await fetchHistoryEvents(params.cert, { signal: controller.signal, repdte: params.repdte }) : [];
         let subjectProxy = null;
@@ -36069,7 +36161,8 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
           ];
           entries.push({
             cert,
-            name: String(profile?.NAME ?? `CERT ${cert}`),
+            name: typeof profile?.NAME === "string" && profile.NAME.length > 0 ? profile.NAME : `CERT ${cert}`,
+            name_source: typeof profile?.NAME === "string" && profile.NAME.length > 0 ? "fdic_institution_profile" : "cert_fallback",
             city: profile?.CITY ? String(profile.CITY) : null,
             state: profile?.STALP ? String(profile.STALP) : null,
             total_assets: asNumber(fin.ASSET),
@@ -36094,18 +36187,12 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
         });
         const subjectRank = params.cert ? entries.findIndex((e) => e.cert === params.cert) + 1 : null;
         let peerContext = null;
+        let metricRows = [];
         if (params.cert) {
           const subjectFin = allFinancials.find((f) => asNumber(f.CERT) === params.cert);
           if (subjectFin) {
             const subjectExtraction = extractCanonicalMetrics(subjectFin);
             const sm = subjectExtraction.metrics;
-            const PEER_METRICS = [
-              { key: "roaPct", label: "roaPct", higherIsBetter: true },
-              { key: "equityCapitalRatioPct", label: "equityCapitalRatioPct", higherIsBetter: true },
-              { key: "netInterestMarginPct", label: "netInterestMarginPct", higherIsBetter: true },
-              { key: "efficiencyRatioPct", label: "efficiencyRatioPct", higherIsBetter: false },
-              { key: "loanToDepositPct", label: "loanToDepositPct", higherIsBetter: false }
-            ];
             const peerFinancials = allFinancials.filter((f) => asNumber(f.CERT) !== params.cert);
             const peerExtractions = peerFinancials.map((f) => extractCanonicalMetrics(f));
             const subjectPercentiles = {};
@@ -36124,15 +36211,28 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
                 }
               }
               if (peerValues.length === 0) continue;
+              let stats = null;
               if (subjectVal !== null) {
-                subjectPercentiles[pm.label] = computePeerStats(subjectVal, peerValues, {
+                stats = computePeerStats(subjectVal, peerValues, {
                   higherIsBetter: pm.higherIsBetter
                 });
+                subjectPercentiles[pm.legacyKey] = stats;
               }
               const weighted = computeWeightedAggregate(weightedEntries);
               if (weighted !== null) {
-                weightedPeerAverages[pm.label] = Math.round(weighted * 100) / 100;
+                weightedPeerAverages[pm.legacyKey] = Math.round(weighted * 100) / 100;
               }
+              metricRows.push({
+                name: pm.name,
+                label: pm.label,
+                subject: subjectVal,
+                peer_median: stats?.peer_median ?? null,
+                peer_weighted_avg: weighted !== null ? Math.round(weighted * 100) / 100 : null,
+                percentile: stats?.subject_percentile ?? null,
+                higher_is_better: pm.higherIsBetter,
+                is_outlier: stats?.is_outlier ?? false,
+                outlier_direction: stats?.outlier_direction ?? null
+              });
             }
             let peerDef;
             if (params.certs) {
@@ -36213,6 +36313,7 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
             returned_count: returned.length,
             subject_cert: params.cert ?? null,
             subject_rank: subjectRank,
+            metrics: metricRows,
             institutions: returned,
             peer_context: peerContext
           }

package/dist/server.js

@@ -47,7 +47,7 @@ var import_types = require("@modelcontextprotocol/sdk/types.js");
 var import_express2 = __toESM(require("express"));
 
 // src/constants.ts
-var VERSION = true ? "1.25.1" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.26.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 DEFAULT_FDIC_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -32058,6 +32058,62 @@ var FdicBankDeepDiveOutputSchema = import_zod2.z.object({
   warnings: import_zod2.z.array(import_zod2.z.string()),
   sources: import_zod2.z.array(Source)
 });
+var PeerStatsSchema = import_zod2.z.object({
+  peer_count: import_zod2.z.number().int(),
+  peer_median: import_zod2.z.number(),
+  peer_mean: import_zod2.z.number(),
+  subject_value: import_zod2.z.number(),
+  subject_percentile: import_zod2.z.number(),
+  robust_z_score: import_zod2.z.number(),
+  is_outlier: import_zod2.z.boolean(),
+  outlier_direction: import_zod2.z.enum(["high", "low"]).optional()
+});
+var PeerHealthMetricRowSchema = import_zod2.z.object({
+  name: import_zod2.z.string(),
+  label: import_zod2.z.string(),
+  subject: import_zod2.z.number().nullable(),
+  peer_median: import_zod2.z.number().nullable(),
+  peer_weighted_avg: import_zod2.z.number().nullable(),
+  percentile: import_zod2.z.number().nullable(),
+  higher_is_better: import_zod2.z.boolean(),
+  is_outlier: import_zod2.z.boolean(),
+  outlier_direction: import_zod2.z.enum(["high", "low"]).nullable()
+});
+var PeerHealthInstitutionSchema = import_zod2.z.object({
+  cert: import_zod2.z.number().int(),
+  name: import_zod2.z.string(),
+  name_source: import_zod2.z.enum(["fdic_institution_profile", "cert_fallback"]),
+  city: import_zod2.z.string().nullable(),
+  state: import_zod2.z.string().nullable(),
+  total_assets: import_zod2.z.number().nullable(),
+  proxy_score: import_zod2.z.number(),
+  proxy_band: import_zod2.z.string(),
+  composite_rating: import_zod2.z.number(),
+  composite_label: import_zod2.z.string(),
+  component_ratings: import_zod2.z.record(import_zod2.z.number()),
+  flags: import_zod2.z.array(import_zod2.z.string())
+});
+var FdicPeerHealthOutputSchema = import_zod2.z.object({
+  model: import_zod2.z.literal("public_camels_proxy_v1"),
+  official_status: import_zod2.z.literal("public off-site proxy, not official CAMELS"),
+  proxy: import_zod2.z.unknown().nullable(),
+  report_date: import_zod2.z.string(),
+  sort_by: import_zod2.z.string(),
+  total_institutions: import_zod2.z.number().int(),
+  returned_count: import_zod2.z.number().int(),
+  subject_cert: import_zod2.z.number().int().nullable(),
+  subject_rank: import_zod2.z.number().int().nullable(),
+  metrics: import_zod2.z.array(PeerHealthMetricRowSchema),
+  institutions: import_zod2.z.array(PeerHealthInstitutionSchema),
+  peer_context: import_zod2.z.object({
+    peer_count: import_zod2.z.number().int(),
+    peer_definition: import_zod2.z.string(),
+    broadening_steps: import_zod2.z.array(import_zod2.z.string()),
+    subject_rank: import_zod2.z.number().int().nullable(),
+    subject_percentiles: import_zod2.z.record(PeerStatsSchema),
+    weighted_peer_averages: import_zod2.z.record(import_zod2.z.number())
+  }).nullable()
+}).passthrough();
 var FdicAnalysisOutputSchema = import_zod2.z.object({}).passthrough();
 
 // src/tools/institutions.ts
@@ -35834,6 +35890,15 @@ function computePeerStats(subjectValue, peerValues, options) {
 }
 
 // src/tools/peerHealth.ts
+var PEER_METRICS = [
+  // legacyKey preserves the original camelCase peer_context map keys for backward compatibility.
+  // New UI consumers should bind to the flat metrics[].name snake_case values instead.
+  { key: "roaPct", legacyKey: "roaPct", name: "roa_pct", label: "Return on assets", higherIsBetter: true },
+  { key: "equityCapitalRatioPct", legacyKey: "equityCapitalRatioPct", name: "equity_capital_ratio_pct", label: "Equity capital ratio", higherIsBetter: true },
+  { key: "netInterestMarginPct", legacyKey: "netInterestMarginPct", name: "net_interest_margin_pct", label: "Net interest margin", higherIsBetter: true },
+  { key: "efficiencyRatioPct", legacyKey: "efficiencyRatioPct", name: "efficiency_ratio_pct", label: "Efficiency ratio", higherIsBetter: false },
+  { key: "loanToDepositPct", legacyKey: "loanToDepositPct", name: "loan_to_deposit_pct", label: "Loan-to-deposit ratio", higherIsBetter: false }
+];
 var PeerHealthInputSchema = import_zod11.z.object({
   cert: import_zod11.z.number().int().positive().optional().describe("Subject institution CERT to highlight in the ranking. Optional."),
   certs: import_zod11.z.array(import_zod11.z.number().int().positive()).max(50).optional().describe("Explicit list of CERTs to compare (max 50)."),
@@ -35868,11 +35933,11 @@ Three usage modes:
 
 Optionally provide cert to highlight a subject institution's position in the ranking.
 
-Output: Ranked list with per-institution proxy_score (1-4 scale) and proxy_band, sorted by composite or any individual component. When a subject cert is provided, includes peer percentile context, asset-weighted peer averages, and the subject's full proxy assessment. Auto-peer selection derives asset bands from report-date financials and broadens the cohort if fewer than 10 peers match.
+Output: structuredContent includes {model, official_status, report_date, institutions, metrics, peer_context, proxy}. Institutions include proxy scores and name_source. When a subject cert is provided, metrics is a flat subject-vs-peer array for UI binding while peer_context preserves the legacy nested percentiles and weighted averages. Auto-peer selection derives asset bands from report-date financials and broadens the cohort if fewer than 10 peers match.
 
 NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`,
       inputSchema: PeerHealthInputSchema,
-      outputSchema: FdicAnalysisOutputSchema,
+      outputSchema: FdicPeerHealthOutputSchema,
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -36046,6 +36111,33 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
           const c = asNumber(r.CERT);
           if (c !== null) profileMap.set(c, r);
         }
+        const financialCerts = allFinancials.map((r) => asNumber(r.CERT)).filter((cert) => cert !== null);
+        const missingProfileCerts = financialCerts.filter((cert) => {
+          const profile = profileMap.get(cert);
+          return !profile || typeof profile.NAME !== "string" || profile.NAME.length === 0;
+        });
+        if (missingProfileCerts.length > 0) {
+          const missingProfileFilters = buildCertFilters(missingProfileCerts);
+          const missingProfileResponses = await mapWithConcurrency(
+            missingProfileFilters,
+            MAX_CONCURRENCY,
+            async (certFilter) => queryEndpoint(
+              ENDPOINTS.INSTITUTIONS,
+              {
+                filters: certFilter,
+                fields: "CERT,NAME,CITY,STALP",
+                limit: 1e4,
+                sort_by: "CERT",
+                sort_order: "ASC"
+              },
+              { signal: controller.signal }
+            )
+          );
+          for (const r of missingProfileResponses.flatMap(extractRecords)) {
+            const c = asNumber(r.CERT);
+            if (c !== null) profileMap.set(c, r);
+          }
+        }
         await sendProgressNotification(server.server, progressToken, 0.7, "Computing proxy assessments");
         const subjectHistory = params.cert ? await fetchHistoryEvents(params.cert, { signal: controller.signal, repdte: params.repdte }) : [];
         let subjectProxy = null;
@@ -36084,7 +36176,8 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
           ];
           entries.push({
             cert,
-            name: String(profile?.NAME ?? `CERT ${cert}`),
+            name: typeof profile?.NAME === "string" && profile.NAME.length > 0 ? profile.NAME : `CERT ${cert}`,
+            name_source: typeof profile?.NAME === "string" && profile.NAME.length > 0 ? "fdic_institution_profile" : "cert_fallback",
             city: profile?.CITY ? String(profile.CITY) : null,
             state: profile?.STALP ? String(profile.STALP) : null,
             total_assets: asNumber(fin.ASSET),
@@ -36109,18 +36202,12 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
         });
         const subjectRank = params.cert ? entries.findIndex((e) => e.cert === params.cert) + 1 : null;
         let peerContext = null;
+        let metricRows = [];
         if (params.cert) {
           const subjectFin = allFinancials.find((f) => asNumber(f.CERT) === params.cert);
           if (subjectFin) {
             const subjectExtraction = extractCanonicalMetrics(subjectFin);
             const sm = subjectExtraction.metrics;
-            const PEER_METRICS = [
-              { key: "roaPct", label: "roaPct", higherIsBetter: true },
-              { key: "equityCapitalRatioPct", label: "equityCapitalRatioPct", higherIsBetter: true },
-              { key: "netInterestMarginPct", label: "netInterestMarginPct", higherIsBetter: true },
-              { key: "efficiencyRatioPct", label: "efficiencyRatioPct", higherIsBetter: false },
-              { key: "loanToDepositPct", label: "loanToDepositPct", higherIsBetter: false }
-            ];
             const peerFinancials = allFinancials.filter((f) => asNumber(f.CERT) !== params.cert);
             const peerExtractions = peerFinancials.map((f) => extractCanonicalMetrics(f));
             const subjectPercentiles = {};
@@ -36139,15 +36226,28 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
                 }
               }
               if (peerValues.length === 0) continue;
+              let stats = null;
               if (subjectVal !== null) {
-                subjectPercentiles[pm.label] = computePeerStats(subjectVal, peerValues, {
+                stats = computePeerStats(subjectVal, peerValues, {
                   higherIsBetter: pm.higherIsBetter
                 });
+                subjectPercentiles[pm.legacyKey] = stats;
               }
               const weighted = computeWeightedAggregate(weightedEntries);
               if (weighted !== null) {
-                weightedPeerAverages[pm.label] = Math.round(weighted * 100) / 100;
+                weightedPeerAverages[pm.legacyKey] = Math.round(weighted * 100) / 100;
               }
+              metricRows.push({
+                name: pm.name,
+                label: pm.label,
+                subject: subjectVal,
+                peer_median: stats?.peer_median ?? null,
+                peer_weighted_avg: weighted !== null ? Math.round(weighted * 100) / 100 : null,
+                percentile: stats?.subject_percentile ?? null,
+                higher_is_better: pm.higherIsBetter,
+                is_outlier: stats?.is_outlier ?? false,
+                outlier_direction: stats?.outlier_direction ?? null
+              });
             }
             let peerDef;
             if (params.certs) {
@@ -36228,6 +36328,7 @@ NOTE: Public off-site analytical proxy \u2014 not official supervisory ratings.`
             returned_count: returned.length,
             subject_cert: params.cert ?? null,
             subject_rank: subjectRank,
+            metrics: metricRows,
             institutions: returned,
             peer_context: peerContext
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdic-mcp-server",
-  "version": "1.25.1",
+  "version": "1.26.0",
   "description": "MCP server for the FDIC BankFind Suite API",
   "mcpName": "io.github.jflamb/fdic-mcp-server",
   "main": "dist/server.js",