tradelab 1.1.0 → 1.2.1

package/src/mcp/liveTools.js

@@ -0,0 +1,202 @@
+import { SessionManager } from "../live/session.js";
+import { getStrategy } from "../strategies/index.js";
+
+// Module-level shared SessionManager for the MCP server process
+const manager = new SessionManager();
+
+function requireSession(sessionId) {
+  const s = manager.get(sessionId);
+  if (!s) throw new Error(`No session found with id "${sessionId}"`);
+  return s;
+}
+
+function strategyContext(session) {
+  const candles = session.candleBuffer;
+  const bar = candles[candles.length - 1] ?? null;
+  const status = session.getStatus();
+  return {
+    candles,
+    index: candles.length - 1,
+    bar,
+    equity: status.equity,
+    openPosition: status.positions[0] ?? null,
+    pendingOrder: null,
+  };
+}
+
+function signalToOrder(signal) {
+  return {
+    side: signal.side ?? signal.direction ?? signal.action,
+    type: signal.type ?? "market",
+    qty: signal.qty ?? signal.size,
+    riskPct: signal.riskPct,
+    stop: signal.stop ?? signal.stopLoss ?? signal.sl,
+    target: signal.target ?? signal.takeProfit ?? signal.tp,
+    rr: signal.rr ?? signal._rr,
+    limitPrice: signal.limitPrice ?? signal.limit ?? signal.entry ?? signal.price,
+  };
+}
+
+export { manager as sessionManager };
+
+export const liveTools = {
+  create_session: {
+    description:
+      "Create a new paper (default) or live (gated) trading session. Paper needs no credentials.",
+    handler: async ({
+      sessionId,
+      symbol,
+      mode = "paper",
+      interval = "1m",
+      equity = 10_000,
+      riskPct,
+      maxDailyLossPct,
+      confirmLive = false,
+    } = {}) => {
+      const session = await manager.create({
+        id: sessionId,
+        symbol,
+        mode,
+        interval,
+        equity,
+        ...(riskPct != null ? { riskPct } : {}),
+        ...(maxDailyLossPct != null ? { maxDailyLossPct } : {}),
+        confirmLive,
+      });
+      return session.getStatus();
+    },
+  },
+
+  list_sessions: {
+    description: "List all active trading sessions and their current status.",
+    handler: async () => {
+      return manager.list().map((s) => s.getStatus());
+    },
+  },
+
+  session_status: {
+    description:
+      "Get a full refreshed status snapshot for a session (positions, orders, equity, risk).",
+    handler: async ({ sessionId } = {}) => {
+      const session = requireSession(sessionId);
+      return session.refresh();
+    },
+  },
+
+  feed_price: {
+    description:
+      "Feed a price bar (or single price) to a session, advancing paper simulations and triggering fills.",
+    handler: async ({ sessionId, bar, price } = {}) => {
+      const session = requireSession(sessionId);
+      let b = bar;
+      if (!b && Number.isFinite(price)) {
+        b = { time: Date.now(), open: price, high: price, low: price, close: price, volume: 0 };
+      }
+      if (!b) throw new Error("Provide either `bar` (OHLCV) or `price` (number)");
+      await session.pushBar(b);
+
+      // If a strategy is attached and session is flat, evaluate it
+      if (session._strategy && session.getStatus().positions.length === 0) {
+        try {
+          const signal = session._strategy(strategyContext(session));
+          if (signal && (signal.side || signal.direction || signal.action)) {
+            await session.placeOrder(signalToOrder(signal)).catch(() => {});
+          }
+        } catch {
+          // strategy errors are non-fatal
+        }
+      }
+
+      return session.getStatus();
+    },
+  },
+
+  place_order: {
+    description:
+      "Place a market or limit order in a session (optionally risk-sized with bracket stop/target).",
+    handler: async ({
+      sessionId,
+      side,
+      type = "market",
+      qty,
+      riskPct,
+      stop,
+      target,
+      rr,
+      limitPrice,
+    } = {}) => {
+      const session = requireSession(sessionId);
+      return session.placeOrder({ side, type, qty, riskPct, stop, target, rr, limitPrice });
+    },
+  },
+
+  close_position: {
+    description: "Close the open position for a symbol in a session via an opposite market order.",
+    handler: async ({ sessionId, symbol } = {}) => {
+      const session = requireSession(sessionId);
+      return session.closePosition(symbol);
+    },
+  },
+
+  flatten: {
+    description: "Flatten all positions and cancel all open orders in a session.",
+    handler: async ({ sessionId } = {}) => {
+      const session = requireSession(sessionId);
+      await session.flatten();
+      return { ok: true };
+    },
+  },
+
+  cancel_order: {
+    description: "Cancel a specific open order in a session.",
+    handler: async ({ sessionId, orderId } = {}) => {
+      const session = requireSession(sessionId);
+      await session.cancelOrder(orderId);
+      return { ok: true };
+    },
+  },
+
+  account: {
+    description: "Get the broker account details for a session (equity, cash, buying power).",
+    handler: async ({ sessionId } = {}) => {
+      const session = requireSession(sessionId);
+      return session.getAccount();
+    },
+  },
+
+  positions: {
+    description: "Get all open positions for a session.",
+    handler: async ({ sessionId } = {}) => {
+      const session = requireSession(sessionId);
+      return session.getPositions();
+    },
+  },
+
+  recent_events: {
+    description: "Get recent session events (fills, risk changes, bars) for monitoring.",
+    handler: async ({ sessionId, limit = 50 } = {}) => {
+      const session = requireSession(sessionId);
+      return session.recentEvents(limit);
+    },
+  },
+
+  attach_strategy: {
+    description:
+      "Attach a named built-in strategy to a session. It will auto-evaluate on each feed_price and place orders when flat.",
+    handler: async ({ sessionId, strategy, params = {} } = {}) => {
+      const session = requireSession(sessionId);
+      const factory = getStrategy(strategy);
+      const signal = factory(params);
+      session._strategy = signal;
+      return { ok: true, strategy, params };
+    },
+  },
+
+  halt_all: {
+    description: "Emergency kill switch: flatten all positions and stop all trading sessions.",
+    handler: async () => {
+      await manager.haltAll();
+      return { ok: true, sessionsHalted: manager.list().length };
+    },
+  },
+};

