# Quant Companion MCP

A Model Context Protocol (MCP) server that gives AI assistants real-time options analytics and trading strategy capabilities.

## Why Use This

- **No more Googling for option prices** — just ask "what's AAPL 200 call worth?"
- **Instant Greeks** — delta, gamma, theta, vega calculated in real-time
- **Backtesting in plain English** — "backtest momentum strategy on SPY last 5 years"
- **Volatility analysis** — compare implied vs historical, spot overpriced options
- **Monte Carlo simulations** — "what's the probability NVDA hits $150 by March?"
- **No coding required** — just talk to Claude like you would a quant analyst

The AI can't hallucinate numbers. Every price, every Greek, every simulation comes from actual market data and deterministic math.

---

## Example Prompts

### Options Analysis
```
"What's the implied volatility on TSLA options right now vs its 30-day historical vol?"

"Price a 6-month AAPL 200 call with current market conditions"

"Show me the volatility smile for SPY options expiring next month"

"Is there any unusual options activity on NVDA today?"
```

### Probability & Simulations
```
"What's the probability NVDA ends above $140 in 3 months?"

"Run a Monte Carlo simulation on AAPL for the next 6 months"

"Compare price forecasts using GBM vs local vol vs SABR models for META"
```

### Strategy & Backtesting
```
"Backtest a 20/50 moving average crossover strategy on SPY from 2020 to now"

"Run the momentum_plus strategy on QQQ and show me the trades"

"Compare momentum_plus_multi against buy-and-hold SPY over 10 years"

"What would my returns be if I ran a dual momentum strategy on these ETFs?"
```

### Risk Analysis
```
"Calculate Sharpe ratio, max drawdown, and VaR for this portfolio"

"How much would I have lost in the 2022 bear market with this strategy?"

"What's the worst-case scenario for holding TSLA calls through earnings?"
```

### Quick Lookups
```
"What's AAPL trading at right now?"

"Get me SPY price history for the last 2 years"

"Show me all available option expirations for GOOGL"
```

---

## Quick Start (5 minutes)

### Prerequisites
- Node.js 18+ installed
- Claude Desktop app

### Step 1: Clone and Build

```bash
git clone https://github.com/yourusername/quant-companion-mcp.git
cd quant-companion-mcp
npm install
npm run build
```

### Step 2: Find Your Claude Config File

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
Usually: `C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json`

**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```

If the file doesn't exist, create it.

### Step 3: Add the MCP Server

Open the config file and add this (replace the path with your actual path):

```json
{
  "mcpServers": {
    "quant-companion": {
      "command": "node",
      "args": ["C:/full/path/to/quant-companion-mcp/packages/mcp-tools/dist/index.js"],
      "env": {
        "POLYGON_API_KEY": ""
      }
    }
  }
}
```

**Important:** Use the full absolute path. On Windows use forward slashes or escaped backslashes.

### Step 4: Restart Claude Desktop

Completely quit Claude Desktop (not just close the window) and reopen it.

### Step 5: Verify It Works

Open a new chat and ask:
```
What's AAPL trading at right now?
```

If you see a real price, you're good. If Claude says it can't access market data, check your path in the config.

---

## Optional: Better Data with Polygon.io

Yahoo Finance works fine for most use cases but rate limits on options chains. For heavier usage:

1. Get a free API key at https://polygon.io
2. Add it to your config:

```json
{
  "mcpServers": {
    "quant-companion": {
      "command": "node",
      "args": ["C:/path/to/packages/mcp-tools/dist/index.js"],
      "env": {
        "POLYGON_API_KEY": "your_key_here"
      }
    }
  }
}
```

The system automatically falls back to Yahoo if Polygon rate limits.

---

## What You Can Do

### Market Data
- get_current_price: Real-time stock/ETF price
- get_historical_prices: OHLCV data for any date range
- get_options_chain: Full options chain with strikes & expirations

### Options Pricing
- price_option_black_scholes: European option pricing with all Greeks
- price_option_monte_carlo: MC pricing with confidence intervals
- compute_implied_vol: Back out IV from observed price

### Volatility Analysis
- compute_historical_vol: Realized volatility from price history
- get_vol_smile: IV curve across strikes (single expiration)
- get_vol_surface: Full IV surface (strike × maturity)
- summarize_vol_regime: HV vs IV comparison with interpretation

### Simulations & Forecasting
- simulate_price: GBM price simulation with probability analysis
- simulate_price_with_local_vol: Skew-adjusted simulation using vol surface
- compare_models_forecast_distribution: Compare GBM, Local Vol, SABR, Heston
- backtest_forecast_accuracy: Historical accuracy of forecast models

### Risk & Strategy
- compute_risk_metrics: Sharpe, Sortino, max drawdown, VaR
- run_backtest: Strategy backtesting (MA crossover, momentum, mean reversion, dual momentum)
- detect_unusual_activity: Options flow analysis (volume spikes, sweeps)

---

## Architecture

```
Claude / AI Assistant
        |
        | MCP Protocol (stdio)
        v
    mcp-tools
        - 18 MCP tool definitions
        - Market data providers (Yahoo Finance, Polygon.io)
        - Input validation (Zod schemas)
        |
        | Function calls
        v
    quant-core
        - Black-Scholes pricing & Greeks
        - Monte Carlo simulations
        - Implied volatility solver (Newton-Raphson)
        - Vol smile & surface computation
        - Risk metrics (Sharpe, Sortino, VaR, max drawdown)
        - Strategy backtesting framework
        - SABR & Heston stochastic vol models
        
        Pure functions. No side effects. No network calls.
```

---

## Project Structure

```
packages/
  quant-core/           # Pure TypeScript math library
    blackScholes.ts     # BS pricing & Greeks
    monteCarlo.ts       # MC simulations
    impliedVol.ts       # Newton-Raphson IV solver
    volatility.ts       # Historical vol calculations
    volSmile.ts         # Smile curve computation
    volSurface.ts       # Surface interpolation
    risk.ts             # Sharpe, Sortino, VaR, drawdown
    backtest.ts         # Simple backtesting (MCP tools)
    sabr.ts             # SABR model calibration
    heston.ts           # Heston stochastic vol
    strategy/           # Advanced strategy framework

  mcp-tools/            # MCP server
    index.ts            # Server entry point (stdio transport)
    marketData.ts       # Yahoo/Polygon data providers
    tools/              # 18 MCP tool definitions
```

---

## Development

```bash
# Run tests
npm test

# Build all packages
npm run build

# Dev mode (auto-rebuild)
npm run dev
```

---

## Troubleshooting

**Claude says it can't access the tools**
- Make sure the path in config is absolute and correct
- Check that you ran `npm run build`
- Fully restart Claude Desktop (quit, not just close)

**Getting rate limited**
- Add a Polygon API key for better limits
- Space out rapid-fire options chain requests

**Numbers look wrong**
- Check if market is open (prices may be stale after hours)
- Options data can be delayed up to 15 min on free tier

**Heston/SABR is slow**
- First calibration takes 2-3 seconds, subsequent calls are faster
- This is expected for stochastic vol models

---

## Known Issues

- Yahoo Finance rate limits aggressively on options chain calls, polygon fallback helps
- Heston calibration can be slow on first run (~2-3 sec)  
- Vol surface interpolation gets weird at far OTM strikes

---

## License

MIT