tradelab 1.1.0 → 1.2.1

package/docs/mcp.md

@@ -1,31 +1,52 @@
 # MCP server
 
-<small>[Back to main page](README.md)</small>
+<small>[Back to docs](README.md)</small>
 
-`tradelab-mcp` exposes the research loop to MCP-capable agents such as Claude Desktop, Cursor, and Claude Code.
+`tradelab-mcp` exposes both a **research API** (backtest/strategy tools) and a **live trading API** (paper and live sessions) over the Model Context Protocol. Use it from MCP clients to research strategies, run paper trading loops, and optionally place real orders through a gated live mode.
 
-## Tools
+## Safety
+
+**Paper is the default and always safe.** Every session is paper unless you explicitly request live mode. Live mode requires all three gates simultaneously — if any is missing the call throws and nothing is created:
+
+1. Environment variable `TRADELAB_ALLOW_LIVE=true` must be set in the server process.
+2. The `create_session` call must include `confirmLive: true`.
+3. A broker with valid credentials must be resolvable (passed via `brokerFactory` in `SessionManager`).
+
+Every session also enforces:
+
+- `maxDailyLossPct` — if realized day PnL drops below this percentage of starting equity, all new `place_order` calls are rejected for the remainder of the day.
+- `halt_all` — an emergency kill-switch tool that flattens all positions and stops all sessions in the server process.
 
-| Tool              | Purpose                                                                 |
-| ----------------- | ----------------------------------------------------------------------- |
-| `list_strategies` | List built-in strategies and their tunable parameters                   |
-| `fetch_candles`   | Fetch Yahoo or CSV candles and return a compact first/last bar summary  |
-| `run_backtest`    | Run a named strategy with JSON params and return compact metrics        |
-| `walk_forward`    | Run a named strategy over a parameter grid and return stability metrics |
+Brackets (stop + target) are true OCO: when one leg fills, the sibling is canceled automatically.
 
-Tool outputs are summaries for agent context, not full report payloads. `run_backtest` returns metrics and a small trade preview, but not replay frames.
+The server runs over stdio. It does not start an HTTP port.
 
-## Agent research loop
+## Install
 
-1. Call `list_strategies` to inspect available strategy names and parameters.
-2. Call `fetch_candles` or provide inline `candles`.
-3. Call `run_backtest` with a strategy name and params.
-4. Read `metrics`, especially trade count, profit factor, drawdown, and annualized Sharpe.
-5. Call `walk_forward` with a parameter grid to check out-of-sample stability.
+Use the published package:
 
-## Claude Desktop config
+```bash
+npx -y tradelab tradelab-mcp
+```
+
+Or install globally:
 
-Use this with the published package:
+```bash
+npm install -g tradelab
+tradelab-mcp
+```
+
+From a local checkout:
+
+```bash
+npm install
+npm run build
+node bin/tradelab-mcp.js
+```
+
+## MCP Client Config
+
+Claude Desktop example:
 
 ```json
 {
@@ -38,7 +59,7 @@ Use this with the published package:
 }
 ```
 
-After installing globally with `npm install -g tradelab`, you can use:
+Global install example:
 
 ```json
 {
@@ -50,15 +71,215 @@ After installing globally with `npm install -g tradelab`, you can use:
 }
 ```
 
