canli-validation-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,20 +1,20 @@
 # 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,
+gives a coding agent nine tools: issue a free key, run the five validators (deflated Sharpe,
+CSCV overfitting, paper-evidence conformance, breadth ceiling, minimum track record length),
+fetch a stored receipt, read service status, and read a company's reported financial history
+from SEC filings. 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 published to npm as [`canli-validation-mcp`](https://www.npmjs.com/package/canli-validation-mcp).
-Run it with `npx`, no install step, as shown below. A local checkout is only needed to develop or
+Also listed on the official MCP Registry (`io.github.arhancanli/canli-validation-mcp`) and
+[cursor.directory](https://cursor.directory/plugins/canli-validation-mcp-1). Run it with `npx`, no install step, as shown below. A local checkout is only needed to develop or
 test this package itself; see "Local checkout" near the bottom.
 
-Release checkpoint, September 20, 2026: npm's latest version is 0.1.1. This checkout
-prepares 0.1.2; its HTTP error flags, request deadlines and redirect handling described
-below are candidate changes until that version is published. Running unversioned
-`npx` uses npm's latest release, not this checkout.
+This README describes the version in `package.json`. Unversioned `npx` runs npm's latest
+release; `npx -y canli-validation-mcp@<version>` pins one.
 
 ## What the API is (and is not)
 
@@ -34,6 +34,7 @@ repository for the full design.
 | `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 |
+| `validate_track_record` | `POST /api/v1/validate/track-record` | yes |
 | `get_receipt` | `GET /api/v1/receipts/{id}` | no |
 | `service_status` | `GET /api/v1/validate/status` | no |
 | `company_financial_history` | `GET /company-data/{cik}.json` | no |
@@ -105,6 +106,28 @@ No install step. `npx` fetches the published package on first run, so every clie
 just spawns `npx -y canli-validation-mcp`. See "Local checkout" near the bottom to develop or test
 this package itself instead of running the published one.
 
+## Hosted endpoint (no install)
+
+The same tools are served at `https://canlicapital.com/mcp` over MCP Streamable HTTP, for clients
+that connect to a URL instead of spawning a process (Claude.ai connectors, ChatGPT, Cursor's remote
+servers). Nothing to install, and no Node.js on your machine.
+
+```bash
+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
+[/developers](https://canlicapital.com/developers#quickstart)) and send it as a header:
+
+```bash
+claude mcp add --transport http canli https://canlicapital.com/mcp --header "Authorization: Bearer $CANLI_KEY"
+```
+
+The endpoint is stateless. On it, `get_key` issues nothing and says which key is in use, because a
+key issued there would not reach the next request. A malformed Authorization header is refused
+rather than replaced with the shared key.
+
 ## Claude Desktop
 
 Add to `claude_desktop_config.json` (Settings, Developer, Edit Config):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.3.0",
+  "version": "0.4.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",

package/src/schemas.mjs

@@ -92,6 +92,22 @@ export const breadthInput = z
   })
   .strict();
 
+// ---------------------------------------------------------------------------------------------
+// validate_track_record
+// ---------------------------------------------------------------------------------------------
+
+export const trackRecordInput = z
+  .object({
+    observed_sharpe_annualized: z.number().min(-10).max(10),
+    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),
+    benchmark_sharpe_annualized: z.number().min(-10).max(10).optional(),
+    confidence: z.number().gt(0).lt(1).optional(),
+    observations: z.number().int().min(2).max(1000000).optional(),
+  })
+  .strict();
+
 // ---------------------------------------------------------------------------------------------
 // get_key / get_receipt
 // ---------------------------------------------------------------------------------------------
@@ -151,6 +167,7 @@ export const TOOL_DESCRIPTIONS = Object.freeze({
   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_track_record: `Minimum track record length for an observed Sharpe to clear a benchmark Sharpe (default 0) at a confidence level (default 0.95), and, when observations is sent, the probabilistic Sharpe of that record against the benchmark. ${LIMITS_SENTENCES.notAdmission}`,
   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

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   breadthInput,
+  trackRecordInput,
   companyHistoryInput,
   deflatedSharpeInput,
   deflatedSharpeToolShape,
@@ -37,14 +38,26 @@ function parseOrThrow(schema, value, label) {
   throw new Error(`${label}: ${issues}`);
 }
 
-export function createSession({ base, fetchImpl, envKey, timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+// An empty CANLI_KEY, or an unsubstituted template such as "${user_config.api_key}" (what a
+// desktop extension host passes for an optional field the user left unset), is no key at all, not
+// a key to send.
+export function configuredKey(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" || /^\$\{[^}]*\}$/.test(trimmed) ? undefined : trimmed;
+}
+
+export function createSession({ base, fetchImpl, envKey, timeoutMs = REQUEST_TIMEOUT_MS, hosted } = {}) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error("Request timeout must be a positive integer");
   return {
     base: base ?? process.env.CANLI_API_BASE ?? DEFAULT_BASE,
     fetchImpl: fetchImpl ?? fetch,
-    envKey: envKey ?? process.env.CANLI_KEY ?? undefined,
+    envKey: envKey ?? configuredKey(process.env.CANLI_KEY),
     key: undefined,
     timeoutMs,
+    // Set by the hosted endpoint (api/mcp.js): which key a request runs under, so get_key can say
+    // so instead of issuing a key the next stateless request would never see.
+    hosted: hosted ?? undefined,
   };
 }
 
@@ -99,6 +112,21 @@ export function columnarObservations(observations) {
 
 export async function toolGetKey(session, args) {
   const { label } = parseOrThrow(getKeyInput, args, "get_key");
+  if (session.hosted) {
+    // The hosted endpoint is stateless: a key issued here would be gone by the next request, and
+    // every hosted caller shares the platform's egress address and so its per-client issuance quota.
+    const ownKey = "get a free key at https://canlicapital.com/developers#quickstart and send it as 'Authorization: Bearer <key>' to this endpoint";
+    const notes = {
+      caller: "This hosted session runs under the key in your Authorization header; no new key was issued.",
+      shared: `This hosted session runs under a shared anonymous key with a shared daily quota; no new key was issued. For your own quota, ${ownKey}.`,
+      none: `This hosted endpoint has no shared key configured, so validations need your own key: ${ownKey}.`,
+    };
+    return asText({
+      note: notes[session.hosted.keySource] ?? notes.none,
+      key_source: session.hosted.keySource,
+      key_present: session.hosted.keySource !== "none",
+    });
+  }
   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.",
@@ -141,6 +169,12 @@ export async function toolValidateBreadth(session, args) {
   return asText(response.envelope, response.failed);
 }
 
+export async function toolValidateTrackRecord(session, args) {
+  const body = parseOrThrow(trackRecordInput, args, "validate_track_record");
+  const response = await callApi(session, { path: "/api/v1/validate/track-record", method: "POST", body });
+  return asText(response.envelope, response.failed);
+}
+
 export async function toolGetReceipt(session, args) {
   const { id } = parseOrThrow(getReceiptInput, args, "get_receipt");
   const response = await callApi(session, { path: `/api/v1/receipts/${id}` });
@@ -223,45 +257,56 @@ export async function toolCompanyFinancialHistory(session, args) {
   });
 }
 
+// MCP tool annotations: every tool reaches the canlicapital.com API (openWorldHint). Reads are
+// marked read-only; a validation stores a receipt and get_key creates a key, so neither is
+// read-only, and nothing any tool does modifies or deletes a caller's data.
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+const WRITES_RECEIPT = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+
 export function registerTools(server, session) {
   server.registerTool(
     "get_key",
-    { title: "Get a free validation key", description: TOOL_DESCRIPTIONS.get_key, inputSchema: getKeyInput },
+    { title: "Get a free validation key", annotations: { title: "Get a free validation key", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, 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 },
+    { title: "Validate deflated Sharpe", annotations: { title: "Validate deflated Sharpe", ...WRITES_RECEIPT }, 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 },
+    { title: "Validate overfitting (CSCV)", annotations: { title: "Validate overfitting (CSCV)", ...WRITES_RECEIPT }, 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 },
+    { title: "Validate paper evidence", annotations: { title: "Validate paper evidence", ...WRITES_RECEIPT }, 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 },
+    { title: "Validate breadth ceiling", annotations: { title: "Validate breadth ceiling", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_breadth, inputSchema: breadthInput },
     (args) => toolValidateBreadth(session, args),
   );
+  server.registerTool(
+    "validate_track_record",
+    { title: "Minimum track record length", annotations: { title: "Minimum track record length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_track_record, inputSchema: trackRecordInput },
+    (args) => toolValidateTrackRecord(session, args),
+  );
   server.registerTool(
     "get_receipt",
-    { title: "Get a receipt", description: TOOL_DESCRIPTIONS.get_receipt, inputSchema: getReceiptInput },
+    { title: "Get a receipt", annotations: { title: "Get a receipt", ...READ_ONLY }, 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 },
+    { title: "Service status", annotations: { title: "Service status", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.service_status, inputSchema: emptyInput },
     () => toolServiceStatus(session),
   );
   server.registerTool(
     "company_financial_history",
-    { title: "Company financial history (SEC)", description: TOOL_DESCRIPTIONS.company_financial_history, inputSchema: companyHistoryInput },
+    { title: "Company financial history (SEC)", annotations: { title: "Company financial history (SEC)", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.company_financial_history, inputSchema: companyHistoryInput },
     (args) => toolCompanyFinancialHistory(session, args),
   );
 }