fdic-mcp-server 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +129 -294
  2. package/dist/index.js +207 -107
  3. package/dist/server.js +211 -109
  4. package/package.json +3 -1
package/README.md CHANGED
@@ -1,83 +1,59 @@
1
1
  # FDIC BankFind MCP Server
2
2
 
3
- 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.
4
-
5
- ## Features
6
-
7
- - **No API key required** — The FDIC BankFind API is publicly available
8
- - **12 tools** covering BankFind datasets plus built-in analytical tools
9
- - **Flexible ElasticSearch-style filtering** on all endpoints
10
- - **Pagination support** for large result sets
11
- - **Dual transport**: stdio (local) or HTTP (remote)
12
- - **Structured tool output** via `structuredContent` for MCP clients
13
- - **Built-in analytical batching** for multi-bank comparisons
14
- - **Short-lived response caching** for repeated analytical prompts
15
-
16
- ## Available Tools
17
-
18
- | Tool | Description |
19
- |------|-------------|
20
- | `fdic_search_institutions` | Search FDIC-insured banks and savings institutions |
21
- | `fdic_get_institution` | Get details for a specific institution by CERT number |
22
- | `fdic_search_failures` | Search failed bank records |
23
- | `fdic_get_institution_failure` | Get failure details for a specific institution |
24
- | `fdic_search_locations` | Search branch/office locations |
25
- | `fdic_search_history` | Search structural change events (mergers, name changes, etc.) |
26
- | `fdic_search_financials` | Search quarterly Call Report financial data |
27
- | `fdic_search_summary` | Search annual financial summary data |
28
- | `fdic_search_sod` | Search Summary of Deposits (branch-level deposit data) |
29
- | `fdic_search_demographics` | Search quarterly demographics and market-structure data |
30
- | `fdic_compare_bank_snapshots` | Compare two reporting snapshots across banks and rank growth/profitability changes |
31
- | `fdic_peer_group_analysis` | Build a peer group and rank an institution against peers on financial metrics |
32
-
33
- Two tools are server-side analysis helpers:
34
- - `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
35
- - `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
36
-
37
- Two tools are convenience lookups rather than separate BankFind datasets:
38
- - `fdic_get_institution` wraps the `institutions` dataset
39
- - `fdic_get_institution_failure` wraps the `failures` dataset
40
-
41
- `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
42
-
43
- ## Filter Syntax
44
-
45
- All tools support ElasticSearch query string syntax for filtering:
46
-
47
- ```
48
- # Exact match
49
- NAME:"Chase Bank"
50
-
51
- # State filter
52
- STNAME:"California"
53
-
54
- # Numeric range (assets in $thousands)
55
- ASSET:[1000000 TO *]
56
-
57
- # Date range (hyphenated format for failures/history datasets)
58
- FAILDATE:[2008-01-01 TO 2010-12-31]
59
-
60
- # Date range (compact YYYYMMDD format for financials/demographics/summary datasets)
61
- REPDTE:[20230101 TO 20231231]
62
-
63
- # Combine with AND / OR
64
- STNAME:"Texas" AND ACTIVE:1 AND ASSET:[500000 TO *]
65
-
66
- # Exclude
67
- !(BKCLASS:NM OR BKCLASS:N)
68
- ```
69
-
70
- Field names vary by dataset. For example:
71
- - `institutions` commonly uses fields like `STNAME`, `ASSET`, `ACTIVE`
72
- - `failures` commonly uses fields like `FAILDATE`, `COST`, `RESTYPE`
73
- - `locations` commonly uses fields like `STALP`, `CITY`, `BRNUM`
74
- - `sod` commonly uses fields like `STALPBR`, `CITYBR`, `DEPSUMBR`
75
-
76
- Use the tool description or `fields` parameter to tailor queries to the dataset you are calling.
3
+ `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.
4
+
5
+ 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.
6
+
7
+ ## Table Of Contents
8
+
9
+ - [Project Status](#project-status)
10
+ - [Why This Project Exists](#why-this-project-exists)
11
+ - [Documentation](#documentation)
12
+ - [Installation](#installation)
13
+ - [Usage](#usage)
14
+ - [Available Tools](#available-tools)
15
+ - [Data Notes](#data-notes)
16
+ - [Support](#support)
17
+ - [Contributing](#contributing)
18
+ - [License](#license)
19
+
20
+ ## Project Status
21
+
22
+ 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.
23
+
24
+ ## Why This Project Exists
25
+
26
+ 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:
27
+
28
+ - exposing BankFind datasets as MCP tools
29
+ - preserving both human-readable and machine-readable responses
30
+ - adding server-side analysis helpers for multi-bank comparison workflows
31
+ - supporting both local stdio hosts and remote HTTP hosts
32
+
33
+ ## Documentation
34
+
35
+ - GitHub Pages docs entry point: <https://jflamb.github.io/fdic-mcp-server/>
36
+ - Hosted MCP endpoint: <https://bankfind.jflamb.com/mcp>
37
+ - Local docs home: [docs/index.md](./docs/index.md)
38
+ - Getting started: [docs/getting-started.md](./docs/getting-started.md)
39
+ - Prompting guide: [docs/prompting-guide.md](./docs/prompting-guide.md)
40
+ - Usage examples: [docs/usage-examples.md](./docs/usage-examples.md)
41
+ - Tool reference: [docs/tool-reference.md](./docs/tool-reference.md)
42
+ - Client setup: [docs/clients.md](./docs/clients.md)
43
+ - Troubleshooting and FAQ: [docs/troubleshooting.md](./docs/troubleshooting.md)
44
+ - Compatibility matrix: [docs/compatibility-matrix.md](./docs/compatibility-matrix.md)
45
+ - Technical specification: [docs/technical/specification.md](./docs/technical/specification.md)
46
+ - Architecture: [docs/technical/architecture.md](./docs/technical/architecture.md)
47
+ - Key decisions: [docs/technical/decisions.md](./docs/technical/decisions.md)
48
+ - Release notes: [docs/release-notes/index.md](./docs/release-notes/index.md)
49
+ - Security policy: [SECURITY.md](./SECURITY.md)
77
50
 
78
51
  ## Installation
79
52
 
80
- ### From npm
53
+ Prerequisites:
54
+
55
+ - Node.js 18 or later
56
+ - npm
81
57
 
82
58
  Run directly without a global install:
83
59
 
@@ -85,61 +61,56 @@ Run directly without a global install:
85
61
  npx fdic-mcp-server
86
62
  ```
87
63
 
88
- Or install globally:
64
+ Install globally:
89
65
 
90
66
  ```bash
91
67
  npm install -g fdic-mcp-server
92
68
  fdic-mcp-server
93
69
  ```
94
70
 
95
- ### From source
71
+ Install from GitHub Packages:
96
72
 
97
73
  ```bash
98
- npm install
99
- npm run build
74
+ npm install -g @jflamb/fdic-mcp-server --registry=https://npm.pkg.github.com
75
+ fdic-mcp-server
100
76
  ```
101
77
 
102
- ## Development
78
+ Install from source:
103
79
 
104
80
  ```bash
105
- npm run typecheck
106
- npm test
81
+ git clone https://github.com/jflamb/fdic-mcp-server.git
82
+ cd fdic-mcp-server
83
+ npm install
107
84
  npm run build
108
85
  ```
109
86
 
110
- ## CI And Releases
87
+ ## Usage
111
88
 
112
- - Pull requests should target `main`
113
- - Continuous integration runs on pushes to `main` and on pull requests targeting `main`
114
- - Package publish is reserved for semantic version tags like `v1.2.3`
115
- - Release tags must point at a commit already on `main`
89
+ ### Hosted Endpoint
116
90
 
117
- To prepare a release:
91
+ If your MCP host supports remote MCP URLs, use:
118
92
 
119
- ```bash
120
- npm version patch
121
- git push origin main --follow-tags
93
+ ```text
94
+ https://bankfind.jflamb.com/mcp
122
95
  ```
123
96
 
124
- Publishing from GitHub Actions is intended to use npm trusted publishing via GitHub Actions OIDC rather than a long-lived `NPM_TOKEN`.
125
-
126
- ## Usage
127
-
128
- Client-specific setup notes for Claude Desktop, ChatGPT, Gemini CLI, and GitHub Copilot CLI are in [docs/clients.md](./docs/clients.md).
97
+ ### Run Locally
129
98
 
130
- ### CLI bundle
99
+ Stdio transport:
131
100
 
132
- The build produces two outputs:
133
- - `dist/index.js`: CLI entrypoint for stdio/HTTP server execution
134
- - `dist/server.js`: import-safe library bundle exporting `createServer`, `createApp`, and `main`
101
+ ```bash
102
+ node dist/index.js
103
+ ```
135
104
 
136
- ### stdio (for Claude Desktop / local MCP clients)
105
+ HTTP transport:
137
106
 
138
107
  ```bash
139
- node dist/index.js
108
+ TRANSPORT=http PORT=3000 node dist/index.js
140
109
  ```
141
110
 
142
- **Claude Desktop config** (`~/Library/Application\ Support/Claude/claude_desktop_config.json`):
111
+ The HTTP MCP endpoint is `http://localhost:3000/mcp`.
112
+
113
+ ### Minimal MCP Configuration
143
114
 
144
115
  ```json
145
116
  {
@@ -152,7 +123,7 @@ node dist/index.js
152
123
  }
153
124
  ```
154
125
 
155
- If running from a local clone instead of the npm package:
126
+ If you are running from a local clone instead of the published package:
156
127
 
157
128
  ```json
158
129
  {
@@ -165,58 +136,28 @@ If running from a local clone instead of the npm package:
165
136
  }
166
137
  ```
167
138
 
168
- ### HTTP server
169
-
170
- ```bash
171
- TRANSPORT=http PORT=3000 node dist/index.js
172
- ```
173
-
174
- The MCP endpoint will be available at `http://localhost:3000/mcp`.
175
-
176
- For direct HTTP MCP clients, include:
177
- - `Content-Type: application/json`
178
- - `Accept: application/json, text/event-stream`
139
+ Client-specific setup details are in [docs/clients.md](./docs/clients.md).
179
140
 
180
- The streamable HTTP transport expects both response types to be accepted.
141
+ ### Usage Examples
181
142
 
182
- ## Example Queries
143
+ Find active banks in North Carolina with assets over $1 billion:
183
144
 
184
- **Find all active banks in North Carolina with assets over $1 billion:**
185
- ```
145
+ ```text
186
146
  filters: STNAME:"North Carolina" AND ACTIVE:1 AND ASSET:[1000000 TO *]
187
147
  ```
188
148
 
189
- **Get the 10 costliest bank failures since 2000:**
190
- ```
149
+ Get the 10 costliest bank failures since January 1, 2000:
150
+
151
+ ```text
191
152
  filters: FAILDATE:[2000-01-01 TO *]
192
153
  sort_by: COST
193
154
  sort_order: DESC
194
155
  limit: 10
195
156
  ```
196
157
 
197
- **Get all branches of a specific bank:**
198
- ```
199
- cert: 3511
200
- (fdic_search_locations)
201
- ```
202
-
203
- **Get quarterly financials for Bank of America for 2023:**
204
- ```
205
- cert: 3511
206
- filters: REPDTE:[20230101 TO 20231231]
207
- (fdic_search_financials)
208
- ```
209
-
210
- **Get demographics history for a bank:**
211
- ```
212
- cert: 3511
213
- sort_by: REPDTE
214
- sort_order: DESC
215
- (fdic_search_demographics)
216
- ```
158
+ Compare North Carolina banks between two quarterly report dates:
217
159
 
218
- **Rank banks by growth across two snapshots (default `analysis_mode: snapshot`):**
219
- ```
160
+ ```text
220
161
  state: North Carolina
221
162
  start_repdte: 20211231
222
163
  end_repdte: 20250630
@@ -225,177 +166,71 @@ sort_order: DESC
225
166
  (fdic_compare_bank_snapshots)
226
167
  ```
227
168
 
228
- **Analyze quarterly trends with streaks and derived metrics (`analysis_mode: timeseries`):**
229
- ```
230
- state: North Carolina
231
- start_repdte: 20211231
232
- end_repdte: 20250630
233
- analysis_mode: timeseries
234
- sort_by: asset_growth_pct
235
- sort_order: DESC
236
- (fdic_compare_bank_snapshots)
237
- ```
238
-
239
- **Find peers for a specific bank (auto-derived criteria):**
240
- ```
241
- cert: 29846
242
- repdte: 20241231
243
- (fdic_peer_group_analysis)
244
- ```
245
-
246
- **Define a peer group with explicit criteria:**
247
- ```
248
- repdte: 20241231
249
- asset_min: 5000000
250
- asset_max: 20000000
251
- charter_classes: ["N"]
252
- state: NC
253
- (fdic_peer_group_analysis)
254
- ```
169
+ Build a peer group for a specific bank:
255
170
 
256
- **Override auto-derived defaults:**
257
- ```
171
+ ```text
258
172
  cert: 29846
259
173
  repdte: 20241231
260
- asset_min: 3000000
261
- state: NC
262
174
  (fdic_peer_group_analysis)
263
175
  ```
264
176
 
265
- ## Peer Group Analysis
177
+ More examples are in [docs/usage-examples.md](./docs/usage-examples.md).
266
178
 
267
- 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.
268
-
269
- The tool returns rankings (competition rank + percentile) and peer group medians for:
270
- - Total Assets, Total Deposits, ROA, ROE, Net Interest Margin
271
- - Equity Capital Ratio, Efficiency Ratio, Loan-to-Deposit Ratio
272
- - Deposits-to-Assets Ratio, Non-Interest Income Share
273
-
274
- 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.
275
-
276
- Peer CERTs from the response can be passed to `fdic_compare_bank_snapshots` for trend analysis across the peer group.
277
-
278
- ## Complex Prompts
279
-
280
- 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:
281
-
282
- - 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
283
- - Rank a set of banks by deposit growth percentage between two report dates and check which ones also improved ROA or ROE
284
- - Compare current active banks in a state between two snapshots to see which institutions grew while reducing office counts
285
- - Analyze whether rapid asset growth was accompanied by stronger profitability or just balance-sheet expansion
286
- - Analyze quarterly trends from 2021 through 2025 and call out inflection points, sustained asset-growth streaks, or multi-quarter ROA declines
287
- - Identify banks whose deposits-per-office and assets-per-office improved even while total branch counts fell
288
- - Separate banks with branch-supported growth from banks that mainly expanded their balance sheets
179
+ ## Available Tools
289
180
 
290
- The tool can take either:
291
- - `state` plus optional `institution_filters` to build a roster
292
- - `certs` to compare a specific list of institutions directly
181
+ | Tool | Description |
182
+ |------|-------------|
183
+ | `fdic_search_institutions` | Search FDIC-insured banks and savings institutions |
184
+ | `fdic_get_institution` | Get details for a specific institution by CERT number |
185
+ | `fdic_search_failures` | Search failed bank records |
186
+ | `fdic_get_institution_failure` | Get failure details for a specific institution |
187
+ | `fdic_search_locations` | Search branch and office locations |
188
+ | `fdic_search_history` | Search structural change events such as mergers and name changes |
189
+ | `fdic_search_financials` | Search quarterly Call Report financial data |
190
+ | `fdic_search_summary` | Search annual financial summary data |
191
+ | `fdic_search_sod` | Search Summary of Deposits branch-level deposit data |
192
+ | `fdic_search_demographics` | Search quarterly demographics and market-structure data |
193
+ | `fdic_compare_bank_snapshots` | Compare two reporting snapshots across banks and rank growth and profitability changes |
194
+ | `fdic_peer_group_analysis` | Build a peer group and rank an institution against peers on financial metrics |
293
195
 
294
- Notable outputs from `fdic_compare_bank_snapshots`:
295
- - point-to-point changes for assets, deposits, net income, ROA, ROE, and office counts
296
- - derived metrics such as `assets_per_office_change`, `deposits_per_office_change`, and `deposits_to_assets_change`
297
- - insight tags (see [Insight Tags](#insight-tags) below)
298
- - in `timeseries` mode, quarterly series plus streak metrics
196
+ Two tools are server-side analysis helpers:
299
197
 
300
- ### Insight Tags
198
+ - `fdic_compare_bank_snapshots` batches roster lookup, financial snapshots, and optional demographics snapshots inside the MCP server
199
+ - `fdic_peer_group_analysis` builds a peer group from asset size, charter class, and geography criteria and then ranks an institution against peers
301
200
 
302
- The analysis tool assigns insight tags to individual comparisons and aggregates them in a top-level `insights` summary. All possible tags:
201
+ ## Data Notes
303
202
 
304
- | Tag | Meaning |
305
- |-----|---------|
306
- | `growth_with_better_profitability` | Asset growth >= 25%, deposit growth >= 15%, and ROA improved |
307
- | `growth_with_branch_expansion` | Asset growth >= 25%, deposit growth >= 15%, and office count increased |
308
- | `balance_sheet_growth_without_profitability` | Asset growth >= 20% but ROA and ROE both flat or declining |
309
- | `growth_with_branch_consolidation` | Positive asset growth while office count decreased |
310
- | `deposit_mix_softening` | Deposits declined both in absolute terms and as a share of total assets |
311
- | `sustained_asset_growth` | (timeseries only) Three or more consecutive quarters of rising assets |
312
- | `multi_quarter_roa_decline` | (timeseries only) Two or more consecutive quarters of falling ROA |
203
+ - Monetary values are generally reported in thousands of dollars.
204
+ - `CERT` is the stable FDIC institution identifier.
205
+ - Financial and demographics datasets are quarterly and use `REPDTE` in `YYYYMMDD`.
206
+ - Summary data is annual and uses `YEAR`.
207
+ - SOD data is annual branch-level data as of June 30.
208
+ - Do not mix quarterly financial data and annual branch data without stating the date basis.
313
209
 
314
- ## Response Shape
210
+ ## Support
315
211
 
316
- All tools return:
317
- - a human-readable text representation in `content[0].text`
318
- - machine-readable data in `structuredContent`
212
+ Use the GitHub issue tracker for bugs, documentation problems, and feature requests: <https://github.com/jflamb/fdic-mcp-server/issues>
319
213
 
320
- Typical search response shape:
214
+ The main support docs are:
321
215
 
322
- ```json
323
- {
324
- "total": 1,
325
- "offset": 0,
326
- "count": 1,
327
- "has_more": false,
328
- "institutions": [
329
- {
330
- "CERT": 3511,
331
- "NAME": "Wells Fargo Bank, National Association"
332
- }
333
- ]
334
- }
335
- ```
216
+ - [docs/support.md](./docs/support.md)
217
+ - [docs/prompting-guide.md](./docs/prompting-guide.md)
218
+ - [docs/usage-examples.md](./docs/usage-examples.md)
219
+ - [docs/troubleshooting.md](./docs/troubleshooting.md)
220
+ - [SECURITY.md](./SECURITY.md)
336
221
 
337
- Typical lookup miss response shape:
222
+ ## Contributing
338
223
 
339
- ```json
340
- {
341
- "found": false,
342
- "cert": 999999999,
343
- "message": "No institution found with CERT number 999999999."
344
- }
345
- ```
224
+ Contributor guidance lives in [CONTRIBUTING.md](./CONTRIBUTING.md).
346
225
 
347
- Typical analysis response shape (`fdic_compare_bank_snapshots`):
226
+ For local validation, run:
348
227
 
349
- ```json
350
- {
351
- "total_candidates": 150,
352
- "analyzed_count": 142,
353
- "start_repdte": "20211231",
354
- "end_repdte": "20250630",
355
- "analysis_mode": "snapshot",
356
- "sort_by": "asset_growth",
357
- "sort_order": "DESC",
358
- "warnings": [],
359
- "insights": {
360
- "growth_with_better_profitability": ["Bank A", "Bank B"],
361
- "growth_with_branch_expansion": ["Bank A"],
362
- "balance_sheet_growth_without_profitability": [],
363
- "growth_with_branch_consolidation": ["Bank C"],
364
- "deposit_mix_softening": [],
365
- "sustained_asset_growth": [],
366
- "multi_quarter_roa_decline": []
367
- },
368
- "total": 142,
369
- "offset": 0,
370
- "count": 10,
371
- "has_more": true,
372
- "next_offset": 10,
373
- "comparisons": [
374
- {
375
- "cert": 12345,
376
- "name": "Bank A",
377
- "asset_growth": 50000,
378
- "asset_growth_pct": 45.2,
379
- "insights": ["growth_with_better_profitability", "growth_with_branch_expansion"]
380
- }
381
- ]
382
- }
228
+ ```bash
229
+ npm run typecheck
230
+ npm test
231
+ npm run build
383
232
  ```
384
233
 
385
- 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.
386
-
387
- In most successful analyses, `warnings` will be empty.
388
-
389
- The `sustained_asset_growth` and `multi_quarter_roa_decline` insight summaries are only populated for `analysis_mode: "timeseries"`.
390
-
391
- ## Data Notes
234
+ ## License
392
235
 
393
- - Monetary values are in **$thousands** unless otherwise noted
394
- - The `CERT` field is the unique FDIC Certificate Number for each institution
395
- - The `ACTIVE` field: `1` = currently active, `0` = inactive/closed
396
- - Report dates (`REPDTE`) are in `YYYYMMDD` format
397
- - The financials endpoint covers **1,100+ Call Report variables** — use `fields` to narrow results
398
- - `fdic_search_financials` defaults to `sort_order: DESC` for most-recent-first results
399
- - Most other search tools default to `sort_order: ASC`
400
- - The demographics endpoint is useful for office counts, metro/micro flags, territory assignments, and related geographic reference attributes
401
- - The demographics dataset is quarterly historical data, not just a current snapshot
236
+ This project is licensed under the MIT License.