canli-validation-mcp 0.6.0 → 0.7.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/canli-validation-mcp)](https://www.npmjs.com/package/canli-validation-mcp)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/arhancanli/canli-validation-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/arhancanli/canli-validation-mcp)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14954/badge)](https://www.bestpractices.dev/projects/14954)
 [![Glama score](https://glama.ai/mcp/servers/arhancanli/canli-validation-mcp/badges/score.svg)](https://glama.ai/mcp/servers/arhancanli/canli-validation-mcp)
 
 An MCP (Model Context Protocol) server over canlicapital.com's free, keyed validation API. It
@@ -133,6 +134,7 @@ an array of objects.
 | `CANLI_API_BASE` | `https://canlicapital.com` | Where the API lives. Point it at a preview deployment for testing. |
 | `CANLI_KEY` | unset | A key already issued from `POST /api/v1/keys`. When set, `get_key` sends no request and reports the key is already configured; every other tool sends it as `Authorization: Bearer <key>`. |
 | `CANLI_FULL_ENVELOPE` | unset | `1` or `true` returns each validation's full API envelope instead of the compact result (below). |
+| `CANLI_TOOLSETS` | all | Which tools to list: a comma-separated choice of `validate`, `receipts`, `company` and `status`, or `all`. An unknown name is refused at startup. See "Toolsets" below. |
 | `CANLI_LOCAL` | unset | `1` or `true` runs the eight validators on this machine (private local mode, below): no key, no network, no receipt. |
 
 If `CANLI_KEY` is not set and local mode is off, call `get_key` once per session before the validators. The key it
@@ -170,6 +172,9 @@ by every hosted caller. For your own quota, issue a free key (see
 claude mcp add --transport http canli https://canlicapital.com/mcp --header "Authorization: Bearer $CANLI_KEY"
 ```
 
+Add `?toolsets=` to the URL to list only some tools (see "Toolsets" below), for example
+`https://canlicapital.com/mcp?toolsets=company`.
+
 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.
@@ -279,6 +284,35 @@ describes the service rather than the answer, and an agent pays for every token
 call. It stays in the stored receipt, which `get_receipt` returns in full, and in `service_status`.
 On a breadth result this is about half the text. Set `CANLI_FULL_ENVELOPE=1` to receive every field.
 
+## Toolsets (tokens)
+
+A client sends the model the whole tool list on every turn, and it is most of each turn's prompt:
+a validation result is a few hundred tokens, the list of all fourteen tools several thousand. A
+client that needs one kind of tool can list only that kind, with `CANLI_TOOLSETS` (stdio) or
+`?toolsets=` (hosted endpoint). The default is every tool.
+
+| toolset | tools |
+|---|---|
+| `validate` | `get_key`, the eight validators, `audit_backtest` |
+| `receipts` | `get_receipt`, `verify_receipt` |
+| `company` | `company_financial_history` |
+| `status` | `service_status` |
+
+Measured with `bench/tool_list_tokens.py` (tokenizer: tiktoken `o200k_base`; other models'
+tokenizers give different absolute counts), in the shape an OpenAI-style client sends the list:
+
+| CANLI_TOOLSETS | tools | tokens per turn | of all |
+|---|---|---|---|
+| `all` | 14 | 3,888 | 100% |
+| `validate` | 10 | 3,154 | 81% |
+| `receipts` | 2 | 340 | 9% |
+| `company` | 1 | 302 | 8% |
+| `status` | 1 | 98 | 3% |
+
+Providers cache a tool list that is identical from turn to turn and bill the cached part at a
+fraction of the price (`test/tool-list-stable.test.mjs` keeps each list byte-stable); a smaller list
+costs less either way.
+
 ## Local checkout
 
 Only needed to develop or test this package itself, not to run the published one.

package/package.json

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

@@ -66,7 +66,29 @@ export function configuredLocal(value) {
   return v === "1" || v?.toLowerCase() === "true";
 }
 
-export function createSession({ base, fetchImpl, envKey, timeoutMs = REQUEST_TIMEOUT_MS, hosted, local, fullEnvelope, receiptKeys } = {}) {
+// Toolsets: which tools the server lists. The tool list is re-sent to the model on every turn and
+// is most of each turn's prompt (README, "Toolsets"; bench/tool_list_tokens.py measures it), so a
+// client that needs one kind of tool can load only that kind. Default: all.
+export const TOOLSETS = Object.freeze({
+  validate: Object.freeze(["get_key", "validate_deflated_sharpe", "validate_overfitting", "validate_paper_evidence", "validate_breadth", "validate_track_record", "validate_backtest_length", "validate_haircut_sharpe", "validate_luck_trials", "audit_backtest"]),
+  receipts: Object.freeze(["get_receipt", "verify_receipt"]),
+  company: Object.freeze(["company_financial_history"]),
+  status: Object.freeze(["service_status"]),
+});
+
+// CANLI_TOOLSETS=validate,company (or ?toolsets= on the hosted endpoint): a comma-separated list of
+// TOOLSETS names, or "all". Empty or unsubstituted means all; an unknown name is refused, so a typo
+// never silently leaves a client without the tools it asked for.
+export function configuredToolsets(value) {
+  const v = configuredKey(value);
+  if (!v || v.trim().toLowerCase() === "all") return Object.keys(TOOLSETS);
+  const names = [...new Set(v.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean))];
+  const unknown = names.filter((n) => !Object.hasOwn(TOOLSETS, n));
+  if (unknown.length || !names.length) throw new Error(`Unknown toolset ${unknown.join(", ") || "(none)"}; choose from ${Object.keys(TOOLSETS).join(", ")} or all`);
+  return names;
+}
+
+export function createSession({ base, fetchImpl, envKey, timeoutMs = REQUEST_TIMEOUT_MS, hosted, local, fullEnvelope, receiptKeys, toolsets } = {}) {
   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,
@@ -81,6 +103,7 @@ export function createSession({ base, fetchImpl, envKey, timeoutMs = REQUEST_TIM
     fullEnvelope: fullEnvelope ?? configuredFullEnvelope(process.env.CANLI_FULL_ENVELOPE),
     // Tests pass their own keys; everyone else verifies against the bundled published keys.
     receiptKeys: receiptKeys ?? undefined,
+    toolsets: toolsets ?? configuredToolsets(process.env.CANLI_TOOLSETS),
   };
 }
 
@@ -476,72 +499,74 @@ const READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: t
 const WRITES_RECEIPT = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
 
 export function registerTools(server, session) {
-  server.registerTool(
+  const enabled = new Set((session.toolsets ?? Object.keys(TOOLSETS)).flatMap((name) => TOOLSETS[name]));
+  const register = (name, ...rest) => { if (enabled.has(name)) server.registerTool(name, ...rest); };
+  register(
     "get_key",
     { 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(
+  register(
     "validate_deflated_sharpe",
     { 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(
+  register(
     "validate_overfitting",
     { title: "Validate overfitting (CSCV)", annotations: { title: "Validate overfitting (CSCV)", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_overfitting, inputSchema: overfittingInput },
     (args) => toolValidateOverfitting(session, args),
   );
-  server.registerTool(
+  register(
     "validate_paper_evidence",
     { 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(
+  register(
     "validate_breadth",
     { title: "Validate breadth ceiling", annotations: { title: "Validate breadth ceiling", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_breadth, inputSchema: breadthInput },
     (args) => toolValidateBreadth(session, args),
   );
-  server.registerTool(
+  register(
     "validate_track_record",
     { title: "Minimum track record length", annotations: { title: "Minimum track record length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_track_record, inputSchema: trackRecordInput },
     (args) => toolValidateTrackRecord(session, args),
   );
-  server.registerTool(
+  register(
     "validate_backtest_length",
     { title: "Minimum backtest length", annotations: { title: "Minimum backtest length", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_backtest_length, inputSchema: backtestLengthInput },
     (args) => toolValidateBacktestLength(session, args),
   );
-  server.registerTool(
+  register(
     "validate_haircut_sharpe",
     { title: "Haircut Sharpe ratio", annotations: { title: "Haircut Sharpe ratio", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_haircut_sharpe, inputSchema: haircutSharpeInput },
     (args) => toolValidateHaircutSharpe(session, args),
   );
-  server.registerTool(
+  register(
     "validate_luck_trials",
     { title: "Luck-equivalent trials", annotations: { title: "Luck-equivalent trials", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.validate_luck_trials, inputSchema: luckTrialsInput },
     (args) => toolValidateLuckTrials(session, args),
   );
-  server.registerTool(
+  register(
     "audit_backtest",
     { title: "Audit a backtest", annotations: { title: "Audit a backtest", ...WRITES_RECEIPT }, description: TOOL_DESCRIPTIONS.audit_backtest, inputSchema: auditBacktestToolShape },
     (args) => toolAuditBacktest(session, args),
   );
-  server.registerTool(
+  register(
     "get_receipt",
     { title: "Get a receipt", annotations: { title: "Get a receipt", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.get_receipt, inputSchema: getReceiptInput },
     (args) => toolGetReceipt(session, args),
   );
-  server.registerTool(
+  register(
     "verify_receipt",
     { title: "Verify a receipt", annotations: { title: "Verify a receipt", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.verify_receipt, inputSchema: verifyReceiptToolShape },
     (args) => toolVerifyReceipt(session, args),
   );
-  server.registerTool(
+  register(
     "service_status",
     { title: "Service status", annotations: { title: "Service status", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.service_status, inputSchema: emptyInput },
     () => toolServiceStatus(session),
   );
-  server.registerTool(
+  register(
     "company_financial_history",
     { title: "Company financial history (SEC)", annotations: { title: "Company financial history (SEC)", ...READ_ONLY }, description: TOOL_DESCRIPTIONS.company_financial_history, inputSchema: companyHistoryToolShape },
     (args) => toolCompanyFinancialHistory(session, args),