fi-lookup-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A local MCP (Model Context Protocol) server built with FastMCP that exposes 11 tools over public US financial-institution regulatory data (FDIC, NCUA, FFIEC NIC). It resolves messy external records to canonical institutions, traces merger/acquisition lineage, and serves a regulatory change feed. This is a tool-use/reconciliation pattern — deterministic scoring and lookups against a pre-built snapshot — not RAG.

There is a small hermetic pytest suite in tests/ (pure-function + convention guards — no snapshot, network, or ZIPs required; run python -m pytest); test deps are in requirements-dev.txt and CI runs them via .github/workflows/ci.yml. No linter or build step is configured. Python 3.11 (.python-version pins 3.11.9), runtime deps in requirements.txt, venv in .venv/.

Commands

# Activate environment
source .venv/bin/activate

# Build / rebuild the data snapshot (fetches FDIC live, reads ZIPs, runs NIC enrichment).
# Required before first run. Takes 2-3 min on cold start.
python -c "import asyncio; from data_loader import build_snapshot; asyncio.run(build_snapshot())"

# Run the MCP server directly (stdio transport; lifespan builds the snapshot on startup)
python server.py

# Install into Claude Desktop
fastmcp install claude-desktop server.py --name "fi-lookup"

To exercise a single tool without Claude Desktop, import it from server.py and await it inside an asyncio.run, after calling build_snapshot() to populate the in-memory snapshot.

Architecture

server.py        — FastMCP app + 11 @mcp.tool() definitions. lifespan() calls build_snapshot() on startup.
data_loader.py   — FDIC API fetch, NCUA ZIP ingestion, FFIEC + SBA + website enrichment, the unified snapshot.
nic_loader.py    — Parses FFIEC NIC bulk ZIPs (transformations, relationships, active+closed name lookup).
reconciler.py    — Name normalization + confidence scoring for reconcile_institution.
sba_loader.py    — Builds the SBA 7(a)/504 small-business-lender index (cache/sba_lenders.json).
business_classifier.py — Scrapes home URLs for advertised business/SMB accounts + business login portals.
web_app.py       — Starlette local web dashboard (FI Explorer) over the snapshot + tools. No new deps.
division_loader.py — per-division coverage: scrapes each `trade_name_urls` entry (reuses business_classifier.scrape_one) → `cache/division_coverage.json`; `enrich_divisions` attaches a `divisions` list (per-division business/SMB/login/provider) to each record. Built by scrape_division_coverage.py — checkpointed + resumable (re-run skips cached URLs). **Name-only divisions:** NCUA publishes credit-union trade names with NO URL, so there's nothing to scrape — `_name_only_divisions` surfaces each CU brand as a division with `url=""`, `name_source="ncua"`, and every coverage field `None` (unknown). The dashboard renders these as "brand only · no home URL". `division_count` counts the attached `divisions` (URL divisions + name-only brands), not `trade_name_urls`.
audit_divisions.py — stress-tests every URL division (and its redirect target) against the quality rules (social / dup_parent / login / redirect_parent / error / unreachable) and exits non-zero on any leak. Re-run after a data refresh.
js_loader.py — **OPTIONAL** headless-Chromium (Playwright) tier for the high-value JS-rendered / blocked sites plain-HTTP can't read. Wraps Playwright in an httpx-response-shaped adapter so `scrape_one` is reused unchanged (only the fetch is swapped); writes into `cache/business_coverage.json`, tagging rendered entries `js: true`. Dep is in `requirements-js.txt` (NOT core; `playwright install chromium`) and imported lazily, so the project runs without it. Built by scrape_js_coverage.py — scoped to a deposit-ranked subset, checkpointed + resumable. Recovers JS-rendered sites (Citibank, Huntington) but NOT hard bot walls (PNC stays unreachable).
find_url_candidates.py — ranks likely corporate-URL institutions (large unreachable / zero-signal) to review for CONSUMER_DOMAIN_OVERRIDES.
refresh_sba.py / scrape_business_coverage.py — occasional (heavy) batch enrichers; build the caches the
                   above two modules read cheaply on every snapshot build.
cache/           — Local data snapshots, source ZIPs, and enrichment caches. NOT committed (see .gitignore).