canli-validation-mcp 0.7.0 → 0.7.1

package/README.md

@@ -5,6 +5,34 @@
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14954/badge)](https://www.bestpractices.dev/projects/14954)
 [![Glama score](https://glama.ai/mcp/servers/arhancanli/canli-validation-mcp/badges/score.svg)](https://glama.ai/mcp/servers/arhancanli/canli-validation-mcp)
 
+**Is your best backtest real, or just the luckiest of the variants you tried?** This MCP server
+lets Claude, Cursor or any MCP client answer that with the standard corrections: the deflated
+Sharpe ratio, the CSCV probability of backtest overfitting, the minimum track record length, the
+haircut Sharpe ratio, and luck-equivalent trials. Free and MIT-licensed.
+
+## Quick start
+
+```bash
+# Claude Code, computed on your machine: no key, nothing sent anywhere
+claude mcp add canli-local --env CANLI_LOCAL=1 -- npx -y canli-validation-mcp
+
+# the same tools with signed, stored receipts from the free API (a free key is issued on first use)
+claude mcp add canli -- npx -y canli-validation-mcp
+
+# nothing to install: the hosted endpoint
+claude mcp add --transport http canli https://canlicapital.com/mcp
+```
+
+Then ask, for example: *"I tried 229 variants and kept the best: an annualised Sharpe of
+1.5 over 730 daily returns (365 a year), skew -0.5, kurtosis 5, and the variants'
+Sharpe ratios spread by 0.57. Is it real?"* The assistant calls `validate_deflated_sharpe`: the
+best of 229 skill-less variants would reach 1.60 by luck alone, so the probability that the
+Sharpe is above zero falls from 98.1% to 44.4% once the search is counted. Claude Desktop and any
+other stdio client (Cursor, VS Code) run the same `npx` command; see "Claude Desktop" and
+"Generic stdio client" below.
+
+## What it does
+
 An MCP (Model Context Protocol) server over canlicapital.com's free, keyed validation API. It
 gives a coding agent fourteen tools: issue a free key, run the eight validators (deflated Sharpe,
 CSCV overfitting, paper-evidence conformance, breadth ceiling, minimum track record length,
@@ -165,7 +193,9 @@ claude mcp add --transport http canli https://canlicapital.com/mcp
 ```
 
 Without a key, requests run under a shared anonymous key, so the daily validation quota is shared
-by every hosted caller. For your own quota, issue a free key (see
+by every hosted caller. When that shared quota is used up for the day, validations are still
+answered, computed by the same code on the hosted endpoint, but without a stored receipt; the
+result says so. For your own quota, issue a free key (see
 [/developers](https://canlicapital.com/developers#quickstart)) and send it as a header:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "MCP server for canlicapital.com's free validation API: deflated Sharpe, CSCV overfitting, paper-evidence conformance, and breadth ceiling, each returned as the full API envelope so the boundary language cannot be dropped.",
   "private": false,
   "type": "module",

package/src/server.mjs

@@ -132,6 +132,29 @@ async function callApi(session, { path, method = "GET", body }) {
   return { envelope, failed: res.status >= 400 || Boolean(envelope?.error) };
 }
 
+// The hosted endpoint's shared anonymous key has one daily quota for every caller who connects
+// without a key of their own. When it is used up, the answer is still computed, by the same code
+// the API runs (src/local, byte for byte), on the hosted endpoint; what the caller loses is the
+// stored, signed receipt, and the note says how to get one. A caller's own key, or a missing
+// shared key, still gets the API's refusal unchanged.
+export const SHARED_QUOTA_NOTE = "The shared anonymous quota of this hosted endpoint is used up for today (it resets at 00:00 UTC), so this result was computed by the same code on the hosted endpoint and no receipt was stored. For a receipt and a quota of your own, get a free key at https://canlicapital.com/developers#quickstart and send it as 'Authorization: Bearer <key>'. To run with no quota at all, on your own machine: npx -y canli-validation-mcp with CANLI_LOCAL=1.";
+
+async function validateRemote(session, tool, path, body) {
+  let response = await callApi(session, { path, method: "POST", body });
+  // stdio without CANLI_KEY: the first validation used to come back 401 and the model had to work
+  // out that get_key comes first. Issue the free key once, as get_key would, and retry once.
+  if (response.failed && response.envelope?.error?.code === "unauthorized" && !session.hosted && !session.key && !session.envKey) {
+    const issued = await callApi(session, { path: "/api/v1/keys", method: "POST", body: { label: "auto" } });
+    if (!issued.failed && issued.envelope?.data?.key) {
+      session.key = issued.envelope.data.key;
+      response = await callApi(session, { path, method: "POST", body });
+    }
+  }
+  if (!response.failed || session.hosted?.keySource !== "shared" || response.envelope?.error?.code !== "quota_exhausted") return response;
+  const fallback = computeLocally(tool, body);
+  return { ...fallback, envelope: { ...fallback.envelope, computed: "hosted_without_receipt", note: SHARED_QUOTA_NOTE } };
+}
+
 // Compact context (0.3.0): minified JSON. Indentation is whitespace an agent pays for in tokens and
 // never reads; every field, boundary sentence and provenance value is kept. Measured on the live
 // Apple StockholdersEquity record (README, "Compact context"): 2,214 -> 1,560 tokens minified,
@@ -230,56 +253,56 @@ export async function toolValidateDeflatedSharpe(session, args) {
     );
   }
   if (session.local) { const local = computeLocally("validate_deflated_sharpe", parsed.data); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/deflated-sharpe", method: "POST", body: parsed.data });
+  const response = await validateRemote(session, "validate_deflated_sharpe", "/api/v1/validate/deflated-sharpe", parsed.data);
   return validationText(session, response);
 }
 
 export async function toolValidateOverfitting(session, args) {
   const body = parseOrThrow(overfittingInput, args, "validate_overfitting");
   if (session.local) { const local = computeLocally("validate_overfitting", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/overfitting", method: "POST", body });
+  const response = await validateRemote(session, "validate_overfitting", "/api/v1/validate/overfitting", body);
   return validationText(session, response);
 }
 
 export async function toolValidatePaperEvidence(session, args) {
   const body = parseOrThrow(paperEvidenceInput, args, "validate_paper_evidence");
   if (session.local) { const local = computeLocally("validate_paper_evidence", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/paper-evidence", method: "POST", body });
+  const response = await validateRemote(session, "validate_paper_evidence", "/api/v1/validate/paper-evidence", body);
   return validationText(session, response);
 }
 
 export async function toolValidateBreadth(session, args) {
   const body = parseOrThrow(breadthInput, args, "validate_breadth");
   if (session.local) { const local = computeLocally("validate_breadth", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/breadth", method: "POST", body });
+  const response = await validateRemote(session, "validate_breadth", "/api/v1/validate/breadth", body);
   return validationText(session, response);
 }
 
 export async function toolValidateTrackRecord(session, args) {
   const body = parseOrThrow(trackRecordInput, args, "validate_track_record");
   if (session.local) { const local = computeLocally("validate_track_record", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/track-record", method: "POST", body });
+  const response = await validateRemote(session, "validate_track_record", "/api/v1/validate/track-record", body);
   return validationText(session, response);
 }
 
 export async function toolValidateBacktestLength(session, args) {
   const body = parseOrThrow(backtestLengthInput, args, "validate_backtest_length");
   if (session.local) { const local = computeLocally("validate_backtest_length", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/backtest-length", method: "POST", body });
+  const response = await validateRemote(session, "validate_backtest_length", "/api/v1/validate/backtest-length", body);
   return validationText(session, response);
 }
 
 export async function toolValidateHaircutSharpe(session, args) {
   const body = parseOrThrow(haircutSharpeInput, args, "validate_haircut_sharpe");
   if (session.local) { const local = computeLocally("validate_haircut_sharpe", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/haircut-sharpe", method: "POST", body });
+  const response = await validateRemote(session, "validate_haircut_sharpe", "/api/v1/validate/haircut-sharpe", body);
   return validationText(session, response);
 }
 
 export async function toolValidateLuckTrials(session, args) {
   const body = parseOrThrow(luckTrialsInput, args, "validate_luck_trials");
   if (session.local) { const local = computeLocally("validate_luck_trials", body); return validationText(session, local); }
-  const response = await callApi(session, { path: "/api/v1/validate/luck-trials", method: "POST", body });
+  const response = await validateRemote(session, "validate_luck_trials", "/api/v1/validate/luck-trials", body);
   return validationText(session, response);
 }
 
@@ -287,7 +310,7 @@ export async function toolValidateLuckTrials(session, args) {
 // through the API (one validation of quota, one receipt).
 async function runValidator(session, tool, path, body) {
   if (session.local) return computeLocally(tool, body);
-  return callApi(session, { path, method: "POST", body });
+  return validateRemote(session, tool, path, body);
 }
 
 const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);