# FinResearch MCP

FinResearch MCP is a production-oriented [Model Context Protocol](https://modelcontextprotocol.io/)
server for SEC EDGAR Company Facts research, financial analysis, valuation, and
plot-ready data. It is designed as a transparent foundation for AI-assisted
equity research—not as investment advice.

## Highlights

- Reusable, rate-limited SEC client with timeouts, transient retries, response
  validation, and a five-minute in-memory Company Facts cache.
- Normalized annual financial histories for income statement, cash-flow, and
  balance-sheet metrics.
- Profitability, liquidity, leverage, efficiency, and cash-conversion ratios.
- Assumption-driven CAPM, WACC, DCF, enterprise value, equity value, intrinsic
  value, and sensitivity analysis tools.
- High-level company analysis, peer comparison, and structured chart data.
- Provider-neutral RAG contracts for future 10-K/10-Q, MD&A, and risk-factor
  retrieval.

## Installation and usage

Requirements: Python 3.12+, [uv](https://docs.astral.sh/uv/), and a contact
email address for SEC requests.

```bash
uv sync
uv run mcp dev main.py
```

`mcp dev main.py` launches MCP Inspector. The exported `main:mcp` object also
works with stdio-based MCP clients. Set `FINRESEARCH_LOG_LEVEL=DEBUG` for
diagnostic logs; logs use stderr so MCP stdio remains clean.

## Tools

| Area | Tools |
| --- | --- |
| Existing tools | `calculate_cagr`, `get_sec_company_facts`, `get_financial_fact` |
| Financial data | `get_company_financials`, `get_financial_ratios` |
| Analysis | `analyze_company`, `get_company_chart_data`, `compare_companies` |
| Valuation | `calculate_capm_cost_of_equity`, `calculate_wacc_rate`, `calculate_dcf_valuation`, `calculate_enterprise_value`, `calculate_equity_value_from_enterprise_value`, `calculate_intrinsic_value_per_share`, `run_dcf_sensitivity_analysis` |
| Version 2 platform | `ai_analyze_company`, `index_sec_filing`, `search_sec_filing_rag`, `analyze_portfolio`, `get_market_snapshot`, `get_market_price_history`, `get_dashboard_data`, `export_company_report_markdown`, `export_company_report_pdf` |

`get_company_financials` covers revenue, revenue history, net income,
operating income/EBIT, gross profit, EBITDA when depreciation data is reported,
EPS, diluted EPS, operating cash flow, free cash flow, CapEx, cash, debt,
current assets/liabilities, total assets/liabilities, equity, and book value.
Market capitalization and market-derived enterprise value are explicitly `null`
because SEC Company Facts is not a market-data service.

## Data and calculation notes

- Annual duration facts are 10-K records between 330 and 380 days; when a
  period has multiple filings, the most recently filed observation is used.
- Instant balance-sheet facts use their latest 10-K period end.
- Unreported or non-standard company concepts return `null`; the server does
  not fabricate estimates.
- Ratio calculations use reported latest values. ROIC assumes a 21% tax rate
  where tax expense is not consistently available.
- DCF tools require explicit assumptions and return structured intermediate
  projections for auditability.

## Development

```bash
.venv/bin/python -m compileall -q main.py clients models rag tools utils tests
.venv/bin/python -m unittest discover -s tests -v
```

The tests use mocked HTTP transports and never call SEC EDGAR. See
[architecture documentation](docs/architecture.md), [RAG preparation](docs/rag.md),
and [example prompts](examples/prompts.md).
See [Version 2 platform documentation](docs/version-2.md) for filing RAG,
market-data limitations, dashboard payloads, portfolios, and report exports.

## Folder structure

```text
clients/   SEC API integration
models/    typed financial domain models
tools/     MCP tool groups
utils/     extraction, ratios, valuation, logging, constants
rag/       future filing-retrieval interfaces
tests/     offline unit tests
docs/      architecture and RAG design
examples/  prompts for MCP clients
```