canli-backtest-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arhan Canli / Canli Capital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# canli-backtest-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Backtests an AI agent can trust. An MCP server that builds **point-in-time factors from SEC
+filings**, runs **cross-sectional backtests of any signal on your own prices** with **no lookahead**
+(enforced in code), charges **costs on the actual trades**, and records **every variant in a trial
+ledger**, so the best of a search is judged against the whole search instead of alone.
+
+Local stdio only: your prices, signals and ledgers never leave your machine.
+
+## Why
+
+Three mistakes make most agent-run backtests look better than they are:
+
+1. **Lookahead.** Using a number before it was public: an annual figure in January that was filed in
+   February, or a value that was later restated. `pit_factor` only uses what had been filed with the
+   SEC by each date, as it stood then; `backtest_signal` only trades on signal rows dated at least
+   `lag_days` trading days earlier, and stops if anything reaches past that.
+2. **Free trading.** Ignoring turnover. Positions drift with prices between rebalances, and costs are
+   charged on the trades from those drifted positions to the new targets.
+3. **Counting only the winner.** An agent tries 200 variants and reports the best. With `ledger`,
+   every run is recorded (in canli-validation-mcp's hash-chained ledger), and each reply gives the
+   best run's deflated Sharpe after counting all of them, and the Sharpe that luck alone reaches.
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `list_factors` | The factors `pit_factor` builds and what each measures. |
+| `pit_factor` | A factor (`roa`, `gross_margin`, `operating_margin`, `revenue_growth`, `asset_growth`, `accruals`, or `level:<measure>`) for your tickers, monthly, as known on each date. Writes a signal CSV. |
+| `backtest_signal` | Rank on the signal, long the top quantile (and short the bottom), rebalance weekly, monthly, quarterly or every N days, with `lag_days`, `cost_bps` and an optional `ledger`. |
+
+## Quick start
+
+```bash
+npx -y canli-backtest-mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add canli-backtest -- npx -y canli-backtest-mcp
+```
+
+Then ask: *"Build roa for these 200 tickers from 2015 to 2024, backtest it monthly on prices.csv with
+10 bps costs, try quantiles 0.1, 0.2 and 0.3 in the ledger 'roa-search', and tell me whether the best
+one survives the search."*
+
+## Files
+
+Both files are CSV with a `date` column (YYYY-MM-DD) and one column per ticker:
+
+- **prices**: closing prices, one row per trading day. Bring your own; adjust for splits and dividends
+  if you want total returns. The server does not supply prices (vendor licences forbid passing them on).
+- **signal**: one row per date the values became known. `pit_factor` writes this; your own signal works
+  too, as long as each row is dated by when it was available.
+
+Empty cells are missing values, never zero.
+
+## What a result does not establish
+
+- Prices are yours: survivorship, splits, dividends and data errors in them pass straight into the result.
+- A backtest measures one path of history under these costs; it does not establish that the signal keeps working.
+- Costs are a flat rate per unit traded; market impact, short-borrow fees and financing are not charged unless included in `cost_bps`.
+- SEC values are what companies reported in XBRL, as filed; late filers, non-XBRL filers and tag changes can be missing.
+
+## Configuration
+
+| variable | default | meaning |
+|---|---|---|
+| `CANLI_LEDGER_DIR` | `~/.canli/ledgers` | where ledgers are kept (shared with canli-validation-mcp) |
+| `CANLI_CACHE_DIR` | `~/.cache/canli-fundamentals` | SEC data cache |
+
+## Part of the Canli Capital MCP family
+
+[canli-validation-mcp](https://www.npmjs.com/package/canli-validation-mcp) (validators and the trial
+ledger), [canli-fundamentals-mcp](https://www.npmjs.com/package/canli-fundamentals-mcp) (SEC fundamentals
+point in time), [canli-research-mcp](https://www.npmjs.com/package/canli-research-mcp) (the open research
+record). Source: [github.com/arhancanli/canlicapital](https://github.com/arhancanli/canlicapital/tree/main/mcp-backtest).
+MIT licensed. Built by Arhan Canli.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "canli-backtest-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for backtests that refuse lookahead: point-in-time factors from SEC filings, cross-sectional backtests of any signal on your own prices, costs on actual trades, and every variant counted in a trial ledger.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "canli-backtest-mcp": "src/server.mjs"
+  },
+  "engines": {
+    "node": ">=20.10"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.3.1",
+    "canli-fundamentals-mcp": "^0.5.0",
+    "canli-validation-mcp": "file:../mcp",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1"
+  },
+  "mcpName": "io.github.arhancanli/canli-backtest-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arhancanli/canlicapital.git",
+    "directory": "mcp-backtest"
+  },
+  "homepage": "https://canlicapital.com/mcp-servers",
+  "bugs": {
+    "url": "https://github.com/arhancanli/canlicapital/issues"
+  },
+  "keywords": ["mcp", "model-context-protocol", "backtesting", "quant", "quantitative-finance", "point-in-time", "sec", "xbrl", "lookahead-bias", "deflated-sharpe", "overfitting", "factor-investing", "ai-agents"]
+}

