# blueprint-10k — an MCP server for SEC filing analysis

An [MCP](https://modelcontextprotocol.io) server that gives Claude a toolbox of
**deterministic finance tools** for analyzing 10-K/10-Q filings: the LLM does the
reading and reasoning, but every number comes from real math in Python — no
hallucinated ratios.

Paired with a set of Claude Code subagents (`.claude/agents/`) that use these
tools as a multi-agent equity-research pipeline: retrieve filing → extract
financials → analyze risk factors → scout news → forecast → validate → format.

## Tools by module

| Module | Tools |
|---|---|
| `tools/edgar.py` | Fetch filings from SEC EDGAR (company lookup, filing index, section extraction, HTML cleaning) |
| `tools/market_data.py` | Prices, history, and market snapshots via yfinance |
| `tools/ratios.py` | Liquidity / leverage / profitability / efficiency ratios from raw statement inputs, schema-validated |
| `tools/fcf.py` | Free-cash-flow computation |
| `tools/econometrics.py` | Regression + time-series diagnostics (statsmodels) |
| `tools/var.py` | Value-at-Risk (parametric + historical) for position sizing |
| `tools/options.py` | Black-Scholes pricing and greeks |
| `tools/news.py` | Multi-source news scout: Alpha Vantage, Finnhub, yfinance, EDGAR 8-Ks, Google News RSS, Reddit — with dedupe, VADER sentiment, and JSON archiving |
| `tools/boilerplate.py` | Jaccard-similarity filter that strips boilerplate legalese from risk-factor sections |
| `tools/validation.py` | JSON-schema validation + token-aware text chunking |
| `tools/charts.py` | Matplotlib chart cards for distribution |
| `tools/output.py` | Report assembly + webhook delivery |
| `tools/forecastx.py` | Stub: cross-validation against Excel forecasts (xlwings) |

Sample news-scout output lives in `news_archive/`.

## Setup

```bash
pip install -r requirements.txt
cp .mcp.json.example .mcp.json   # then fix the paths for your machine
mcp run server.py                # or let Claude Code start it via .mcp.json
```

Optional API keys (each news source degrades gracefully if its key is absent):

| Env var | Source |
|---|---|
| `ALPHAVANTAGE_KEY` | Alpha Vantage news + sentiment |
| `FINNHUB_KEY` | Finnhub company news |
| `REDDIT_CLIENT_ID` / `REDDIT_CLIENT_SECRET` | Reddit via PRAW |
| `MAKE_WEBHOOK_INTERNAL` / `MAKE_WEBHOOK_PUBLIC` | Make.com delivery webhooks for `tools/output.py` |

**Note:** SEC EDGAR requires a `User-Agent` identifying you (see
`tools/edgar.py`) — replace the contact info with your own before heavy use.

## The agent pipeline

`.claude/agents/` defines the subagents Claude Code spawns for a full analysis:

- **coordinator** — orchestrates the run, delegates to the specialists
- **filing_retrieval** — finds and fetches the right 10-K/10-Q from EDGAR
- **financial_extractor** — pulls the statements out of Item 8
- **risk_analyst** — reads Item 1A with the boilerplate filter
- **news_scout** — recent-news sweep with sentiment
- **forecaster** — projections grounded in the econometrics tools
- **options_strategist** — strategy ideas priced with the BS tools
- **validator** / **output_formatter** — schema checks, then the final report