canli-validation-mcp 0.2.0 → 0.3.0

package/README.md

@@ -58,6 +58,29 @@ original SEC response and the record's own boundary sentence: these are accounti
 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.2.0",
+  "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/server.mjs

@@ -73,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) {
@@ -199,7 +218,7 @@ export async function toolCompanyFinancialHistory(session, args) {
       units: [...new Set((history.observations ?? []).map((o) => o.unit))],
       total_observations: history.observations?.length ?? 0,
       returned: observations.length,
-      observations,
+      observations: columnarObservations(observations),
     },
   });
 }