package/src/engine.mjs

@@ -0,0 +1,164 @@
+// mcp-backtest/src/engine.mjs
+//
+// A cross-sectional backtest of any signal against prices the caller supplies, built so the usual
+// ways to fool yourself are refused in code:
+//
+// - Each signal row is dated when it became KNOWN. A trade on day t uses only signal rows dated at
+//   least lag_days trading days before t; every rebalance records the signal date it used, and the
+//   run stops if one ever reaches past that bound.
+// - Positions drift with prices between rebalances. Turnover and costs are charged on the actual
+//   trades from drifted positions to targets, not on an idealized daily rebalance.
+// - A held name with no price on a day earns nothing that day and is counted; nothing is filled in.
+//
+// Pure: no files, no network. Inputs are aligned arrays; series-io.mjs reads CSV files into them.
+
+export const ENGINE_LIMITS_TEXT = Object.freeze([
+  "Prices are the caller's: survivorship, splits, dividends and data errors in them pass straight into the result.",
+  "A backtest measures one path of history under these costs; it does not establish that the signal will keep working.",
+  "Costs are a flat rate per unit traded; market impact, borrow fees for shorts and financing are not charged unless included in cost_bps.",
+]);
+
+const REBALANCE = Object.freeze({ weekly: "week", monthly: "month", quarterly: "quarter" });
+const periodKey = (date, every) => {
+  const [y, m] = date.split("-").map(Number);
+  if (every === "month") return `${y}-${m}`;
+  if (every === "quarter") return `${y}-Q${Math.ceil(m / 3)}`;
+  const d = new Date(`${date}T00:00:00Z`); // ISO week: Thursday's year and week number
+  d.setUTCDate(d.getUTCDate() + 3 - ((d.getUTCDay() + 6) % 7));
+  const jan4 = new Date(Date.UTC(d.getUTCFullYear(), 0, 4));
+  return `${d.getUTCFullYear()}-W${1 + Math.round(((d - jan4) / 86400000 - 3 + ((jan4.getUTCDay() + 6) % 7)) / 7)}`;
+};
+
+// Indices of the first trading day of each period (or every N days from the first usable day).
+export function rebalanceIndices(dates, rebalance, start = 0) {
+  const out = [];
+  if (Number.isInteger(rebalance)) {
+    if (rebalance < 1) throw new RangeError("rebalance as a number of days must be at least 1");
+    for (let i = start; i < dates.length; i += rebalance) out.push(i);
+    return out;
+  }
+  const every = REBALANCE[rebalance];
+  if (!every) throw new RangeError(`rebalance must be weekly, monthly, quarterly or a whole number of trading days; got ${JSON.stringify(rebalance)}`);
+  let last = null;
+  for (let i = start; i < dates.length; i += 1) {
+    const key = periodKey(dates[i], every);
+    if (key !== last) { out.push(i); last = key; }
+  }
+  return out;
+}
+
+const finite = (x) => typeof x === "number" && Number.isFinite(x);
+
+function checkInputs({ dates, tickers, prices, signalDates, signals }) {
+  if (!Array.isArray(dates) || dates.length < 3) throw new RangeError("prices need at least 3 dates");
+  for (let i = 1; i < dates.length; i += 1) if (!(dates[i] > dates[i - 1])) throw new RangeError(`price dates must be strictly increasing; ${dates[i - 1]} then ${dates[i]}`);
+  for (let i = 1; i < signalDates.length; i += 1) if (!(signalDates[i] > signalDates[i - 1])) throw new RangeError(`signal dates must be strictly increasing; ${signalDates[i - 1]} then ${signalDates[i]}`);
+  if (!tickers.length) throw new RangeError("no ticker appears in both the prices and the signal");
+  for (const t of tickers) {
+    if (prices[t]?.length !== dates.length) throw new RangeError(`prices for ${t} are not aligned with the price dates`);
+    if (signals[t]?.length !== signalDates.length) throw new RangeError(`signal for ${t} is not aligned with the signal dates`);
+  }
+}
+
+// The latest signal row dated on or before `bound` (binary search), or -1.
+function lastRowOnOrBefore(signalDates, bound) {
+  let lo = 0, hi = signalDates.length - 1, found = -1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (signalDates[mid] <= bound) { found = mid; lo = mid + 1; } else hi = mid - 1;
+  }
+  return found;
+}
+
+export function runBacktest({ dates, tickers, prices, signalDates, signals, rebalance = "monthly", lagDays = 1, side = "long_short", quantile = 0.2, costBps = 10, minNames = 5, periodsPerYear = 252 }) {
+  checkInputs({ dates, tickers, prices, signalDates, signals });
+  if (!Number.isInteger(lagDays) || lagDays < 1) throw new RangeError("lag_days must be a whole number of at least 1: a signal cannot trade on the day it becomes known");
+  if (!(quantile > 0 && quantile <= 0.5)) throw new RangeError("quantile must be in (0, 0.5]");
+  if (!["long_short", "long_only"].includes(side)) throw new RangeError("side must be long_short or long_only");
+  if (!(costBps >= 0)) throw new RangeError("cost_bps cannot be negative");
+
+  const n = dates.length;
+  const rebal = new Set(rebalanceIndices(dates, rebalance, lagDays));
+  let nav = 1;
+  let pos = new Map(); // ticker -> signed value (fraction of starting capital, drifts with price)
+  const out = { dates: [], returns: [] };
+  const used = []; // { trade_date, signal_date }
+  let pendingCost = 1; // the first rebalance's cost, charged on the first recorded day
+  let started = false, turnoverSum = 0, costSum = 0, rebalances = 0, missingDays = 0, longNames = 0, shortNames = 0;
+
+  for (let t = 1; t < n; t += 1) {
+    // 1. Positions earn day t's return.
+    if (started) {
+      let pnl = 0;
+      for (const [tk, v] of pos) {
+        const a = prices[tk][t - 1], b = prices[tk][t];
+        if (finite(a) && finite(b) && a > 0) { const r = b / a - 1; pnl += v * r; pos.set(tk, v * (1 + r)); }
+        else missingDays += 1;
+      }
+      const before = nav;
+      nav += pnl;
+      out.dates.push(dates[t]);
+      out.returns.push((1 + (before > 0 ? pnl / before : 0)) * pendingCost - 1);
+      pendingCost = 1;
+    }
+    // 2. Rebalance at the close of day t, on signals known lagDays trading days earlier.
+    if (!rebal.has(t) || t - lagDays < 0) continue;
+    const bound = dates[t - lagDays];
+    const row = lastRowOnOrBefore(signalDates, bound);
+    if (row < 0) continue;
+    if (!(signalDates[row] < dates[t])) throw new Error(`causality violated: a trade on ${dates[t]} would use a signal dated ${signalDates[row]}`);
+    const ranked = tickers
+      .filter((tk) => finite(signals[tk][row]) && finite(prices[tk][t]) && prices[tk][t] > 0)
+      .sort((x, y) => signals[y][row] - signals[x][row] || (x < y ? -1 : 1));
+    const k = Math.floor(ranked.length * quantile);
+    if (k < 1 || ranked.length < minNames) continue;
+    const target = new Map();
+    const long = ranked.slice(0, k), short = side === "long_short" ? ranked.slice(-k) : [];
+    for (const tk of long) target.set(tk, nav / long.length);
+    for (const tk of short) target.set(tk, (target.get(tk) ?? 0) - nav / short.length);
+    let traded = 0;
+    for (const tk of new Set([...pos.keys(), ...target.keys()])) traded += Math.abs((target.get(tk) ?? 0) - (pos.get(tk) ?? 0));
+    const cost = traded * costBps / 1e4;
+    nav -= cost;
+    const factor = 1 - cost / (nav + cost);
+    if (started && out.returns.length) {
+      const last = out.returns.length - 1; // cost is charged on the rebalance day's return
+      out.returns[last] = (1 + out.returns[last]) * factor - 1;
+    } else pendingCost = factor;
+    pos = new Map([...target].filter(([, v]) => v !== 0));
+    turnoverSum += traded / (nav + cost);
+    costSum += cost;
+    rebalances += 1; longNames += long.length; shortNames += short.length;
+    used.push({ trade_date: dates[t], signal_date: signalDates[row] });
+    started = true;
+  }
+  if (!rebalances) throw new RangeError("no rebalance had enough names with both a known signal and a price; check the dates overlap and min_names");
+  return { ...out, used, nav, rebalances, turnoverSum, costSum, missingDays, longNames, shortNames, periodsPerYear };
+}
+
+// Plain statistics of a return series, in the same Sharpe convention as the validators (sample sd).
+export function describe(result) {
+  const r = result.returns;
+  const m = r.length;
+  const mean = r.reduce((a, b) => a + b, 0) / m;
+  const sd = Math.sqrt(r.reduce((a, b) => a + (b - mean) ** 2, 0) / Math.max(1, m - 1));
+  let peak = 1, wealth = 1, maxDd = 0;
+  for (const x of r) { wealth *= 1 + x; peak = Math.max(peak, wealth); maxDd = Math.max(maxDd, 1 - wealth / peak); }
+  const years = m / result.periodsPerYear;
+  const gaps = result.used.map((u) => (Date.parse(u.trade_date) - Date.parse(u.signal_date)) / 86400000);
+  return {
+    first_date: result.dates[0], last_date: result.dates.at(-1), days: m,
+    total_return: wealth - 1,
+    annualized_return: years > 0 ? wealth ** (1 / years) - 1 : null,
+    annualized_volatility: sd * Math.sqrt(result.periodsPerYear),
+    sharpe_annualized: sd > 0 ? (mean / sd) * Math.sqrt(result.periodsPerYear) : null,
+    max_drawdown: maxDd,
+    rebalances: result.rebalances,
+    turnover_per_year: years > 0 ? result.turnoverSum / years : null,
+    cost_paid: result.costSum,
+    average_long_names: result.longNames / result.rebalances,
+    average_short_names: result.shortNames / result.rebalances,
+    missing_price_days: result.missingDays,
+    causality: { checked_rebalances: result.used.length, min_days_signal_to_trade: Math.min(...gaps), first: result.used.slice(0, 3) },
+  };
+}

