canli-validation-mcp 0.8.0 → 0.8.2

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Check whether a backtest is real: deflated Sharpe, CSCV probability of backtest overfitting, minimum track record and backtest length, haircut Sharpe and luck-equivalent trials, as an MCP server. Local mode, hosted endpoint, signed receipts.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "backtesting",
+    "backtest",
+    "deflated-sharpe-ratio",
+    "probability-of-backtest-overfitting",
+    "cscv",
+    "sharpe-ratio",
+    "overfitting",
+    "quantitative-finance",
+    "quant",
+    "trading"
+  ],
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/schemas.mjs

@@ -47,7 +47,7 @@ export const FIELD_DESCRIPTIONS = Object.freeze({
   autocorrelation: "First-order autocorrelation of the returns, -1 to 1; default 0. Corrects the annualized Sharpe as Lo (2002).",
   other_sharpes: "Annualized Sharpe ratios of the other tests, over the same observations; adds the Holm and BHY haircuts.",
   lt_trials: "Independent trials tried; adds the chance that the best of them reached this Sharpe by luck.",
-  skew: "Skewness of the returns; below -0.5 the reading warns that the counts are too generous.",
+  lt_skew: "Skewness of the returns; below -0.5 the reading warns that the counts are too generous.",
   variants: "Optional returns of every variant tried, this one included, as fractions: one row per period, one column per variant. Adds the overfitting check.",
   returns_file: "Path to a CSV or JSON file of the returns on the machine running this server, instead of returns. Not available on the hosted endpoint.",
   returns_column: "Header name or 1-based position of the returns column when returns_file has several numeric columns.",
@@ -108,7 +108,7 @@ export const deflatedSharpeToolShape = z
 
 export const overfittingInput = z
   .object({
-    matrix: z.array(z.array(z.number())).min(2).max(20000).describe(d.matrix),
+    matrix: z.array(z.array(z.number()).max(200)).min(2).max(20000).describe(d.matrix),
     n_splits: z.number().int().positive().optional().describe(d.n_splits),
     max_combinations: z.number().int().positive().max(2000).optional().describe(d.max_combinations),
     seed: z.number().optional().describe(d.seed),
@@ -192,7 +192,7 @@ export const luckTrialsInput = z
     periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
     observations: z.number().int().min(3).max(1000000).describe(d.hc_observations),
     effective_independent_trials: z.number().int().min(1).max(1000000000).optional().describe(d.lt_trials),
-    skew: z.number().min(-100).max(100).optional().describe(d.skew),
+    skew: z.number().min(-100).max(100).optional().describe(d.lt_skew),
     autocorrelation: z.number().gt(-1).lt(1).optional().describe(d.autocorrelation),
   })
   .strict();
@@ -212,7 +212,7 @@ export const auditBacktestToolShape = z
     cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).describe(d.cross_trial_sharpe_sd_annualized),
     benchmark_sharpe_annualized: z.number().min(-10).max(10).optional().describe(d.benchmark_sharpe_annualized),
     confidence: z.number().gt(0).lt(1).optional().describe(d.confidence),
-    variants: z.array(z.array(z.number())).min(2).max(20000).optional().describe(d.variants),
+    variants: z.array(z.array(z.number()).max(200)).min(2).max(20000).optional().describe(d.variants),
     variants_file: z.string().min(1).max(4096).optional().describe(d.variants_file),
     n_splits: z.number().int().positive().optional().describe(d.n_splits),
   })

package/src/series-file.mjs

@@ -41,6 +41,26 @@ function readText(path) {
 }
 
 const isNumber = (cell) => cell.trim() !== "" && Number.isFinite(Number(cell.trim()));