-## Strategies
+Local checkout example:
+
+```json
+{
+  "mcpServers": {
+    "tradelab": {
+      "command": "node",
+      "args": ["/absolute/path/to/tradelab/bin/tradelab-mcp.js"]
+    }
+  }
+}
+```
+
+## Tools
+
+### Research tools
+
+| Tool                 | Use it to                                                             |
+| -------------------- | --------------------------------------------------------------------- |
+| `list_strategies`    | See built-in strategy names and tunable parameters                    |
+| `fetch_candles`      | Load Yahoo or CSV candles and return first/last bars                  |
+| `run_backtest`       | Run one named strategy and return compact metrics                     |
+| `walk_forward`       | Run a parameter grid through walk-forward validation                  |
+| `analyze_robustness` | Backtest + Monte Carlo + Deflated Sharpe — validate before you trade  |
+| `optimize_strategy`  | In-process grid sweep; returns a leaderboard sorted by chosen metric  |
+| `compare_strategies` | Run several named strategies on the same dataset, ranked head-to-head |
+| `candle_stats`       | Sanity-check candle data: count, date range, price range, interval    |
+
+Tool responses are intentionally compact. They are meant for planning and comparison, not for replacing full HTML/CSV/JSON reports from the CLI.
+
+### Live trading tools
+
+| Tool              | Args (required)                                          | Returns                              |
+| ----------------- | -------------------------------------------------------- | ------------------------------------ |
+| `create_session`  | `sessionId`, `symbol`                                    | session status snapshot              |
+| `list_sessions`   | —                                                        | array of session statuses            |
+| `session_status`  | `sessionId`                                              | full refresh (positions/orders/risk) |
+| `feed_price`      | `sessionId`, `bar` OR `price`                            | status after fills                   |
+| `place_order`     | `sessionId`, `side`, `type?`, `qty?` OR `riskPct`+`stop` | order receipt                        |
+| `close_position`  | `sessionId`, `symbol?`                                   | order receipt                        |
+| `flatten`         | `sessionId`                                              | `{ ok: true }`                       |
+| `cancel_order`    | `sessionId`, `orderId`                                   | `{ ok: true }`                       |
+| `account`         | `sessionId`                                              | broker account info                  |
+| `positions`       | `sessionId`                                              | open positions                       |
+| `recent_events`   | `sessionId`, `limit?`                                    | event log                            |
+| `attach_strategy` | `sessionId`, `strategy`, `params?`                       | `{ ok: true }`                       |
+| `halt_all`        | —                                                        | `{ ok: true, sessionsHalted: N }`    |
+
+## Agent trading loop
+
+A typical autonomous paper-trading loop:
+
+1. Call `create_session` with `sessionId`, `symbol`, and `equity` (paper by default).
+2. Call `feed_price` with each new bar as it arrives — fills resting bracket orders automatically.
+3. Call `place_order` with `riskPct` + `stop` to size automatically; add `target` or `rr` for a bracket.
+4. Call `session_status` any time for a snapshot of positions, orders, equity, and risk state.
+5. Call `flatten` or `halt_all` to emergency-close everything.
+
+If you attach a strategy with `attach_strategy`, `feed_price` will auto-evaluate it each bar and place orders when the session is flat. Attached strategies receive the same `{ candles, index, bar, equity, openPosition, pendingOrder }` context as `backtest()`, and returned order intents default to a market order unless `type` is set.
+
+## Typical Research Flow
+
+1. Call `list_strategies`.
+2. Choose a built-in strategy such as `ema-cross`, `rsi-reversion`, `donchian-breakout`, or `buy-hold`.
+3. Call `fetch_candles` for a quick data sanity check, or pass a `data` object directly to `run_backtest`.
+4. Call `run_backtest` with `strategy`, `params`, and either `candles` or `data`.
+5. Inspect trade count, profit factor, drawdown, return, and Sharpe fields.
+6. Call `walk_forward` with a grid to see whether parameters hold up out of sample.
+
+## Example Calls
+
+Fetch candles:
+
+```json
+{
+  "source": "yahoo",
+  "symbol": "SPY",
+  "interval": "1d",
+  "period": "1y",
+  "cache": true
+}
+```
+
+Run a backtest:
+
+```json
+{
+  "data": {
+    "source": "yahoo",
+    "symbol": "SPY",
+    "interval": "1d",
+    "period": "2y",
+    "cache": true
+  },
+  "symbol": "SPY",
+  "interval": "1d",
+  "strategy": "ema-cross",
+  "params": {
+    "fast": 10,
+    "slow": 30,
+    "rr": 2
+  },
+  "backtestOptions": {
+    "warmupBars": 40,
+    "riskPct": 1,
+    "collectReplay": false
+  }
+}
+```
+
+Run walk-forward validation:
+
+```json
+{
+  "data": {
+    "source": "yahoo",
+    "symbol": "QQQ",
+    "interval": "1d",
+    "period": "3y"
+  },
+  "interval": "1d",
+  "strategy": "ema-cross",
+  "trainBars": 180,
+  "testBars": 60,
+  "mode": "anchored",
+  "scoreBy": "profitFactor",
+  "grid": {
+    "fast": [8, 10, 12],
+    "slow": [30, 40, 50],
+    "rr": [1.5, 2, 3]
+  },
+  "backtestOptions": {
+    "warmupBars": 60,
+    "riskPct": 1
+  }
+}
+```
 