package/src/panel-io.mjs

@@ -0,0 +1,67 @@
+// mcp-backtest/src/panel-io.mjs
+//
+// Reads and writes panels: a CSV with a `date` column (YYYY-MM-DD) and one column per ticker, one
+// row per date. Prices are closes; a signal row is dated when its values became known. Empty cells
+// are missing values (null), never zero. Files are read on this machine; nothing is uploaded.
+import { readFileSync, writeFileSync } from "node:fs";
+
+export const MAX_PANEL_BYTES = 64 * 1024 * 1024;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+function splitLine(line) {
+  const out = [];
+  let cell = "", quoted = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const c = line[i];
+    if (quoted) {
+      if (c === '"' && line[i + 1] === '"') { cell += '"'; i += 1; }
+      else if (c === '"') quoted = false;
+      else cell += c;
+    } else if (c === '"') quoted = true;
+    else if (c === ",") { out.push(cell); cell = ""; }
+    else cell += c;
+  }
+  out.push(cell);
+  return out.map((s) => s.trim());
+}
+
+export function parsePanel(text, name = "panel") {
+  const lines = text.replace(/^/, "").split(/\r?\n/).filter((l) => l.trim() !== "");
+  if (lines.length < 2) throw new RangeError(`${name} needs a header row and at least one data row`);
+  const header = splitLine(lines[0]);
+  if (header[0].toLowerCase() !== "date") throw new RangeError(`${name}'s first column must be "date"; got ${JSON.stringify(header[0])}`);
+  const tickers = header.slice(1);
+  if (!tickers.length) throw new RangeError(`${name} has no ticker columns`);
+  const dupe = tickers.find((t, i) => tickers.indexOf(t) !== i);
+  if (dupe) throw new RangeError(`${name} names the column ${dupe} twice`);
+  const dates = [];
+  const values = Object.fromEntries(tickers.map((t) => [t, []]));
+  for (let r = 1; r < lines.length; r += 1) {
+    const cells = splitLine(lines[r]);
+    const date = cells[0];
+    if (!DATE.test(date)) throw new RangeError(`${name} row ${r + 1}: date ${JSON.stringify(date)} is not YYYY-MM-DD`);
+    if (dates.length && !(date > dates.at(-1))) throw new RangeError(`${name} row ${r + 1}: dates must be strictly increasing (${dates.at(-1)} then ${date})`);
+    dates.push(date);
+    tickers.forEach((t, i) => {
+      const raw = cells[i + 1] ?? "";
+      if (raw === "" || /^(na|nan|null)$/i.test(raw)) { values[t].push(null); return; }
+      const x = Number(raw);
+      if (!Number.isFinite(x)) throw new RangeError(`${name} row ${r + 1}, column ${t}: ${JSON.stringify(raw)} is not a number`);
+      values[t].push(x);
+    });
+  }
+  return { dates, tickers, values };
+}
+
+// One read, then the size check on the bytes actually read (no check-then-read window).
+export function readPanel(path, name) {
+  const bytes = readFileSync(path);
+  if (bytes.length > MAX_PANEL_BYTES) throw new RangeError(`${path} is ${bytes.length} bytes; the limit is ${MAX_PANEL_BYTES}`);
+  return parsePanel(bytes.toString("utf8"), name ?? path);
+}
+
+export function writePanel(path, { dates, tickers, values }) {
+  const rows = [["date", ...tickers].join(",")];
+  dates.forEach((d, i) => rows.push([d, ...tickers.map((t) => (values[t][i] === null || values[t][i] === undefined ? "" : String(values[t][i])))].join(",")));
+  writeFileSync(path, rows.join("\n") + "\n");
+}