+// Cells a spreadsheet or pandas writes for a missing value.
+const isMissing = (cell) => /^(|nan|na|n\/a|#n\/a|null|none|-)$/i.test(cell.trim());
+const DATE = /^(\d{4}[-/.]\d{1,2}[-/.]\d{1,2}|\d{1,2}[-/.]\d{1,2}[-/.]\d{2,4})([ T].*)?$/;
+const kindOf = (cell) => (isNumber(cell) ? "number" : isMissing(cell) ? "missing" : DATE.test(cell.trim()) ? "date" : "text");
+
+// The first row is a header when one of its cells differs in kind from the cells below it: a label
+// above numbers or dates. A date above dates is data, so a file without a header keeps its first row.
+function hasHeader(first, below) {
+  if (!first.some((cell) => !isNumber(cell))) return false;
+  if (!below.length) return true;
+  return first.some((cell, j) => {
+    if (isNumber(cell)) return false;
+    // Missing values say nothing about what a column holds, so they do not vote.
+    const kinds = below.map((row) => kindOf(row[j] ?? "")).filter((k) => k !== "missing");
+    if (!kinds.length) return true;
+    const count = (k) => kinds.filter((x) => x === k).length;
+    const common = [...new Set(kinds)].sort((a, b) => count(b) - count(a))[0];
+    return kindOf(cell) !== common;
+  });
+}
 
 // A JSON array (of numbers, or of arrays of numbers), or delimited text: comma, semicolon or tab
 // separated, one row per line, with an optional header row naming the columns.
@@ -65,7 +85,7 @@ function parseTable(text, path) {
   const delimiter = [",", ";", "\t"].find((d) => lines[0].includes(d)) ?? ",";
   const split = (line) => line.split(delimiter).map((cell) => cell.trim());
   const first = split(lines[0]);
-  const header = first.some((cell) => !isNumber(cell)) ? first : null;
+  const header = hasHeader(first, lines.slice(1, 6).map(split)) ? first : null;
   const body = header ? lines.slice(1) : lines;
   const width = (header ?? first).length;
   const rows = body.map((line, i) => {
@@ -85,40 +105,58 @@ function isRowCounter(name, values) {
 }
 
 // Numeric columns only: a date or label column is dropped, never parsed; a row counter is skipped.
+// A column of numbers with some empty or NaN cells is not dropped: it is reported as incomplete, so
+// a blank cell can never make the reader pick a different column (a benchmark) in its place.
 function numericColumns({ header, rows }) {
   const width = rows[0]?.length ?? 0;
   const columns = [];
+  const incomplete = [];
   const skipped = [];
+  const offset = header ? 2 : 1; // file line of the first data row
   for (let j = 0; j < width; j += 1) {
-    if (rows.every((row) => typeof row[j] === "number" || isNumber(String(row[j])))) {
-      const values = rows.map((row) => Number(row[j]));
+    const cells = rows.map((row) => (typeof row[j] === "number" ? String(row[j]) : String(row[j])));
+    const numeric = cells.filter(isNumber).length;
+    if (numeric === cells.length) {
+      const values = cells.map(Number);
       if (isRowCounter(header ? header[j] : null, values)) skipped.push(j + 1);
       else columns.push({ index: j, name: header ? header[j] : String(j + 1), values });
+    } else if (numeric > 0 && numeric * 2 >= cells.length && cells.every((c) => isNumber(c) || isMissing(c))) {
+      const gaps = cells.map((c, i) => (isNumber(c) ? null : i + offset)).filter((i) => i !== null);
+      incomplete.push({ index: j, name: header ? header[j] : String(j + 1), gaps });
     }
   }
-  return { columns, skipped };
+  return { columns, incomplete, skipped };
 }
 
+const lineList = (gaps) => (gaps.length > 5 ? `${gaps.slice(0, 5).join(", ")} and ${gaps.length - 5} more` : gaps.join(", "));
+const incompleteError = (path, c) => new Error(`${path}: column ${c.index + 1} holds numbers but is empty or not a number on line${c.gaps.length > 1 ? "s" : ""} ${lineList(c.gaps)}; fill or remove those rows, or pick another column with returns_column`);
+
 // One series. With several numeric columns, `column` (a header name or a 1-based index) picks it.
-// Returns the values and the positions of any row-counter columns skipped.
+// Returns the values, the 1-based position of the column read, and the positions of any row-counter
+// columns skipped. Without `column`, any incomplete numeric column is refused, naming its lines.
 export function readSeriesFile(path, column) {
   const table = parseTable(readText(path), path);
   if (!table.rows.length) throw new Error(`${path}: no data rows`);
-  const { columns, skipped } = numericColumns(table);
-  if (!columns.length) throw new Error(`${path}: no column holds only numbers`);
+  const { columns, incomplete, skipped } = numericColumns(table);
+  const match = (list) => list.find((c) => c.name === String(column)) ?? list.find((c) => String(c.index + 1) === String(column));
   if (column === undefined) {
+    if (incomplete.length) throw incompleteError(path, incomplete[0]);
+    if (!columns.length) throw new Error(`${path}: no column holds only numbers`);
     if (columns.length > 1) throw new Error(`${path}: ${columns.length} numeric columns (positions ${columns.map((c) => c.index + 1).join(", ")}); pick one with returns_column, by header name or position`);
-    return { values: columns[0].values, skipped };
+    return { values: columns[0].values, column: columns[0].index + 1, skipped };
   }
-  const picked = columns.find((c) => c.name === String(column)) ?? columns.find((c) => String(c.index + 1) === String(column));
-  if (!picked) throw new Error(`${path}: returns_column matches no numeric column; numeric columns are at positions ${columns.map((c) => c.index + 1).join(", ")}`);
-  return { values: picked.values, skipped };
+  const gappy = match(incomplete);
+  if (gappy) throw incompleteError(path, gappy);
+  const picked = match(columns);
+  if (!picked) throw new Error(`${path}: returns_column matches no numeric column; numeric columns are at positions ${columns.map((c) => c.index + 1).join(", ") || "none"}`);
+  return { values: picked.values, column: picked.index + 1, skipped };
 }
 
-// Every numeric column is one variant; rows are periods.
+// Every numeric column is one variant; rows are periods. An incomplete column is refused.
 export function readMatrixFile(path) {
   const table = parseTable(readText(path), path);
-  const { columns, skipped } = numericColumns(table);
+  const { columns, incomplete, skipped } = numericColumns(table);
+  if (incomplete.length) throw incompleteError(path, incomplete[0]);
   if (columns.length < 2) throw new Error(`${path}: needs at least 2 numeric columns, one per variant`);
   return { matrix: table.rows.map((_, i) => columns.map((c) => c.values[i])), skipped };
 }

package/src/server.mjs

@@ -19,6 +19,18 @@ import { breadthInput, trackRecordInput, auditBacktestInput, verifyReceiptToolSh
 export const DEFAULT_BASE = "https://canlicapital.com";
 export const SERVER_NAME = "canlicapital-validation-mcp";
 export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+// How the server introduces itself in initialize: a readable title, the page that documents it
+// and its icon, so clients and directories that read serverInfo show more than a package name.
+export const SERVER_INFO = Object.freeze({
+  name: SERVER_NAME,
+  version: SERVER_VERSION,
+  title: "Canli Validation",
+  websiteUrl: "https://canlicapital.com/developers#ai-assistant",
+  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"] },
+  ],
+});
 export const REQUEST_TIMEOUT_MS = 30_000;
 
 // One place a value fails a zod schema turns into a short, readable message instead of a raw
@@ -349,7 +361,7 @@ export async function toolAuditBacktest(session, args) {
     checks,
     ...(input.returns_file || input.variants_file
       ? { source: {
-          ...(returnsRead ? { returns_file: input.returns_file, observations: returns.length, ...(returnsRead.skipped.length ? { skipped_row_counter_columns: returnsRead.skipped } : {}) } : {}),
+          ...(returnsRead ? { returns_file: input.returns_file, returns_column_position: returnsRead.column, observations: returns.length, ...(returnsRead.skipped.length ? { skipped_row_counter_columns: returnsRead.skipped } : {}) } : {}),
           ...(variantsRead ? { variants_file: input.variants_file, variants: variants[0].length, periods: variants.length, ...(variantsRead.skipped.length ? { skipped_variant_row_counter_columns: variantsRead.skipped } : {}) } : {}),
         } }
       : {}),
@@ -372,7 +384,21 @@ export async function toolVerifyReceipt(session, args) {
     data = response.envelope?.data;
   }
   const endpoint = String(data?.endpoint ?? "").replace(/^\/api\/v1\//, "");
-  const result = verifyReceipt({ ...data, endpoint }, session.receiptKeys ?? RECEIPT_KEYS.keys);
+  // A receipt missing a field (output, bindings, input_sha256) cannot be hashed, and that is a
+  // failed check, not a tool error: the answer is still "not issued for this content".
+  let result;
+  try {
+    result = verifyReceipt({ ...data, endpoint }, session.receiptKeys ?? RECEIPT_KEYS.keys);
+  } catch {
+    const missing = ["id", "endpoint", "input_sha256", "output", "bindings", "signature"].filter((k) => data?.[k] === undefined);
+    return asText({
+      receipt_id: data?.id ?? null,
+      valid: false,
+      checks: { well_formed: false, id_matches_content: false, signature_valid: false, key_published: false },
+      key_id: data?.signature?.key_id ?? null,
+      meaning: `The receipt is not well formed${missing.length ? `: it has no ${missing.join(", ")}` : ""}, so it cannot be checked. Send the whole receipt object as get_receipt or the validation result returned it, or send its id.`,
+    });
+  }
   return asText({
     receipt_id: data?.id ?? null,
     valid: result.valid,
@@ -408,7 +434,7 @@ async function resolveTicker(session, ticker) {
     try {
       res = await session.fetchImpl(`${session.base}/api/v1/company-tickers.json`, { headers: { Accept: "application/json" }, signal, redirect: "error" });
     } catch {
-      throw new Error(signal.aborted ? "company_financial_history: the ticker index request timed out" : "company_financial_history: could not reach the ticker index");
+      throw new Error(`company_financial_history: ${signal.aborted ? "the ticker index request timed out" : "could not reach the ticker index"} at ${session.base}. Retry, check service_status, or pass the SEC CIK instead of a ticker.`);
     }
     if (!res.ok) throw new Error(`company_financial_history: the ticker index returned HTTP ${res.status}`);
     session.tickerIndex = await res.json();
@@ -679,7 +705,7 @@ export function registerAll(server, session) {
 }
 
 export function createServer(session = createSession()) {
-  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  const server = new McpServer(SERVER_INFO);
   registerAll(server, session);
   return server;
 }