package/src/mcp/schemas.js

@@ -20,6 +20,19 @@ const dataSpec = z
   })
   .passthrough();
 
+const barShape = z.object({
+  time: z.number(),
+  open: z.number().optional(),
+  high: z.number().optional(),
+  low: z.number().optional(),
+  close: z.number(),
+  volume: z.number().optional(),
+});
+
+const sessionMode = z.enum(["paper", "live"]).optional();
+const orderSide = z.enum(["long", "short", "buy", "sell"]);
+const orderType = z.enum(["market", "limit", "stop", "stop_limit"]).optional();
+
 export const schemas = {
   list_strategies: {},
   fetch_candles: dataSpec.shape,
@@ -45,4 +58,110 @@ export const schemas = {
     grid: z.record(z.string(), z.array(z.any())).optional(),
     backtestOptions: z.record(z.string(), z.any()).optional(),
   },
+
+  // Research-plus tools
+  analyze_robustness: {
+    candles: z.array(candle).optional(),
+    data: dataSpec.optional(),
+    symbol: z.string().optional(),
+    interval: z.string().optional(),
+    strategy: z.string(),
+    params: z.record(z.string(), z.any()).optional(),
+    equityStart: z.number().optional(),
+    iterations: z.number().optional(),
+    blockSize: z.number().optional(),
+    seed: z.union([z.string(), z.number()]).optional(),
+    numTrials: z.number().optional(),
+    sharpeStd: z.number().optional(),
+    skew: z.number().optional(),
+    kurtosis: z.number().optional(),
+    backtestOptions: z.record(z.string(), z.any()).optional(),
+  },
+  optimize_strategy: {
+    candles: z.array(candle).optional(),
+    data: dataSpec.optional(),
+    symbol: z.string().optional(),
+    interval: z.string().optional(),
+    strategy: z.string(),
+    grid: z.record(z.string(), z.array(z.any())).optional(),
+    scoreBy: z.string().optional(),
+    backtestOptions: z.record(z.string(), z.any()).optional(),
+  },
+  compare_strategies: {
+    candles: z.array(candle).optional(),
+    data: dataSpec.optional(),
+    symbol: z.string().optional(),
+    interval: z.string().optional(),
+    strategies: z.array(
+      z.object({
+        strategy: z.string(),
+        params: z.record(z.string(), z.any()).optional(),
+      })
+    ),
+    scoreBy: z.string().optional(),
+    backtestOptions: z.record(z.string(), z.any()).optional(),
+  },
+  candle_stats: {
+    candles: z.array(candle).optional(),
+    data: dataSpec.optional(),
+  },
+
+  // Live trading tools
+  create_session: {
+    sessionId: z.string(),
+    symbol: z.string(),
+    mode: sessionMode,
+    interval: z.string().optional(),
+    equity: z.number().optional(),
+    riskPct: z.number().optional(),
+    maxDailyLossPct: z.number().optional(),
+    confirmLive: z.boolean().optional(),
+  },
+  list_sessions: {},
+  session_status: {
+    sessionId: z.string(),
+  },
+  feed_price: {
+    sessionId: z.string(),
+    bar: barShape.optional(),
+    price: z.number().optional(),
+  },
+  place_order: {
+    sessionId: z.string(),
+    side: orderSide,
+    type: orderType,
+    qty: z.number().optional(),
+    riskPct: z.number().optional(),
+    stop: z.number().optional(),
+    target: z.number().optional(),
+    rr: z.number().optional(),
+    limitPrice: z.number().optional(),
+  },
+  close_position: {
+    sessionId: z.string(),
+    symbol: z.string().optional(),
+  },
+  flatten: {
+    sessionId: z.string(),
+  },
+  cancel_order: {
+    sessionId: z.string(),
+    orderId: z.string(),
+  },
+  account: {
+    sessionId: z.string(),
+  },
+  positions: {
+    sessionId: z.string(),
+  },
+  recent_events: {
+    sessionId: z.string(),
+    limit: z.number().optional(),
+  },
+  attach_strategy: {
+    sessionId: z.string(),
+    strategy: z.string(),
+    params: z.record(z.string(), z.any()).optional(),
+  },
+  halt_all: {},
 };