-Agents cannot pass JavaScript closures over MCP, so strategies are name-addressable. Built-ins currently include:
+## Strategy Names
+
+MCP calls cannot pass JavaScript functions, so strategies are selected by name.
+
+Built-ins:
 
 - `ema-cross`
 - `rsi-reversion`
 - `donchian-breakout`
 - `buy-hold`
 
-Register custom strategies in application code with `registerStrategy(name, def)` from the main package. A strategy definition includes `description`, `params`, and a `factory(params)` function that returns a normal tradelab `signal(context)`.
+In application code, register custom strategies with `registerStrategy(name, definition)`:
+
+```js
+import { registerStrategy } from "tradelab";
+
+registerStrategy("my-breakout", {
+  description: "Simple close-over-high breakout",
+  params: {
+    lookback: { type: "number", default: 20 },
+    rr: { type: "number", default: 2 },
+  },
+  factory(params) {
+    return ({ candles, bar }) => {
+      if (candles.length < params.lookback + 1) return null;
+
+      const recent = candles.slice(-params.lookback - 1, -1);
+      const high = Math.max(...recent.map((candle) => candle.high));
+
+      if (bar.close <= high) return null;
+
+      return {
+        side: "long",
+        entry: bar.close,
+        stop: Math.min(...recent.map((candle) => candle.low)),
+        rr: params.rr,
+      };
+    };
+  },
+});
+```
+
+The packaged `tradelab-mcp` server only knows strategies registered in the package process. For project-specific strategies, create a small wrapper server that imports your registrations before calling `createServer()` from `tradelab/mcp`.
+
+```js
+// mcp-server.js
+import "./strategies/register.js";
+import { startStdioServer } from "tradelab/mcp";
+
+await startStdioServer();
+```
+
+## Public Server API
+
+```js
+import { createServer, startStdioServer } from "tradelab/mcp";
+```
+
+| Export               | Purpose                                       |
+| -------------------- | --------------------------------------------- |
+| `createServer()`     | Build an `McpServer` with tradelab tools      |
+| `startStdioServer()` | Create the server and connect stdio transport |
+
+## Troubleshooting
+
+| Symptom                         | Check                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| Client says server disconnected | The command must stay running and write protocol messages only to stdio |
+| `npx` starts slowly             | Install globally or point the client at a local checkout                |
+| Yahoo fetch fails               | Try a shorter `period`, set `cache: false`, or use CSV data             |
+| No trades                       | Verify candle count, `warmupBars`, params, and stop placement           |
+| Custom strategy not found       | Register it in the same Node process that starts the MCP server         |
 
-<small>[Back to main page](README.md)</small>
+<small>[Back to docs](README.md)</small>

package/docs/research.md

@@ -1,35 +1,32 @@
-# Research & overfitting
+# Research checks
 
-<small>[Back to main page](README.md)</small>
+<small>[Back to docs](README.md)</small>
 
-The `research` namespace contains pure statistical helpers for checking whether a backtest is robust enough to take seriously.
+The `research` namespace contains statistical checks for the part of trading research that usually fails quietly: too many trials, too few trades, unstable winners, and lucky trade order.
 
 ```js
 import { backtest, research } from "tradelab";
 
 const result = backtest({ candles, interval: "1d", signal });
-const pnls = result.positions.map((p) => p.exit.pnl);
+const tradePnls = result.positions.map((position) => position.exit.pnl);
 
-const mc = research.monteCarlo({ tradePnls: pnls, equityStart: 10_000, seed: 1 });
-console.log("5% worst final equity:", mc.finalEquity.p5);
-
-const dsr = research.deflatedSharpe({
-  sharpe: result.metrics.sharpeDaily,
-  sampleSize: result.metrics.trades,
-  numTrials: 20,
-  sharpeStd: 0.5,
-  skew: 0,
-  kurtosis: 3,
+const mc = research.monteCarlo({
+  tradePnls,
+  equityStart: 10_000,
+  seed: "spy-ema-v1",
 });
-console.log("Deflated Sharpe prob:", dsr);
+
+console.log(mc.finalEquity.p5);
 ```
 
