canli-validation-mcp 0.2.0 → 0.3.1

package/README.md

@@ -1,20 +1,19 @@
 # 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,
-so the agent cannot see a number without the sentences beside it that say what the number does
-not establish.
+gives a coding agent eight tools: issue a free key, run the four validators (deflated Sharpe,
+CSCV overfitting, paper-evidence conformance, breadth ceiling), 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)
 
@@ -58,6 +57,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 |
@@ -82,6 +104,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.2.0",
+  "version": "0.3.1",
   "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

@@ -37,14 +37,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,
   };
 }
 
@@ -73,13 +85,47 @@ 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.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.",
@@ -199,50 +245,56 @@ 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),
     },
   });
 }
 
+// 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(
     "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),
   );
 }