fdic-mcp-server 1.0.8 → 1.1.0

package/README.md

@@ -5,7 +5,7 @@ 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
-- **11 tools** covering BankFind datasets plus a built-in comparative analysis tool
+- **12 tools** covering BankFind datasets plus built-in analytical tools
 - **Flexible ElasticSearch-style filtering** on all endpoints
 - **Pagination support** for large result sets
 - **Dual transport**: stdio (local) or HTTP (remote)
@@ -28,15 +28,17 @@ An MCP (Model Context Protocol) server that provides access to the [FDIC BankFin
 | `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 |
+| `fdic_peer_group_analysis` | Build a peer group and rank an institution against peers on financial metrics |
+
+Two tools are server-side analysis helpers:
+- `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
+- `fdic_peer_group_analysis` builds a peer group from asset size, charter class, and geography criteria, then ranks an institution against peers on financial and efficiency metrics
 
 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
+`fdic_compare_bank_snapshots` 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
 
@@ -52,9 +54,12 @@ STNAME:"California"
 # Numeric range (assets in $thousands)
 ASSET:[1000000 TO *]
 
-# Date range
+# Date range (hyphenated format for failures/history datasets)
 FAILDATE:[2008-01-01 TO 2010-12-31]
 
+# Date range (compact YYYYMMDD format for financials/demographics/summary datasets)
+REPDTE:[20230101 TO 20231231]
+
 # Combine with AND / OR
 STNAME:"Texas" AND ACTIVE:1 AND ASSET:[500000 TO *]
 
@@ -72,6 +77,23 @@ Use the tool description or `fields` parameter to tailor queries to the dataset
 
 ## Installation
 
+### From npm
+
+Run directly without a global install:
+
+```bash
+npx fdic-mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g fdic-mcp-server
+fdic-mcp-server
+```
+
+### From source
+
 ```bash
 npm install
 npm run build
@@ -103,6 +125,8 @@ Publishing from GitHub Actions is intended to use npm trusted publishing via Git
 
 ## Usage
 
+Client-specific setup notes for Claude Desktop, ChatGPT, Gemini CLI, and GitHub Copilot CLI are in [docs/clients.md](./docs/clients.md).
+
 ### CLI bundle
 
 The build produces two outputs:
@@ -117,6 +141,19 @@ node dist/index.js
 
 **Claude Desktop config** (`~/Library/Application\ Support/Claude/claude_desktop_config.json`):
 
+```json
+{
+  "mcpServers": {
+    "fdic": {
+      "command": "npx",
+      "args": ["-y", "fdic-mcp-server"]
+    }
+  }
+}
+```
+
+If running from a local clone instead of the npm package:
+
 ```json
 {
   "mcpServers": {
@@ -178,7 +215,7 @@ sort_order: DESC
 (fdic_search_demographics)
 ```
 
-**Rank banks by growth across two dates without orchestrating many separate queries:**
+**Rank banks by growth across two snapshots (default `analysis_mode: snapshot`):**
 ```
 state: North Carolina
 start_repdte: 20211231
@@ -188,7 +225,7 @@ sort_order: DESC
 (fdic_compare_bank_snapshots)
 ```
 
-**Analyze quarterly trends with streaks and derived metrics:**
+**Analyze quarterly trends with streaks and derived metrics (`analysis_mode: timeseries`):**
 ```
 state: North Carolina
 start_repdte: 20211231
@@ -199,6 +236,45 @@ sort_order: DESC
 (fdic_compare_bank_snapshots)
 ```
 
+**Find peers for a specific bank (auto-derived criteria):**
+```
+cert: 29846
+repdte: 20241231
+(fdic_peer_group_analysis)
+```
+
+**Define a peer group with explicit criteria:**
+```
+repdte: 20241231
+asset_min: 5000000
+asset_max: 20000000
+charter_classes: ["N"]
+state: NC
+(fdic_peer_group_analysis)
+```
+
+**Override auto-derived defaults:**
+```
+cert: 29846
+repdte: 20241231
+asset_min: 3000000
+state: NC
+(fdic_peer_group_analysis)
+```
+
+## Peer Group Analysis
+
+The `fdic_peer_group_analysis` tool builds a peer group for a bank and ranks it against peers on financial and efficiency metrics at a single report date.
+
+The tool returns rankings (competition rank + percentile) and peer group medians for:
+- Total Assets, Total Deposits, ROA, ROE, Net Interest Margin
+- Equity Capital Ratio, Efficiency Ratio, Loan-to-Deposit Ratio
+- Deposits-to-Assets Ratio, Non-Interest Income Share
+
+The subject bank is excluded from the peer set and ranking denominators. Ranking denominators are metric-specific — if some peers lack data for a metric, the denominator reflects only peers with valid values.
+
+Peer CERTs from the response can be passed to `fdic_compare_bank_snapshots` for trend analysis across the peer group.
+
 ## 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:
@@ -218,8 +294,22 @@ The tool can take either:
 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
+- insight tags (see [Insight Tags](#insight-tags) below)
+- in `timeseries` mode, quarterly series plus streak metrics
+
+### Insight Tags
+
+The analysis tool assigns insight tags to individual comparisons and aggregates them in a top-level `insights` summary. All possible tags:
+
+| Tag | Meaning |
+|-----|---------|
+| `growth_with_better_profitability` | Asset growth >= 25%, deposit growth >= 15%, and ROA improved |
+| `growth_with_branch_expansion` | Asset growth >= 25%, deposit growth >= 15%, and office count increased |
+| `balance_sheet_growth_without_profitability` | Asset growth >= 20% but ROA and ROE both flat or declining |
+| `growth_with_branch_consolidation` | Positive asset growth while office count decreased |
+| `deposit_mix_softening` | Deposits declined both in absolute terms and as a share of total assets |
+| `sustained_asset_growth` | (timeseries only) Three or more consecutive quarters of rising assets |
+| `multi_quarter_roa_decline` | (timeseries only) Two or more consecutive quarters of falling ROA |
 
 ## Response Shape
 
@@ -254,6 +344,50 @@ Typical lookup miss response shape:
 }
 ```
 
+Typical analysis response shape (`fdic_compare_bank_snapshots`):
+
+```json
+{
+  "total_candidates": 150,
+  "analyzed_count": 142,
+  "start_repdte": "20211231",
+  "end_repdte": "20250630",
+  "analysis_mode": "snapshot",
+  "sort_by": "asset_growth",
+  "sort_order": "DESC",
+  "warnings": [],
+  "insights": {
+    "growth_with_better_profitability": ["Bank A", "Bank B"],
+    "growth_with_branch_expansion": ["Bank A"],
+    "balance_sheet_growth_without_profitability": [],
+    "growth_with_branch_consolidation": ["Bank C"],
+    "deposit_mix_softening": [],
+    "sustained_asset_growth": [],
+    "multi_quarter_roa_decline": []
+  },
+  "total": 142,
+  "offset": 0,
+  "count": 10,
+  "has_more": true,
+  "next_offset": 10,
+  "comparisons": [
+    {
+      "cert": 12345,
+      "name": "Bank A",
+      "asset_growth": 50000,
+      "asset_growth_pct": 45.2,
+      "insights": ["growth_with_better_profitability", "growth_with_branch_expansion"]
+    }
+  ]
+}
+```
+
+The `warnings` array is populated when the server detects a data issue, such as the institution roster being truncated because it exceeded the FDIC API's per-request limit.
+
+In most successful analyses, `warnings` will be empty.
+
+The `sustained_asset_growth` and `multi_quarter_roa_decline` insight summaries are only populated for `analysis_mode: "timeseries"`.
+
 ## Data Notes
 
 - Monetary values are in **$thousands** unless otherwise noted