canli-validation-mcp 0.8.1 → 0.9.0

package/README.md

@@ -333,11 +333,11 @@ tokenizers give different absolute counts), in the shape an OpenAI-style client
 
 | CANLI_TOOLSETS | tools | tokens per turn | of all |
 |---|---|---|---|
-| `all` | 14 | 3,888 | 100% |
-| `validate` | 10 | 3,154 | 81% |
-| `receipts` | 2 | 340 | 9% |
-| `company` | 1 | 302 | 8% |
-| `status` | 1 | 98 | 3% |
+| `all` | 14 | 3,834 | 100% |
+| `validate` | 10 | 3,166 | 83% |
+| `receipts` | 2 | 312 | 8% |
+| `company` | 1 | 273 | 7% |
+| `status` | 1 | 89 | 2% |
 
 Providers cache a tool list that is identical from turn to turn and bill the cached part at a
 fraction of the price (`test/tool-list-stable.test.mjs` keeps each list byte-stable); a smaller list

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "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

@@ -14,44 +14,44 @@ import { z } from "zod";
 export const FIELD_DESCRIPTIONS = Object.freeze({
   observed_sharpe_annualized: "Annualized Sharpe as observed.",
   observations: "Number of return observations.",
-  periods_per_year: "Observations per year: 252 daily, 365 daily crypto, 52 weekly, 12 monthly.",
+  periods_per_year: "Periods per year: 252 daily, 365 crypto, 52 weekly, 12 monthly.",
   skew: "Skewness of returns; 0 if Normal.",
   non_excess_kurtosis: "Kurtosis, not excess kurtosis; 3 if Normal.",
   effective_independent_trials: "Independent variants tried before choosing this one.",
-  cross_trial_sharpe_sd_annualized: "Standard deviation of the annualized Sharpe across those trials.",
-  returns: "Periodic returns as fractions (0.01 is 1%), oldest first; replaces the Sharpe, observations, skew and kurtosis fields.",
-  matrix: "Returns as fractions: one row per period, one column per variant.",
+  cross_trial_sharpe_sd_annualized: "Standard deviation of annualized Sharpe across those trials.",
+  returns: "Periodic returns as fractions (0.01 = 1%), oldest first; replaces the Sharpe, observations, skew and kurtosis.",
+  matrix: "Returns as fractions, one row per period, one column per variant.",
   n_splits: "Even number of blocks, at least 2; default 16.",
   max_combinations: "Most splits evaluated, up to 2000 (default).",
   seed: "Sampling seed; default 42.",
   record: "A canli.paper-evidence.v0 record.",
   sleeve_sharpe: "Annualized Sharpe of one sleeve.",
   average_pairwise_correlation: "Average correlation between sleeves, -1 to 1.",
-  sleeves: "Sleeve count, to get that book's Sharpe.",
-  target: "Target book Sharpe, to get the sleeves it needs.",
+  sleeves: "Sleeve count, for that book's Sharpe.",
+  target: "Target book Sharpe, for the sleeves it needs.",
   benchmark_sharpe_annualized: "Annualized Sharpe to beat; default 0.",
   confidence: "Between 0 and 1; default 0.95.",
-  record_observations: "Record length so far, to get its probabilistic Sharpe.",
+  record_observations: "Record length so far, for its probabilistic Sharpe.",
   label: "Name for the key.",
   receipt_id: "Receipt id from a validation result.",
-  receipt_object: "A receipt as get_receipt returns it (its data), to verify without fetching it.",
+  receipt_object: "A receipt as get_receipt returns it, to verify without fetching.",
   cik: "SEC CIK; send cik or ticker.",
   ticker: "Ticker such as AAPL; send ticker or cik.",
   concept: "us-gaap concept such as Assets; omit to list them.",
   limit: "Most observations, newest first; default 40.",
-  target_sharpe_annualized: "In-sample annualized Sharpe you would take as a discovery; default 1.",
-  backtest_years: "Length of the backtest in years, to get the most independent trials it allows.",
-  bt_trials: "Independent trials (backtests, parameter sets, ideas) tried; gives the minimum backtest length.",
-  hc_observations: "Number of return observations behind the Sharpe ratio.",
-  hc_tests: "Total tests run, this one included; gives the Bonferroni and independent-test haircuts.",
-  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.",
-  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.",
-  variants_file: "Path to a CSV or JSON file of every variant's returns (one numeric column per variant), instead of variants.",
+  target_sharpe_annualized: "In-sample annualized Sharpe you would call a discovery; default 1.",
+  backtest_years: "Backtest length in years, for the most trials it allows.",
+  bt_trials: "Independent trials tried (backtests, parameter sets, ideas).",
+  hc_observations: "Return observations behind the Sharpe.",
+  hc_tests: "Tests run, this one included; gives the Bonferroni and independent-test haircuts.",
+  autocorrelation: "Lag-1 autocorrelation of returns, -1 to 1; default 0. Corrects the annualized Sharpe (Lo 2002).",
+  other_sharpes: "Annualized Sharpes of the other tests over the same observations; adds Holm and BHY.",
+  lt_trials: "Independent trials tried; adds the chance the best reached this Sharpe by luck.",
+  lt_skew: "Skewness; below -0.5 the reading warns the counts are too generous.",
+  variants: "Optional returns of every variant tried (this one included), one row per period, one column per variant; adds the overfitting check.",
+  returns_file: "Path to a CSV or JSON of the returns on this machine (not on the hosted endpoint), instead of returns.",
+  returns_column: "Column name or 1-based position, when returns_file has several numeric columns.",
+  variants_file: "Path to a CSV or JSON with one numeric column per variant, instead of variants.",
 });
 const d = FIELD_DESCRIPTIONS;
 