-## `research.monteCarlo(options)`
+Use these helpers after a backtest or parameter sweep. They do not fetch data or run the strategy for you.
+
+## Monte Carlo
 
-Seeded block-bootstrap of trade PnLs.
+`research.monteCarlo(options)` bootstraps completed trade PnLs into many alternate equity paths.
 
 ```js
-research.monteCarlo({
+const simulation = research.monteCarlo({
   tradePnls,
   equityStart: 10_000,
   iterations: 1000,
@@ -40,54 +37,79 @@ research.monteCarlo({
 
 Returns:
 
-- `finalEquity`: `{ p5, p25, p50, p75, p95 }`
-- `maxDrawdown`: `{ p5, p25, p50, p75, p95 }`
-- `pathBands`: per-trade-step `{ p5, p50, p95 }` equity bands
-- `probProfit`: fraction of simulations ending above starting equity
+| Field         | Meaning                                                       |
+| ------------- | ------------------------------------------------------------- |
+| `finalEquity` | Percentiles of final equity: `p5`, `p25`, `p50`, `p75`, `p95` |
+| `maxDrawdown` | Percentiles of maximum drawdown across simulations            |
+| `pathBands`   | Per-trade-step equity bands for charting                      |
+| `probProfit`  | Fraction of simulations ending above starting equity          |
 
-Use `blockSize > 1` when you want to preserve short streaks in the resampled trade sequence.
+Use `blockSize > 1` when you want to preserve short streaks in the realized trade sequence.
 
-## `research.deflatedSharpe(options)`
+## Deflated Sharpe
 
-Returns a probability in `[0, 1]` that the observed Sharpe is real after accounting for finite sample size, non-normality, and multiple trials.
+`research.deflatedSharpe(options)` estimates how convincing an observed Sharpe is after accounting for finite sample size, non-normal returns, and multiple trials.
 
 ```js
