fdic-mcp-server 1.0.5 → 1.0.7

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.5" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.0.7" : 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 = {
@@ -54,42 +54,73 @@ var apiClient = import_axios.default.create({
     "User-Agent": `fdic-mcp-server/${VERSION}`
   }
 });
+var QUERY_CACHE_TTL_MS = 6e4;
+var queryCache = /* @__PURE__ */ new Map();
+function getCacheKey(endpoint, params) {
+  return JSON.stringify([
+    endpoint,
+    params.filters ?? null,
+    params.fields ?? null,
+    params.limit ?? null,
+    params.offset ?? null,
+    params.sort_by ?? null,
+    params.sort_order ?? null
+  ]);
+}
 async function queryEndpoint(endpoint, params) {
-  try {
-    const queryParams = {
-      limit: params.limit ?? 20,
-      offset: params.offset ?? 0,
-      output: "json"
-    };
-    if (params.filters) queryParams.filters = params.filters;
-    if (params.fields) queryParams.fields = params.fields;
-    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
-    });
-    return response.data;
-  } catch (err) {
-    if (err instanceof import_axios.AxiosError) {
-      const status = err.response?.status;
-      const detail = err.response?.data?.message ?? err.message;
-      if (status === 400) {
-        throw new Error(
-          `Bad request to FDIC API: ${detail}. Check your filter syntax (use ElasticSearch query string syntax, e.g. STNAME:"California" AND ACTIVE:1).`
-        );
-      } else if (status === 429) {
-        throw new Error(
-          "FDIC API rate limit exceeded. Please wait a moment and try again."
-        );
-      } else if (status === 500) {
-        throw new Error(
-          "FDIC API server error. The service may be temporarily unavailable. Try again later."
-        );
-      } else {
-        throw new Error(`FDIC API error (HTTP ${status}): ${detail}`);
+  const cacheKey = getCacheKey(endpoint, params);
+  const now = Date.now();
+  const cached = queryCache.get(cacheKey);
+  if (cached && cached.expiresAt > now) {
+    return cached.value;
+  }
+  const requestPromise = (async () => {
+    try {
+      const queryParams = {
+        limit: params.limit ?? 20,
+        offset: params.offset ?? 0,
+        output: "json"
+      };
+      if (params.filters) queryParams.filters = params.filters;
+      if (params.fields) queryParams.fields = params.fields;
+      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
+      });
+      return response.data;
+    } catch (err) {
+      if (err instanceof import_axios.AxiosError) {
+        const status = err.response?.status;
+        const detail = err.response?.data?.message ?? err.message;
+        if (status === 400) {
+          throw new Error(
+            `Bad request to FDIC API: ${detail}. Check your filter syntax (use ElasticSearch query string syntax, e.g. STNAME:"California" AND ACTIVE:1).`
+          );
+        } else if (status === 429) {
+          throw new Error(
+            "FDIC API rate limit exceeded. Please wait a moment and try again."
+          );
+        } else if (status === 500) {
+          throw new Error(
+            "FDIC API server error. The service may be temporarily unavailable. Try again later."
+          );
+        } else {
+          throw new Error(`FDIC API error (HTTP ${status}): ${detail}`);
+        }
       }
+      throw new Error(`Unexpected error calling FDIC API: ${String(err)}`);
     }
-    throw new Error(`Unexpected error calling FDIC API: ${String(err)}`);
+  })();
+  queryCache.set(cacheKey, {
+    expiresAt: now + QUERY_CACHE_TTL_MS,
+    value: requestPromise
+  });
+  try {
+    return await requestPromise;
+  } catch (error) {
+    queryCache.delete(cacheKey);
+    throw error;
   }
 }
 function extractRecords(response) {
@@ -111,6 +142,37 @@ function truncateIfNeeded(text, charLimit) {
 
 [Response truncated at ${charLimit} characters. Use limit/offset parameters to paginate or narrow your query with filters.]`;
 }
+function formatValue(value) {
+  if (value === null || value === void 0) return "n/a";
+  if (typeof value === "number") return Number.isInteger(value) ? `${value}` : value.toFixed(4);
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return JSON.stringify(value);
+}
+function summarizeRecord(record, preferredKeys, maxFields = 4) {
+  const orderedKeys = [
+    ...preferredKeys.filter((key) => key in record),
+    ...Object.keys(record).filter(
+      (key) => key !== "ID" && !preferredKeys.includes(key)
+    )
+  ];
+  return orderedKeys.slice(0, maxFields).map((key) => `${key}: ${formatValue(record[key])}`).join(" | ");
+}
+function formatSearchResultText(label, records, pagination, preferredKeys) {
+  const header = `Found ${pagination.total} ${label} (showing ${pagination.count}, offset ${pagination.offset}).`;
+  if (records.length === 0) {
+    return header;
+  }
+  const rows = records.map((record, index) => `${index + 1}. ${summarizeRecord(record, preferredKeys)}`).join("\n");
+  const footer = pagination.has_more ? `
+More results available. Use offset ${pagination.next_offset} to continue.` : "";
+  return `${header}
+${rows}${footer}`;
+}
+function formatLookupResultText(label, record, preferredKeys) {
+  return `${label}
+${summarizeRecord(record, preferredKeys, 8)}`;
+}
 function formatToolError(err) {
   const message = err instanceof Error ? err.message : String(err);
   return {
@@ -183,7 +245,7 @@ Args:
   - sort_by (string, optional): Field to sort by
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, institutions[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and institution records.`,
       inputSchema: CommonQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -203,7 +265,14 @@ Returns JSON with { total, offset, count, has_more, next_offset?, institutions[]
         );
         const output = { ...pagination, institutions: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("institutions", records, pagination, [
+            "CERT",
+            "NAME",
+            "CITY",
+            "STALP",
+            "ASSET",
+            "ACTIVE"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -227,7 +296,7 @@ Args:
   - cert (number): FDIC Certificate Number (e.g., 3511 for Bank of America)
   - fields (string, optional): Comma-separated list of fields to return
 
-Returns full institution profile including financial metrics, charter info, locations, and regulatory details.`,
+Returns a detailed institution profile suitable for concise summaries, with structured fields available for exact values when needed.`,
       inputSchema: CertSchema,
       annotations: {
         readOnlyHint: true,
@@ -256,7 +325,16 @@ Returns full institution profile including financial metrics, charter info, loca
           };
         }
         const output = records[0];
-        const text = JSON.stringify(output, null, 2);
+        const text = formatLookupResultText("Institution details", output, [
+          "CERT",
+          "NAME",
+          "CITY",
+          "STALP",
+          "ASSET",
+          "DEP",
+          "ACTIVE",
+          "REGAGNT"
+        ]);
         return {
           content: [{ type: "text", text }],
           structuredContent: output
@@ -304,7 +382,7 @@ Args:
   - sort_by (string, optional): Field to sort by (e.g., FAILDATE, COST)
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, failures[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and failure records.`,
       inputSchema: CommonQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -324,7 +402,15 @@ Returns JSON with { total, offset, count, has_more, next_offset?, failures[] }`,
         );
         const output = { ...pagination, failures: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("failures", records, pagination, [
+            "CERT",
+            "NAME",
+            "CITY",
+            "STALP",
+            "FAILDATE",
+            "COST",
+            "RESTYPE"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -348,7 +434,7 @@ Args:
   - cert (number): FDIC Certificate Number of the failed institution
   - fields (string, optional): Comma-separated list of fields to return
 
-Returns failure details including failure date, resolution method, and cost to FDIC.`,
+Returns detailed failure information suitable for concise summaries, with structured fields available for exact values when needed.`,
       inputSchema: CertSchema,
       annotations: {
         readOnlyHint: true,
@@ -377,7 +463,16 @@ Returns failure details including failure date, resolution method, and cost to F
           };
         }
         const output = records[0];
-        const text = JSON.stringify(output, null, 2);
+        const text = formatLookupResultText("Failure details", output, [
+          "CERT",
+          "NAME",
+          "FAILDATE",
+          "RESTYPE",
+          "COST",
+          "QBFASSET",
+          "CITY",
+          "STALP"
+        ]);
         return {
           content: [{ type: "text", text }],
           structuredContent: output
@@ -435,7 +530,7 @@ Args:
   - sort_by (string, optional): Field to sort by
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, locations[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and branch location records.`,
       inputSchema: LocationQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -462,7 +557,14 @@ Returns JSON with { total, offset, count, has_more, next_offset?, locations[] }`
         );
         const output = { ...pagination, locations: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("locations", records, pagination, [
+            "CERT",
+            "UNINAME",
+            "NAMEFULL",
+            "CITY",
+            "STALP",
+            "BRNUM"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -523,7 +625,7 @@ Args:
   - sort_by (string, optional): Field to sort by (e.g., PROCDATE)
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, events[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and event records.`,
       inputSchema: HistoryQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -550,7 +652,14 @@ Returns JSON with { total, offset, count, has_more, next_offset?, events[] }`,
         );
         const output = { ...pagination, events: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("events", records, pagination, [
+            "CERT",
+            "INSTNAME",
+            "TYPE",
+            "PROCDATE",
+            "PCITY",
+            "PSTALP"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -620,7 +729,7 @@ Args:
   - sort_by (string, optional): Field to sort by
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'DESC' recommended for most recent first)
 
-Returns JSON with { total, offset, count, has_more, next_offset?, financials[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and quarterly financial records.`,
       inputSchema: FinancialQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -647,7 +756,14 @@ Returns JSON with { total, offset, count, has_more, next_offset?, financials[] }
         );
         const output = { ...pagination, financials: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("financial records", records, pagination, [
+            "CERT",
+            "NAME",
+            "REPDTE",
+            "ASSET",
+            "DEP",
+            "NETINC"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -695,7 +811,7 @@ Args:
   - sort_by (string, optional): Field to sort by (e.g., YEAR, ASSET)
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, summary[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and annual summary records.`,
       inputSchema: SummaryQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -722,7 +838,14 @@ Returns JSON with { total, offset, count, has_more, next_offset?, summary[] }`,
         );
         const output = { ...pagination, summary: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("annual summary records", records, pagination, [
+            "CERT",
+            "YEAR",
+            "ASSET",
+            "DEP",
+            "NETINC",
+            "ROA"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -784,7 +907,7 @@ Args:
   - sort_by (string, optional): Field to sort by (e.g., DEPSUMBR, YEAR)
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, deposits[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and deposit records.`,
       inputSchema: SodQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -811,7 +934,14 @@ Returns JSON with { total, offset, count, has_more, next_offset?, deposits[] }`,
         );
         const output = { ...pagination, deposits: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("deposit records", records, pagination, [
+            "CERT",
+            "YEAR",
+            "UNINAME",
+            "NAMEFULL",
+            "CITYBR",
+            "DEPSUMBR"
+          ]),
           CHARACTER_LIMIT
         );
         return {
@@ -873,7 +1003,7 @@ Args:
   - sort_by (string, optional): Field to sort by
   - sort_order ('ASC'|'DESC'): Sort direction (default: 'ASC')
 
-Returns JSON with { total, offset, count, has_more, next_offset?, demographics[] }`,
+Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and demographic records.`,
       inputSchema: DemographicsQuerySchema,
       annotations: {
         readOnlyHint: true,
@@ -900,7 +1030,657 @@ Returns JSON with { total, offset, count, has_more, next_offset?, demographics[]
         );
         const output = { ...pagination, demographics: records };
         const text = truncateIfNeeded(
-          JSON.stringify(output, null, 2),
+          formatSearchResultText("demographic records", records, pagination, [
+            "CERT",
+            "REPDTE",
+            "OFFTOT",
+            "OFFSTATE",
+            "METRO",
+            "CBSANAME"
+          ]),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/analysis.ts
+var import_zod7 = require("zod");
+var CHUNK_SIZE = 25;
+var MAX_CONCURRENCY = 4;
+var SortFieldSchema = import_zod7.z.enum([
+  "asset_growth",
+  "asset_growth_pct",
+  "dep_growth",
+  "dep_growth_pct",
+  "netinc_change",
+  "netinc_change_pct",
+  "roa_change",
+  "roe_change",
+  "offices_change",
+  "assets_per_office_change",
+  "deposits_per_office_change",
+  "deposits_to_assets_change"
+]);
+var AnalysisModeSchema = import_zod7.z.enum(["snapshot", "timeseries"]);
+var SnapshotAnalysisSchema = import_zod7.z.object({
+  state: import_zod7.z.string().optional().describe(
+    'State name for the institution roster filter. Example: "North Carolina"'
+  ),
+  certs: import_zod7.z.array(import_zod7.z.number().int().positive()).max(100).optional().describe(
+    "Optional list of FDIC certificate numbers to compare directly. Max 100."
+  ),
+  institution_filters: import_zod7.z.string().optional().describe(
+    'Additional institution-level filter used when building the comparison set. Example: BKCLASS:N or CITY:"Charlotte"'
+  ),
+  active_only: import_zod7.z.boolean().default(true).describe("Limit the comparison set to currently active institutions."),
+  start_repdte: import_zod7.z.string().regex(/^\d{8}$/).describe("Starting report date in YYYYMMDD format."),
+  end_repdte: import_zod7.z.string().regex(/^\d{8}$/).describe("Ending report date in YYYYMMDD format."),
+  analysis_mode: AnalysisModeSchema.default("snapshot").describe(
+    "Use snapshot for two-point comparison or timeseries for quarterly trend analysis across the date range."
+  ),
+  include_demographics: import_zod7.z.boolean().default(true).describe(
+    "Include office-count changes from the demographics dataset when available."
+  ),
+  limit: import_zod7.z.number().int().min(1).max(100).default(10).describe("Maximum number of ranked comparisons to return."),
+  sort_by: SortFieldSchema.default("asset_growth").describe(
+    "Comparison field used to rank institutions."
+  ),
+  sort_order: import_zod7.z.enum(["ASC", "DESC"]).default("DESC").describe("Sort direction for the ranked comparisons.")
+}).superRefine((value, ctx) => {
+  if (!value.state && (!value.certs || value.certs.length === 0)) {
+    ctx.addIssue({
+      code: import_zod7.z.ZodIssueCode.custom,
+      message: "Provide either state or certs.",
+      path: ["state"]
+    });
+  }
+});
+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 ratio(numerator, denominator) {
+  if (numerator === null || denominator === null || denominator === 0) {
+    return null;
+  }
+  return numerator / denominator;
+}
+function pctChange(start, end) {
+  if (start === null || end === null || start === 0) return null;
+  return (end - start) / start * 100;
+}
+function change(start, end) {
+  if (start === null || end === null) return null;
+  return end - start;
+}
+function yearsBetween(startRepdte, endRepdte) {
+  const start = /* @__PURE__ */ new Date(
+    `${startRepdte.slice(0, 4)}-${startRepdte.slice(4, 6)}-${startRepdte.slice(6, 8)}`
+  );
+  const end = /* @__PURE__ */ new Date(
+    `${endRepdte.slice(0, 4)}-${endRepdte.slice(4, 6)}-${endRepdte.slice(6, 8)}`
+  );
+  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) {
+    return null;
+  }
+  return (Math.pow(end / start, 1 / years) - 1) * 100;
+}
+function formatPercent(value) {
+  return value === null ? "n/a" : `${value.toFixed(1)}%`;
+}
+function formatChange(value, digits = 4) {
+  if (value === null) return "n/a";
+  return value.toFixed(digits);
+}
+function formatInteger(value) {
+  return value === null ? "n/a" : `${Math.round(value).toLocaleString()}`;
+}
+function sortComparisons(comparisons, sortBy, sortOrder) {
+  const direction = sortOrder === "ASC" ? 1 : -1;
+  return [...comparisons].sort((left, right) => {
+    const leftValue = asNumber(left[sortBy]) ?? Number.NEGATIVE_INFINITY;
+    const rightValue = asNumber(right[sortBy]) ?? Number.NEGATIVE_INFINITY;
+    return (leftValue - rightValue) * direction;
+  });
+}
+function classifyInsights(comparison) {
+  const insights = [];
+  const assetGrowthPct = asNumber(comparison.asset_growth_pct);
+  const depGrowthPct = asNumber(comparison.dep_growth_pct);
+  const roaChange = asNumber(comparison.roa_change);
+  const roeChange = asNumber(comparison.roe_change);
+  const officesChange = asNumber(comparison.offices_change);
+  const depositsToAssetsChange = asNumber(comparison.deposits_to_assets_change);
+  if (assetGrowthPct !== null && assetGrowthPct >= 25 && depGrowthPct !== null && depGrowthPct >= 15 && roaChange !== null && roaChange > 0) {
+    insights.push("growth_with_better_profitability");
+  }
+  if (assetGrowthPct !== null && assetGrowthPct >= 25 && depGrowthPct !== null && depGrowthPct >= 15 && officesChange !== null && officesChange > 0) {
+    insights.push("growth_with_branch_expansion");
+  }
+  if (assetGrowthPct !== null && assetGrowthPct >= 20 && (roaChange === null || roaChange <= 0) && (roeChange === null || roeChange <= 0)) {
+    insights.push("balance_sheet_growth_without_profitability");
+  }
+  if (assetGrowthPct !== null && assetGrowthPct > 0 && officesChange !== null && officesChange < 0) {
+    insights.push("growth_with_branch_consolidation");
+  }
+  if (depositsToAssetsChange !== null && depositsToAssetsChange < 0 && depGrowthPct !== null && depGrowthPct < 0) {
+    insights.push("deposit_mix_softening");
+  }
+  return insights;
+}
+function buildTopLevelInsights(comparisons) {
+  return {
+    growth_with_better_profitability: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "growth_with_better_profitability"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    growth_with_branch_expansion: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "growth_with_branch_expansion"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    balance_sheet_growth_without_profitability: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "balance_sheet_growth_without_profitability"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name)),
+    growth_with_branch_consolidation: comparisons.filter(
+      (comparison) => comparison.insights?.includes(
+        "growth_with_branch_consolidation"
+      )
+    ).slice(0, 5).map((comparison) => String(comparison.name))
+  };
+}
+function longestMonotonicStreak(values, direction) {
+  let longest = 0;
+  let current = 0;
+  for (let i = 1; i < values.length; i += 1) {
+    const previous = values[i - 1];
+    const next = values[i];
+    if (previous === null || next === null) {
+      current = 0;
+      continue;
+    }
+    const matches = direction === "up" ? next > previous : next < previous;
+    if (matches) {
+      current += 1;
+      longest = Math.max(longest, current);
+    } else {
+      current = 0;
+    }
+  }
+  return longest;
+}
+function summarizeTimeSeries(records, demographicsByDate, institution) {
+  if (records.length < 2) return null;
+  const sorted = [...records].sort(
+    (left, right) => String(left.REPDTE).localeCompare(String(right.REPDTE))
+  );
+  const start = sorted[0];
+  const end = sorted[sorted.length - 1];
+  const startRepdte = String(start.REPDTE);
+  const endRepdte = String(end.REPDTE);
+  const years = yearsBetween(startRepdte, endRepdte);
+  const assetSeries = sorted.map((record) => asNumber(record.ASSET));
+  const roaSeries = sorted.map((record) => asNumber(record.ROA));
+  const roeSeries = sorted.map((record) => asNumber(record.ROE));
+  const officesSeries = sorted.map(
+    (record) => asNumber(demographicsByDate.get(String(record.REPDTE))?.OFFTOT)
+  );
+  const assetStart = asNumber(start.ASSET);
+  const assetEnd = asNumber(end.ASSET);
+  const depStart = asNumber(start.DEP);
+  const depEnd = asNumber(end.DEP);
+  const roaStart = asNumber(start.ROA);
+  const roaEnd = asNumber(end.ROA);
+  const roeStart = asNumber(start.ROE);
+  const roeEnd = asNumber(end.ROE);
+  const netIncStart = asNumber(start.NETINC);
+  const netIncEnd = asNumber(end.NETINC);
+  const officesStart = officesSeries[0] ?? null;
+  const officesEnd = officesSeries[officesSeries.length - 1] ?? null;
+  const assetsPerOfficeStart = ratio(assetStart, officesStart);
+  const assetsPerOfficeEnd = ratio(assetEnd, officesEnd);
+  const depositsPerOfficeStart = ratio(depStart, officesStart);
+  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 troughRoaValues = roaSeries.filter((value) => value !== null);
+  const troughRoa = troughRoaValues.length > 0 ? Math.min(...troughRoaValues) : null;
+  const comparison = {
+    cert: asNumber(start.CERT),
+    name: end.NAME ?? start.NAME ?? institution.NAME,
+    city: institution.CITY,
+    stalp: institution.STALP,
+    analysis_mode: "timeseries",
+    start_repdte: startRepdte,
+    end_repdte: endRepdte,
+    periods_analyzed: sorted.length,
+    asset_start: assetStart,
+    asset_end: assetEnd,
+    asset_growth: change(assetStart, assetEnd),
+    asset_growth_pct: pctChange(assetStart, assetEnd),
+    asset_cagr: cagr(assetStart, assetEnd, years),
+    dep_start: depStart,
+    dep_end: depEnd,
+    dep_growth: change(depStart, depEnd),
+    dep_growth_pct: pctChange(depStart, depEnd),
+    netinc_start: netIncStart,
+    netinc_end: netIncEnd,
+    netinc_change: change(netIncStart, netIncEnd),
+    netinc_change_pct: pctChange(netIncStart, netIncEnd),
+    roa_start: roaStart,
+    roa_end: roaEnd,
+    roa_change: change(roaStart, roaEnd),
+    roe_start: roeStart,
+    roe_end: roeEnd,
+    roe_change: change(roeStart, roeEnd),
+    offices_start: officesStart,
+    offices_end: officesEnd,
+    offices_change: change(officesStart, officesEnd),
+    assets_per_office_start: assetsPerOfficeStart,
+    assets_per_office_end: assetsPerOfficeEnd,
+    assets_per_office_change: change(assetsPerOfficeStart, assetsPerOfficeEnd),
+    deposits_per_office_start: depositsPerOfficeStart,
+    deposits_per_office_end: depositsPerOfficeEnd,
+    deposits_per_office_change: change(
+      depositsPerOfficeStart,
+      depositsPerOfficeEnd
+    ),
+    deposits_to_assets_start: depositsToAssetsStart,
+    deposits_to_assets_end: depositsToAssetsEnd,
+    deposits_to_assets_change: change(
+      depositsToAssetsStart,
+      depositsToAssetsEnd
+    ),
+    asset_peak: peakAsset,
+    roa_trough: troughRoa,
+    asset_growth_streak: longestMonotonicStreak(assetSeries, "up"),
+    roa_decline_streak: longestMonotonicStreak(roaSeries, "down"),
+    roe_decline_streak: longestMonotonicStreak(roeSeries, "down"),
+    time_series: sorted.map((record) => {
+      const repdte = String(record.REPDTE);
+      const demo = demographicsByDate.get(repdte);
+      return {
+        repdte,
+        asset: asNumber(record.ASSET),
+        dep: asNumber(record.DEP),
+        netinc: asNumber(record.NETINC),
+        roa: asNumber(record.ROA),
+        roe: asNumber(record.ROE),
+        offices: asNumber(demo?.OFFTOT)
+      };
+    })
+  };
+  comparison.insights = classifyInsights(comparison);
+  if (comparison.asset_growth_streak >= 3) {
+    comparison.insights.push("sustained_asset_growth");
+  }
+  if (comparison.roa_decline_streak >= 2) {
+    comparison.insights.push("multi_quarter_roa_decline");
+  }
+  return comparison;
+}
+function formatComparisonText(output) {
+  const header = `Compared ${output.analyzed_count} institutions from ${output.start_repdte} to ${output.end_repdte} (from ${output.total_candidates} candidates), ranked by ${output.sort_by} using ${output.analysis_mode} analysis.`;
+  if (output.comparisons.length === 0) {
+    return header;
+  }
+  const rows = output.comparisons.map((comparison, index) => {
+    const name = String(comparison.name ?? comparison.cert);
+    const city = comparison.city ? `, ${comparison.city}` : "";
+    const base = `${index + 1}. ${name}${city} | Asset growth: ${formatInteger(asNumber(comparison.asset_growth))} (${formatPercent(asNumber(comparison.asset_growth_pct))}) | Deposit growth: ${formatPercent(asNumber(comparison.dep_growth_pct))} | Offices: ${formatInteger(asNumber(comparison.offices_change))} | ROA: ${formatChange(asNumber(comparison.roa_change))} | ROE: ${formatChange(asNumber(comparison.roe_change))}`;
+    if (output.analysis_mode === "timeseries") {
+      return `${base} | Asset CAGR: ${formatPercent(asNumber(comparison.asset_cagr))} | Streaks: asset ${formatInteger(asNumber(comparison.asset_growth_streak))}, ROA decline ${formatInteger(asNumber(comparison.roa_decline_streak))}`;
+    }
+    return base;
+  });
+  const insights = output.insights ? Object.entries(output.insights).filter(([, names]) => names.length > 0).map(([label, names]) => `${label}: ${names.join(", ")}`).join("\n") : "";
+  return insights ? `${header}
+${rows.join("\n")}
+Insights
+${insights}` : `${header}
+${rows.join("\n")}`;
+}
+async function fetchInstitutionRoster(state, institutionFilters, activeOnly) {
+  const filterParts = [];
+  if (state) filterParts.push(`STNAME:"${state}"`);
+  if (activeOnly) filterParts.push("ACTIVE:1");
+  if (institutionFilters) filterParts.push(`(${institutionFilters})`);
+  const response = await queryEndpoint(ENDPOINTS.INSTITUTIONS, {
+    filters: filterParts.join(" AND "),
+    fields: "CERT,NAME,CITY,STALP,ACTIVE",
+    limit: 1e4,
+    offset: 0,
+    sort_by: "CERT",
+    sort_order: "ASC"
+  });
+  return extractRecords(response);
+}
+async function fetchBatchedRecordsForDates(endpoint, certs, repdteFilters, fields) {
+  const certFilters = buildCertFilters(certs);
+  const tasks = repdteFilters.flatMap(
+    (repdteFilter) => certFilters.map((certFilter) => ({
+      repdteFilter,
+      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"
+    });
+    return { repdteFilter: task.repdteFilter, response };
+  });
+  const byDate = /* @__PURE__ */ new Map();
+  for (const { repdteFilter, response } of responses) {
+    if (!byDate.has(repdteFilter)) {
+      byDate.set(repdteFilter, /* @__PURE__ */ new Map());
+    }
+    const target = byDate.get(repdteFilter);
+    for (const record of extractRecords(response)) {
+      const cert = asNumber(record.CERT);
+      if (cert !== null) target.set(cert, record);
+    }
+  }
+  return byDate;
+}
+async function fetchSeriesRecords(endpoint, certs, startRepdte, endRepdte, fields) {
+  const certFilters = buildCertFilters(certs);
+  const responses = await mapWithConcurrency(
+    certFilters,
+    MAX_CONCURRENCY,
+    async (certFilter) => queryEndpoint(endpoint, {
+      filters: `(${certFilter}) AND REPDTE:[${startRepdte} TO ${endRepdte}]`,
+      fields,
+      limit: 1e4,
+      offset: 0,
+      sort_by: "REPDTE",
+      sort_order: "ASC"
+    })
+  );
+  const grouped = /* @__PURE__ */ new Map();
+  for (const response of responses) {
+    for (const record of extractRecords(response)) {
+      const cert = asNumber(record.CERT);
+      if (cert === null) continue;
+      if (!grouped.has(cert)) grouped.set(cert, []);
+      grouped.get(cert).push(record);
+    }
+  }
+  return grouped;
+}
+function buildSnapshotComparison(cert, institution, startFinancial, endFinancial, startDemo, endDemo, startRepdte, endRepdte) {
+  const assetStart = asNumber(startFinancial.ASSET);
+  const assetEnd = asNumber(endFinancial.ASSET);
+  const depStart = asNumber(startFinancial.DEP);
+  const depEnd = asNumber(endFinancial.DEP);
+  const netIncStart = asNumber(startFinancial.NETINC);
+  const netIncEnd = asNumber(endFinancial.NETINC);
+  const roaStart = asNumber(startFinancial.ROA);
+  const roaEnd = asNumber(endFinancial.ROA);
+  const roeStart = asNumber(startFinancial.ROE);
+  const roeEnd = asNumber(endFinancial.ROE);
+  const officesStart = asNumber(startDemo?.OFFTOT);
+  const officesEnd = asNumber(endDemo?.OFFTOT);
+  const assetsPerOfficeStart = ratio(assetStart, officesStart);
+  const assetsPerOfficeEnd = ratio(assetEnd, officesEnd);
+  const depositsPerOfficeStart = ratio(depStart, officesStart);
+  const depositsPerOfficeEnd = ratio(depEnd, officesEnd);
+  const depositsToAssetsStart = ratio(depStart, assetStart);
+  const depositsToAssetsEnd = ratio(depEnd, assetEnd);
+  const comparison = {
+    cert,
+    name: endFinancial.NAME ?? startFinancial.NAME ?? institution.NAME,
+    city: institution.CITY,
+    stalp: institution.STALP,
+    analysis_mode: "snapshot",
+    start_repdte: startRepdte,
+    end_repdte: endRepdte,
+    asset_start: assetStart,
+    asset_end: assetEnd,
+    asset_growth: change(assetStart, assetEnd),
+    asset_growth_pct: pctChange(assetStart, assetEnd),
+    dep_start: depStart,
+    dep_end: depEnd,
+    dep_growth: change(depStart, depEnd),
+    dep_growth_pct: pctChange(depStart, depEnd),
+    netinc_start: netIncStart,
+    netinc_end: netIncEnd,
+    netinc_change: change(netIncStart, netIncEnd),
+    netinc_change_pct: pctChange(netIncStart, netIncEnd),
+    roa_start: roaStart,
+    roa_end: roaEnd,
+    roa_change: change(roaStart, roaEnd),
+    roe_start: roeStart,
+    roe_end: roeEnd,
+    roe_change: change(roeStart, roeEnd),
+    offices_start: officesStart,
+    offices_end: officesEnd,
+    offices_change: change(officesStart, officesEnd),
+    assets_per_office_start: assetsPerOfficeStart,
+    assets_per_office_end: assetsPerOfficeEnd,
+    assets_per_office_change: change(assetsPerOfficeStart, assetsPerOfficeEnd),
+    deposits_per_office_start: depositsPerOfficeStart,
+    deposits_per_office_end: depositsPerOfficeEnd,
+    deposits_per_office_change: change(
+      depositsPerOfficeStart,
+      depositsPerOfficeEnd
+    ),
+    deposits_to_assets_start: depositsToAssetsStart,
+    deposits_to_assets_end: depositsToAssetsEnd,
+    deposits_to_assets_change: change(
+      depositsToAssetsStart,
+      depositsToAssetsEnd
+    ),
+    cbsa_start: startDemo?.CBSANAME,
+    cbsa_end: endDemo?.CBSANAME
+  };
+  comparison.insights = classifyInsights(comparison);
+  return comparison;
+}
+function registerAnalysisTools(server) {
+  server.registerTool(
+    "fdic_compare_bank_snapshots",
+    {
+      title: "Compare Bank Snapshot Trends",
+      description: `Compare FDIC reporting snapshots across a set of institutions and rank the results by growth, profitability, or efficiency changes.
+
+This tool is designed for heavier analytical prompts that would otherwise require many separate MCP calls. It batches institution roster lookup, financial snapshots, optional office-count snapshots, and can also fetch a quarterly time series inside the server.
+
+Good uses:
+  - Identify North Carolina banks with the strongest asset growth from 2021 to 2025
+  - Compare whether deposit growth came with branch expansion or profitability improvement
+  - Rank a specific cert list by ROA, ROE, asset-per-office, or deposit-to-asset changes
+  - Pull a quarterly trend series and highlight inflection points, streaks, and structural shifts
+
+Inputs:
+  - state or certs: choose a geographic roster or provide a direct comparison set
+  - start_repdte, end_repdte: report dates in YYYYMMDD format
+  - analysis_mode: snapshot or timeseries
+  - institution_filters: optional extra institution filter when building the roster
+  - active_only: default true
+  - include_demographics: default true, adds office-count comparisons when available
+  - sort_by: ranking field such as asset_growth, dep_growth_pct, roa_change, assets_per_office_change
+  - sort_order: ASC or DESC
+  - limit: maximum ranked results to return
+
+Returns concise comparison text plus structured deltas, derived metrics, and insight tags for each institution.`,
+      inputSchema: SnapshotAnalysisSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({
+      state,
+      certs,
+      institution_filters,
+      active_only,
+      start_repdte,
+      end_repdte,
+      analysis_mode,
+      include_demographics,
+      limit,
+      sort_by,
+      sort_order
+    }) => {
+      try {
+        const roster = certs && certs.length > 0 ? certs.map((cert) => ({ CERT: cert })) : await fetchInstitutionRoster(
+          state,
+          institution_filters,
+          active_only
+        );
+        const candidateCerts = roster.map((record) => asNumber(record.CERT)).filter((cert) => cert !== null);
+        if (candidateCerts.length === 0) {
+          const output2 = {
+            total_candidates: 0,
+            analyzed_count: 0,
+            start_repdte,
+            end_repdte,
+            analysis_mode,
+            sort_by,
+            sort_order,
+            comparisons: []
+          };
+          return {
+            content: [
+              { type: "text", text: "No institutions matched the comparison set." }
+            ],
+            structuredContent: output2
+          };
+        }
+        const rosterByCert = new Map(
+          roster.map((record) => [asNumber(record.CERT), record]).filter(
+            (entry) => entry[0] !== null
+          )
+        );
+        let comparisons = [];
+        if (analysis_mode === "timeseries") {
+          const [financialSeries, demographicsSeries] = await Promise.all([
+            fetchSeriesRecords(
+              ENDPOINTS.FINANCIALS,
+              candidateCerts,
+              start_repdte,
+              end_repdte,
+              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE"
+            ),
+            include_demographics ? fetchSeriesRecords(
+              ENDPOINTS.DEMOGRAPHICS,
+              candidateCerts,
+              start_repdte,
+              end_repdte,
+              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME"
+            ) : Promise.resolve(/* @__PURE__ */ new Map())
+          ]);
+          comparisons = candidateCerts.map(
+            (cert) => summarizeTimeSeries(
+              financialSeries.get(cert) ?? [],
+              new Map(
+                (demographicsSeries.get(cert) ?? []).map((record) => [
+                  String(record.REPDTE),
+                  record
+                ])
+              ),
+              rosterByCert.get(cert) ?? {}
+            )
+          ).filter((comparison) => comparison !== null);
+        } else {
+          const [financialSnapshots, demographicSnapshots] = await Promise.all([
+            fetchBatchedRecordsForDates(
+              ENDPOINTS.FINANCIALS,
+              candidateCerts,
+              [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
+              "CERT,NAME,REPDTE,ASSET,DEP,NETINC,ROA,ROE"
+            ),
+            include_demographics ? fetchBatchedRecordsForDates(
+              ENDPOINTS.DEMOGRAPHICS,
+              candidateCerts,
+              [`REPDTE:${start_repdte}`, `REPDTE:${end_repdte}`],
+              "CERT,REPDTE,OFFTOT,OFFSTATE,CBSANAME"
+            ) : Promise.resolve(/* @__PURE__ */ new Map())
+          ]);
+          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();
+          const endDemographics = demographicSnapshots.get(`REPDTE:${end_repdte}`) ?? /* @__PURE__ */ new Map();
+          comparisons = candidateCerts.map((cert) => {
+            const startFinancial = startFinancials.get(cert);
+            const endFinancial = endFinancials.get(cert);
+            if (!startFinancial || !endFinancial) return null;
+            return buildSnapshotComparison(
+              cert,
+              rosterByCert.get(cert) ?? {},
+              startFinancial,
+              endFinancial,
+              startDemographics.get(cert),
+              endDemographics.get(cert),
+              start_repdte,
+              end_repdte
+            );
+          }).filter((comparison) => comparison !== null);
+        }
+        const ranked = sortComparisons(comparisons, sort_by, sort_order).slice(
+          0,
+          limit
+        );
+        const pagination = buildPaginationInfo(comparisons.length, 0, ranked.length);
+        const output = {
+          total_candidates: candidateCerts.length,
+          analyzed_count: comparisons.length,
+          start_repdte,
+          end_repdte,
+          analysis_mode,
+          sort_by,
+          sort_order,
+          insights: buildTopLevelInsights(comparisons),
+          ...pagination,
+          comparisons: ranked
+        };
+        const text = truncateIfNeeded(
+          formatComparisonText(output),
           CHARACTER_LIMIT
         );
         return {
@@ -927,6 +1707,7 @@ function createServer() {
   registerFinancialTools(server);
   registerSodTools(server);
   registerDemographicsTools(server);
+  registerAnalysisTools(server);
   return server;
 }
 async function runStdio() {