package/src/pit.mjs

@@ -0,0 +1,94 @@
+// mcp-backtest/src/pit.mjs
+//
+// Point-in-time factors from SEC XBRL data: for each company and each date, only values whose
+// filing had reached EDGAR on or before that date, each as it stood then (later restatements are
+// not visible earlier). Data and selection come from canli-fundamentals-mcp (loadCompany,
+// resolveSeries); the rule here is the one its cross_section and known_as_of tools use.
+//
+// A ratio pairs numerator and denominator from the same fiscal period; growth compares a fiscal
+// year with the one before it, both as known on the date. A signal row is dated with the date it
+// was known, so pass it to backtest_signal with lag_days of at least 1.
+
+export const FACTORS = Object.freeze({
+  roa: { needs: ["net_income", "assets"], meaning: "net income / total assets, same fiscal year" },
+  gross_margin: { needs: ["gross_profit", "revenue"], meaning: "gross profit / revenue, same fiscal year" },
+  operating_margin: { needs: ["operating_income", "revenue"], meaning: "operating income / revenue, same fiscal year" },
+  revenue_growth: { needs: ["revenue"], meaning: "latest fiscal-year revenue / the year before - 1" },
+  asset_growth: { needs: ["assets"], meaning: "latest fiscal-year total assets / the year before - 1" },
+  accruals: { needs: ["net_income", "operating_cash_flow", "assets"], meaning: "(net income - operating cash flow) / total assets, same fiscal year" },
+});
+
+export const PIT_LIMITS_TEXT = Object.freeze([
+  "Values are what companies reported to the SEC in XBRL, as filed by each date; a company that files late, files outside XBRL or changes its tags can be missing.",
+  "Ticker symbols are resolved to today's SEC assignment; a ticker reused by another company maps to the current holder, so check the matched names.",
+]);
+
+// Annual periods of one series known on `asOf`, newest first: [{ end, val, filed, accn }].
+export function annualAsOf(series, asOf) {
+  const out = [];
+  for (const p of series.periods) {
+    if (p.kind !== "annual") continue;
+    let v = null;
+    for (const x of p.vintages) if (x.filed <= asOf) v = x; // vintages are oldest first
+    if (v) out.push({ end: p.end, val: v.val, filed: v.filed, accn: v.accn });
+  }
+  return out.sort((a, b) => (a.end < b.end ? 1 : -1));
+}
+
+const byEnd = (rows, end) => rows.find((r) => r.end === end) ?? null;
+const ratio = (a, b) => (a && b && b.val !== 0 ? a.val / b.val : null);
+
+// series: { name -> resolved series } for one company. Returns the factor value known on asOf.
+export function factorAsOf(factor, series, asOf) {
+  if (factor.startsWith("level:")) {
+    const s = series[factor.slice(6)];
+    return s ? annualAsOf(s, asOf)[0]?.val ?? null : null;
+  }
+  const known = Object.fromEntries(Object.entries(series).map(([k, s]) => [k, annualAsOf(s, asOf)]));
+  switch (factor) {
+    case "roa": { const n = known.net_income?.[0]; return n ? ratio(n, byEnd(known.assets ?? [], n.end)) : null; }
+    case "gross_margin": { const g = known.gross_profit?.[0]; return g ? ratio(g, byEnd(known.revenue ?? [], g.end)) : null; }
+    case "operating_margin": { const o = known.operating_income?.[0]; return o ? ratio(o, byEnd(known.revenue ?? [], o.end)) : null; }
+    case "revenue_growth": case "asset_growth": {
+      const rows = known[factor === "revenue_growth" ? "revenue" : "assets"] ?? [];
+      return rows.length >= 2 && rows[1].val !== 0 ? rows[0].val / rows[1].val - 1 : null;
+    }
+    case "accruals": {
+      const n = known.net_income?.[0];
+      if (!n) return null;
+      const c = byEnd(known.operating_cash_flow ?? [], n.end), a = byEnd(known.assets ?? [], n.end);
+      return c && a && a.val !== 0 ? (n.val - c.val) / a.val : null;
+    }
+    default: throw new RangeError(`unknown factor ${JSON.stringify(factor)}; choose from ${Object.keys(FACTORS).join(", ")} or level:<measure>`);
+  }
+}
+
+export function factorNeeds(factor) {
+  if (factor.startsWith("level:")) return [factor.slice(6)];
+  const f = FACTORS[factor];
+  if (!f) throw new RangeError(`unknown factor ${JSON.stringify(factor)}; choose from ${Object.keys(FACTORS).join(", ")} or level:<measure>`);
+  return f.needs;
+}
+
+// Builds the panel. loadSeries(ticker, names) -> { matchedName, series: { name -> series } } or throws.
+export async function buildFactorPanel({ factor, tickers, dates, loadSeries, parallel = 4 }) {
+  const needs = factorNeeds(factor);
+  const values = Object.fromEntries(tickers.map((t) => [t, dates.map(() => null)]));
+  const matched = {}, missing = {};
+  let next = 0;
+  const worker = async () => {
+    while (next < tickers.length) {
+      const t = tickers[next++];
+      try {
+        const { matchedName, series } = await loadSeries(t, needs);
+        matched[t] = matchedName;
+        dates.forEach((d, i) => { values[t][i] = factorAsOf(factor, series, d); });
+      } catch (err) {
+        missing[t] = String(err.message ?? err).split(". ")[0];
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(parallel, tickers.length) }, worker));
+  const coverage = dates.map((d, i) => ({ date: d, companies_with_value: tickers.filter((t) => values[t][i] !== null).length }));
+  return { dates, tickers, values, matched, missing, coverage };
+}

