canli-validation-mcp 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+# canli-validation-mcp
+
+An MCP (Model Context Protocol) server over canlicapital.com's free, keyed validation API. It
+gives a coding agent seven tools: issue a free key, run the four validators (deflated Sharpe,
+CSCV overfitting, paper-evidence conformance, breadth ceiling), fetch a stored receipt, and read
+service status. Every tool returns the full API envelope as its result text, success or error,
+so the agent cannot see a number without the sentences beside it that say what the number does
+not establish.
+
+This package is not published to npm. Run it from a local checkout, as shown below.
+
+## What the API is (and is not)
+
+The engine is the product. The service runs your submitted numbers through the same honesty
+arithmetic canlicapital.com's own paper record runs on itself and hands back a verdict anyone can
+recompute from the receipt. It does not accept market data, does not sign receipts, does not
+grade a strategy, and never saw your data source, its costs, or any lookahead in how a series was
+built. See `docs/superpowers/specs/2026-09-05-developer-key-validation-api-design.md` in the main
+repository for the full design.
+
+## Tools
+
+| Tool | Calls | Key required |
+|---|---|---|
+| `get_key` | `POST /api/v1/keys` | no |
+| `validate_deflated_sharpe` | `POST /api/v1/validate/deflated-sharpe` | yes |
+| `validate_overfitting` | `POST /api/v1/validate/overfitting` | yes |
+| `validate_paper_evidence` | `POST /api/v1/validate/paper-evidence` | yes |
+| `validate_breadth` | `POST /api/v1/validate/breadth` | yes |
+| `get_receipt` | `GET /api/v1/receipts/{id}` | no |
+| `service_status` | `GET /api/v1/validate/status` | no |
+
+`validate_deflated_sharpe` accepts exactly one of two input shapes, never a mix of both:
+
+- the seven contract fields: `observed_sharpe_annualized`, `observations`, `periods_per_year`,
+  `skew`, `non_excess_kurtosis`, `effective_independent_trials`,
+  `cross_trial_sharpe_sd_annualized`;
+- or a return series plus the trials behind it: `returns`, `periods_per_year`,
+  `effective_independent_trials`, `cross_trial_sharpe_sd_annualized`.
+
+Sending fields from both shapes, or from neither, is rejected before any request leaves the
+process; see `src/schemas.mjs`.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CANLI_API_BASE` | `https://canlicapital.com` | Where the API lives. Point it at a preview deployment for testing. |
+| `CANLI_KEY` | unset | A key already issued from `POST /api/v1/keys`. When set, `get_key` sends no request and reports the key is already configured; every other tool sends it as `Authorization: Bearer <key>`. |
+
+If `CANLI_KEY` is not set, call `get_key` once per session before the four validators. The key it
+returns lives only in this process's memory for the life of the session; it is not written to
+disk.
+
+## Install
+
+```bash
+cd mcp
+npm ci
+```
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings, Developer, Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "canlicapital-validation": {
+      "command": "node",
+      "args": ["/absolute/path/to/meridian/mcp/src/server.mjs"],
+      "env": {
+        "CANLI_API_BASE": "https://canlicapital.com"
+      }
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/meridian` with the real path to this checkout, then restart Claude
+Desktop.
+
+## Claude Code
+
+```bash
+claude mcp add canlicapital-validation \
+  --env CANLI_API_BASE=https://canlicapital.com \
+  -- node /absolute/path/to/meridian/mcp/src/server.mjs
+```
+
+Run `claude mcp list` to confirm it is registered, and `claude mcp remove canlicapital-validation`
+to remove it.
+
+## Generic stdio client
+
+Any MCP client that can spawn a process and speak stdio will work. Using the official SDK
+directly, from Node:
+
+```js
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "node",
+  args: ["/absolute/path/to/meridian/mcp/src/server.mjs"],
+  env: { ...process.env, CANLI_API_BASE: "https://canlicapital.com" },
+});
+
+const client = new Client({ name: "my-agent", version: "0.1.0" });
+await client.connect(transport);
+
+const { tools } = await client.listTools();
+console.log(tools.map((t) => t.name));
+
+const keyResult = await client.callTool({ name: "get_key", arguments: { label: "my-agent" } });
+console.log(keyResult.content[0].text); // the full envelope, key included
+
+const result = await client.callTool({
+  name: "validate_deflated_sharpe",
+  arguments: {
+    returns: [0.004, -0.002, 0.007, 0.001, -0.003, 0.005, 0.002, -0.001],
+    periods_per_year: 252,
+    effective_independent_trials: 30,
+    cross_trial_sharpe_sd_annualized: 0.5,
+  },
+});
+console.log(result.content[0].text); // the full envelope, including limits and receipt.url
+
+await client.close();
+```
+
+## What a result does not establish (boundary language)
+
+Every envelope this server returns carries these sentences, verbatim, from the API itself
+(`api/_lib/limits.js`):
+
+- This verdict is about the series exactly as submitted. The service never saw the data source,
+  its costs, survivorship, or any lookahead in how the series was built.
+- A deflated Sharpe or overfitting probability above or below any threshold is not admission to
+  anything and is not a forecast.
+- The receipt is content-hashed and reproducible from the open-source core it names. It is not
+  signed.
+- Quotas: 1000 validations per key per UTC day, 5 keys per client per UTC day, 1048576 bytes per
+  request, 20000 observations per series, 200 variants per matrix.
+
+Each tool's description also states one of these sentences, so an agent sees the boundary before
+it calls the tool, not only after. No tool in this server strips `limits` or `receipt.url` from
+a response; the full envelope is always the result text.
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs `node --test` over `test/*.test.mjs`: schema round-trips against the API's own OpenAPI and
+manifest examples, one success, error-envelope and quota-429 case per keyed tool (a fake `fetch`
+stands in for the network), a check that every tool description carries a limits sentence, a
+check that those sentences have not drifted from `api/_lib/limits.js`, a check that no shipped
+file contains an em dash, and one test that spawns the actual server binary and performs a real
+MCP `tools/list` and `callTool` handshake over stdio against a local HTTP stub, so the wiring is
+proven rather than assumed.
+
+## Dependencies
+
+Only `@modelcontextprotocol/sdk` (pinned exact) and `zod` (pinned exact). No other runtime
+dependency is added, and nothing in this package touches the site's root `package.json`,
+`.vercelignore`, `api/`, `scripts/`, `js/`, or `public/`.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "canli-validation-mcp",
+  "version": "0.1.0",
+  "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",
+  "license": "MIT",
+  "bin": {
+    "canlicapital-validation-mcp": "src/server.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.5.4"
+  }
+}

package/src/schemas.mjs

@@ -0,0 +1,137 @@
+// mcp/src/schemas.mjs
+//
+// Input schemas for canlicapital.com's free validation API, kept in one module so a test can
+// round-trip them against the API's own examples: public/api/v1/openapi.json, the manifest at
+// api/_lib/manifest.js, and the seven-field contract at
+// public/glassbox/deflated_sharpe_calculator_contract.json. See
+// docs/superpowers/specs/2026-09-05-developer-key-validation-api-design.md section 4 for the
+// validator semantics these shapes mirror.
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------------------------
+// validate_deflated_sharpe: the API accepts exactly one of two input modes, never a mix.
+// Input A is the seven fields of deflated_sharpe_calculator_contract.json.
+// Input B is a raw return series plus the trials and dispersion behind it.
+// ---------------------------------------------------------------------------------------------
+
+export const deflatedSharpeContractInputs = z
+  .object({
+    observed_sharpe_annualized: z.number().min(-10).max(10),
+    observations: z.number().int().min(2).max(1000000),
+    periods_per_year: z.number().min(1).max(10000),
+    skew: z.number().min(-20).max(20),
+    non_excess_kurtosis: z.number().min(1).max(100),
+    effective_independent_trials: z.number().int().min(2).max(10000000),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10),
+  })
+  .strict();
+
+export const deflatedSharpeReturnSeriesInputs = z
+  .object({
+    returns: z.array(z.number()).min(2).max(20000),
+    periods_per_year: z.number().min(1).max(10000),
+    effective_independent_trials: z.number().int().min(2).max(10000000),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10),
+  })
+  .strict();
+
+// The oneOf: exactly one of the two shapes above. A value carrying fields from both, or neither,
+// fails every branch and so fails the union, which is the rejection this module is tested for.
+export const deflatedSharpeInput = z.union([deflatedSharpeContractInputs, deflatedSharpeReturnSeriesInputs]);
+
+// The MCP-facing shape: every field from both modes, all optional. A bare union has no useful
+// JSON Schema for a client to read, so the tool advertises this flat shape (for discovery and
+// per-field type checking) while the strict oneOf rule above is enforced in the tool handler.
+export const deflatedSharpeToolShape = z
+  .object({
+    observed_sharpe_annualized: z.number().min(-10).max(10).optional(),
+    observations: z.number().int().min(2).max(1000000).optional(),
+    periods_per_year: z.number().min(1).max(10000).optional(),
+    skew: z.number().min(-20).max(20).optional(),
+    non_excess_kurtosis: z.number().min(1).max(100).optional(),
+    effective_independent_trials: z.number().int().min(2).max(10000000).optional(),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).optional(),
+    returns: z.array(z.number()).min(2).max(20000).optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// validate_overfitting
+// ---------------------------------------------------------------------------------------------
+
+export const overfittingInput = z
+  .object({
+    matrix: z.array(z.array(z.number())).min(2).max(20000),
+    n_splits: z.number().int().positive().optional(),
+    max_combinations: z.number().int().positive().max(2000).optional(),
+    seed: z.number().optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// validate_paper_evidence: the record shape is the open standard itself, so this schema only
+// checks that a record object was sent; canlicapital.com runs the real conformance check.
+// ---------------------------------------------------------------------------------------------
+
+export const paperEvidenceInput = z
+  .object({
+    record: z.record(z.string(), z.unknown()),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// validate_breadth
+// ---------------------------------------------------------------------------------------------
+
+export const breadthInput = z
+  .object({
+    sleeve_sharpe: z.number().positive(),
+    average_pairwise_correlation: z.number().min(-1).max(1),
+    sleeves: z.number().int().min(1).max(500).optional(),
+    target: z.number().positive().optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// get_key / get_receipt
+// ---------------------------------------------------------------------------------------------
+
+export const getKeyInput = z
+  .object({
+    label: z.string().max(64).optional(),
+  })
+  .strict();
+
+export const getReceiptInput = z
+  .object({
+    id: z.string().regex(/^[0-9a-f]{24}$/, "A receipt id is 24 hex characters"),
+  })
+  .strict();
+
+export const emptyInput = z.object({}).strict();
+
+// ---------------------------------------------------------------------------------------------
+// Boundary language: verbatim sentences from api/_lib/limits.js LIMITS_TEXT. A test asserts each
+// of these strings is still present, byte for byte, in that source array, so this module cannot
+// drift from the text the live API actually attaches to every envelope.
+// ---------------------------------------------------------------------------------------------
+
+export const LIMITS_SENTENCES = Object.freeze({
+  scope: "This verdict is about the series exactly as submitted. The service never saw the data source, its costs, survivorship, or any lookahead in how the series was built.",
+  notAdmission: "A deflated Sharpe or overfitting probability above or below any threshold is not admission to anything and is not a forecast.",
+  unsigned: "The receipt is content-hashed and reproducible from the open-source core it names. It is not signed.",
+  quotas: "Quotas: 1000 validations per key per UTC day, 5 keys per client per UTC day, 1048576 bytes per request, 20000 observations per series, 200 variants per matrix.",
+});
+
+// One tool description per tool, each stating (in one sentence lifted from the boundary language
+// 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; skipped when CANLI_KEY is already set. ${LIMITS_SENTENCES.quotas}`,
+  validate_deflated_sharpe: `Probabilistic and deflated Sharpe from the seven contract inputs, or from a return series plus the trials and dispersion behind it, never both. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_overfitting: `Probability of backtest overfitting by CSCV over the returns of every variant tried. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_paper_evidence: `Conformance of a performance record against the canli.paper-evidence.v0 standard. ${LIMITS_SENTENCES.scope}`,
+  validate_breadth: `Book Sharpe ceiling from per-sleeve quality and average pairwise correlation, and the sleeves a target needs. ${LIMITS_SENTENCES.scope}`,
+  get_receipt: `Fetch a stored verdict by its content-hash id (GET /api/v1/receipts/{id}), immutable and cacheable. ${LIMITS_SENTENCES.unsigned}`,
+  service_status: `Service, store and quota constants for the validation API (GET /api/v1/validate/status); no key required. ${LIMITS_SENTENCES.scope}`,
+});

package/src/server.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// mcp/src/server.mjs
+//
+// stdio MCP server over canlicapital.com's free validation API. Every tool returns the FULL API
+// envelope as its result text, success or error, so an agent cannot see a number without the
+// sentences beside it that say what the number does not establish (see schemas.mjs, LIMITS_SENTENCES
+// and TOOL_DESCRIPTIONS). Reads CANLI_API_BASE (default https://canlicapital.com) and an optional
+// CANLI_KEY; when CANLI_KEY is set, get_key does not call the network.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  breadthInput,
+  deflatedSharpeInput,
+  deflatedSharpeToolShape,
+  emptyInput,
+  getKeyInput,
+  getReceiptInput,
+  overfittingInput,
+  paperEvidenceInput,
+  TOOL_DESCRIPTIONS,
+} from "./schemas.mjs";
+
+export const DEFAULT_BASE = "https://canlicapital.com";
+export const SERVER_NAME = "canlicapital-validation-mcp";
+export const SERVER_VERSION = "0.1.0";
+
+// One place a value fails a zod schema turns into a short, readable message instead of a raw
+// ZodError, so a thrown error reads well inside an MCP isError result.
+function parseOrThrow(schema, value, label) {
+  const result = schema.safeParse(value ?? {});
+  if (result.success) return result.data;
+  const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+  throw new Error(`${label}: ${issues}`);
+}
+
+export function createSession({ base, fetchImpl, envKey } = {}) {
+  return {
+    base: base ?? process.env.CANLI_API_BASE ?? DEFAULT_BASE,
+    fetchImpl: fetchImpl ?? fetch,
+    envKey: envKey ?? process.env.CANLI_KEY ?? undefined,
+    key: undefined,
+  };
+}
+
+async function callApi(session, { path, method = "GET", body }) {
+  const headers = { "Content-Type": "application/json" };
+  const key = session.key ?? session.envKey;
+  if (key) headers.Authorization = `Bearer ${key}`;
+  const init = { method, headers };
+  if (body !== undefined) init.body = JSON.stringify(body);
+  const res = await session.fetchImpl(`${session.base}${path}`, init);
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${path} returned a non-JSON body (status ${res.status}): ${text.slice(0, 300)}`);
+  }
+}
+
+const asText = (envelope) => ({ content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }] });
+
+export async function toolGetKey(session, args) {
+  const { label } = parseOrThrow(getKeyInput, args, "get_key");
+  if (session.envKey) {
+    return asText({
+      note: "CANLI_KEY is set in the environment; no new key was issued and no request was sent. Using the configured key for this session.",
+      key_source: "CANLI_KEY",
+      key_present: true,
+    });
+  }
+  const envelope = await callApi(session, { path: "/api/v1/keys", method: "POST", body: { label } });
+  if (envelope?.data?.key) session.key = envelope.data.key;
+  return asText(envelope);
+}
+
+export async function toolValidateDeflatedSharpe(session, args) {
+  const parsed = deflatedSharpeInput.safeParse(args ?? {});
+  if (!parsed.success) {
+    throw new Error(
+      "Send either the seven contract inputs (observed_sharpe_annualized, observations, periods_per_year, skew, non_excess_kurtosis, effective_independent_trials, cross_trial_sharpe_sd_annualized) " +
+        "or a return series (returns, periods_per_year, effective_independent_trials, cross_trial_sharpe_sd_annualized), never a mix of both and never neither.",
+    );
+  }
+  const envelope = await callApi(session, { path: "/api/v1/validate/deflated-sharpe", method: "POST", body: parsed.data });
+  return asText(envelope);
+}
+
+export async function toolValidateOverfitting(session, args) {
+  const body = parseOrThrow(overfittingInput, args, "validate_overfitting");
+  const envelope = await callApi(session, { path: "/api/v1/validate/overfitting", method: "POST", body });
+  return asText(envelope);
+}
+
+export async function toolValidatePaperEvidence(session, args) {
+  const body = parseOrThrow(paperEvidenceInput, args, "validate_paper_evidence");
+  const envelope = await callApi(session, { path: "/api/v1/validate/paper-evidence", method: "POST", body });
+  return asText(envelope);
+}
+
+export async function toolValidateBreadth(session, args) {
+  const body = parseOrThrow(breadthInput, args, "validate_breadth");
+  const envelope = await callApi(session, { path: "/api/v1/validate/breadth", method: "POST", body });
+  return asText(envelope);
+}
+
+export async function toolGetReceipt(session, args) {
+  const { id } = parseOrThrow(getReceiptInput, args, "get_receipt");
+  const envelope = await callApi(session, { path: `/api/v1/receipts/${id}` });
+  return asText(envelope);
+}
+
+export async function toolServiceStatus(session) {
+  const envelope = await callApi(session, { path: "/api/v1/validate/status" });
+  return asText(envelope);
+}
+
+export function registerTools(server, session) {
+  server.registerTool(
+    "get_key",
+    { title: "Get a free validation key", description: TOOL_DESCRIPTIONS.get_key, inputSchema: getKeyInput },
+    (args) => toolGetKey(session, args),
+  );
+  server.registerTool(
+    "validate_deflated_sharpe",
+    { title: "Validate deflated Sharpe", description: TOOL_DESCRIPTIONS.validate_deflated_sharpe, inputSchema: deflatedSharpeToolShape },
+    (args) => toolValidateDeflatedSharpe(session, args),
+  );
+  server.registerTool(
+    "validate_overfitting",
+    { title: "Validate overfitting (CSCV)", description: TOOL_DESCRIPTIONS.validate_overfitting, inputSchema: overfittingInput },
+    (args) => toolValidateOverfitting(session, args),
+  );
+  server.registerTool(
+    "validate_paper_evidence",
+    { title: "Validate paper evidence", description: TOOL_DESCRIPTIONS.validate_paper_evidence, inputSchema: paperEvidenceInput },
+    (args) => toolValidatePaperEvidence(session, args),
+  );
+  server.registerTool(
+    "validate_breadth",
+    { title: "Validate breadth ceiling", description: TOOL_DESCRIPTIONS.validate_breadth, inputSchema: breadthInput },
+    (args) => toolValidateBreadth(session, args),
+  );
+  server.registerTool(
+    "get_receipt",
+    { title: "Get a receipt", description: TOOL_DESCRIPTIONS.get_receipt, inputSchema: getReceiptInput },
+    (args) => toolGetReceipt(session, args),
+  );
+  server.registerTool(
+    "service_status",
+    { title: "Service status", description: TOOL_DESCRIPTIONS.service_status, inputSchema: emptyInput },
+    () => toolServiceStatus(session),
+  );
+}
+
+export function createServer(session = createSession()) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  registerTools(server, session);
+  return server;
+}
+
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+const isMain = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  main().catch((err) => {
+    console.error(`${SERVER_NAME}: fatal`, err);
+    process.exit(1);
+  });
+}