# TradingAssistantMCP

A learning project: an MCP (Model Context Protocol) server that lets an agent (e.g. Claude) fetch stock data and, eventually, run backtests and custom trading strategies.

## Setup

Requires Python 3.11+. No API keys needed yet (current tools use [yfinance](https://github.com/ranaroussi/yfinance), which needs no signup).

```
python3 -m venv .venv
.venv/bin/pip install -e .
```

That creates an isolated environment in `.venv/` and installs this project's dependencies into it. `.venv/` is gitignored — anyone cloning this repo needs to run these two commands themselves before anything will work.

## Running the server

The server (`src/trading_assistant_mcp/server.py`) isn't meant to be run directly by you — it's meant to be spawned by an MCP client (an agent) over stdio. Two ways to exercise it:

**1. MCP Inspector** (manual testing, no agent needed) — a browser UI for calling tools directly:
```
.venv/bin/mcp dev src/trading_assistant_mcp/server.py
```
Opens a local URL (e.g. `http://127.0.0.1:6274`). Click Connect, go to the Tools tab, and call a tool manually.

Requires [`uv`](https://docs.astral.sh/uv/) to be installed (`mcp dev` launches the server via `uv run` internally, regardless of the venv above).

**2. Claude Code** (real agent) — registered as a project-scoped MCP server in `.mcp.json`. Open a Claude Code session in this directory and just ask a question like "what's the price of AAPL?" — Claude decides on its own whether to call the tool.

> **Portability note:** `.mcp.json` hardcodes an absolute path to this machine's `.venv/bin/python`. If you clone this repo elsewhere, re-run:
> ```
> claude mcp add -s project trading-assistant -- /absolute/path/to/.venv/bin/python /absolute/path/to/src/trading_assistant_mcp/server.py
> ```

## What's here so far

Tools:
- `get_quote(symbol)` — current price, day range, volume for a stock ticker.
- `get_fundamentals(symbol)` — valuation/financial ratios (P/E, market cap, EPS, dividend yield, beta, 52-week range, margins, growth).
- `get_candles(symbol, period, interval)` — historical OHLCV bars. Note: returns can be large (hundreds of candles) — not meant to be chained into another tool call by an agent, just for direct inspection.
- `get_technical_indicators(symbol, period, interval)` — SMA-20/50, RSI-14, MACD, Bollinger Bands, ATR-14, volume vs. its average. Fetches its own candle data internally rather than taking `get_candles`'s output as input, since that output is too large to round-trip through a tool call/agent context.

Prompts:
- `analyze_stock(symbol)` — standardized workflow: call all three data tools above, then apply a fixed textbook-interpretation rubric (trend/momentum/volatility/valuation). Explicitly framed as "what conventional signals say," not a price prediction — short-term price movement is close to a random walk and technical analysis doesn't reliably forecast it.

## Project layout

```
src/trading_assistant_mcp/
├── server.py              # MCP server: wraps data/analysis functions as tools + the analyze_stock prompt
├── models.py               # shared types (Candle) used across data/ and analysis/
├── data/
│   └── yfinance_client.py # plain Python, no MCP dependency — reusable/testable on its own
└── analysis/
    └── indicators.py      # technical indicators computed from candle data, hand-rolled pandas (no pandas-ta)
```

`server.py` is intentionally a thin adapter: it's the only file that imports `mcp`. Data-fetching and (later) analysis logic stay in plain Python modules so they're testable and reusable independent of the protocol layer.

## Roadmap

Current-data analysis (candlesticks, fundamentals/ratios, technical indicators) before backtesting and custom natural-language strategies (e.g. "buy AMD every time it drops 1%, sell every time it rises 5%"). See project decisions for the full plan.