package/src/server.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// canli-backtest-mcp: backtests an agent can trust. Point-in-time factors from SEC filings, a
+// cross-sectional backtest of any signal against prices the caller supplies (a trade only ever uses
+// what was known before it), costs and turnover on the actual trades, and every variant recorded in
+// a trial ledger so the best of a search is judged against the whole search.
+//
+// Local stdio only: prices, signals and ledgers stay on this machine. Point-in-time SEC data comes
+// from canli-fundamentals-mcp (cached under ~/.cache/canli-fundamentals); the ledger is
+// canli-validation-mcp's (files under ~/.canli/ledgers), so both servers read the same searches.
+import { mkdtempSync, readFileSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
+import { createSession as fundamentalsSession, loadCompany, resolveSeries } from "canli-fundamentals-mcp/src/server.mjs";
+import { ledgerDir, recordTrial } from "canli-validation-mcp/src/ledger.mjs";
+
+import { ENGINE_LIMITS_TEXT, describe, runBacktest } from "./engine.mjs";
+import { readPanel, writePanel } from "./panel-io.mjs";
+import { FACTORS, PIT_LIMITS_TEXT, buildFactorPanel } from "./pit.mjs";
+
+export const SERVER_NAME = "canli-backtest-mcp";
+export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const SERVER_INSTRUCTIONS = "Backtests that refuse lookahead. Build a point-in-time factor from SEC filings with pit_factor (or bring your own signal CSV, each row dated when it was known), then run backtest_signal against your own prices CSV. Pass the same ledger name to every backtest_signal call in one search: the reply judges the best variant against all of them.";
+export const SERVER_INFO = Object.freeze({
+  name: SERVER_NAME,
+  version: SERVER_VERSION,
+  title: "Canli Backtest",
+  websiteUrl: "https://canlicapital.com/mcp-servers",
+  icons: [
+    { src: "https://canlicapital.com/icon-512.png", mimeType: "image/png", sizes: ["512x512"] },
+    { src: "https://canlicapital.com/favicon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
+  ],
+});
+
+const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value });
+const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date as YYYY-MM-DD");
+
+export function createSession({ fundamentals, ledger, outDir } = {}) {
+  return { fundamentals: fundamentals ?? fundamentalsSession(), ledgerDir: ledger ?? ledgerDir(), outDir: outDir ?? null };
+}
+
+// First trading day of each month in [start, end], from the weekday calendar (exchange holidays are
+// not modelled; the engine aligns signal rows to whatever price dates exist).
+export function monthStarts(start, end) {
+  const out = [];
+  const d = new Date(`${start}T00:00:00Z`);
+  let month = null;
+  while (d.toISOString().slice(0, 10) <= end) {
+    const iso = d.toISOString().slice(0, 10);
+    if (d.getUTCDay() % 6 !== 0 && iso.slice(0, 7) !== month) { out.push(iso); month = iso.slice(0, 7); }
+    d.setUTCDate(d.getUTCDate() + 1);
+  }
+  return out;
+}
+
+export const pitInput = z.object({
+  factor: z.string().describe(`One of ${Object.keys(FACTORS).join(", ")}, or level:<measure> (revenue, net_income, assets, ...).`),
+  tickers: z.array(z.string().min(1).max(20)).min(1).max(1000).describe("Tickers (or CIKs) to compute it for."),
+  start: date, end: date,
+  out_file: z.string().optional().describe("Where to write the signal CSV; default a new temporary file."),
+});
+export const backtestInput = z.object({
+  prices_file: z.string().describe("CSV: a date column (YYYY-MM-DD) and one column of closing prices per ticker."),
+  signal_file: z.string().describe("CSV in the same shape; each row dated when its values became known (pit_factor writes this)."),
+  rebalance: z.union([z.enum(["weekly", "monthly", "quarterly"]), z.number().int().min(1)]).optional().describe("Default monthly; or every N trading days."),
+  lag_days: z.number().int().min(1).optional().describe("Trading days between a signal becoming known and trading on it. Default 1, the minimum."),
+  side: z.enum(["long_short", "long_only"]).optional().describe("Default long_short: long the top quantile, short the bottom."),
+  quantile: z.number().gt(0).max(0.5).optional().describe("Fraction of ranked names in each leg. Default 0.2."),
+  cost_bps: z.number().min(0).optional().describe("Cost per unit traded, in basis points. Default 10."),
+  min_names: z.number().int().min(2).optional().describe("Skip a rebalance with fewer ranked names. Default 5."),
+  periods_per_year: z.number().positive().optional().describe("Default 252 (daily prices)."),
+  ledger: z.string().regex(/^[a-z0-9][a-z0-9-]{2,63}$/).optional().describe("Record this run in a search ledger (created if new) and judge it against every run recorded there."),
+  label: z.string().min(1).max(200).optional().describe("The variant's name in the ledger. Default: the settings."),
+});
+
+export const TOOL_DESCRIPTIONS = Object.freeze({
+  list_factors: "The point-in-time factors pit_factor builds from SEC filings, and what each measures.",
+  pit_factor: `Build a factor from SEC filings for a list of tickers, monthly from start to end, using only what had been filed by each date (restatements invisible until filed). Writes a signal CSV for backtest_signal. ${PIT_LIMITS_TEXT[0]}`,
+  backtest_signal: `Backtest a signal against your prices: rank, long and short quantiles, rebalance, trading only on what was known lag_days earlier, costs on actual trades. Pass ledger to judge the best of a search against all of it. ${ENGINE_LIMITS_TEXT[1]}`,
+});
+
+export async function toolPitFactor(session, args) {
+  const { factor, tickers, start, end, out_file } = pitInput.parse(args);
+  if (!(start < end)) throw new RangeError("start must be before end");
+  const dates = monthStarts(start, end);
+  const loadSeries = async (ticker, names) => {
+    const entry = await loadCompany(session.fundamentals, ticker);
+    const series = {};
+    for (const n of names) { try { series[n] = resolveSeries(entry, n); } catch { /* measure not reported */ } }
+    return { matchedName: entry.name, series };
+  };
+  const panel = await buildFactorPanel({ factor, tickers, dates, loadSeries });
+  const file = out_file ?? join(session.outDir ?? mkdtempSync(join(tmpdir(), "canli-pit-")), `${factor.replace(":", "-")}.csv`);
+  writePanel(file, panel);
+  const covered = panel.coverage.map((c) => c.companies_with_value);
+  return text({
+    factor, meaning: FACTORS[factor]?.meaning ?? `annual ${factor.slice(6)} as filed`, file,
+    dates: dates.length, tickers: tickers.length, first_date: dates[0], last_date: dates.at(-1),
+    coverage: { min: Math.min(...covered), median: covered.slice().sort((a, b) => a - b)[Math.floor(covered.length / 2)], max: Math.max(...covered) },
+    matched: panel.matched, ...(Object.keys(panel.missing).length ? { missing: panel.missing } : {}),
+    next: `backtest_signal with signal_file ${file} and your prices_file; lag_days 1 or more.`,
+    limits: PIT_LIMITS_TEXT,
+  });
+}
+
+export async function toolBacktestSignal(session, args) {
+  const a = backtestInput.parse(args);
+  const prices = readPanel(a.prices_file, "prices_file");
+  const signal = readPanel(a.signal_file, "signal_file");
+  const tickers = prices.tickers.filter((t) => signal.tickers.includes(t));
+  const cfg = { rebalance: a.rebalance ?? "monthly", lagDays: a.lag_days ?? 1, side: a.side ?? "long_short", quantile: a.quantile ?? 0.2, costBps: a.cost_bps ?? 10, minNames: a.min_names ?? 5, periodsPerYear: a.periods_per_year ?? 252 };
+  const result = runBacktest({ dates: prices.dates, tickers, prices: prices.values, signalDates: signal.dates, signals: signal.values, ...cfg });
+  const stats = describe(result);
+  const settings = { rebalance: cfg.rebalance, lag_days: cfg.lagDays, side: cfg.side, quantile: cfg.quantile, cost_bps: cfg.costBps, min_names: cfg.minNames };
+  let search = null;
+  if (a.ledger) {
+    const label = a.label ?? `${a.signal_file.split("/").pop()} ${cfg.side} q${cfg.quantile} ${cfg.rebalance} lag${cfg.lagDays} ${cfg.costBps}bps`;
+    const r = recordTrial(session.ledgerDir, { ledger: a.ledger, label, returns: result.returns, periods_per_year: cfg.periodsPerYear, params: { ...settings, signal_file: a.signal_file } });
+    search = { ledger: r.ledger, trial: r.trial, trials: r.trials, best: r.best, deflated: r.deflated, overfitting: r.overfitting, plain_reading: r.plain_reading };
+  }
+  const plain = `${stats.first_date} to ${stats.last_date}, ${tickers.length} tickers: annualized Sharpe ${stats.sharpe_annualized?.toFixed(2)}, return ${(100 * (stats.annualized_return ?? 0)).toFixed(1)}% a year, worst drawdown ${(100 * stats.max_drawdown).toFixed(1)}%, turnover ${stats.turnover_per_year?.toFixed(1)}x a year after ${cfg.costBps} bps costs. Every trade used signals at least ${stats.causality.min_days_signal_to_trade} calendar days old.`;
+  return text({ settings, tickers: tickers.length, ...stats, plain_reading: plain, ...(search ? { search } : {}), limits: ENGINE_LIMITS_TEXT });
+}
+
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const WRITES_LOCAL = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+
+export function registerTools(server, session) {
+  const catalog = {};
+  const tool = (name, title, input, annotations, handler) => {
+    server.registerTool(name, { title, annotations: { title, ...annotations }, description: TOOL_DESCRIPTIONS[name], inputSchema: input }, handler);
+    catalog[name] = { description: TOOL_DESCRIPTIONS[name], inputSchema: input };
+  };
+  tool("list_factors", "Point-in-time factors", z.object({}).strict(), READ_ONLY, async () => text({ factors: Object.fromEntries(Object.entries(FACTORS).map(([k, v]) => [k, v.meaning])), plus: "level:<measure> for any annual measure (revenue, net_income, assets, equity, operating_cash_flow, ...)", limits: PIT_LIMITS_TEXT }));
+  tool("pit_factor", "Build a point-in-time factor", pitInput, { ...WRITES_LOCAL, openWorldHint: true }, (args) => toolPitFactor(session, args));
+  tool("backtest_signal", "Backtest a signal without lookahead", backtestInput, WRITES_LOCAL, (args) => toolBacktestSignal(session, args));
+  return catalog;
+}
+
+const isMain = (() => {
+  try { return realpathSync(process.argv[1] ?? "") === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+})();
+
+if (isMain) {
+  const server = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
+  registerTools(server, createSession());
+  await server.connect(new StdioServerTransport());
+}