fdic-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,1000 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+var import_express = __toESM(require("express"));
+
+// src/constants.ts
+var VERSION = "1.0.0";
+var FDIC_API_BASE_URL = "https://banks.data.fdic.gov/api";
+var CHARACTER_LIMIT = 5e4;
+var ENDPOINTS = {
+  INSTITUTIONS: "institutions",
+  FAILURES: "failures",
+  LOCATIONS: "locations",
+  HISTORY: "history",
+  SUMMARY: "summary",
+  FINANCIALS: "financials",
+  SOD: "sod",
+  DEMOGRAPHICS: "demographics"
+};
+
+// src/services/fdicClient.ts
+var import_axios = __toESM(require("axios"));
+var apiClient = import_axios.default.create({
+  baseURL: FDIC_API_BASE_URL,
+  timeout: 3e4,
+  headers: {
+    Accept: "application/json",
+    "User-Agent": `fdic-mcp-server/${VERSION}`
+  }
+});
+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}`);
+      }
+    }
+    throw new Error(`Unexpected error calling FDIC API: ${String(err)}`);
+  }
+}
+function extractRecords(response) {
+  return response.data.map((item) => item.data);
+}
+function buildPaginationInfo(total, offset, count) {
+  const has_more = total > offset + count;
+  return {
+    total,
+    offset,
+    count,
+    has_more,
+    ...has_more ? { next_offset: offset + count } : {}
+  };
+}
+function truncateIfNeeded(text, charLimit) {
+  if (text.length <= charLimit) return text;
+  return text.slice(0, charLimit) + `
+
+[Response truncated at ${charLimit} characters. Use limit/offset parameters to paginate or narrow your query with filters.]`;
+}
+function formatToolError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true
+  };
+}
+
+// src/schemas/common.ts
+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"'
+  ),
+  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"
+  ),
+  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)"),
+  sort_by: import_zod.z.string().optional().describe(
+    "Field name to sort results by. Example: ASSET, NAME, FAILDATE"
+  ),
+  sort_order: import_zod.z.enum(["ASC", "DESC"]).default("ASC").describe("Sort direction: ASC (ascending) or DESC (descending)")
+});
+var CertSchema = import_zod.z.object({
+  cert: import_zod.z.number().int().positive().describe(
+    "FDIC Certificate Number \u2014 the unique identifier for an institution"
+  ),
+  fields: import_zod.z.string().optional().describe("Comma-separated list of fields to return")
+});
+
+// src/tools/institutions.ts
+function registerInstitutionTools(server) {
+  server.registerTool(
+    "fdic_search_institutions",
+    {
+      title: "Search FDIC Institutions",
+      description: `Search for FDIC-insured financial institutions (banks and savings institutions) using flexible filters.
+
+Returns institution profile data including name, location, charter class, asset size, deposit totals, profitability metrics, and regulatory status.
+
+Common filter examples:
+  - By state: STNAME:"California"
+  - Active banks only: ACTIVE:1
+  - Large banks: ASSET:[10000000 TO *]  (assets in $thousands)
+  - By bank class: BKCLASS:N (national bank), BKCLASS:SM (state member bank), BKCLASS:NM (state non-member)
+  - By name: NAME:"Wells Fargo"
+  - Commercial banks: CB:1
+  - Savings institutions: MUTUAL:1
+  - Recently established: ESTYMD:[2010-01-01 TO *]
+
+Key returned fields:
+  - CERT: FDIC Certificate Number (unique ID)
+  - NAME: Institution name
+  - CITY, STALP, STNAME: Location
+  - ASSET: Total assets ($thousands)
+  - DEP: Total deposits ($thousands)
+  - BKCLASS: Charter class code
+  - ACTIVE: 1 if currently active, 0 if inactive
+  - ROA, ROE: Profitability ratios
+  - OFFICES: Number of branch offices
+  - ESTYMD: Establishment date
+  - REGAGNT: Primary federal regulator
+
+Args:
+  - filters (string, optional): ElasticSearch query filter
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return, 1-10000 (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: CommonQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const response = await queryEndpoint(ENDPOINTS.INSTITUTIONS, params);
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, institutions: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+  server.registerTool(
+    "fdic_get_institution",
+    {
+      title: "Get Institution by Certificate Number",
+      description: `Retrieve detailed information for a specific FDIC-insured institution using its FDIC Certificate Number (CERT).
+
+Use this when you know the exact CERT number for an institution. To find a CERT number, use fdic_search_institutions first.
+
+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.`,
+      inputSchema: CertSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ cert, fields }) => {
+      try {
+        const response = await queryEndpoint(ENDPOINTS.INSTITUTIONS, {
+          filters: `CERT:${cert}`,
+          fields,
+          limit: 1
+        });
+        const records = extractRecords(response);
+        if (records.length === 0) {
+          const output2 = {
+            found: false,
+            cert,
+            message: `No institution found with CERT number ${cert}.`
+          };
+          return {
+            content: [{ type: "text", text: output2.message }],
+            structuredContent: output2
+          };
+        }
+        const output = records[0];
+        const text = JSON.stringify(output, null, 2);
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/failures.ts
+function registerFailureTools(server) {
+  server.registerTool(
+    "fdic_search_failures",
+    {
+      title: "Search Bank Failures",
+      description: `Search for details on failed FDIC-insured financial institutions.
+
+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 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
+  - Large failures by cost: COST:[100000 TO *]  (cost in $thousands)
+  - By name: NAME:"Washington Mutual"
+
+Key returned fields:
+  - CERT: FDIC Certificate Number
+  - NAME: Institution name
+  - CITY, STALP, STNAME: Location
+  - FAILDATE: Date of failure (YYYY-MM-DD)
+  - SAVR: Savings rate at failure
+  - RESTYPE: Resolution type (PAYOFF, MERGER, PURCHASE & ASSUMPTION, etc.)
+  - QBFASSET: Total assets at failure ($thousands)
+  - COST: Estimated cost to FDIC DIF ($thousands)
+
+Args:
+  - filters (string, optional): ElasticSearch query filter
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: CommonQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const response = await queryEndpoint(ENDPOINTS.FAILURES, params);
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, failures: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+  server.registerTool(
+    "fdic_get_institution_failure",
+    {
+      title: "Get Failure Details by Certificate Number",
+      description: `Retrieve failure details for a specific institution by FDIC Certificate Number.
+
+Use this when you know the CERT of a failed institution to get its specific failure record.
+
+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.`,
+      inputSchema: CertSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ cert, fields }) => {
+      try {
+        const response = await queryEndpoint(ENDPOINTS.FAILURES, {
+          filters: `CERT:${cert}`,
+          fields,
+          limit: 1
+        });
+        const records = extractRecords(response);
+        if (records.length === 0) {
+          const output2 = {
+            found: false,
+            cert,
+            message: `No failure record found for CERT ${cert}. The institution may not have failed, or the CERT may be incorrect.`
+          };
+          return {
+            content: [{ type: "text", text: output2.message }],
+            structuredContent: output2
+          };
+        }
+        const output = records[0];
+        const text = JSON.stringify(output, null, 2);
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/locations.ts
+var import_zod2 = require("zod");
+var LocationQuerySchema = CommonQuerySchema.extend({
+  cert: import_zod2.z.number().int().positive().optional().describe(
+    "Filter by FDIC Certificate Number to get all branches of a specific institution"
+  )
+});
+function registerLocationTools(server) {
+  server.registerTool(
+    "fdic_search_locations",
+    {
+      title: "Search Institution Locations / Branches",
+      description: `Search for branch locations of FDIC-insured financial institutions.
+
+Returns branch/office data including address, city, state, coordinates, branch type, and establishment date.
+
+Common filter examples:
+  - All branches of a bank: CERT:3511
+  - By state: STALP:TX
+  - 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"
+
+Key returned fields:
+  - CERT: FDIC Certificate Number
+  - UNINAME: Institution name
+  - NAMEFULL: Full branch name
+  - ADDRESS, CITY, STALP, ZIP: Branch address
+  - COUNTY: County name
+  - BRNUM: Branch number (0 = main office)
+  - BRSERTYP: Branch service type
+  - LATITUDE, LONGITUDE: Geographic coordinates
+  - ESTYMD: Branch established date
+  - ENDEFYMD: Branch end date (9999-12-31 if still active)
+
+Args:
+  - cert (number, optional): Filter by institution CERT number
+  - filters (string, optional): Additional ElasticSearch query filters
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: LocationQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ cert, ...params }) => {
+      try {
+        let filters = params.filters ?? "";
+        if (cert !== void 0) {
+          filters = filters ? `CERT:${cert} AND (${filters})` : `CERT:${cert}`;
+        }
+        const response = await queryEndpoint(ENDPOINTS.LOCATIONS, {
+          ...params,
+          filters: filters || void 0
+        });
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, locations: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/history.ts
+var import_zod3 = require("zod");
+var HistoryQuerySchema = CommonQuerySchema.extend({
+  cert: import_zod3.z.number().int().positive().optional().describe(
+    "Filter by FDIC Certificate Number to get history for a specific institution"
+  )
+});
+function registerHistoryTools(server) {
+  server.registerTool(
+    "fdic_search_history",
+    {
+      title: "Search Institution History / Structure Changes",
+      description: `Search for structural change events for FDIC-insured financial institutions.
+
+Returns records on mergers, acquisitions, name changes, charter conversions, failures, and other significant structural events.
+
+Common filter examples:
+  - History for a specific bank: CERT:3511
+  - Mergers: TYPE:merger
+  - Failures: TYPE:failure
+  - Name changes: CHANGECODE:CO (name change code)
+  - By date range: PROCDATE:[2008-01-01 TO 2009-12-31]
+  - By state: PSTALP:CA
+
+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
+  - 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
+  - INSDATE: Insurance date
+
+Args:
+  - cert (number, optional): Filter by institution CERT number
+  - filters (string, optional): ElasticSearch query filters
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: HistoryQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ cert, ...params }) => {
+      try {
+        let filters = params.filters ?? "";
+        if (cert !== void 0) {
+          filters = filters ? `CERT:${cert} AND (${filters})` : `CERT:${cert}`;
+        }
+        const response = await queryEndpoint(ENDPOINTS.HISTORY, {
+          ...params,
+          filters: filters || void 0
+        });
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, events: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/financials.ts
+var import_zod4 = require("zod");
+var FinancialQuerySchema = CommonQuerySchema.extend({
+  sort_order: import_zod4.z.enum(["ASC", "DESC"]).default("DESC").describe(
+    "Sort direction: DESC (descending, default for most recent first) or ASC (ascending)"
+  ),
+  cert: import_zod4.z.number().int().positive().optional().describe(
+    "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"
+  )
+});
+var SummaryQuerySchema = CommonQuerySchema.extend({
+  cert: import_zod4.z.number().int().positive().optional().describe("Filter by FDIC Certificate Number"),
+  year: import_zod4.z.number().int().min(1934).optional().describe("Filter by specific year (e.g., 2022)")
+});
+function registerFinancialTools(server) {
+  server.registerTool(
+    "fdic_search_financials",
+    {
+      title: "Search Institution Financial Data",
+      description: `Search quarterly financial (Call Report) data for FDIC-insured institutions. Covers over 1,100 financial variables reported quarterly.
+
+Returns balance sheet, income statement, capital, and performance ratio data from FDIC Call Reports.
+
+Common filter examples:
+  - Financials for a specific bank: CERT:3511
+  - By report date: REPDTE:20231231
+  - High-profit banks in Q4 2023: REPDTE:20231231 AND ROA:[1.5 TO *]
+  - Large banks most recent: ASSET:[10000000 TO *]
+  - Negative net income: NETINC:[* TO 0]
+
+Key returned fields:
+  - CERT: FDIC Certificate Number
+  - REPDTE: Report date (YYYYMMDD)
+  - ASSET: Total assets ($thousands)
+  - DEP: Total deposits ($thousands)
+  - DEPDOM: Domestic deposits ($thousands)
+  - INTINC: Total interest income ($thousands)
+  - EINTEXP: Total interest expense ($thousands)
+  - NETINC: Net income ($thousands)
+  - ROA: Return on assets (%)
+  - ROE: Return on equity (%)
+  - NETNIM: Net interest margin (%)
+
+Args:
+  - cert (number, optional): Filter by institution CERT number
+  - repdte (string, optional): Report date in YYYYMMDD format
+  - 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)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: FinancialQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ cert, repdte, ...params }) => {
+      try {
+        const filterParts = [];
+        if (params.filters) filterParts.push(`(${params.filters})`);
+        if (cert !== void 0) filterParts.push(`CERT:${cert}`);
+        if (repdte) filterParts.push(`REPDTE:${repdte}`);
+        const response = await queryEndpoint(ENDPOINTS.FINANCIALS, {
+          ...params,
+          filters: filterParts.length > 0 ? filterParts.join(" AND ") : void 0
+        });
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, financials: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+  server.registerTool(
+    "fdic_search_summary",
+    {
+      title: "Search Annual Financial Summary Data",
+      description: `Search aggregate financial and structure summary data subtotaled by year for FDIC-insured institutions.
+
+Returns annual snapshots of key financial metrics \u2014 useful for tracking an institution's growth over time.
+
+Common filter examples:
+  - Annual history for a bank: CERT:3511
+  - Specific year: YEAR:2022
+  - Year range: YEAR:[2010 TO 2020]
+  - Large banks in 2022: YEAR:2022 AND ASSET:[10000000 TO *]
+  - Profitable in 2023: YEAR:2023 AND ROE:[10 TO *]
+
+Key returned fields:
+  - CERT: FDIC Certificate Number
+  - YEAR: Report year
+  - ASSET: Total assets ($thousands)
+  - DEP: Total deposits ($thousands)
+  - NETINC: Net income ($thousands)
+  - ROA: Return on assets (%)
+  - ROE: Return on equity (%)
+  - OFFICES: Number of branch offices
+  - REPDTE: Report date
+
+Args:
+  - cert (number, optional): Filter by institution CERT number
+  - year (number, optional): Filter by specific year (1934-present)
+  - filters (string, optional): Additional ElasticSearch query filters
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: SummaryQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ cert, year, ...params }) => {
+      try {
+        const filterParts = [];
+        if (params.filters) filterParts.push(`(${params.filters})`);
+        if (cert !== void 0) filterParts.push(`CERT:${cert}`);
+        if (year !== void 0) filterParts.push(`YEAR:${year}`);
+        const response = await queryEndpoint(ENDPOINTS.SUMMARY, {
+          ...params,
+          filters: filterParts.length > 0 ? filterParts.join(" AND ") : void 0
+        });
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, summary: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/sod.ts
+var import_zod5 = require("zod");
+var SodQuerySchema = CommonQuerySchema.extend({
+  cert: import_zod5.z.number().int().positive().optional().describe("Filter by FDIC Certificate Number"),
+  year: import_zod5.z.number().int().min(1994).optional().describe(
+    "Filter by specific year (1994-present). SOD data is annual."
+  )
+});
+function registerSodTools(server) {
+  server.registerTool(
+    "fdic_search_sod",
+    {
+      title: "Search Summary of Deposits (SOD)",
+      description: `Search annual Summary of Deposits (SOD) data for individual bank branches.
+
+The SOD report provides annual deposit data at the branch level, showing deposit balances for each office of every FDIC-insured institution as of June 30 each year.
+
+Common filter examples:
+  - All branches for a bank: CERT:3511
+  - SOD for specific year: YEAR:2022
+  - Branches in a state: STALPBR:CA
+  - Branches in a city: CITYBR:"Austin"
+  - High-deposit branches: DEPSUMBR:[1000000 TO *]
+  - By metro area: MSANAMEBR:"Dallas-Fort Worth-Arlington"
+
+Key returned fields:
+  - YEAR: Report year (as of June 30)
+  - CERT: FDIC Certificate Number
+  - BRNUM: Branch number (0 = main office)
+  - UNINAME: Institution name
+  - NAMEFULL: Full branch name
+  - ADDRESBR, CITYBR, STALPBR, ZIPBR: Branch address
+  - CNTYBR: County
+  - DEPSUMBR: Total deposits at branch ($thousands)
+  - MSABR: Metropolitan Statistical Area code
+  - MSANAMEBR: MSA name
+  - LATITUDE, LONGITUDE: Coordinates
+
+Args:
+  - cert (number, optional): Filter by institution CERT number
+  - year (number, optional): SOD report year (1994-present)
+  - filters (string, optional): Additional ElasticSearch query filters
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: SodQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ cert, year, ...params }) => {
+      try {
+        const filterParts = [];
+        if (params.filters) filterParts.push(`(${params.filters})`);
+        if (cert !== void 0) filterParts.push(`CERT:${cert}`);
+        if (year !== void 0) filterParts.push(`YEAR:${year}`);
+        const response = await queryEndpoint(ENDPOINTS.SOD, {
+          ...params,
+          filters: filterParts.length > 0 ? filterParts.join(" AND ") : void 0
+        });
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, deposits: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/tools/demographics.ts
+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"
+  )
+});
+function registerDemographicsTools(server) {
+  server.registerTool(
+    "fdic_search_demographics",
+    {
+      title: "Search Institution Demographics Data",
+      description: `Search BankFind demographics data for FDIC-insured institutions.
+
+Returns quarterly demographic and market-structure attributes such as office counts, territory assignments, metro classification, county/country codes, and selected geographic reference data.
+
+Common filter examples:
+  - Demographics for a specific bank: CERT:3511
+  - By report date: REPDTE:20251231
+  - Institutions in metro areas: METRO:1
+  - Institutions with out-of-state offices: OFFSTATE:[1 TO *]
+  - Minority status date present: MNRTYDTE:[19000101 TO 99991231]
+
+Key returned fields:
+  - CERT: FDIC Certificate Number
+  - REPDTE: Report date (YYYYMMDD)
+  - QTRNO: Quarter number
+  - OFFTOT: Total offices
+  - OFFSTATE: Offices in other states
+  - OFFNDOM: Offices in non-domestic territories
+  - OFFOTH: Other offices
+  - OFFSOD: Offices included in Summary of Deposits
+  - METRO, MICRO: Metro/micro area flags
+  - CBSANAME, CSA: Core-based statistical area data
+  - FDICTERR, RISKTERR: FDIC and risk territory assignments
+  - SIMS_LAT, SIMS_LONG: Geographic coordinates
+
+Args:
+  - cert (number, optional): Filter by institution CERT number
+  - repdte (string, optional): Report date in YYYYMMDD format
+  - filters (string, optional): Additional ElasticSearch query filters
+  - fields (string, optional): Comma-separated field names
+  - limit (number): Records to return (default: 20)
+  - offset (number): Pagination offset (default: 0)
+  - 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[] }`,
+      inputSchema: DemographicsQuerySchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ cert, repdte, ...params }) => {
+      try {
+        const filterParts = [];
+        if (params.filters) filterParts.push(`(${params.filters})`);
+        if (cert !== void 0) filterParts.push(`CERT:${cert}`);
+        if (repdte) filterParts.push(`REPDTE:${repdte}`);
+        const response = await queryEndpoint(ENDPOINTS.DEMOGRAPHICS, {
+          ...params,
+          filters: filterParts.length > 0 ? filterParts.join(" AND ") : void 0
+        });
+        const records = extractRecords(response);
+        const pagination = buildPaginationInfo(
+          response.meta.total,
+          params.offset ?? 0,
+          records.length
+        );
+        const output = { ...pagination, demographics: records };
+        const text = truncateIfNeeded(
+          JSON.stringify(output, null, 2),
+          CHARACTER_LIMIT
+        );
+        return {
+          content: [{ type: "text", text }],
+          structuredContent: output
+        };
+      } catch (err) {
+        return formatToolError(err);
+      }
+    }
+  );
+}
+
+// src/index.ts
+function createServer() {
+  const server = new import_mcp.McpServer({
+    name: "fdic-mcp-server",
+    version: VERSION
+  });
+  registerInstitutionTools(server);
+  registerFailureTools(server);
+  registerLocationTools(server);
+  registerHistoryTools(server);
+  registerFinancialTools(server);
+  registerSodTools(server);
+  registerDemographicsTools(server);
+  return server;
+}
+async function runStdio() {
+  const server = createServer();
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+  console.error("FDIC BankFind MCP server running on stdio");
+}
+function createApp() {
+  const app = (0, import_express.default)();
+  app.use(import_express.default.json());
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok", server: "fdic-mcp-server", version: VERSION });
+  });
+  app.post("/mcp", async (req, res) => {
+    const server = createServer();
+    const transport = new import_streamableHttp.StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
+    res.on("close", () => {
+      void transport.close().catch(() => {
+      });
+      void server.close().catch(() => {
+      });
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP request error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: "Internal server error"
+          },
+          id: null
+        });
+      }
+      await transport.close().catch(() => {
+      });
+      await server.close().catch(() => {
+      });
+    }
+  });
+  return app;
+}
+async function runHTTP() {
+  const app = createApp();
+  const port = parseInt(process.env.PORT ?? "3000");
+  app.listen(port, () => {
+    console.error(
+      `FDIC BankFind MCP server running on http://localhost:${port}/mcp`
+    );
+  });
+}
+async function main() {
+  const transportMode = process.env.TRANSPORT ?? "stdio";
+  if (transportMode === "http") {
+    await runHTTP();
+  } else {
+    await runStdio();
+  }
+}
+
+// src/cli.ts
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});