@@ -302,20 +302,20 @@ export const REGISTRY_DESCRIPTION_MAX = 100;
 // above) what the tool's result cannot be used to claim, so an agent sees this before it ever
 // calls the tool, not only inside the returned envelope.
 export const TOOL_DESCRIPTIONS = Object.freeze({
-  get_key: `Issue a free canlicapital.com validation key (POST /api/v1/keys) and hold it in memory for this session. Only needed before a validation when neither CANLI_KEY nor local mode is set; the read tools (get_receipt, service_status, company_financial_history) never need a key. ${LIMITS_SENTENCES.quotas}`,
-  validate_deflated_sharpe: `Deflated Sharpe ratio: the probability (0 to 1) that one selected strategy's Sharpe beats the best Sharpe that luck alone would give across the variants tried, with the probabilistic Sharpe and that luck benchmark. Use it for the strategy you kept after a search, when you know how many variants were tried and how their Sharpe ratios spread; send the seven statistics or a return series, not both. With every variant's returns use validate_overfitting; to state luck as a trial count use validate_luck_trials; for a multiple-testing haircut use validate_haircut_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
-  audit_backtest: `Audit one strategy's return series in one call: deflated Sharpe, the minimum track record length for its Sharpe to beat the benchmark, and, with every variant's returns, the probability of backtest overfitting. Point returns_file at the backtest's CSV or JSON rather than copying long series into the call. Each check is the matching validate_ tool's result with its own receipt, side by side; the audit does not grade the strategy. Prefer it to calling those validators one by one when you have one strategy's return series. Uses one validation per check. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_overfitting: `Probability of backtest overfitting (0 to 1) by CSCV: how often the variant that is best in sample falls below the median out of sample. Use it when you have every variant's returns as a matrix (periods by variants); with summary statistics only, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_paper_evidence: `Whether a paper or simulated performance record meets canli.paper-evidence.v0, with each failure's JSON pointer. Use it on a record document before publishing or relying on it: it checks structure and required disclosures, not whether the returns are good. ${LIMITS_SENTENCES.scope}`,
-  validate_backtest_length: `Minimum backtest length, in years, before the best of N independent trials is not expected to reach a target Sharpe by luck, and with backtest_years, the most independent trials those years allow. Send effective_independent_trials, backtest_years, or both. Use it before or while planning a search, to size the backtest for the number of trials; once a search has a result, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_luck_trials: `How many skill-less strategies a search would have had to try for its best to reach this Sharpe by luck, and, with a trial count, the chance that it did. Calibrated by Monte Carlo. Use it to state luck as a count ("as good as the best of N random tries") or to test a result against the trials actually run; for a probability that the Sharpe is real, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_haircut_sharpe: `Haircut Sharpe ratio for multiple testing (Harvey and Liu, 2015): the Sharpe a single test would have needed once the number of tests is counted, by Bonferroni and for independent tests, and with the other tests' Sharpe ratios by Holm and BHY. Use it to report a Sharpe adjusted for the number of tests, as finance papers do; for a probability that the Sharpe is real, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_track_record: `Minimum track record length, in observations and years, for an observed Sharpe to beat a benchmark at a confidence level, and with observations, the record's probabilistic Sharpe so far. Use it for a live or paper record: how long it must run before its Sharpe is evidence. To size a backtest against the number of trials, use validate_backtest_length. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_breadth: `Highest book Sharpe reachable by adding sleeves of this quality and correlation, the Sharpe at a sleeve count, and the sleeves a target needs. Use it for portfolio construction, to see what adding strategies can and cannot do; it validates no single strategy. ${LIMITS_SENTENCES.scope}`,
-  verify_receipt: `Check a validation receipt's Ed25519 signature offline against the canlicapital.com public key bundled in this package, that its output hashes to its output_sha256, and that its content hashes to its id. Send an id to fetch the receipt first, or a receipt already fetched. ${LIMITS_SENTENCES.unsigned}`,
-  get_receipt: `Fetch a stored verdict by receipt id (GET /api/v1/receipts/{id}) to re-read an earlier result. No key. To check that the receipt is genuine, use verify_receipt. ${LIMITS_SENTENCES.unsigned}`,
-  service_status: `Whether the validation API is up, with quota constants (GET /api/v1/validate/status); check after a timeout before resubmitting. No key. ${LIMITS_SENTENCES.scope}`,
-  company_financial_history: `SEC-reported financial history for one company from the canlicapital.com company reference (GET /company-data/{cik}.json), by cik or by ticker (resolved through GET /api/v1/company-tickers.json, companies in the release only). Without a concept it lists the available histories; with one it returns observations, newest first, each with its filing accession, form, filed date and unit, plus the SHA-256 of the original SEC response. No key required. ${COMPANY_REFERENCE_BOUNDARY}`,
+  get_key: `Issue a free validation key for this session. Rarely needed: the first validation issues one itself unless CANLI_KEY or local mode is set, and the read tools need none. ${LIMITS_SENTENCES.quotas}`,
+  validate_deflated_sharpe: `Deflated Sharpe ratio: the probability (0 to 1) that the selected strategy's Sharpe beats the best that luck gives across the variants tried, with the probabilistic Sharpe and that luck benchmark. Send the seven statistics or a return series. With every variant's returns use validate_overfitting; luck as a trial count, validate_luck_trials; a multiple-testing haircut, validate_haircut_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  audit_backtest: `One-call audit of a strategy's returns: deflated Sharpe, minimum track record and, with every variant's returns, the probability of backtest overfitting, each the matching validator's result with its own receipt. Point returns_file at the backtest's CSV or JSON instead of pasting long series. Prefer it to calling the validators one by one; one validation per check. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_overfitting: `Probability of backtest overfitting (0 to 1) by CSCV: how often the in-sample best variant falls below the out-of-sample median. Needs every variant's returns (periods by variants); with summary statistics only, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_paper_evidence: `Whether a paper or simulated performance record meets canli.paper-evidence.v0, with a JSON pointer per failure. Checks structure and required disclosures, not whether the returns are good. ${LIMITS_SENTENCES.scope}`,
+  validate_backtest_length: `Minimum backtest length (years) before the best of N independent trials is not expected to reach a target Sharpe by luck; with backtest_years, the most trials those years allow. For planning a search; once it has a result, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_luck_trials: `How many skill-less strategies a search would need for its best to reach this Sharpe by luck (Monte Carlo), and with a trial count, the chance it did. States luck as the best of N random tries; for the probability the Sharpe is real, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_haircut_sharpe: `Haircut Sharpe for multiple testing (Harvey and Liu 2015): the Sharpe a single test would have needed, by Bonferroni and independent tests, and with the other tests' Sharpes, Holm and BHY. For the probability the Sharpe is real, use validate_deflated_sharpe. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_track_record: `Minimum track record length (observations and years) for an observed Sharpe to beat a benchmark at a confidence level; with observations, the record's probabilistic Sharpe so far. For live or paper records; to size a backtest for its trials, use validate_backtest_length. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_breadth: `Book Sharpe ceiling from adding sleeves of this quality and correlation, the Sharpe at a sleeve count, and the sleeves a target needs. For portfolio construction; it validates no single strategy. ${LIMITS_SENTENCES.scope}`,
+  verify_receipt: `Verify a receipt offline: its Ed25519 signature against the bundled canlicapital.com key, its output hash and its id. Send an id to fetch it first, or the receipt itself. ${LIMITS_SENTENCES.unsigned}`,
+  get_receipt: `Fetch a stored verdict by receipt id to re-read it. No key; verify_receipt checks it is genuine. ${LIMITS_SENTENCES.unsigned}`,
+  service_status: `Whether the validation API is up, with its quotas; check after a timeout before resubmitting. No key. ${LIMITS_SENTENCES.scope}`,
+  company_financial_history: `SEC-reported financial history for one company in the canlicapital.com reference, by cik or ticker: without a concept, the histories available; with one, observations newest first with accession, form, filed date and unit, plus the source's SHA-256. For point-in-time values use canli-fundamentals-mcp. ${COMPANY_REFERENCE_BOUNDARY}`,
 });
 
 // Output schemas (0.8.0). Published OPEN: extra fields always pass. A client validates a tool's

package/src/server.mjs

@@ -19,6 +19,22 @@ 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;
+// Sent once in initialize; clients such as Claude Code put it in the system prompt, so the model
+// knows the first call to make even when tool definitions are deferred. Byte-stable across runs.
+export const SERVER_INSTRUCTIONS = "Checks whether a backtest's result is real. For one strategy's returns, call audit_backtest, pointing returns_file at the backtest's CSV instead of pasting long series. For a Sharpe found by a search, validate_deflated_sharpe needs how many independent variants were tried and how their Sharpes spread; with every variant's returns, validate_overfitting gives the probability of backtest overfitting. Set CANLI_LOCAL=1 to compute on this machine with no network. Every result says what it does not establish; quote those limits with the number.";
+
+// 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
@@ -693,7 +709,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, { instructions: SERVER_INSTRUCTIONS });
   registerAll(server, session);
   return server;
 }