canli-validation-mcp 0.3.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)
 
@@ -105,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.3.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,
   };
 }
 
@@ -99,6 +111,21 @@ export function columnarObservations(observations) {
 
 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.",
@@ -223,45 +250,51 @@ export async function toolCompanyFinancialHistory(session, args) {
   });
 }
 
+// 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),
   );
 }