data.load → preflight.run → optimize.* → models.fit → diagnostics.run
    → compare.run → risk.var → backtest.rolling → backtest.coverage
    → report.excel → feedback.explain_decision

# Clone
git clone https://github.com/volatility-analytics-lab/volatility-mcp.git
cd volatility-mcp

# Install
python -m pip install -e ".[dev]"

# Run tests
make test

# Start the MCP server (stdio transport)
make run

# Or SSE transport for remote access
make run-sse

{
  "mcpServers": {
    "volatility": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/volatility-mcp"
    }
  }
}

Presentation:  Streamlit · Claude Desktop · REST clients · Jupyter
                              │ HTTP / stdio / SSE
Protocol:       FastMCP server (tools · resources · prompts)
                              │
Engine:         core/  (preflight · diagnostics · models · optimize
                        · risk · backtest · feedback · reporting)
                              │
Storage:        session_store/ (SQLite + parquet)
Data:           yfinance · CSV · Alpha Vantage · Polygon · Kite

volatility-mcp/
├── mcp_server/                   # MCP protocol layer
│   ├── server.py                 # Entry point: registers tools, resources, prompts
│   ├── tools/                    # Tools callable by the LLM agent
│   │   ├── session.py            # open_session / close_session / get_state
│   │   ├── data.py               # load_market / load_csv / list_universes
│   │   ├── preflight.py          # run_preflight / get_gate_status
│   │   ├── diagnostics.py        # run_diagnostics (LB, ARCH-LM, JB, Q-Q stats)
│   │   ├── optimize.py           # optimize_order / optimize_distribution / optimize_window
│   │   ├── models.py             # fit_model / forecast / list_models
│   │   ├── compare.py            # compare_models (AIC/BIC/QLIKE/RMSE)
│   │   ├── risk.py               # compute_var / compute_es / basel_es
│   │   ├── scenario.py           # apply_shock / stressed_var
│   │   ├── backtest.py           # rolling_backtest / kupiec / christoffersen
│   │   ├── report.py             # build_excel / build_pdf / build_markdown
│   │   └── feedback.py           # get_next_action / explain_decision
│   ├── resources/                # Static context (read by LLM, not executed)
│   │   ├── model_catalog.md
│   │   ├── test_catalog.md
│   │   └── workflows/            # 01_discovery → 05_validation
│   ├── prompts/                  # Prompt templates for guided workflows
│   └── schemas/                  # JSON schemas for tool I/O contracts
│
├── core/                         # Framework-agnostic engine (no MCP code here)
│   ├── data/                     # Providers: yfinance, CSV, Alpha Vantage, Polygon, Kite
│   ├── preflight/                # 12-check gate layer
│   │   └── checks/               # 01_sample_size.py … 12_frequency_adequacy.py
│   ├── diagnostics/              # Post-fit: LB, ARCH-LM, JB, sign-bias, Nyblom
│   ├── models/
│   │   ├── univariate/           # ARCH, GARCH, GJR-GARCH, EGARCH, FIGARCH, EWMA
│   │   ├── multivariate/         # DCC, BEKK, O-GARCH
│   │   ├── stochastic/           # Heston, SV-Jumps
│   │   └── ml/                   # LSTM, Transformer, TFT
│   ├── optimize/                 # order_selector, distribution_selector, window_selector…
│   ├── risk/                     # VaR (parametric, historical, FHS, MC), ES, Basel, portfolio
│   ├── backtest/                 # Kupiec, Christoffersen, DQ, Traffic Light, Diebold-Mariano
│   ├── feedback/                 # Session, state machine, workflow DAG, advisor, decision log
│   └── reporting/                # Excel, PDF, Markdown, Plotly charts
│
├── session_store/                # SQLite / DuckDB persistent session backend
├── tests/                        # Mirrors core/ structure; synthetic GARCH fixtures
├── examples/
│   ├── 01_basic_flow.py          # preflight → fit → forecast → VaR
│   ├── 02_feedback_loop_demo.py  # Full iterate-until-stable flow
│   ├── 03_optimization_walkthrough.py
│   └── notebooks/mcp_client_demo.ipynb
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── entrypoint.sh
└── docs/
    ├── ARCHITECTURE.md
    ├── FEEDBACK_LOOP.md
    ├── PREFLIGHT_CHECKS.md
    ├── INPUT_OPTIMIZATION.md
    ├── MODEL_CATALOG.md
    ├── TEST_CATALOG.md
    ├── MCP_PROTOCOL.md
    └── DECISION_RULES.md