canli-validation-mcp 0.1.1 → 0.2.0

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
@@ -31,6 +36,7 @@ repository for the full design.
 | `validate_breadth` | `POST /api/v1/validate/breadth` | 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 |
 
 `validate_deflated_sharpe` accepts exactly one of two input shapes, never a mix of both:
 
@@ -43,6 +49,15 @@ repository for the full design.
 Sending fields from both shapes, or from neither, is rejected before any request leaves the
 process; see `src/schemas.mjs`.
 
+`company_financial_history` is different from the other tools: it reads the public company
+reference at canlicapital.com, not the validation API. Give it a CIK (1 to 10 digits) to list a
+company's available financial histories, or a CIK and a us-gaap concept such as `Revenues` to
+get the observations, newest first (`limit` defaults to 40, maximum 200). Every observation
+keeps its filing accession, form, filed date and unit, and the result carries the SHA-256 of the
+original SEC response and the record's own boundary sentence: these are accounting values as
+reported to the SEC, not market prices, returns or a recommendation. Companies and concepts
+outside the current release return an error with the available concepts listed.
+
 ## Configuration
 
 | Variable | Default | Meaning |
@@ -54,6 +69,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 +130,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 +182,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 +193,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.2.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",
@@ -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

@@ -110,6 +110,19 @@ export const getReceiptInput = z
 
 export const emptyInput = z.object({}).strict();
 
+// company_financial_history reads the public company reference, not the validation API.
+export const companyHistoryInput = z
+  .object({
+    cik: z.string().regex(/^\d{1,10}$/, "A CIK is 1 to 10 digits"),
+    concept: z.string().regex(/^[A-Za-z][A-Za-z0-9]{0,99}$/, "A concept is a us-gaap tag such as Revenues or Assets").optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+  })
+  .strict();
+
+// The company reference carries its own boundary sentence in every record (claim_boundary),
+// written by scripts/lib/company-reference.mjs. A test pins this copy to that source verbatim.
+export const COMPANY_REFERENCE_BOUNDARY = "Public company accounting reference, not market prices, returns, an investment recommendation, or ALPHAC performance. Validate a separately constructed return series with the validation API; accounting values are not returns.";
+
 // ---------------------------------------------------------------------------------------------
 // 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
@@ -120,9 +133,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.
@@ -134,4 +154,5 @@ export const TOOL_DESCRIPTIONS = Object.freeze({
   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}`,
+  company_financial_history: `SEC-reported financial history for one company from the canlicapital.com company reference (GET /company-data/{cik}.json). 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}`,
 });

package/src/server.mjs

@@ -6,10 +6,13 @@
 // 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 {
   breadthInput,
+  companyHistoryInput,
   deflatedSharpeInput,
   deflatedSharpeToolShape,
   emptyInput,
@@ -22,7 +25,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 +37,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 +52,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 +87,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 +100,108 @@ 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);
+}
+
+// The company reference is a public data file, not an API envelope. The result keeps every
+// field that says where a value came from (accession, form, filed date, unit, source hash) and
+// the record's own claim_boundary and policy sentences, so an agent cannot quote a number
+// without its provenance or boundary.
+export async function toolCompanyFinancialHistory(session, args) {
+  const { cik, concept, limit = 40 } = parseOrThrow(companyHistoryInput, args, "company_financial_history");
+  const id = cik.padStart(10, "0");
+  const path = `/company-data/${id}.json`;
+  const signal = AbortSignal.timeout(session.timeoutMs);
+  let res, text;
+  try {
+    res = await session.fetchImpl(`${session.base}${path}`, { headers: { Accept: "application/json" }, signal, redirect: "error" });
+    text = await res.text();
+  } catch {
+    throw new Error(signal.aborted
+      ? `${path} exceeded the request deadline; no automatic retry was sent.`
+      : `${path} could not be reached or read. Check the API base and service status; no automatic retry was sent.`);
+  }
+  if (res.status === 404) return asText({ error: { code: "not_found", message: `No company record for CIK ${id} in the current company reference release.` }, page: `${session.base}/companies` }, true);
+  if (res.status >= 400) return asText({ error: { code: "unavailable", message: `${path} returned status ${res.status}.` } }, true);
+  let record;
+  try {
+    record = JSON.parse(text);
+  } catch {
+    throw new Error(`${path} returned a non-JSON body (status ${res.status}). Response body omitted.`);
+  }
+  if (record?.schema !== "canli.company-reference.v1" || record.cik !== id || !Array.isArray(record.concepts) || typeof record.claim_boundary !== "string") {
+    return asText({ error: { code: "unexpected_record", message: `${path} did not return a canli.company-reference.v1 record for CIK ${id}.` } }, true);
+  }
+  const base = {
+    schema: "canli.mcp.company-history.v1",
+    company: { cik: record.cik, name: record.name },
+    claim_boundary: record.claim_boundary,
+    policy: record.policy,
+    source: {
+      sec_response_url: record.source_url,
+      sec_response_sha256: record.source_sha256,
+      snapshot: record.source_snapshot ? `${session.base}${record.source_snapshot}` : null,
+      fetched_at: record.fetched_at,
+      record: `${session.base}${path}`,
+    },
+  };
+  if (concept === undefined) {
+    return asText({
+      ...base,
+      page: `${session.base}/companies/${id}`,
+      histories: record.concepts.map((c) => ({ concept: c.tag, label: c.label, kind: c.kind, observations: c.observations?.length ?? 0, page: `${session.base}/companies/${id}/${c.tag}` })),
+    });
+  }
+  const history = record.concepts.find((c) => c.tag === concept);
+  if (!history) {
+    return asText({ ...base, error: { code: "concept_not_found", message: `${record.name} has no ${concept} history in this release.`, available: record.concepts.map((c) => c.tag) } }, true);
+  }
+  const observations = [...(history.observations ?? [])].sort((a, b) => String(b.end).localeCompare(String(a.end))).slice(0, limit);
+  return asText({
+    ...base,
+    page: `${session.base}/companies/${id}/${history.tag}`,
+    history: {
+      concept: history.tag,
+      taxonomy: history.taxonomy,
+      label: history.label,
+      kind: history.kind,
+      meaning: history.meaning,
+      units: [...new Set((history.observations ?? []).map((o) => o.unit))],
+      total_observations: history.observations?.length ?? 0,
+      returned: observations.length,
+      observations,
+    },
+  });
 }
 
 export function registerTools(server, session) {
@@ -150,6 +240,11 @@ export function registerTools(server, session) {
     { title: "Service status", 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 },
+    (args) => toolCompanyFinancialHistory(session, args),
+  );
 }
 
 export function createServer(session = createSession()) {
@@ -164,7 +259,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);