canli-validation-mcp 0.1.2 → 0.3.0

package/README.md

@@ -36,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:
 
@@ -48,6 +49,38 @@ 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.
+
+## Compact context (0.3.0)
+
+An agent pays for every token a tool returns, including whitespace it never reads. Since 0.3.0
+every result is minified JSON, and a company history returns its observations as one `columns`
+header and one row per observation, with a unit shared by every row stated once. No field is
+dropped: every boundary sentence, accession number, form, filed date and source hash is still in
+the result, and `columns` + `rows` rebuild each observation exactly.
+
+Measured with `bench/token_cost.py` on live records (tokenizer: tiktoken `o200k_base`; other
+tokenizers give different absolute counts), 20 observations each:
+
+| Record | 0.2.0 (indented) | minified | 0.3.0 (minified, columnar) |
+| --- | ---: | ---: | ---: |
+| Apple, StockholdersEquity | 2,214 | 1,560 (−29.5%) | 1,060 (−52.1%) |
+| Microsoft, CashAndCashEquivalentsAtCarryingValue | 2,231 | 1,574 (−29.4%) | 1,065 (−52.3%) |
+
+The validation tools gain the minification only: the live `service_status` envelope measured 593
+tokens indented and 475 minified (−19.9%); their boundary sentences are kept word for word. These
+are measurements of these results, not a claim about any other server.
+
+**Breaking change from 0.2.0:** `history.observations` is now `{unit?, columns, rows}` instead of
+an array of objects.
+
 ## Configuration
 
 | Variable | Default | Meaning |

package/package.json

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

@@ -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
@@ -141,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

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   breadthInput,
+  companyHistoryInput,
   deflatedSharpeInput,
   deflatedSharpeToolShape,
   emptyInput,
@@ -72,11 +73,30 @@ async function callApi(session, { path, method = "GET", body }) {
   return { envelope, failed: res.status >= 400 || Boolean(envelope?.error) };
 }
 
+// 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,
+// 1,056 with the columnar history below.
 const asText = (envelope, failed = false) => ({
-  content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+  content: [{ type: "text", text: JSON.stringify(envelope) }],
   ...(failed ? { isError: true } : {}),
 });
 
+// A history's observations as one header and one row each, instead of every field name repeated
+// on every observation. The column order is fixed so a row can be read without its keys; a unit
+// shared by every row is stated once.
+export const OBSERVATION_COLUMNS = ["end", "val", "accn", "fy", "fp", "form", "filed", "unit"];
+
+export function columnarObservations(observations) {
+  const units = [...new Set(observations.map((o) => o.unit))];
+  const columns = units.length === 1 ? OBSERVATION_COLUMNS.filter((c) => c !== "unit") : OBSERVATION_COLUMNS;
+  return {
+    ...(units.length === 1 ? { unit: units[0] } : {}),
+    columns,
+    rows: observations.map((o) => columns.map((c) => o[c] ?? null)),
+  };
+}
+
 export async function toolGetKey(session, args) {
   const { label } = parseOrThrow(getKeyInput, args, "get_key");
   if (session.envKey) {
@@ -132,6 +152,77 @@ export async function toolServiceStatus(session) {
   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: columnarObservations(observations),
+    },
+  });
+}
+
 export function registerTools(server, session) {
   server.registerTool(
     "get_key",
@@ -168,6 +259,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()) {