-research.deflatedSharpe({
-  sharpe,
-  sampleSize,
-  numTrials,
-  sharpeStd,
-  skew,
-  kurtosis,
+const probability = research.deflatedSharpe({
+  sharpe: result.metrics.sharpeDaily,
+  sampleSize: result.metrics.trades,
+  numTrials: 20,
+  sharpeStd: 0.5,
+  skew: 0,
+  kurtosis: 3,
 });
 ```
 
-Below roughly `0.95`, treat the Sharpe as not convincingly significant.
+Interpretation:
+
+| Value           | Practical read                                   |
+| --------------- | ------------------------------------------------ |
+| `< 0.8`         | Weak evidence. Treat the result as exploratory   |
+| `0.8` to `0.95` | Interesting, but not enough on its own           |
+| `> 0.95`        | Stronger evidence, assuming inputs are realistic |
 
-## `research.sweepHaircut(options)`
+This is not a guarantee that a strategy will work live. It is a way to penalize easy-to-overfit research.
 
-Estimates the expected maximum Sharpe under the null when trying many strategy variants.
+## Sweep Haircut
+
+`research.sweepHaircut(options)` estimates the Sharpe hurdle created by trying many variants.
 
 ```js
-research.sweepHaircut({ numTrials: 50, sharpeStd: 0.4 });
+const haircut = research.sweepHaircut({
+  numTrials: 50,
+  sharpeStd: 0.4,
+});
+
+console.log(haircut.expectedMaxSharpe);
 ```
 
-Use `expectedMaxSharpe` as the multiple-testing hurdle your selected strategy should clear.
+Use `expectedMaxSharpe` as a rough threshold: if your selected strategy barely clears what random searching could have produced, keep testing before trusting it.
 
-## `research.probabilityOfBacktestOverfitting(matrix, options)`
+## Probability Of Backtest Overfitting
 
-CSCV estimate of Probability of Backtest Overfitting.
+`research.probabilityOfBacktestOverfitting(matrix, options)` estimates PBO with combinatorially symmetric cross-validation.
 
 ```js
 const matrix = parameterSets.map((params) => returnsForParams(params));
-const pbo = research.probabilityOfBacktestOverfitting(matrix, { groups: 8 });
+
+const pbo = research.probabilityOfBacktestOverfitting(matrix, {
+  groups: 8,
+});
 ```
 
-Rows are strategy variants or parameter sets. Columns are per-period returns. `pbo > 0.5` means the selection process is likely overfit; lower is better.
+Input shape:
 
-## `research.combinatorialPurgedSplits(options)`
+| Dimension | Meaning                             |
+| --------- | ----------------------------------- |
+| Rows      | Strategy variants or parameter sets |
+| Columns   | Comparable per-period returns       |
 
-Creates CPCV train/test index splits with optional embargo.
+`pbo > 0.5` means the selection process is likely overfit. Lower is better.
+
+## Purged Splits
+
+`research.combinatorialPurgedSplits(options)` creates train/test index splits with optional embargo.
 
 ```js
 const splits = research.combinatorialPurgedSplits({
@@ -98,6 +120,38 @@ const splits = research.combinatorialPurgedSplits({
 });
 ```
 
-Each split is `{ train, test, testGroups }`. Training observations near test blocks are purged by `embargo` observations to reduce leakage from overlapping or serially correlated samples.
+Each split is:
+
+```js
+{
+  train: [0, 1, 2],
+  test: [30, 31, 32],
+  testGroups: [2, 3]
+}
+```
+
+Use an embargo when labels, indicators, or trade outcomes overlap nearby observations. It keeps training rows too close to the test block out of the training set.
+
+## Low-Level Stats
+
+These are exported for advanced research code:
+
+| Export                             | Purpose                        |
+| ---------------------------------- | ------------------------------ |
+| `research.combinations(values, k)` | Generate k-combinations        |
+| `research.normalCdf(x)`            | Standard normal CDF            |
+| `research.normalPpf(p)`            | Standard normal inverse CDF    |
+| `research.moments(values)`         | Mean, variance, skew, kurtosis |
+
+## A Practical Gate
+
+For a strategy you might run live, combine several checks:
+
+1. Backtest on realistic costs and slippage.
+2. Run walk-forward validation with `walkForwardOptimize()`.
+3. Check parameter stability in `bestParamsSummary`.
+4. Run Monte Carlo on completed trade PnLs.
+5. Penalize multiple trials with deflated Sharpe or sweep haircut.
+6. Re-run on a later untouched data period before using live credentials.
 
-<small>[Back to main page](README.md)</small>
+<small>[Back to docs](README.md)</small>

package/examples/mcpLiveTrading.js

@@ -0,0 +1,77 @@
+/**
+ * mcpLiveTrading.js — Programmatic demo of TradingSession (no network, paper only).
+ *
+ * Shows: create session, feed bars, place a bracket order (entry → stop + target OCO),
+ * simulate the target hitting, and print final status.
+ *
+ *   node examples/mcpLiveTrading.js
+ */
+
+import { PaperEngine } from "../src/live/engine/paperEngine.js";
+import { TradingSession } from "../src/live/session.js";
+
+function bar(time, price, { high = price, low = price } = {}) {
+  return { time, open: price, high, low, close: price, volume: 1000 };
+}
+
+async function main() {
+  // 1. Create a paper session backed by an in-process PaperEngine.
+  const broker = new PaperEngine({ equity: 10_000 });
+  const session = new TradingSession({
+    id: "demo",
+    symbol: "AAPL",
+    interval: "1m",
+    broker,
+    equity: 10_000,
+    maxDailyLossPct: 2, // halt trading if day loss exceeds 2%
+  });
+  await session.start();
+
+  console.log("Session started:", session.getStatus().id);
+
+  // 2. Feed the first price bar so PaperEngine knows the mark.
+  await session.pushBar(bar(1, 100));
+
+  // 3. Place a risk-sized bracket order: long with stop at 98 and target at 104.
+  //    Risk: 1% of $10k = $100 risk, $2 per share risk → size = 50 shares.
+  const receipt = await session.placeOrder({
+    side: "long",
+    type: "market",
+    riskPct: 1,
+    stop: 98,
+    target: 104,
+  });
+  console.log(
+    "Entry filled:",
+    receipt.status,
+    "qty:",
+    receipt.filledQty,
+    "@",
+    receipt.avgFillPrice
+  );
+
+  let status = session.getStatus();
+  console.log("Open positions:", status.positions.length);
+  console.log("Resting bracket orders (stop + limit target):", status.openOrders.length);
+
+  // 4. Feed a bar that hits the target price (high = 104).
+  await session.pushBar(bar(2, 104, { high: 104 }));
+
+  // 5. Target filled, stop canceled (OCO). Position is closed.
+  status = session.getStatus();
+  console.log("\nAfter target bar:");
+  console.log("  positions:", status.positions.length, "(should be 0 — flat)");
+  console.log("  openOrders:", status.openOrders.length, "(should be 0 — stop canceled)");
+  console.log("  equity:", status.equity.toFixed(2), "(should be > $10,000)");
+  console.log("  dayPnl:", status.dayPnl.toFixed(2));
+  console.log("  risk.halted:", status.risk.halted, "(should be false)");
+
+  // 6. Shut down the session.
+  await session.stop();
+  console.log("\nSession stopped. Done.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradelab",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -45,13 +45,21 @@
       "require": "./dist/cjs/ta.cjs"
     },
     "./mcp": {
+      "types": "./types/mcp.d.ts",
       "import": "./src/mcp/server.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "bin",
-    "docs",
+    "docs/README.md",
+    "docs/api-reference.md",
+    "docs/backtest-engine.md",
+    "docs/data-reporting-cli.md",
+    "docs/examples.md",
+    "docs/live-trading.md",
+    "docs/mcp.md",
+    "docs/research.md",
     "dist",
     "src",
     "types",
@@ -88,7 +96,7 @@
   "devDependencies": {
     "@eslint/js": "^9.25.1",
     "@types/node": "^22.15.2",
-    "esbuild": "^0.27.3",
+    "esbuild": "^0.28.1",
     "eslint": "^9.25.1",
     "globals": "^15.15.0",
     "prettier": "^3.5.3",

package/src/engine/optimize.js

@@ -1,5 +1,8 @@
 import { Worker } from "node:worker_threads";
 import os from "node:os";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 function defaultConcurrency() {
   return Math.max(1, (os.cpus()?.length ?? 2) - 1);
@@ -10,6 +13,27 @@ function scoreValue(metrics, scoreBy) {
   return Number.isFinite(v) ? v : -Infinity;
 }
 
+function callerModuleDir() {
+  const stack = new Error().stack || "";
+  const lines = stack.split("\n").slice(1);
+  const match = lines
+    .map((line) => line.match(/(?:\()?(file:\/\/\/[^\s)]+|\/[^\s)]+):\d+:\d+/))
+    .find(Boolean);
+  if (!match) return process.cwd();
+  const filePath = match[1].startsWith("file://") ? fileURLToPath(match[1]) : match[1];
+  return path.dirname(filePath);
+}
+
+function workerUrl() {
+  const here = callerModuleDir();
+  const candidates = [
+    path.join(here, "optimizeWorker.js"),
+    path.join(here, "..", "..", "src", "engine", "optimizeWorker.js"),
+    path.join(process.cwd(), "src", "engine", "optimizeWorker.js"),
+  ];
+  return pathToFileURL(candidates.find((candidate) => existsSync(candidate)) || candidates[0]);
+}
+
 export function optimize({
   candles,
   signalModulePath,
@@ -59,7 +83,7 @@ export function optimize({
     };
 
     for (let i = 0; i < poolSize; i += 1) {
-      const worker = new Worker(new URL("./optimizeWorker.js", import.meta.url), {
+      const worker = new Worker(workerUrl(), {
         workerData: { candles, signalModulePath, interval, backtestOptions },
       });
       workers.push(worker);