fdic-mcp-server 1.7.6 → 1.8.1

package/README.md

@@ -32,6 +32,8 @@ The FDIC BankFind Suite API is public and useful, but it is not packaged for MCP
 
 ## Documentation
 
+Public user docs:
+
 - [GitHub Pages docs entry point](https://jflamb.github.io/fdic-mcp-server/)
 - [Hosted MCP endpoint](https://bankfind.jflamb.com/mcp)
 - [Local docs home](./docs/index.md)
@@ -42,9 +44,18 @@ The FDIC BankFind Suite API is public and useful, but it is not packaged for MCP
 - [Client setup](./docs/clients.md)
 - [Troubleshooting and FAQ](./docs/troubleshooting.md)
 - [Compatibility matrix](./docs/compatibility-matrix.md)
-- [Technical specification](./docs/technical/specification.md)
-- [Architecture](./docs/technical/architecture.md)
-- [Key decisions](./docs/technical/decisions.md)
+
+Repo reference docs:
+
+- [Reference home](./reference/README.md)
+- [Technical specification](./reference/specification.md)
+- [Architecture](./reference/architecture.md)
+- [Key decisions](./reference/decisions.md)
+- [Cloud Run deployment](./reference/cloud-run-deployment.md)
+- [Plans and design notes](./reference/plans/README.md)
+
+Project and release info:
+
 - [Release history](https://github.com/jflamb/fdic-mcp-server/releases)
 - [Archived release notes](./docs/release-notes/index.md)
 - [Security policy](./SECURITY.md)

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.7.6" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.8.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 DEFAULT_FDIC_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -31850,10 +31850,10 @@ function formatToolError(err) {
 var import_zod = require("zod");
 var CommonQuerySchema = import_zod.z.object({
   filters: import_zod.z.string().optional().describe(
-    'ElasticSearch query string filter. Examples: STNAME:"California", ACTIVE:1 AND ASSET:[1000000 TO *], NAME:"Chase"'
+    'FDIC API filter using ElasticSearch query string syntax. Combine conditions with AND/OR, use quotes for multi-word values, and [min TO max] for ranges (* = unbounded). Common fields: NAME (institution name), STNAME (state name), STALP (two-letter state code), CERT (certificate number), ASSET (total assets in $thousands), ACTIVE (1=active, 0=inactive). Examples: STNAME:"California", ACTIVE:1 AND ASSET:[1000000 TO *], NAME:"Chase"'
   ),
   fields: import_zod.z.string().optional().describe(
-    "Comma-separated list of fields to return. Leave empty to return all fields. Example: NAME,CERT,ASSET,DEP,STALP"
+    "Comma-separated list of FDIC field names to return. Leave empty to return all fields. Field names are ALL_CAPS (e.g., NAME, CERT, ASSET, DEP, STALP). Example: NAME,CERT,ASSET,DEP,STALP"
   ),
   limit: import_zod.z.number().int().min(1).max(1e4).default(20).describe("Maximum number of records to return (1-10000, default: 20)"),
   offset: import_zod.z.number().int().min(0).default(0).describe("Number of records to skip for pagination (default: 0)"),
@@ -31889,18 +31889,26 @@ Common filter examples:
   - Savings institutions: MUTUAL:1
   - Recently established: ESTYMD:[2010-01-01 TO *]
 
+Charter class codes (BKCLASS):
+  N = National commercial bank (OCC-supervised)
+  SM = State-chartered, Federal Reserve member
+  NM = State-chartered, non-member (FDIC-supervised)
+  SB = Federal savings bank (OCC-supervised)
+  SA = State savings association
+  OI = Insured branch of foreign bank
+
 Key returned fields:
   - CERT: FDIC Certificate Number (unique ID)
   - NAME: Institution name
-  - CITY, STALP, STNAME: Location
+  - CITY, STALP (two-letter state code), STNAME (full state name): Location
   - ASSET: Total assets ($thousands)
   - DEP: Total deposits ($thousands)
-  - BKCLASS: Charter class code
+  - BKCLASS: Charter class code (see above)
   - ACTIVE: 1 if currently active, 0 if inactive
   - ROA, ROE: Profitability ratios
   - OFFICES: Number of branch offices
-  - ESTYMD: Establishment date
-  - REGAGNT: Primary federal regulator
+  - ESTYMD: Establishment date (YYYY-MM-DD)
+  - REGAGNT: Primary federal regulator (OCC, FRS, FDIC)
 
 Args:
   - filters (string, optional): ElasticSearch query filter
@@ -32023,22 +32031,27 @@ function registerFailureTools(server) {
 Returns data on bank failures including failure date, resolution type, estimated cost to the FDIC Deposit Insurance Fund, and acquiring institution info.
 
 Common filter examples:
-  - By state: STALP:CA
+  - By state: STALP:CA (two-letter state code)
   - By year range: FAILDATE:[2008-01-01 TO 2010-12-31]
   - Recent failures: FAILDATE:[2020-01-01 TO *]
-  - By resolution type: RESTYPE:PAYOFF or RESTYPE:MERGER
+  - By resolution type: RESTYPE:PAYOFF or RESTYPE:"PURCHASE AND ASSUMPTION"
   - Large failures by cost: COST:[100000 TO *]  (cost in $thousands)
   - By name: NAME:"Washington Mutual"
 
+Resolution types (RESTYPE):
+  PAYOFF = depositors paid directly, no acquirer
+  PURCHASE AND ASSUMPTION = acquirer buys assets and assumes deposits
+  PAYOUT = variant of payoff with insured-deposit transfer
+
 Key returned fields:
   - CERT: FDIC Certificate Number
   - NAME: Institution name
-  - CITY, STALP, STNAME: Location
+  - CITY, STALP (two-letter state code), STNAME (full state name): Location
   - FAILDATE: Date of failure (YYYY-MM-DD)
-  - SAVR: Savings rate at failure
-  - RESTYPE: Resolution type (PAYOFF, MERGER, PURCHASE & ASSUMPTION, etc.)
+  - SAVR: Savings association flag (SA) or bank (BK)
+  - RESTYPE: Resolution type (see above)
   - QBFASSET: Total assets at failure ($thousands)
-  - COST: Estimated cost to FDIC DIF ($thousands)
+  - COST: Estimated cost to FDIC Deposit Insurance Fund ($thousands)
 
 Args:
   - filters (string, optional): ElasticSearch query filter
@@ -32158,6 +32171,27 @@ var import_zod2 = require("zod");
 var CHUNK_SIZE = 25;
 var MAX_CONCURRENCY = 4;
 var ANALYSIS_TIMEOUT_MS = 9e4;
+function getDefaultReportDate() {
+  const target = new Date(Date.now() - 90 * 24 * 60 * 60 * 1e3);
+  const year = target.getFullYear();
+  const month = target.getMonth() + 1;
+  if (month >= 10) return `${year}0930`;
+  if (month >= 7) return `${year}0630`;
+  if (month >= 4) return `${year}0331`;
+  return `${year - 1}1231`;
+}
+function getReportDateOneYearPrior(repdte) {
+  const year = Number.parseInt(repdte.slice(0, 4), 10);
+  return `${year - 1}${repdte.slice(4)}`;
+}
+var VALID_QUARTER_END_SUFFIXES = /* @__PURE__ */ new Set(["0331", "0630", "0930", "1231"]);
+function validateQuarterEndDate(repdte, label) {
+  const suffix = repdte.slice(4);
+  if (!VALID_QUARTER_END_SUFFIXES.has(suffix)) {
+    return `${label} "${repdte}" is not a valid quarter-end date. FDIC data is published quarterly \u2014 use a date ending in 0331 (Q1), 0630 (Q2), 0930 (Q3), or 1231 (Q4). Example: ${repdte.slice(0, 4)}1231 for Q4 ${repdte.slice(0, 4)}.`;
+  }
+  return null;
+}
 function asNumber(value) {
   return typeof value === "number" ? value : null;
 }
@@ -32226,23 +32260,34 @@ Returns branch/office data including address, city, state, coordinates, branch t
 
 Common filter examples:
   - All branches of a bank: CERT:3511
-  - By state: STALP:TX
+  - By state: STALP:TX (two-letter state code)
   - By city: CITY:"Austin"
   - Main offices only: BRNUM:0
   - By county: COUNTY:"Travis"
-  - Active branches: ENDEFYMD:[9999-01-01 TO *]
-  - By CBSA (metro area): CBSA_METRO_NAME:"New York-Newark-Jersey City"
+  - Active branches only: ENDEFYMD:[9999-01-01 TO *]  (sentinel date 9999-12-31 means still open)
+  - By metro area (CBSA): CBSA_METRO_NAME:"New York-Newark-Jersey City"
+
+Branch service types (BRSERTYP):
+  11 = Full service brick and mortar
+  12 = Full service retail
+  21 = Limited service administrative
+  22 = Limited service military
+  23 = Limited service drive-through
+  24 = Limited service loan production
+  25 = Limited service consumer/trust
+  26 = Limited service Internet/mobile
+  29 = Limited service other
 
 Key returned fields:
   - CERT: FDIC Certificate Number
   - UNINAME: Institution name
   - NAMEFULL: Full branch name
-  - ADDRESS, CITY, STALP, ZIP: Branch address
+  - ADDRESS, CITY, STALP (two-letter state code), ZIP: Branch address
   - COUNTY: County name
   - BRNUM: Branch number (0 = main office)
-  - BRSERTYP: Branch service type
+  - BRSERTYP: Branch service type code (see above)
   - LATITUDE, LONGITUDE: Geographic coordinates
-  - ESTYMD: Branch established date
+  - ESTYMD: Branch established date (YYYY-MM-DD)
   - ENDEFYMD: Branch end date (9999-12-31 if still active)
 
 Args:
@@ -32323,22 +32368,36 @@ Common filter examples:
   - History for a specific bank: CERT:3511
   - Mergers: TYPE:merger
   - Failures: TYPE:failure
-  - Name changes: CHANGECODE:CO (name change code)
+  - Name changes: CHANGECODE:CO
   - By date range: PROCDATE:[2008-01-01 TO 2009-12-31]
-  - By state: PSTALP:CA
+  - By state: PSTALP:CA (two-letter state code)
+
+Event types (TYPE):
+  merger = institution was merged into another
+  failure = institution failed
+  assistance = received FDIC assistance transaction
+  insurance = insurance-related event (new coverage, termination)
+
+Common change codes (CHANGECODE):
+  CO = name change
+  CR = charter conversion
+  DC = deposit assumption change
+  MA = merger/acquisition (absorbed by another institution)
+  NI = new institution insured
+  TC = trust company conversion
 
 Key returned fields:
   - CERT: FDIC Certificate Number
   - INSTNAME: Institution name
   - CLASS: Charter class at time of change
-  - PCITY, PSTALP: Location (city, state abbreviation)
-  - PROCDATE: Processing date of the change
-  - EFFDATE: Effective date of the change
+  - PCITY, PSTALP: Location (city, two-letter state code)
+  - PROCDATE: Processing date of the change (YYYY-MM-DD)
+  - EFFDATE: Effective date of the change (YYYY-MM-DD)
   - ENDEFYMD: End effective date
   - PCERT: Predecessor/successor CERT (for mergers)
-  - TYPE: Type of structural change
-  - CHANGECODE: Code for type of change
-  - CHANGECODE_DESC: Description of change code
+  - TYPE: Type of structural change (see above)
+  - CHANGECODE: Code for type of change (see above)
+  - CHANGECODE_DESC: Human-readable description of the change code
   - INSDATE: Insurance date
 
 Args:
@@ -32409,7 +32468,7 @@ var FinancialQuerySchema = CommonQuerySchema.extend({
     "Filter by FDIC Certificate Number to get financials for a specific institution"
   ),
   repdte: import_zod4.z.string().optional().describe(
-    "Filter by report date in YYYYMMDD format (quarterly call report dates). Example: 20231231 for Q4 2023"
+    "Filter by Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on call report dates: March 31, June 30, September 30, and December 31. Example: 20231231 for Q4 2023. If omitted, returns all available dates (sorted most recent first by default)."
   )
 });
 var SummaryQuerySchema = CommonQuerySchema.extend({
@@ -32434,7 +32493,7 @@ Common filter examples:
 
 Key returned fields:
   - CERT: FDIC Certificate Number
-  - REPDTE: Report date (YYYYMMDD)
+  - REPDTE: Report Date \u2014 the last day of the quarterly reporting period (YYYYMMDD)
   - ASSET: Total assets ($thousands)
   - DEP: Total deposits ($thousands)
   - DEPDOM: Domestic deposits ($thousands)
@@ -32447,7 +32506,7 @@ Key returned fields:
 
 Args:
   - cert (number, optional): Filter by institution CERT number
-  - repdte (string, optional): Report date in YYYYMMDD format
+  - repdte (string, optional): Report Date in YYYYMMDD format (quarter-end dates: 0331, 0630, 0930, 1231)
   - filters (string, optional): Additional ElasticSearch query filters
   - fields (string, optional): Comma-separated field names (the full set has 1,100+ fields)
   - limit (number): Records to return (default: 20)
@@ -32527,7 +32586,7 @@ Key returned fields:
   - ROA: Return on assets (%)
   - ROE: Return on equity (%)
   - OFFICES: Number of branch offices
-  - REPDTE: Report date
+  - REPDTE: Report Date \u2014 the last day of the reporting period (YYYYMMDD)
 
 Args:
   - cert (number, optional): Filter by institution CERT number
@@ -32692,7 +32751,7 @@ var import_zod6 = require("zod");
 var DemographicsQuerySchema = CommonQuerySchema.extend({
   cert: import_zod6.z.number().int().positive().optional().describe("Filter by FDIC Certificate Number"),
   repdte: import_zod6.z.string().optional().describe(
-    "Filter by report date in YYYYMMDD format. Example: 20251231"
+    "Filter by Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on: March 31, June 30, September 30, and December 31. Example: 20251231 for Q4 2025. If omitted, returns all available dates."
   )
 });
 function registerDemographicsTools(server) {
@@ -32713,7 +32772,7 @@ Common filter examples:
 
 Key returned fields:
   - CERT: FDIC Certificate Number
-  - REPDTE: Report date (YYYYMMDD)
+  - REPDTE: Report Date \u2014 the last day of the quarterly reporting period (YYYYMMDD)
   - QTRNO: Quarter number
   - OFFTOT: Total offices
   - OFFSTATE: Offices in other states
@@ -32727,7 +32786,7 @@ Key returned fields:
 
 Args:
   - cert (number, optional): Filter by institution CERT number
-  - repdte (string, optional): Report date in YYYYMMDD format
+  - repdte (string, optional): Report Date in YYYYMMDD format (quarter-end dates: 0331, 0630, 0930, 1231)
   - filters (string, optional): Additional ElasticSearch query filters
   - fields (string, optional): Comma-separated field names
   - limit (number): Records to return (default: 20)
@@ -32838,8 +32897,12 @@ var SnapshotAnalysisSchema = import_zod7.z.object({
     '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."),
+  start_repdte: import_zod7.z.string().regex(/^\d{8}$/).optional().describe(
+    "Starting Report Date (REPDTE) in YYYYMMDD format. Must be a quarter-end date: March 31 (0331), June 30 (0630), September 30 (0930), or December 31 (1231). Example: 20210331 for Q1 2021. If omitted, defaults to the same quarter one year before end_repdte."
+  ),
+  end_repdte: import_zod7.z.string().regex(/^\d{8}$/).optional().describe(
+    "Ending Report Date (REPDTE) in YYYYMMDD format. Must be a quarter-end date: March 31 (0331), June 30 (0630), September 30 (0930), or December 31 (1231). Must be later than start_repdte. Example: 20251231 for Q4 2025. If omitted, defaults to the most recent quarter-end date with published data (~90-day lag)."
+  ),
   analysis_mode: AnalysisModeSchema.default("snapshot").describe(
     "Use snapshot for two-point comparison or timeseries for quarterly trend analysis across the date range."
   ),
@@ -32848,14 +32911,23 @@ var SnapshotAnalysisSchema = import_zod7.z.object({
   ),
   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."
+    "Comparison field used to rank institutions. Valid options: 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."
   ),
   sort_order: import_zod7.z.enum(["ASC", "DESC"]).default("DESC").describe("Sort direction for the ranked comparisons.")
 });
+function resolveSnapshotDefaults(params) {
+  const end_repdte = params.end_repdte ?? getDefaultReportDate();
+  const start_repdte = params.start_repdte ?? getReportDateOneYearPrior(end_repdte);
+  return { ...params, start_repdte, end_repdte };
+}
 function validateSnapshotAnalysisParams(value) {
   if (!value.state && (!value.certs || value.certs.length === 0)) {
     return "Provide either state or certs.";
   }
+  const startDateError = validateQuarterEndDate(value.start_repdte, "start_repdte");
+  if (startDateError) return startDateError;
+  const endDateError = validateQuarterEndDate(value.end_repdte, "end_repdte");
+  if (endDateError) return endDateError;
   if (value.start_repdte >= value.end_repdte) {
     return "start_repdte must be earlier than end_repdte.";
   }
@@ -33381,12 +33453,12 @@ Good uses:
 
 Inputs:
   - state or certs: choose a geographic roster or provide a direct comparison set
-  - start_repdte, end_repdte: report dates in YYYYMMDD format
+  - start_repdte, end_repdte: Report Dates (REPDTE) in YYYYMMDD format \u2014 must be quarter-end dates (0331, 0630, 0930, 1231)
   - 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_by: ranking field (default: asset_growth). All options: 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
   - sort_order: ASC or DESC
   - limit: maximum ranked results to return
 
@@ -33399,19 +33471,20 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
         openWorldHint: true
       }
     },
-    async ({
-      state,
-      certs,
-      institution_filters,
-      active_only,
-      start_repdte,
-      end_repdte,
-      analysis_mode,
-      include_demographics,
-      limit,
-      sort_by,
-      sort_order
-    }, extra) => {
+    async (rawParams, extra) => {
+      const {
+        state,
+        certs,
+        institution_filters,
+        active_only,
+        start_repdte,
+        end_repdte,
+        analysis_mode,
+        include_demographics,
+        limit,
+        sort_by,
+        sort_order
+      } = resolveSnapshotDefaults(rawParams);
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       const progressToken = extra._meta?.progressToken;
@@ -33631,7 +33704,7 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
         if (controller.signal.aborted) {
           return formatToolError(
             new Error(
-              `Analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Narrow the comparison set with certs or institution_filters and try again.`
+              `Analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Try reducing the comparison set: use certs (max 100) instead of a state-wide roster, add institution_filters (e.g., BKCLASS:N), or shorten the date range for timeseries mode.`
             )
           );
         }
@@ -33792,7 +33865,9 @@ 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."),
+  repdte: import_zod8.z.string().regex(/^\d{8}$/).optional().describe(
+    "Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on: March 31, June 30, September 30, and December 31. Example: 20231231 for Q4 2023. If omitted, defaults to the most recent quarter-end date likely to have published data (~90-day lag)."
+  ),
   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."
   ),
@@ -33948,7 +34023,8 @@ Override precedence: cert derives defaults, then explicit params override them.`
         openWorldHint: true
       }
     },
-    async (params, extra) => {
+    async (rawParams, extra) => {
+      const params = { ...rawParams, repdte: rawParams.repdte ?? getDefaultReportDate() };
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       const progressToken = extra._meta?.progressToken;
@@ -33957,6 +34033,10 @@ Override precedence: cert derives defaults, then explicit params override them.`
         if (validationError) {
           return formatToolError(new Error(validationError));
         }
+        const dateError = validateQuarterEndDate(params.repdte, "repdte");
+        if (dateError) {
+          return formatToolError(new Error(dateError));
+        }
         const extraFieldsError = validateExtraFields(params.extra_fields);
         if (extraFieldsError) {
           return formatToolError(extraFieldsError);
@@ -34004,7 +34084,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
           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.`
+                `No financial data for CERT ${params.cert} at report date ${params.repdte}. FDIC quarterly data is published ~90 days after each quarter-end (March 31, June 30, September 30, December 31). Try an earlier quarter-end date, or verify the institution was active at that date.`
               )
             );
           }
@@ -34259,7 +34339,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
         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.`
+              `Peer group analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Try narrowing the peer group: add a state filter, tighten the asset_min/asset_max range, or specify charter_classes.`
             )
           );
         }

package/dist/server.js

@@ -46,7 +46,7 @@ var import_types = require("@modelcontextprotocol/sdk/types.js");
 var import_express2 = __toESM(require("express"));
 
 // src/constants.ts
-var VERSION = true ? "1.7.6" : process.env.npm_package_version ?? "0.0.0-dev";
+var VERSION = true ? "1.8.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 DEFAULT_FDIC_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -31864,10 +31864,10 @@ function formatToolError(err) {
 var import_zod = require("zod");
 var CommonQuerySchema = import_zod.z.object({
   filters: import_zod.z.string().optional().describe(
-    'ElasticSearch query string filter. Examples: STNAME:"California", ACTIVE:1 AND ASSET:[1000000 TO *], NAME:"Chase"'
+    'FDIC API filter using ElasticSearch query string syntax. Combine conditions with AND/OR, use quotes for multi-word values, and [min TO max] for ranges (* = unbounded). Common fields: NAME (institution name), STNAME (state name), STALP (two-letter state code), CERT (certificate number), ASSET (total assets in $thousands), ACTIVE (1=active, 0=inactive). Examples: STNAME:"California", ACTIVE:1 AND ASSET:[1000000 TO *], NAME:"Chase"'
   ),
   fields: import_zod.z.string().optional().describe(
-    "Comma-separated list of fields to return. Leave empty to return all fields. Example: NAME,CERT,ASSET,DEP,STALP"
+    "Comma-separated list of FDIC field names to return. Leave empty to return all fields. Field names are ALL_CAPS (e.g., NAME, CERT, ASSET, DEP, STALP). Example: NAME,CERT,ASSET,DEP,STALP"
   ),
   limit: import_zod.z.number().int().min(1).max(1e4).default(20).describe("Maximum number of records to return (1-10000, default: 20)"),
   offset: import_zod.z.number().int().min(0).default(0).describe("Number of records to skip for pagination (default: 0)"),
@@ -31903,18 +31903,26 @@ Common filter examples:
   - Savings institutions: MUTUAL:1
   - Recently established: ESTYMD:[2010-01-01 TO *]
 
+Charter class codes (BKCLASS):
+  N = National commercial bank (OCC-supervised)
+  SM = State-chartered, Federal Reserve member
+  NM = State-chartered, non-member (FDIC-supervised)
+  SB = Federal savings bank (OCC-supervised)
+  SA = State savings association
+  OI = Insured branch of foreign bank
+
 Key returned fields:
   - CERT: FDIC Certificate Number (unique ID)
   - NAME: Institution name
-  - CITY, STALP, STNAME: Location
+  - CITY, STALP (two-letter state code), STNAME (full state name): Location
   - ASSET: Total assets ($thousands)
   - DEP: Total deposits ($thousands)
-  - BKCLASS: Charter class code
+  - BKCLASS: Charter class code (see above)
   - ACTIVE: 1 if currently active, 0 if inactive
   - ROA, ROE: Profitability ratios
   - OFFICES: Number of branch offices
-  - ESTYMD: Establishment date
-  - REGAGNT: Primary federal regulator
+  - ESTYMD: Establishment date (YYYY-MM-DD)
+  - REGAGNT: Primary federal regulator (OCC, FRS, FDIC)
 
 Args:
   - filters (string, optional): ElasticSearch query filter
@@ -32037,22 +32045,27 @@ function registerFailureTools(server) {
 Returns data on bank failures including failure date, resolution type, estimated cost to the FDIC Deposit Insurance Fund, and acquiring institution info.
 
 Common filter examples:
-  - By state: STALP:CA
+  - By state: STALP:CA (two-letter state code)
   - By year range: FAILDATE:[2008-01-01 TO 2010-12-31]
   - Recent failures: FAILDATE:[2020-01-01 TO *]
-  - By resolution type: RESTYPE:PAYOFF or RESTYPE:MERGER
+  - By resolution type: RESTYPE:PAYOFF or RESTYPE:"PURCHASE AND ASSUMPTION"
   - Large failures by cost: COST:[100000 TO *]  (cost in $thousands)
   - By name: NAME:"Washington Mutual"
 
+Resolution types (RESTYPE):
+  PAYOFF = depositors paid directly, no acquirer
+  PURCHASE AND ASSUMPTION = acquirer buys assets and assumes deposits
+  PAYOUT = variant of payoff with insured-deposit transfer
+
 Key returned fields:
   - CERT: FDIC Certificate Number
   - NAME: Institution name
-  - CITY, STALP, STNAME: Location
+  - CITY, STALP (two-letter state code), STNAME (full state name): Location
   - FAILDATE: Date of failure (YYYY-MM-DD)
-  - SAVR: Savings rate at failure
-  - RESTYPE: Resolution type (PAYOFF, MERGER, PURCHASE & ASSUMPTION, etc.)
+  - SAVR: Savings association flag (SA) or bank (BK)
+  - RESTYPE: Resolution type (see above)
   - QBFASSET: Total assets at failure ($thousands)
-  - COST: Estimated cost to FDIC DIF ($thousands)
+  - COST: Estimated cost to FDIC Deposit Insurance Fund ($thousands)
 
 Args:
   - filters (string, optional): ElasticSearch query filter
@@ -32172,6 +32185,27 @@ var import_zod2 = require("zod");
 var CHUNK_SIZE = 25;
 var MAX_CONCURRENCY = 4;
 var ANALYSIS_TIMEOUT_MS = 9e4;
+function getDefaultReportDate() {
+  const target = new Date(Date.now() - 90 * 24 * 60 * 60 * 1e3);
+  const year = target.getFullYear();
+  const month = target.getMonth() + 1;
+  if (month >= 10) return `${year}0930`;
+  if (month >= 7) return `${year}0630`;
+  if (month >= 4) return `${year}0331`;
+  return `${year - 1}1231`;
+}
+function getReportDateOneYearPrior(repdte) {
+  const year = Number.parseInt(repdte.slice(0, 4), 10);
+  return `${year - 1}${repdte.slice(4)}`;
+}
+var VALID_QUARTER_END_SUFFIXES = /* @__PURE__ */ new Set(["0331", "0630", "0930", "1231"]);
+function validateQuarterEndDate(repdte, label) {
+  const suffix = repdte.slice(4);
+  if (!VALID_QUARTER_END_SUFFIXES.has(suffix)) {
+    return `${label} "${repdte}" is not a valid quarter-end date. FDIC data is published quarterly \u2014 use a date ending in 0331 (Q1), 0630 (Q2), 0930 (Q3), or 1231 (Q4). Example: ${repdte.slice(0, 4)}1231 for Q4 ${repdte.slice(0, 4)}.`;
+  }
+  return null;
+}
 function asNumber(value) {
   return typeof value === "number" ? value : null;
 }
@@ -32240,23 +32274,34 @@ Returns branch/office data including address, city, state, coordinates, branch t
 
 Common filter examples:
   - All branches of a bank: CERT:3511
-  - By state: STALP:TX
+  - By state: STALP:TX (two-letter state code)
   - By city: CITY:"Austin"
   - Main offices only: BRNUM:0
   - By county: COUNTY:"Travis"
-  - Active branches: ENDEFYMD:[9999-01-01 TO *]
-  - By CBSA (metro area): CBSA_METRO_NAME:"New York-Newark-Jersey City"
+  - Active branches only: ENDEFYMD:[9999-01-01 TO *]  (sentinel date 9999-12-31 means still open)
+  - By metro area (CBSA): CBSA_METRO_NAME:"New York-Newark-Jersey City"
+
+Branch service types (BRSERTYP):
+  11 = Full service brick and mortar
+  12 = Full service retail
+  21 = Limited service administrative
+  22 = Limited service military
+  23 = Limited service drive-through
+  24 = Limited service loan production
+  25 = Limited service consumer/trust
+  26 = Limited service Internet/mobile
+  29 = Limited service other
 
 Key returned fields:
   - CERT: FDIC Certificate Number
   - UNINAME: Institution name
   - NAMEFULL: Full branch name
-  - ADDRESS, CITY, STALP, ZIP: Branch address
+  - ADDRESS, CITY, STALP (two-letter state code), ZIP: Branch address
   - COUNTY: County name
   - BRNUM: Branch number (0 = main office)
-  - BRSERTYP: Branch service type
+  - BRSERTYP: Branch service type code (see above)
   - LATITUDE, LONGITUDE: Geographic coordinates
-  - ESTYMD: Branch established date
+  - ESTYMD: Branch established date (YYYY-MM-DD)
   - ENDEFYMD: Branch end date (9999-12-31 if still active)
 
 Args:
@@ -32337,22 +32382,36 @@ Common filter examples:
   - History for a specific bank: CERT:3511
   - Mergers: TYPE:merger
   - Failures: TYPE:failure
-  - Name changes: CHANGECODE:CO (name change code)
+  - Name changes: CHANGECODE:CO
   - By date range: PROCDATE:[2008-01-01 TO 2009-12-31]
-  - By state: PSTALP:CA
+  - By state: PSTALP:CA (two-letter state code)
+
+Event types (TYPE):
+  merger = institution was merged into another
+  failure = institution failed
+  assistance = received FDIC assistance transaction
+  insurance = insurance-related event (new coverage, termination)
+
+Common change codes (CHANGECODE):
+  CO = name change
+  CR = charter conversion
+  DC = deposit assumption change
+  MA = merger/acquisition (absorbed by another institution)
+  NI = new institution insured
+  TC = trust company conversion
 
 Key returned fields:
   - CERT: FDIC Certificate Number
   - INSTNAME: Institution name
   - CLASS: Charter class at time of change
-  - PCITY, PSTALP: Location (city, state abbreviation)
-  - PROCDATE: Processing date of the change
-  - EFFDATE: Effective date of the change
+  - PCITY, PSTALP: Location (city, two-letter state code)
+  - PROCDATE: Processing date of the change (YYYY-MM-DD)
+  - EFFDATE: Effective date of the change (YYYY-MM-DD)
   - ENDEFYMD: End effective date
   - PCERT: Predecessor/successor CERT (for mergers)
-  - TYPE: Type of structural change
-  - CHANGECODE: Code for type of change
-  - CHANGECODE_DESC: Description of change code
+  - TYPE: Type of structural change (see above)
+  - CHANGECODE: Code for type of change (see above)
+  - CHANGECODE_DESC: Human-readable description of the change code
   - INSDATE: Insurance date
 
 Args:
@@ -32423,7 +32482,7 @@ var FinancialQuerySchema = CommonQuerySchema.extend({
     "Filter by FDIC Certificate Number to get financials for a specific institution"
   ),
   repdte: import_zod4.z.string().optional().describe(
-    "Filter by report date in YYYYMMDD format (quarterly call report dates). Example: 20231231 for Q4 2023"
+    "Filter by Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on call report dates: March 31, June 30, September 30, and December 31. Example: 20231231 for Q4 2023. If omitted, returns all available dates (sorted most recent first by default)."
   )
 });
 var SummaryQuerySchema = CommonQuerySchema.extend({
@@ -32448,7 +32507,7 @@ Common filter examples:
 
 Key returned fields:
   - CERT: FDIC Certificate Number
-  - REPDTE: Report date (YYYYMMDD)
+  - REPDTE: Report Date \u2014 the last day of the quarterly reporting period (YYYYMMDD)
   - ASSET: Total assets ($thousands)
   - DEP: Total deposits ($thousands)
   - DEPDOM: Domestic deposits ($thousands)
@@ -32461,7 +32520,7 @@ Key returned fields:
 
 Args:
   - cert (number, optional): Filter by institution CERT number
-  - repdte (string, optional): Report date in YYYYMMDD format
+  - repdte (string, optional): Report Date in YYYYMMDD format (quarter-end dates: 0331, 0630, 0930, 1231)
   - filters (string, optional): Additional ElasticSearch query filters
   - fields (string, optional): Comma-separated field names (the full set has 1,100+ fields)
   - limit (number): Records to return (default: 20)
@@ -32541,7 +32600,7 @@ Key returned fields:
   - ROA: Return on assets (%)
   - ROE: Return on equity (%)
   - OFFICES: Number of branch offices
-  - REPDTE: Report date
+  - REPDTE: Report Date \u2014 the last day of the reporting period (YYYYMMDD)
 
 Args:
   - cert (number, optional): Filter by institution CERT number
@@ -32706,7 +32765,7 @@ var import_zod6 = require("zod");
 var DemographicsQuerySchema = CommonQuerySchema.extend({
   cert: import_zod6.z.number().int().positive().optional().describe("Filter by FDIC Certificate Number"),
   repdte: import_zod6.z.string().optional().describe(
-    "Filter by report date in YYYYMMDD format. Example: 20251231"
+    "Filter by Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on: March 31, June 30, September 30, and December 31. Example: 20251231 for Q4 2025. If omitted, returns all available dates."
   )
 });
 function registerDemographicsTools(server) {
@@ -32727,7 +32786,7 @@ Common filter examples:
 
 Key returned fields:
   - CERT: FDIC Certificate Number
-  - REPDTE: Report date (YYYYMMDD)
+  - REPDTE: Report Date \u2014 the last day of the quarterly reporting period (YYYYMMDD)
   - QTRNO: Quarter number
   - OFFTOT: Total offices
   - OFFSTATE: Offices in other states
@@ -32741,7 +32800,7 @@ Key returned fields:
 
 Args:
   - cert (number, optional): Filter by institution CERT number
-  - repdte (string, optional): Report date in YYYYMMDD format
+  - repdte (string, optional): Report Date in YYYYMMDD format (quarter-end dates: 0331, 0630, 0930, 1231)
   - filters (string, optional): Additional ElasticSearch query filters
   - fields (string, optional): Comma-separated field names
   - limit (number): Records to return (default: 20)
@@ -32852,8 +32911,12 @@ var SnapshotAnalysisSchema = import_zod7.z.object({
     '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."),
+  start_repdte: import_zod7.z.string().regex(/^\d{8}$/).optional().describe(
+    "Starting Report Date (REPDTE) in YYYYMMDD format. Must be a quarter-end date: March 31 (0331), June 30 (0630), September 30 (0930), or December 31 (1231). Example: 20210331 for Q1 2021. If omitted, defaults to the same quarter one year before end_repdte."
+  ),
+  end_repdte: import_zod7.z.string().regex(/^\d{8}$/).optional().describe(
+    "Ending Report Date (REPDTE) in YYYYMMDD format. Must be a quarter-end date: March 31 (0331), June 30 (0630), September 30 (0930), or December 31 (1231). Must be later than start_repdte. Example: 20251231 for Q4 2025. If omitted, defaults to the most recent quarter-end date with published data (~90-day lag)."
+  ),
   analysis_mode: AnalysisModeSchema.default("snapshot").describe(
     "Use snapshot for two-point comparison or timeseries for quarterly trend analysis across the date range."
   ),
@@ -32862,14 +32925,23 @@ var SnapshotAnalysisSchema = import_zod7.z.object({
   ),
   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."
+    "Comparison field used to rank institutions. Valid options: 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."
   ),
   sort_order: import_zod7.z.enum(["ASC", "DESC"]).default("DESC").describe("Sort direction for the ranked comparisons.")
 });
+function resolveSnapshotDefaults(params) {
+  const end_repdte = params.end_repdte ?? getDefaultReportDate();
+  const start_repdte = params.start_repdte ?? getReportDateOneYearPrior(end_repdte);
+  return { ...params, start_repdte, end_repdte };
+}
 function validateSnapshotAnalysisParams(value) {
   if (!value.state && (!value.certs || value.certs.length === 0)) {
     return "Provide either state or certs.";
   }
+  const startDateError = validateQuarterEndDate(value.start_repdte, "start_repdte");
+  if (startDateError) return startDateError;
+  const endDateError = validateQuarterEndDate(value.end_repdte, "end_repdte");
+  if (endDateError) return endDateError;
   if (value.start_repdte >= value.end_repdte) {
     return "start_repdte must be earlier than end_repdte.";
   }
@@ -33395,12 +33467,12 @@ Good uses:
 
 Inputs:
   - state or certs: choose a geographic roster or provide a direct comparison set
-  - start_repdte, end_repdte: report dates in YYYYMMDD format
+  - start_repdte, end_repdte: Report Dates (REPDTE) in YYYYMMDD format \u2014 must be quarter-end dates (0331, 0630, 0930, 1231)
   - 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_by: ranking field (default: asset_growth). All options: 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
   - sort_order: ASC or DESC
   - limit: maximum ranked results to return
 
@@ -33413,19 +33485,20 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
         openWorldHint: true
       }
     },
-    async ({
-      state,
-      certs,
-      institution_filters,
-      active_only,
-      start_repdte,
-      end_repdte,
-      analysis_mode,
-      include_demographics,
-      limit,
-      sort_by,
-      sort_order
-    }, extra) => {
+    async (rawParams, extra) => {
+      const {
+        state,
+        certs,
+        institution_filters,
+        active_only,
+        start_repdte,
+        end_repdte,
+        analysis_mode,
+        include_demographics,
+        limit,
+        sort_by,
+        sort_order
+      } = resolveSnapshotDefaults(rawParams);
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       const progressToken = extra._meta?.progressToken;
@@ -33645,7 +33718,7 @@ Returns concise comparison text plus structured deltas, derived metrics, and ins
         if (controller.signal.aborted) {
           return formatToolError(
             new Error(
-              `Analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Narrow the comparison set with certs or institution_filters and try again.`
+              `Analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Try reducing the comparison set: use certs (max 100) instead of a state-wide roster, add institution_filters (e.g., BKCLASS:N), or shorten the date range for timeseries mode.`
             )
           );
         }
@@ -33806,7 +33879,9 @@ 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."),
+  repdte: import_zod8.z.string().regex(/^\d{8}$/).optional().describe(
+    "Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on: March 31, June 30, September 30, and December 31. Example: 20231231 for Q4 2023. If omitted, defaults to the most recent quarter-end date likely to have published data (~90-day lag)."
+  ),
   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."
   ),
@@ -33962,7 +34037,8 @@ Override precedence: cert derives defaults, then explicit params override them.`
         openWorldHint: true
       }
     },
-    async (params, extra) => {
+    async (rawParams, extra) => {
+      const params = { ...rawParams, repdte: rawParams.repdte ?? getDefaultReportDate() };
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), ANALYSIS_TIMEOUT_MS);
       const progressToken = extra._meta?.progressToken;
@@ -33971,6 +34047,10 @@ Override precedence: cert derives defaults, then explicit params override them.`
         if (validationError) {
           return formatToolError(new Error(validationError));
         }
+        const dateError = validateQuarterEndDate(params.repdte, "repdte");
+        if (dateError) {
+          return formatToolError(new Error(dateError));
+        }
         const extraFieldsError = validateExtraFields(params.extra_fields);
         if (extraFieldsError) {
           return formatToolError(extraFieldsError);
@@ -34018,7 +34098,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
           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.`
+                `No financial data for CERT ${params.cert} at report date ${params.repdte}. FDIC quarterly data is published ~90 days after each quarter-end (March 31, June 30, September 30, December 31). Try an earlier quarter-end date, or verify the institution was active at that date.`
               )
             );
           }
@@ -34273,7 +34353,7 @@ Override precedence: cert derives defaults, then explicit params override them.`
         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.`
+              `Peer group analysis timed out after ${Math.floor(ANALYSIS_TIMEOUT_MS / 1e3)} seconds. Try narrowing the peer group: add a state filter, tighten the asset_min/asset_max range, or specify charter_classes.`
             )
           );
         }

package/package.json

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