# NQ Advisor MCP

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that gives Claude Desktop and Claude Code a live, tool-shaped view of NinjaTrader 8 market data for the NQ futures contract, plus a deterministic research engine that answers one question: *when a similar setup appeared before, what happened next?*

**Research and advisory only.** Nothing in this repository places, modifies, or cancels an order.

## What is here

| Path | What it does |
|---|---|
| `nq_advisor_mcp/` | The MCP server (Python, FastMCP). One deterministic feature layer, one structured Claude call per bar, hard vetoes on bad data. |
| `research/` | Deterministic research engine: export validation, session anchoring, candidate probes, MFE/MAE outcomes, kNN setup bank, expectancy report with an out-of-sample split. No network, no AI. |
| `NTBridge.cs` | NinjaTrader 8 indicator that publishes bars and indicator values over a local HTTP endpoint. |
| `validate_export.py`, `research_report.py` | Command-line entry points for the research engine. |
| `docs/` | Export schema, research workflow, NinjaTrader validation checklist, signal schema. |
| `tests/` | Unit tests for the feature engine and the suggestion payload logic. |

## How it works

1. `NTBridge.cs` runs inside NinjaTrader 8 and serves the latest bars and indicator values on `http://localhost:8765`.
2. The MCP server polls the bridge, computes trend and momentum features deterministically (`features.py`), and exposes them as tools. `nq_market_state` and `nq_recent_bars` never call a model, so they are free and fast.
3. `nq_suggest_trade` makes exactly one structured Claude call per bar (`ai.py`): direction, entry, stop, target, confidence, reasoning, and invalidation. The result is cached per bar, a server-side fallback model covers outages, and two hard vetoes cannot be overridden by the model: stale data past a trust threshold, and a `HardNoTrade` condition from the feature layer.
4. `nq_analog_stats` finds the k nearest historical setups in the research bank (`analogs.py`, `research/neighbors.py`) and reports their outcomes.
5. `nq_health` reports bridge connectivity, data freshness, and AI telemetry so a bad feed is visible before it becomes a bad suggestion.

## Tools

| Tool | Calls a model? | Returns |
|---|---|---|
| `nq_market_state` | No | Live snapshot plus trend and momentum composites |
| `nq_recent_bars` | No | Recent 1-minute bars with indicators |
| `nq_analog_stats` | No | Outcomes of the nearest historical setups |
| `nq_health` | No | Bridge, freshness, and AI telemetry diagnostics |
| `nq_suggest_trade` | Yes, once per bar | Direction, entry, stop, target, confidence, reasoning, invalidation |

## Setup

```powershell
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
copy .env.example .env      # then add your ANTHROPIC_API_KEY
```

Register the server with Claude Desktop or Claude Code (adjust the path):

```json
{
  "mcpServers": {
    "nq-advisor": {
      "command": "C:\\path\\to\\nq-advisor-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "nq_advisor_mcp"],
      "cwd": "C:\\path\\to\\nq-advisor-mcp"
    }
  }
}
```

Or run it directly:

```powershell
.\start_advisor_mcp.ps1        # or: .\.venv\Scripts\python.exe -m nq_advisor_mcp
```

Configuration lives in `.env` (see `.env.example`): `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, `ANTHROPIC_EFFORT`, `ANTHROPIC_MAX_TOKENS`, `NT_BRIDGE_URL`, `NT_BRIDGE_TIMEOUT_SECONDS`, and optional `ADVISOR_*` overrides for the fallback model, chart timezone, staleness thresholds, and replay glob.

## Research workflow

Export 1-minute bars from NinjaTrader in the format described in `docs/EXPORT_SCHEMA.md` (exports are not included in this repository), then:

```powershell
.\.venv\Scripts\python.exe validate_export.py replays\*.jsonl   # check data and timezone
.\.venv\Scripts\python.exe research_report.py --latest          # expectancy report
```

`docs/RESEARCH_WORKFLOW.md` walks through the pipeline. `docs/NINJATRADER_VALIDATION.md` lists what must be checked manually in NinjaTrader 8, especially the chart timezone assumption, before trusting any output.

## Tests

```powershell
.\.venv\Scripts\python.exe -m pytest -q tests
```

## Safety and scope

- Advisory only. There is no order-execution code in this repository.
- The model can decline or lower confidence, but it cannot override the stale-data or `HardNoTrade` vetoes.
- Nothing here is financial advice. Validate the research engine against your own exports before relying on it.

## Author

Jordan Rhodes, [github.com/ReSparkOS](https://github.com/ReSparkOS)