fdic-mcp-server 1.0.8 → 1.1.1

package/README.md

@@ -1,185 +1,163 @@
 # FDIC BankFind MCP Server
 
-An MCP (Model Context Protocol) server that provides access to the [FDIC BankFind Suite API](https://api.fdic.gov/banks/docs/), giving LLMs programmatic access to public data on FDIC-insured financial institutions.
+`fdic-mcp-server` is an MCP (Model Context Protocol) server for the [FDIC BankFind Suite API](https://api.fdic.gov/banks/docs/). It gives LLM hosts a clean way to search FDIC-insured institutions, retrieve public banking records, and run common multi-bank analysis workflows without custom FDIC API plumbing.
+
+It is useful when you want an MCP-compatible client to answer questions about banks, failures, branches, quarterly financials, deposit data, or peer performance using a stable tool surface and machine-readable responses.
+
+## Table Of Contents
+
+- [Project Status](#project-status)
+- [Why This Project Exists](#why-this-project-exists)
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Available Tools](#available-tools)
+- [Data Notes](#data-notes)
+- [Support](#support)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Project Status
+
+Active development. The server is usable today and the tool surface is covered by tests, but the project is still evolving as client support and analysis workflows improve.
+
+## Why This Project Exists
+
+The FDIC BankFind Suite API is public and useful, but it is not packaged for MCP clients out of the box. This project solves that by:
+
+- exposing BankFind datasets as MCP tools
+- preserving both human-readable and machine-readable responses
+- adding server-side analysis helpers for multi-bank comparison workflows
+- supporting both local stdio hosts and remote HTTP hosts
+
+## Documentation
+
+- 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](./docs/index.md)
+- Getting started: [docs/getting-started.md](./docs/getting-started.md)
+- Prompting guide: [docs/prompting-guide.md](./docs/prompting-guide.md)
+- Usage examples: [docs/usage-examples.md](./docs/usage-examples.md)
+- Tool reference: [docs/tool-reference.md](./docs/tool-reference.md)
+- Client setup: [docs/clients.md](./docs/clients.md)
+- Troubleshooting and FAQ: [docs/troubleshooting.md](./docs/troubleshooting.md)
+- Compatibility matrix: [docs/compatibility-matrix.md](./docs/compatibility-matrix.md)
+- Technical specification: [docs/technical/specification.md](./docs/technical/specification.md)
+- Architecture: [docs/technical/architecture.md](./docs/technical/architecture.md)
+- Key decisions: [docs/technical/decisions.md](./docs/technical/decisions.md)
+- Release notes: [docs/release-notes/index.md](./docs/release-notes/index.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
 
-## Features
-
-- **No API key required** — The FDIC BankFind API is publicly available
-- **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
-
-| Tool | Description |
-|------|-------------|
-| `fdic_search_institutions` | Search FDIC-insured banks and savings institutions |
-| `fdic_get_institution` | Get details for a specific institution by CERT number |
-| `fdic_search_failures` | Search failed bank records |
-| `fdic_get_institution_failure` | Get failure details for a specific institution |
-| `fdic_search_locations` | Search branch/office locations |
-| `fdic_search_history` | Search structural change events (mergers, name changes, etc.) |
-| `fdic_search_financials` | Search quarterly Call Report financial data |
-| `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
+## Installation
 
-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
+Prerequisites:
 
-## Filter Syntax
+- Node.js 18 or later
+- npm
 
-All tools support ElasticSearch query string syntax for filtering:
+Run directly without a global install:
 
+```bash
+npx fdic-mcp-server
 ```
-# Exact match
-NAME:"Chase Bank"
-
-# State filter
-STNAME:"California"
-
-# Numeric range (assets in $thousands)
-ASSET:[1000000 TO *]
-
-# Date range
-FAILDATE:[2008-01-01 TO 2010-12-31]
 
-# Combine with AND / OR
-STNAME:"Texas" AND ACTIVE:1 AND ASSET:[500000 TO *]
+Install globally:
 
-# Exclude
-!(BKCLASS:NM OR BKCLASS:N)
+```bash
+npm install -g fdic-mcp-server
+fdic-mcp-server
 ```
 
-Field names vary by dataset. For example:
-- `institutions` commonly uses fields like `STNAME`, `ASSET`, `ACTIVE`
-- `failures` commonly uses fields like `FAILDATE`, `COST`, `RESTYPE`
-- `locations` commonly uses fields like `STALP`, `CITY`, `BRNUM`
-- `sod` commonly uses fields like `STALPBR`, `CITYBR`, `DEPSUMBR`
-
-Use the tool description or `fields` parameter to tailor queries to the dataset you are calling.
-
-## Installation
+Install from GitHub Packages:
 
 ```bash
-npm install
-npm run build
+npm install -g @jflamb/fdic-mcp-server --registry=https://npm.pkg.github.com
+fdic-mcp-server
 ```
 
-## Development
+Install from source:
 
 ```bash
-npm run typecheck
-npm test
+git clone https://github.com/jflamb/fdic-mcp-server.git
+cd fdic-mcp-server
+npm install
 npm run build
 ```
 
-## CI And Releases
+## Usage
 
-- Pull requests should target `main`
-- Continuous integration runs on pushes to `main` and on pull requests targeting `main`
-- Package publish is reserved for semantic version tags like `v1.2.3`
-- Release tags must point at a commit already on `main`
+### Hosted Endpoint
 
-To prepare a release:
+If your MCP host supports remote MCP URLs, use:
 
-```bash
-npm version patch
-git push origin main --follow-tags
+```text
+https://bankfind.jflamb.com/mcp
 ```
 
-Publishing from GitHub Actions is intended to use npm trusted publishing via GitHub Actions OIDC rather than a long-lived `NPM_TOKEN`.
-
-## Usage
+### Run Locally
 
-### CLI bundle
+Stdio transport:
 
-The build produces two outputs:
-- `dist/index.js`: CLI entrypoint for stdio/HTTP server execution
-- `dist/server.js`: import-safe library bundle exporting `createServer`, `createApp`, and `main`
+```bash
+node dist/index.js
+```
 
-### stdio (for Claude Desktop / local MCP clients)
+HTTP transport:
 
 ```bash
-node dist/index.js
+TRANSPORT=http PORT=3000 node dist/index.js
 ```
 
-**Claude Desktop config** (`~/Library/Application\ Support/Claude/claude_desktop_config.json`):
+The HTTP MCP endpoint is `http://localhost:3000/mcp`.
+
+### Minimal MCP Configuration
 
 ```json
 {
   "mcpServers": {
     "fdic": {
-      "command": "node",
-      "args": ["/path/to/fdic-mcp-server/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "fdic-mcp-server"]
     }
   }
 }
 ```
 
-### HTTP server
+If you are running from a local clone instead of the published package:
 
-```bash
-TRANSPORT=http PORT=3000 node dist/index.js
+```json
+{
+  "mcpServers": {
+    "fdic": {
+      "command": "node",
+      "args": ["/path/to/fdic-mcp-server/dist/index.js"]
+    }
+  }
+}
 ```
 
-The MCP endpoint will be available at `http://localhost:3000/mcp`.
-
-For direct HTTP MCP clients, include:
-- `Content-Type: application/json`
-- `Accept: application/json, text/event-stream`
+Client-specific setup details are in [docs/clients.md](./docs/clients.md).
 
-The streamable HTTP transport expects both response types to be accepted.
+### Usage Examples
 
-## Example Queries
+Find active banks in North Carolina with assets over $1 billion:
 
-**Find all active banks in North Carolina with assets over $1 billion:**
-```
+```text
 filters: STNAME:"North Carolina" AND ACTIVE:1 AND ASSET:[1000000 TO *]
 ```
 
-**Get the 10 costliest bank failures since 2000:**
-```
+Get the 10 costliest bank failures since January 1, 2000:
+
+```text
 filters: FAILDATE:[2000-01-01 TO *]
 sort_by: COST
 sort_order: DESC
 limit: 10
 ```
 
-**Get all branches of a specific bank:**
-```
-cert: 3511
-(fdic_search_locations)
-```
+Compare North Carolina banks between two quarterly report dates:
 
-**Get quarterly financials for Bank of America for 2023:**
-```
-cert: 3511
-filters: REPDTE:[20230101 TO 20231231]
-(fdic_search_financials)
-```
-
-**Get demographics history for a bank:**
-```
-cert: 3511
-sort_by: REPDTE
-sort_order: DESC
-(fdic_search_demographics)
-```
-
-**Rank banks by growth across two dates without orchestrating many separate queries:**
-```
+```text
 state: North Carolina
 start_repdte: 20211231
 end_repdte: 20250630
@@ -188,80 +166,71 @@ 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)
+Build a peer group for a specific bank:
+
+```text
+cert: 29846
+repdte: 20241231
+(fdic_peer_group_analysis)
 ```
 
-## Complex Prompts
+More examples are in [docs/usage-examples.md](./docs/usage-examples.md).
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `fdic_search_institutions` | Search FDIC-insured banks and savings institutions |
+| `fdic_get_institution` | Get details for a specific institution by CERT number |
+| `fdic_search_failures` | Search failed bank records |
+| `fdic_get_institution_failure` | Get failure details for a specific institution |
+| `fdic_search_locations` | Search branch and office locations |
+| `fdic_search_history` | Search structural change events such as mergers and name changes |
+| `fdic_search_financials` | Search quarterly Call Report financial data |
+| `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 and profitability changes |
+| `fdic_peer_group_analysis` | Build a peer group and rank an institution against peers on financial metrics |
 
-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:
+Two tools are server-side analysis helpers:
 
-- 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
+- `fdic_compare_bank_snapshots` batches roster lookup, financial snapshots, and optional demographics snapshots inside the MCP server
+- `fdic_peer_group_analysis` builds a peer group from asset size, charter class, and geography criteria and then ranks an institution against peers
 
-The tool can take either:
-- `state` plus optional `institution_filters` to build a roster
-- `certs` to compare a specific list of institutions directly
+## Data Notes
 
-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
+- Monetary values are generally reported in thousands of dollars.
+- `CERT` is the stable FDIC institution identifier.
+- Financial and demographics datasets are quarterly and use `REPDTE` in `YYYYMMDD`.
+- Summary data is annual and uses `YEAR`.
+- SOD data is annual branch-level data as of June 30.
+- Do not mix quarterly financial data and annual branch data without stating the date basis.
 
-## Response Shape
+## Support
 
-All tools return:
-- a human-readable text representation in `content[0].text`
-- machine-readable data in `structuredContent`
+Use the GitHub issue tracker for bugs, documentation problems, and feature requests: <https://github.com/jflamb/fdic-mcp-server/issues>
 
-Typical search response shape:
+The main support docs are:
 
-```json
-{
-  "total": 1,
-  "offset": 0,
-  "count": 1,
-  "has_more": false,
-  "institutions": [
-    {
-      "CERT": 3511,
-      "NAME": "Wells Fargo Bank, National Association"
-    }
-  ]
-}
-```
+- [docs/support.md](./docs/support.md)
+- [docs/prompting-guide.md](./docs/prompting-guide.md)
+- [docs/usage-examples.md](./docs/usage-examples.md)
+- [docs/troubleshooting.md](./docs/troubleshooting.md)
+- [SECURITY.md](./SECURITY.md)
 
-Typical lookup miss response shape:
+## Contributing
 
-```json
-{
-  "found": false,
-  "cert": 999999999,
-  "message": "No institution found with CERT number 999999999."
-}
+Contributor guidance lives in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+For local validation, run:
+
+```bash
+npm run typecheck
+npm test
+npm run build
 ```
 
-## Data Notes
+## License
 
-- Monetary values are in **$thousands** unless otherwise noted
-- The `CERT` field is the unique FDIC Certificate Number for each institution
-- The `ACTIVE` field: `1` = currently active, `0` = inactive/closed
-- Report dates (`REPDTE`) are in `YYYYMMDD` format
-- The financials endpoint covers **1,100+ Call Report variables** — use `fields` to narrow results
-- `fdic_search_financials` defaults to `sort_order: DESC` for most-recent-first results
-- Most other search tools default to `sort_order: ASC`
-- The demographics endpoint is useful for office counts, metro/micro flags, territory assignments, and related geographic reference attributes
-- The demographics dataset is quarterly historical data, not just a current snapshot
+This project is licensed under the MIT License.