canli-validation-mcp 0.1.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arhan Canli / Canli Capital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,6 +11,11 @@ This package is published to npm as [`canli-validation-mcp`](https://www.npmjs.c
 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.
+
 ## What the API is (and is not)
 
 The engine is the product. The service runs your submitted numbers through the same honesty
@@ -54,6 +59,13 @@ If `CANLI_KEY` is not set, call `get_key` once per session before the four valid
 returns lives only in this process's memory for the life of the session; it is not written to
 disk.
 
+HTTP failures and API error envelopes are marked as MCP tool errors while preserving
+the complete JSON envelope. A successful validation with a negative verdict remains
+a normal result. Requests have a 30-second deadline covering headers and body, reject
+redirects, and are never retried automatically. A timeout may occur after the service
+has processed a request; check service status before deciding to submit again.
+Non-JSON response bodies and raw network errors are omitted from tool errors.
+
 ## Install
 
 No install step. `npx` fetches the published package on first run, so every client config below
@@ -108,7 +120,8 @@ 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
+if (keyResult.isError) throw new Error("Key setup failed; inspect the error privately.");
+// The session retains the issued key. Avoid printing its envelope into logs.
 
 const result = await client.callTool({
   name: "validate_deflated_sharpe",
@@ -159,6 +172,7 @@ in place of `npx -y canli-validation-mcp` in any config above.
 
 ```bash
 npm test
+npm run test:package
 ```
 
 Runs `node --test` over `test/*.test.mjs`: schema round-trips against the API's own OpenAPI and
@@ -169,6 +183,11 @@ file contains an em dash, and one test that spawns the actual server binary and
 MCP `tools/list` and `callTool` handshake over stdio against a local HTTP stub, so the wiring is
 proven rather than assumed.
 
+`test:package` creates the actual npm tarball, checks its exact file list and license,
+installs it in a temporary consumer directory, and runs the stdio test against that
+installed entry. Dependency installation contacts npm; tool calls use only the local
+HTTP stub. It neither publishes a package nor issues a production API key.
+
 ## Dependencies
 
 Only `@modelcontextprotocol/sdk` (pinned exact) and `zod` (pinned exact). No other runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",
@@ -16,11 +16,21 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "test:package": "node test/package-smoke.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "zod": "4.5.4"
   },
-  "mcpName": "io.github.arhancanli/canli-validation-mcp"
+  "mcpName": "io.github.arhancanli/canli-validation-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arhancanli/canlicapital.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://canlicapital.com/developers",
+  "bugs": {
+    "url": "https://github.com/arhancanli/canlicapital/issues"
+  }
 }

package/src/schemas.mjs

@@ -120,9 +120,16 @@ 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.",
+  quotas: "Quotas: 1000 validations per key per UTC day, 5 keys per client per UTC day, 1048576 bytes per validation request, 1024 bytes per key revocation request, 20000 observations per series, 200 variants per matrix.",
 });
 
+// The MCP registry caps server.json's top-level description at 100 characters (its 422 reads
+// "expected length <= 100"), shorter than any sentence above. That one description carries this
+// clause instead: the verbatim tail of `notAdmission`, so it cannot drift from the boundary
+// language either (test/schemas.test.mjs pins the tail, test/registry-files.test.mjs the cap).
+export const REGISTRY_LIMITS_CLAUSE = "is not admission to anything and is not a forecast.";
+export const REGISTRY_DESCRIPTION_MAX = 100;
+
 // 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.

package/src/server.mjs

@@ -6,6 +6,8 @@
 // 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 { readFileSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -22,7 +24,8 @@ import {
 
 export const DEFAULT_BASE = "https://canlicapital.com";
 export const SERVER_NAME = "canlicapital-validation-mcp";
-export const SERVER_VERSION = "0.1.0";
+export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+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
 // ZodError, so a thrown error reads well inside an MCP isError result.
@@ -33,12 +36,14 @@ function parseOrThrow(schema, value, label) {
   throw new Error(`${label}: ${issues}`);
 }
 
-export function createSession({ base, fetchImpl, envKey } = {}) {
+export function createSession({ base, fetchImpl, envKey, timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+  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,
     key: undefined,
+    timeoutMs,
   };
 }
 
@@ -46,18 +51,31 @@ 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 };
+  const signal = AbortSignal.timeout(session.timeoutMs);
+  const init = { method, headers, signal, redirect: "error" };
   if (body !== undefined) init.body = JSON.stringify(body);
-  const res = await session.fetchImpl(`${session.base}${path}`, init);
-  const text = await res.text();
+  let res, text;
   try {
-    return JSON.parse(text);
+    res = await session.fetchImpl(`${session.base}${path}`, init);
+    text = await res.text();
   } catch {
-    throw new Error(`${path} returned a non-JSON body (status ${res.status}): ${text.slice(0, 300)}`);
+    throw new Error(signal.aborted
+      ? `${path} exceeded the request deadline. The server may have processed the request; no automatic retry was sent.`
+      : `${path} could not be reached or read. Check the API base and service status; no automatic retry was sent.`);
   }
+  let envelope;
+  try {
+    envelope = JSON.parse(text);
+  } catch {
+    throw new Error(`${path} returned a non-JSON body (status ${res.status}). Response body omitted.`);
+  }
+  return { envelope, failed: res.status >= 400 || Boolean(envelope?.error) };
 }
 
-const asText = (envelope) => ({ content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }] });
+const asText = (envelope, failed = false) => ({
+  content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+  ...(failed ? { isError: true } : {}),
+});
 
 export async function toolGetKey(session, args) {
   const { label } = parseOrThrow(getKeyInput, args, "get_key");
@@ -68,9 +86,9 @@ export async function toolGetKey(session, args) {
       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);
+  const response = await callApi(session, { path: "/api/v1/keys", method: "POST", body: { label } });
+  if (!response.failed && response.envelope?.data?.key) session.key = response.envelope.data.key;
+  return asText(response.envelope, response.failed);
 }
 
 export async function toolValidateDeflatedSharpe(session, args) {
@@ -81,37 +99,37 @@ export async function toolValidateDeflatedSharpe(session, args) {
         "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);
+  const response = await callApi(session, { path: "/api/v1/validate/deflated-sharpe", method: "POST", body: parsed.data });
+  return asText(response.envelope, response.failed);
 }
 
 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);
+  const response = await callApi(session, { path: "/api/v1/validate/overfitting", method: "POST", body });
+  return asText(response.envelope, response.failed);
 }
 
 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);
+  const response = await callApi(session, { path: "/api/v1/validate/paper-evidence", method: "POST", body });
+  return asText(response.envelope, response.failed);
 }
 
 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);
+  const response = await callApi(session, { path: "/api/v1/validate/breadth", method: "POST", body });
+  return asText(response.envelope, response.failed);
 }
 
 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);
+  const response = await callApi(session, { path: `/api/v1/receipts/${id}` });
+  return asText(response.envelope, response.failed);
 }
 
 export async function toolServiceStatus(session) {
-  const envelope = await callApi(session, { path: "/api/v1/validate/status" });
-  return asText(envelope);
+  const response = await callApi(session, { path: "/api/v1/validate/status" });
+  return asText(response.envelope, response.failed);
 }
 
 export function registerTools(server, session) {
@@ -164,7 +182,7 @@ async function main() {
   await server.connect(transport);
 }
 
-const isMain = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
 if (isMain) {
   main().catch((err) => {
     console.error(`${SERVER_NAME}: fatal`, err);