fdic-mcp-server 1.0.5 → 1.0.7

package/README.md

@@ -5,11 +5,13 @@ An MCP (Model Context Protocol) server that provides access to the [FDIC BankFin
 ## Features
 
 - **No API key required** — The FDIC BankFind API is publicly available
-- **10 tools** covering all BankFind dataset endpoints
+- **11 tools** covering BankFind datasets plus a built-in comparative analysis tool
 - **Flexible ElasticSearch-style filtering** on all endpoints
 - **Pagination support** for large result sets
 - **Dual transport**: stdio (local) or HTTP (remote)
 - **Structured tool output** via `structuredContent` for MCP clients
+- **Built-in analytical batching** for multi-bank comparisons
+- **Short-lived response caching** for repeated analytical prompts
 
 ## Available Tools
 
@@ -25,11 +27,17 @@ An MCP (Model Context Protocol) server that provides access to the [FDIC BankFin
 | `fdic_search_summary` | Search annual financial summary data |
 | `fdic_search_sod` | Search Summary of Deposits (branch-level deposit data) |
 | `fdic_search_demographics` | Search quarterly demographics and market-structure data |
+| `fdic_compare_bank_snapshots` | Compare two reporting snapshots across banks and rank growth/profitability changes |
 
 Two tools are convenience lookups rather than separate BankFind datasets:
 - `fdic_get_institution` wraps the `institutions` dataset
 - `fdic_get_institution_failure` wraps the `failures` dataset
 
+One tool is a server-side analysis helper:
+- `fdic_compare_bank_snapshots` batches roster lookup, financial snapshots, and optional demographics snapshots inside the MCP server so complex trend prompts do not require many separate tool calls
+- It supports both `snapshot` comparisons and `timeseries` analysis across a quarterly range
+- It computes derived efficiency and balance-sheet metrics and assigns insight tags for notable growth patterns
+
 ## Filter Syntax
 
 All tools support ElasticSearch query string syntax for filtering:
@@ -93,24 +101,6 @@ git push origin main --follow-tags
 
 Publishing from GitHub Actions is intended to use npm trusted publishing via GitHub Actions OIDC rather than a long-lived `NPM_TOKEN`.
 
-### Local Secrets With direnv
-
-To keep tokens local to this repo without committing them:
-
-```bash
-cp .envrc.example .envrc
-$EDITOR .envrc
-direnv allow
-```
-
-Example `.envrc` entry:
-
-```bash
-export GITHUB_TOKEN="your_pat_here"
-```
-
-The repo ignores `.envrc`, `.envrc.local`, and `.env` so local secrets stay untracked.
-
 ## Usage
 
 ### CLI bundle
@@ -188,10 +178,53 @@ sort_order: DESC
 (fdic_search_demographics)
 ```
 
+**Rank banks by growth across two dates without orchestrating many separate queries:**
+```
+state: North Carolina
+start_repdte: 20211231
+end_repdte: 20250630
+sort_by: asset_growth
+sort_order: DESC
+(fdic_compare_bank_snapshots)
+```
+
+**Analyze quarterly trends with streaks and derived metrics:**
+```
+state: North Carolina
+start_repdte: 20211231
+end_repdte: 20250630
+analysis_mode: timeseries
+sort_by: asset_growth_pct
+sort_order: DESC
+(fdic_compare_bank_snapshots)
+```
+
+## Complex Prompts
+
+The built-in `fdic_compare_bank_snapshots` tool is meant to make analysis-heavy prompts performant by batching FDIC calls inside the MCP server. The server also caches repeated state/date lookups for a short period, which helps iterative analysis. Good examples:
+
+- Identify North Carolina banks with the strongest asset growth from 2021 to 2025, then compare whether that growth came with higher deposits, more branches, or better profitability
+- Rank a set of banks by deposit growth percentage between two report dates and check which ones also improved ROA or ROE
+- Compare current active banks in a state between two snapshots to see which institutions grew while reducing office counts
+- Analyze whether rapid asset growth was accompanied by stronger profitability or just balance-sheet expansion
+- Analyze quarterly trends from 2021 through 2025 and call out inflection points, sustained asset-growth streaks, or multi-quarter ROA declines
+- Identify banks whose deposits-per-office and assets-per-office improved even while total branch counts fell
+- Separate banks with branch-supported growth from banks that mainly expanded their balance sheets
+
+The tool can take either:
+- `state` plus optional `institution_filters` to build a roster
+- `certs` to compare a specific list of institutions directly
+
+Notable outputs from `fdic_compare_bank_snapshots`:
+- point-to-point changes for assets, deposits, net income, ROA, ROE, and office counts
+- derived metrics such as `assets_per_office_change`, `deposits_per_office_change`, and `deposits_to_assets_change`
+- insight tags such as `growth_with_better_profitability`, `growth_with_branch_expansion`, `balance_sheet_growth_without_profitability`, and `growth_with_branch_consolidation`
+- in `timeseries` mode, quarterly series plus streak metrics like sustained asset growth and multi-quarter ROA decline
+
 ## Response Shape
 
 All tools return:
-- human-readable JSON in `content[0].text`
+- a human-readable text representation in `content[0].text`
 - machine-readable data in `structuredContent`
 
 Typical search response shape: