tradelab 1.0.1 → 1.2.0

package/docs/mcp.md

@@ -0,0 +1,285 @@
+# MCP server
+
+<small>[Back to docs](README.md)</small>
+
+`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.
+
+## 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.
+
+Brackets (stop + target) are true OCO: when one leg fills, the sibling is canceled automatically.
+
+The server runs over stdio. It does not start an HTTP port.
+
+## Install
+
+Use the published package:
+
+```bash
+npx -y tradelab tradelab-mcp
+```
+
+Or install globally:
+
+```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
+{
+  "mcpServers": {
+    "tradelab": {
+      "command": "npx",
+      "args": ["-y", "tradelab", "tradelab-mcp"]
+    }
+  }
+}
+```
+
+Global install example:
+
+```json
+{
+  "mcpServers": {
+    "tradelab": {
+      "command": "tradelab-mcp"
+    }
+  }
+}
+```
+
+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.
+
+## 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
+  }
+}
+```
+
+## Strategy Names
+
+MCP calls cannot pass JavaScript functions, so strategies are selected by name.
+
+Built-ins:
+
+- `ema-cross`
+- `rsi-reversion`
+- `donchian-breakout`
+- `buy-hold`
+
+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 docs](README.md)</small>

package/docs/research.md

@@ -0,0 +1,157 @@
+# Research checks
+
+<small>[Back to docs](README.md)</small>
+
+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 tradePnls = result.positions.map((position) => position.exit.pnl);
+
+const mc = research.monteCarlo({
+  tradePnls,
+  equityStart: 10_000,
+  seed: "spy-ema-v1",
+});
+
+console.log(mc.finalEquity.p5);
+```
+
+Use these helpers after a backtest or parameter sweep. They do not fetch data or run the strategy for you.
+
+## Monte Carlo
+
+`research.monteCarlo(options)` bootstraps completed trade PnLs into many alternate equity paths.
+
+```js
+const simulation = research.monteCarlo({
+  tradePnls,
+  equityStart: 10_000,
+  iterations: 1000,
+  blockSize: 1,
+  seed: "run-1",
+});
+```
+
+Returns:
+
+| 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 realized trade sequence.
+
+## Deflated Sharpe
+
+`research.deflatedSharpe(options)` estimates how convincing an observed Sharpe is after accounting for finite sample size, non-normal returns, and multiple trials.
+
+```js
+const probability = research.deflatedSharpe({
+  sharpe: result.metrics.sharpeDaily,
+  sampleSize: result.metrics.trades,
+  numTrials: 20,
+  sharpeStd: 0.5,
+  skew: 0,
+  kurtosis: 3,
+});
+```
+
+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 |
+
+This is not a guarantee that a strategy will work live. It is a way to penalize easy-to-overfit research.
+
+## Sweep Haircut
+
+`research.sweepHaircut(options)` estimates the Sharpe hurdle created by trying many variants.
+
+```js
+const haircut = research.sweepHaircut({
+  numTrials: 50,
+  sharpeStd: 0.4,
+});
+
+console.log(haircut.expectedMaxSharpe);
+```
+
+Use `expectedMaxSharpe` as a rough threshold: if your selected strategy barely clears what random searching could have produced, keep testing before trusting it.
+
+## 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,
+});
+```
+
+Input shape:
+
+| Dimension | Meaning                             |
+| --------- | ----------------------------------- |
+| Rows      | Strategy variants or parameter sets |
+| Columns   | Comparable per-period returns       |
+
+`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({
+  nObservations: candles.length,
+  nGroups: 6,
+  nTestGroups: 2,
+  embargo: 3,
+});
+```
+
+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 docs](README.md)</small>

package/examples/liveDashboard.js

@@ -0,0 +1,33 @@
+// Run: node examples/liveDashboard.js
+// Then open the printed URL.
+import {
+  LiveEngine,
+  PaperEngine,
+  JsonFileStorage,
+  createDashboardServer,
+} from "../src/live/index.js";
+
+const engine = new LiveEngine({
+  id: "aapl-1m",
+  symbol: "AAPL",
+  interval: "1m",
+  mode: "polling",
+  broker: new PaperEngine({ equity: 25_000 }),
+  storage: new JsonFileStorage({ baseDir: "./output/live-state" }),
+  signal({ bar, openPosition }) {
+    if (openPosition) return null;
+    return { side: "long", stop: bar.close - 1, rr: 2 };
+  },
+});
+
+const dashboard = createDashboardServer({ source: engine });
+const url = await dashboard.start();
+console.log(`Dashboard running at ${url} - Ctrl+C to stop`);
+
+await engine.start();
+
+process.on("SIGINT", async () => {
+  await engine.stop();
+  await dashboard.close();
+  process.exit(0);
+});

package/examples/llmSignal.js

@@ -0,0 +1,33 @@
+// Run: node examples/llmSignal.js
+import { backtestAsync, LlmSignal, getHistoricalCandles } from "../src/index.js";
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "1y",
+  cache: true,
+});
+
+// Stand-in for a real model call. Replace `resolve` with an LLM/agent request.
+const llm = new LlmSignal({
+  budgetMs: 2000,
+  onError: "skip",
+  async resolve({ candles: history, bar }) {
+    const closes = history.map((c) => c.close);
+    const recent = closes.slice(-5);
+    const rising = recent.every((c, i) => i === 0 || c >= recent[i - 1]);
+    return rising ? { side: "long", stop: bar.close * 0.98, rr: 2 } : null;
+  },
+});
+
+const result = await backtestAsync({
+  candles,
+  symbol: "SPY",
+  interval: "1d",
+  signal: llm.signal,
+  signalBudgetMs: 3000,
+});
+
+console.log("trades:", result.metrics.trades, "PnL:", result.metrics.totalPnL.toFixed(2));
+console.log("decisions logged:", llm.log.length);

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/examples/optimize.js

@@ -0,0 +1,25 @@
+// Run: node examples/optimize.js
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { optimize, grid, getHistoricalCandles } from "../src/index.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "2y",
+  cache: true,
+});
+
+const { leaderboard, best } = await optimize({
+  candles,
+  interval: "1d",
+  signalModulePath: path.join(here, "..", "test", "fixtures", "emaSignal.js"),
+  parameterSets: grid({ fast: [5, 8, 10, 12], slow: [20, 30, 50] }),
+  scoreBy: "sharpeAnnualized",
+});
+
+console.log("best params:", best?.params, "sharpe:", best?.metrics.sharpeAnnualized);
+console.table(leaderboard.slice(0, 5).map((r) => ({ ...r.params, ...r.metrics })));

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "tradelab",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./src/index.js",
   "types": "./types/index.d.ts",
   "bin": {
-    "tradelab": "bin/tradelab.js"
+    "tradelab": "bin/tradelab.js",
+    "tradelab-mcp": "bin/tradelab-mcp.js"
   },
   "license": "MIT",
   "repository": {
@@ -38,17 +39,34 @@
       "import": "./src/live/index.js",
       "require": "./dist/cjs/live.cjs"
     },
+    "./ta": {
+      "types": "./types/ta.d.ts",
+      "import": "./src/ta/index.js",
+      "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",
     "templates",
     "examples/*.js",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -78,10 +96,14 @@
   "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",
     "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   }
 }