# TradePause

**TradePause is a self-hosted MCP server with a browser client demonstrating an Alexa+-style paper-trading workflow.**

The demo uses real MCP calls for intent capture, preflight checks, cooldown, paper confirmation, recent-intent recovery, and review. The server requires a bound preflight before starting its cooldown, rejects confirmation while that cooldown is active, and records rejected attempts in the local event log.

TradePause is a local-first pause-and-review exercise for paper trading. A person can state a supported trade idea; TradePause structures it, checks it against disclosed sample limits, enforces a server-policy cooling-off period, requires an exact manual confirmation, and preserves a local review trail.

The product is designed to slow a decision down, not make trading faster. It does not predict markets or optimize returns. Its job is to create useful friction precisely when urgency, concentration, missing exits, or repeated trading make a decision worth revisiting.

> **Safety boundary:** TradePause is not investment advice. It uses deterministic mock quotes and a local SQLite paper ledger. It has no broker integration, never sends a live order, and returns `real_money_enabled: false` on the paper-confirmation path.

## The experience

1. Say a complete idea, such as “Buy half my portfolio of BTC now.”
2. TradePause turns it into a typed intent and applies disclosed sample limits for position size, concentration, stop loss, daily frequency, and a cooling list.
3. If a rule fails, a 20-minute cooling-off state begins. Attempts to order or confirm early are rejected.
4. After expiry, the exact phrase `CONFIRM PAPER ORDER` records one local paper fill. A review then cites the underlying audit-event IDs.

The included no-build browser simulator shows the conversation and the actual JSON-RPC exchange side by side. Both columns scroll independently, and tool results are rendered as readable structured JSON.

## Why MCP

The workflow is exposed as six small tools instead of being hidden inside a chat prompt:

- `capture_trade_intent`
- `run_preflight`
- `start_cooldown`
- `review_decision`
- `list_recent_intents`
- `get_quote` (read-only deterministic mock data)

This makes the boundary inspectable: an assistant can ask TradePause to structure, check, pause, or review, but it cannot call a real-money execution tool because no such tool exists.

## Architecture

```mermaid
flowchart LR
    Person[Person states a trade idea] --> Surface[Alexa+-style simulated assistant / browser]
    Surface -->|JSON-RPC| MCP[TradePause MCP server<br/>Streamable HTTP /mcp]
    MCP --> Tools[Six MCP tools]
    Tools --> Policy[Intent parser + preflight + cooldown state machine]
    Policy --> Quotes[Deterministic mock quotes]
    Policy --> Ledger[(Local SQLite<br/>paper ledger + audit events)]
    Ledger --> Review[Review with source event IDs]
    Review --> Surface
```

## MCP 2025-11-25 compliance

TradePause uses the official Python MCP SDK (`FastMCP`) and targets protocol revision `2025-11-25`:

- **Version negotiation:** the client requests `2025-11-25` during `initialize` and verifies the negotiated version before continuing.
- **Lifecycle:** the client sends `notifications/initialized` after a successful initialization.
- **Streamable HTTP:** JSON-RPC is served from the same-origin `/mcp` endpoint with `application/json` and `text/event-stream` accepted.
- **Session handling:** the server is stateful; the client retains `Mcp-Session-Id` and sends it with `MCP-Protocol-Version` on subsequent requests.
- **Tool schemas:** FastMCP generates typed input schemas. Current output schemas accept arbitrary JSON objects.
- **Structured results:** the simulator prefers `structuredContent`, falling back to parsed text content only when structured data is unavailable.

The 33 automated cases cover domain behavior and selected MCP flows through ASGI. They do not execute the browser JavaScript or establish full protocol conformance.

## Alexa+ track relationship

This submission is an explicitly labeled **simulated Alexa+ experience**, as permitted by the track rules. The browser represents the conversational surface: one natural-language utterance is routed to real MCP tool calls, and the user sees the safety intervention and protocol trace. It does **not** claim a production Alexa+ integration or access to unreleased Alexa+ APIs. The MCP service is the reusable backend that an authorized Alexa+ client could call in a future integration.

## Safety model

- Paper trading only; no exchange or brokerage credentials are accepted.
- No investment recommendations, price forecasts, or claims of improved returns.
- Deterministic, read-only mock quotes by default.
- The browser demo uses disclosed sample limits. MCP callers can supply alternative rule and simulated-account inputs for a new intent; saved user profiles are not yet implemented.
- The server requires a bound preflight, fixes the normal cooldown at 20 minutes, and requires the exact manual confirmation phrase before a local paper fill.
- SQLite records intent, checks, cooldown state, rejected attempts, paper fill, and retrospective source IDs locally.
- `real_money_enabled` is hard-coded `false`; there is no live-order tool or hidden execution path.
- The default demo uses deterministic routing. The optional LLM adapter falls back on errors, but model-selected actions do not establish user consent.

## Install and run

Requirements: Python 3.11 or newer. No API key or account is needed for the default path.

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e ".[dev]"
tradepause-server
```

Open `http://127.0.0.1:8765/`. The MCP endpoint is `http://127.0.0.1:8765/mcp`.

Configuration:

- `TRADEPAUSE_HOST` and `TRADEPAUSE_PORT` override `127.0.0.1:8765`.
- `TRADEPAUSE_DB` moves the ledger from `data/tradepause.db`.
- When set, `TRADEPAUSE_DEMO_COOLDOWN_SECONDS` overrides cooldown durations for new intents in that server process. Unset it to use the server-approved 20-minute policy.
- `TRADEPAUSE_LLM_PROVIDER=litellm` enables an optional routing adapter. The stable demo uses deterministic routing and needs no model key.

For the seventy-second recording cooldown:

```powershell
$env:TRADEPAUSE_DEMO_COOLDOWN_SECONDS = "70"
tradepause-server
```

## Demo in four steps

1. Enter `Buy half my portfolio of BTC now.` The intent, failed sample limits, and server-approved cooldown appear alongside real `tools/call` exchanges.
2. Immediately enter `Submit order`. TradePause rejects confirmation while the timer is active and creates no paper fill.
3. After the timer expires, enter `Confirm`, then type `CONFIRM PAPER ORDER` exactly. The first asks for manual input; the second records a local paper fill and shows `real_money_enabled: false`.
4. Enter `Review my last decision`. The review reports the outcome and cites the stored event IDs used to produce it.

See [the recording script](docs/demo_script.md) and [the bilingual storyboard](docs/video_storyboard.md) for the complete capture plan.

## Test

Keep pytest's temporary directory outside the repository:

```powershell
py -m pytest --basetemp="$env:TEMP\tradepause-pytest"
```

## 中文说明

TradePause 不是帮人“更快下单”的交易助手，而是一套本地纸面交易暂停与复盘练习：先把受支持的想法结构化，再按明确披露的示例阈值检查；服务端要求绑定检查、执行冷静期并核对精确确认串，最终只记入本机纸面账本。当前展示是 Alexa+ 风格的浏览器模拟体验，不代表已接入生产 Alexa+；项目不连接券商、不碰真钱，也不提供投资建议。

## License

MIT © 2026 Kyu Q