# TradeSathi 🗣️📈

**"Alexa, ask TradeSathi the price of Reliance."**

TradeSathi is a **self-hosted MCP server** that gives **Alexa+** live Indian
stock-market (NSE) skills: real-time quotes, market status, top movers, a
spoken morning brief — and a **PAPER-trading** account so users can practise
buying and selling shares with ₹1,00,000 of fake money. No broker, no real
money, ever.

Built for the **Amazon Developer Hackathon — "Build, Ship, Shape"**,
**Alexa+ track**.

## MCP protocol: 2025-11-25, verified

The server implements the Model Context Protocol over **Streamable HTTP**
(endpoint `/mcp`) using the official Python MCP SDK (`mcp` 2.3.0,
`MCPServer`). The `initialize` handshake negotiates **protocol version
2025-11-25** — this is not just claimed, it is tested: `test_mcp.py` speaks
raw JSON-RPC to the server, requests `2025-11-25`, and asserts the server
negotiates exactly that version before exercising the tools.

## Architecture

```
                 ┌──────────────────────────────────────────────┐
                 │              Alexa+ (simulated)              │
                 │   static/index.html — chat UI that shows     │
                 │   the live MCP tool call + raw JSON result   │
                 └───────────────┬──────────────────────────────┘
                                 │  POST /api/chat (intent parse)
                                 ▼
                 ┌──────────────────────────────────────────────┐
                 │  simulator.py  (port 8600)                   │
                 │  keyword intent parsing → raw JSON-RPC       │
                 │  MCP client (session, version 2025-11-25)    │
                 └───────────────┬──────────────────────────────┘
                                 │  Streamable HTTP  POST /mcp
                                 ▼
                 ┌──────────────────────────────────────────────┐
                 │  server.py  (port 8000) — MCP server         │
                 │  official MCP SDK (MCPServer), 7 tools       │
                 └───────┬──────────────────────┬───────────────┘
                         │ yfinance             │ JSON ledger
                         ▼                      ▼
                 Yahoo Finance            paper_state.json
                 (NSE tickers *.NS)       (PAPER cash ₹1,00,000)
```

In production, Alexa+ connects to the same `/mcp` endpoint directly as an
MCP client; the simulator exists so anyone can see and try the exact same
tool calls in a browser, with the MCP layer fully visible.

## Tools

| Tool | What it does |
|---|---|
| `market_status` | Is the NSE open now? (Mon–Fri 09:15–15:30 IST; holiday calendar noted as not applied) + next open time |
| `get_quote(symbol)` | Latest price, day change %, open/high/low/previous close, volume for any NSE symbol |
| `top_movers` | Top 5 gainers + top 5 losers by day change % across ~20 large Nifty-50 names |
| `paper_buy(symbol, qty)` | PAPER buy at the live price against the paper ledger |
| `paper_sell(symbol, qty)` | PAPER sell (rejects sales beyond holdings) |
| `paper_portfolio` | Holdings at live prices, invested value, unrealised P&L, cash |
| `daily_brief` | Spoken-style brief: NIFTY / SENSEX / NIFTY BANK levels + top movers |

## Setup

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

Run the MCP server (terminal 1):

```bash
.venv/bin/python server.py            # http://127.0.0.1:8000/mcp
```

Run the Alexa+ simulator (terminal 2), then open http://127.0.0.1:8600 :

```bash
.venv/bin/python simulator.py         # http://127.0.0.1:8600
```

The paper ledger (`paper_state.json`) is created automatically on first
use with ₹1,00,000 PAPER cash. Set `TRADESATHI_STATE_FILE` to use a
different ledger file, `PORT` / `SIM_PORT` / `MCP_URL` to change ports.

## Try the MCP endpoint directly

Initialize handshake (note the negotiated `protocolVersion`):

```bash
curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -D - \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-11-25","capabilities":{},
        "clientInfo":{"name":"curl","version":"1.0"}}}'
```

Verified response (2026-10-23):

```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",
 "capabilities":{...},"serverInfo":{"name":"TradeSathi","version":""}}}
```

Then, with the `Mcp-Session-Id` header from the handshake (and an
`MCP-Protocol-Version: 2025-11-25` header), call a tool:

```bash
curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Session-Id: <session-id>' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"get_quote","arguments":{"symbol":"RELIANCE"}}}'
```

Verified live result (2026-10-23, after market close):

```json
{"symbol":"RELIANCE","exchange":"NSE","currency":"INR","price":1184.5,
 "day_change_pct":-2.03,"open":1206.2,"high":1208.0,"low":1184.5,
 "previous_close":1209.0,"volume":14931109}
```

## Tests

```bash
.venv/bin/python test_mcp.py
```

Starts the server on a scratch port with a throwaway ledger and asserts:
the 2025-11-25 handshake, all 7 tools in `tools/list`, a live
`get_quote("RELIANCE")`, and a paper buy → portfolio → sell round-trip.
Expected tail: `RESULT: ALL PASS`.

## Screenshots

<!-- TODO: add screenshots of the Alexa+ Simulator chat and the MCP
     tool-call panel here before submission. -->

## ⚠️ Paper-trading disclaimer

TradeSathi is an educational demo. All trades are **PAPER** — simulated
against live prices with fake money in a local JSON file. There are **no
broker integrations, no order placement, and no real-money functionality**
of any kind. Market data comes from Yahoo Finance via `yfinance` and may be
delayed; nothing here is investment advice.

## Built with

Python 3.12 · official MCP Python SDK (`mcp` 2.3.0) · `yfinance` ·
`httpx` · vanilla HTML/JS for the simulator UI.

## License

MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Swarnnim Agnihotri.