package/src/mcp/server.js

@@ -1,11 +1,15 @@
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { mcpTools } from "./tools.js";
 import { schemas } from "./schemas.js";
 
+const _require = createRequire(import.meta.url);
+const { version } = _require("../../package.json");
+
 /** Build (but do not start) an McpServer with all tradelab tools registered. */
 export function createServer() {
-  const server = new McpServer({ name: "tradelab", version: "1.1.0" });
+  const server = new McpServer({ name: "tradelab", version });
 
   for (const [name, def] of Object.entries(mcpTools)) {
     server.tool(name, def.description, schemas[name] ?? {}, async (args) => {

package/src/mcp/tools.js

@@ -1,7 +1,10 @@
 import { backtest } from "../engine/backtest.js";
 import { walkForwardOptimize } from "../engine/walkForward.js";
-import { getHistoricalCandles } from "../data/index.js";
+import { getHistoricalCandles, candleStats } from "../data/index.js";
 import { getStrategy, listStrategies } from "../strategies/index.js";
+import { grid } from "../engine/grid.js";
+import { monteCarlo, deflatedSharpe } from "../research/index.js";
+import { liveTools } from "./liveTools.js";
 
 function summarizeMetrics(metrics) {
   const {
@@ -57,7 +60,7 @@ function expandGrid(grid) {
   );
 }
 
-export const mcpTools = {
+export const researchTools = {
   list_strategies: {
     description: "List built-in trading strategies with their tunable parameters.",
     handler: async () => ({ strategies: listStrategies() }),
@@ -140,3 +143,123 @@ export const mcpTools = {
     },
   },
 };
+
+export const researchPlusTools = {
+  analyze_robustness: {
+    description:
+      "Run a backtest on a named strategy then Monte Carlo + Deflated Sharpe on the realized trade PnLs. Degrades gracefully if fewer than 2 trades.",
+    handler: async (args) => {
+      const candles = await resolveCandles(args);
+      const factory = getStrategy(args.strategy);
+      const signal = factory(args.params || {});
+      const result = backtest({
+        candles,
+        symbol: args.symbol ?? "UNKNOWN",
+        interval: args.interval,
+        signal,
+        collectReplay: false,
+        warmupBars: 0,
+        ...(args.backtestOptions || {}),
+      });
+      const metrics = summarizeMetrics(result.metrics);
+      const tradePnls = result.positions.map((p) => p.exit.pnl);
+      if (tradePnls.length < 2) {
+        return {
+          metrics,
+          monteCarlo: null,
+          deflatedSharpe: null,
+          note: `Only ${tradePnls.length} trade(s) — need at least 2 for statistical analysis.`,
+        };
+      }
+      const mc = monteCarlo({
+        tradePnls,
+        equityStart: args.equityStart ?? 10_000,
+        iterations: args.iterations ?? 1000,
+        blockSize: args.blockSize ?? 1,
+        seed: args.seed ?? "tradelab-mc",
+      });
+      const dsr = deflatedSharpe({
+        sharpe: result.metrics.sharpe,
+        sampleSize: result.metrics.trades,
+        numTrials: args.numTrials ?? 1,
+        sharpeStd: args.sharpeStd ?? 0,
+        skew: args.skew ?? 0,
+        kurtosis: args.kurtosis ?? 3,
+      });
+      return { metrics, monteCarlo: mc, deflatedSharpe: dsr };
+    },
+  },
+
+  optimize_strategy: {
+    description:
+      "In-process grid sweep of a named strategy. Returns a leaderboard ranked by a chosen metric (default: profitFactor).",
+    handler: async (args) => {
+      const candles = await resolveCandles(args);
+      const factory = getStrategy(args.strategy);
+      const scoreBy = args.scoreBy ?? "profitFactor";
+      const paramSets = grid(args.grid || {});
+      const rows = paramSets.map((params) => {
+        const signal = factory(params);
+        const result = backtest({
+          candles,
+          symbol: args.symbol ?? "UNKNOWN",
+          interval: args.interval,
+          signal,
+          collectReplay: false,
+          ...(args.backtestOptions || {}),
+        });
+        const raw = result.metrics[scoreBy];
+        const score = Number.isFinite(raw) ? raw : -Infinity;
+        return { params, score, metrics: summarizeMetrics(result.metrics) };
+      });
+      rows.sort((a, b) => b.score - a.score);
+      return { leaderboard: rows, best: rows[0] ?? null };
+    },
+  },
+
+  compare_strategies: {
+    description:
+      "Run several named strategies on the same candle dataset and return a ranked comparison.",
+    handler: async (args) => {
+      const candles = await resolveCandles(args);
+      const scoreBy = args.scoreBy ?? "profitFactor";
+      const entries = args.strategies ?? [];
+      const rows = entries.map(({ strategy, params }) => {
+        const factory = getStrategy(strategy);
+        const signal = factory(params || {});
+        const result = backtest({
+          candles,
+          symbol: args.symbol ?? "UNKNOWN",
+          interval: args.interval,
+          signal,
+          collectReplay: false,
+          ...(args.backtestOptions || {}),
+        });
+        const raw = result.metrics[scoreBy];
+        const score = Number.isFinite(raw) ? raw : -Infinity;
+        return { strategy, params: params ?? {}, score, metrics: summarizeMetrics(result.metrics) };
+      });
+      rows.sort((a, b) => b.score - a.score);
+      return { rankedBy: scoreBy, results: rows };
+    },
+  },
+
+  candle_stats: {
+    description:
+      "Return shape statistics (count, date range, price range, estimated interval) for an inline candle array or a data spec. Useful for sanity-checking data before backtesting.",
+    handler: async (args) => {
+      const candles = await resolveCandles(args);
+      const stats = candleStats(candles);
+      if (!stats) {
+        return { stats: null, note: "No candles returned." };
+      }
+      const gapNote =
+        stats.estimatedIntervalMin > 0
+          ? `Estimated bar interval ~${stats.estimatedIntervalMin} min.`
+          : "Could not estimate interval.";
+      return { stats, note: gapNote };
+    },
+  },
+};
+
+export const mcpTools = { ...researchTools, ...researchPlusTools, ...liveTools };

package/src/research/monteCarlo.js

@@ -35,6 +35,10 @@ export function monteCarlo({
   if (!Array.isArray(tradePnls) || tradePnls.length === 0) {
     throw new Error("monteCarlo() requires a non-empty tradePnls array");
   }
+  const runCount = Math.floor(Number(iterations));
+  if (!Number.isFinite(runCount) || runCount < 1) {
+    throw new Error("monteCarlo() requires positive iterations");
+  }
   const rng = makeRng(seed);
   const n = tradePnls.length;
   const block = Math.max(1, Math.floor(blockSize));
@@ -43,7 +47,7 @@ export function monteCarlo({
   const drawdowns = [];
   const pathSamples = Array.from({ length: n + 1 }, () => []);
 
-  for (let it = 0; it < iterations; it += 1) {
+  for (let it = 0; it < runCount; it += 1) {
     const path = [equityStart];
     let equity = equityStart;
     let filled = 0;
@@ -78,7 +82,7 @@ export function monteCarlo({
   });
 
   return {
-    iterations,
+    iterations: runCount,
     blockSize: block,
     finalEquity: bands(sortedFinals),
     maxDrawdown: bands(sortedDd),