# MCP-Quant Financial Research

A provenance-aware MCP server for deterministic financial research. The LLM boundary is intentionally narrow: planning is optional, while data retrieval, validation, metrics, and risk calculations are deterministic Python operations.

## Architecture

```text
MCP client
   |
   +--> research(query)
   |       |
   |       +--> typed analysis plan
   |       +--> Yahoo Finance data + quality metadata
   |       +--> deterministic metrics
   |       +--> cited/provenance-aware report
   |
   +--> get_price_history(...)
   +--> calculate_risk_metrics(...)
   +--> research://capabilities
```

## Run locally

```bash
source venv/bin/activate
export PYTHONPATH="$PWD/src"
python main.py
```

The local smoke test does not require a Groq key. Start the MCP server over stdio with:

```bash
PYTHONPATH=src python -m financial_mcp.server
```

The VS Code MCP configuration is in `.vscode/mcp.json`.

## Test

```bash
PYTHONPATH=src pytest -q
```

## MCP surface

- `research(query)`: runs the full typed research workflow.
- `get_price_history(symbols, start_date, end_date)`: retrieves adjusted prices and data-quality metadata.
- `calculate_risk_metrics(symbols, start_date, end_date)`: computes cumulative and annualized returns, volatility, Sharpe ratio, drawdown, and beta.
- `research://capabilities`: describes the server guarantees.

## Design decisions

- No arbitrary LLM-generated code is executed.
- LLM planning is disabled by default to avoid unnecessary quota usage and preserve reproducibility.
- External data is returned with source, retrieval time, requested range, and quality checks.
- Quantitative calculations are performed by pandas/numpy, not generated by the model.
- Tool arguments are validated with Pydantic before execution.

## Next research extensions

The natural next modules are a news/filings adapter, transaction-cost-aware backtesting, SQLite caching, OpenTelemetry traces, and an evaluation set measuring extraction accuracy, numerical correctness, citation completeness, latency, and token usage.

This project is for research and education, not investment advice.