crosscheck-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,145 @@
+Copyright (c) 2026 Frank Speiser. All rights reserved.
+
+This software is licensed under the PolyForm Noncommercial License 1.0.0.
+The full license text follows. The authoritative source is:
+
+    https://polyformproject.org/licenses/noncommercial/1.0.0
+
+Commercial use of this software is NOT permitted under this license. For
+commercial licensing inquiries, contact the copyright holder
+(frank@metafide.io). Pre-existing commercial license grants (if any)
+are recorded in COMMERCIAL-LICENSES.md.
+
+================================================================================
+
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+any changes or new works or licenses or to third parties
+according to [Notices](#notices).
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else, or make any other licenses
+to the software.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control
+of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+================================================================================
+
+NOTE ON PRIOR LICENSE
+
+This software was previously released under the MIT License. The MIT
+grant on those historical snapshots remains in effect for anyone who
+obtained the software while it was MIT-licensed; this PolyForm
+Noncommercial License governs all subsequent commits and releases.

package/README.md

@@ -0,0 +1,272 @@
+# crosscheck-mcp
+
+A multi-LLM MCP server. Ask several models the same question, debate them,
+orchestrate them, audit them, or rubric-grade their work — all from a single
+MCP tool surface that drops into Claude Desktop / Claude Code / Cursor /
+Continue / any other MCP host.
+
+This is the **TypeScript** implementation. There is also a Python implementation
+in [`../python/`](../python/) — both ship the same tool surface; pick whichever
+fits your stack. The TypeScript build runs natively in Node 18.17+ and has
+**no Python dependency at runtime**.
+
+## What it does
+
+Twenty-six tools across deliberation, planning, auditing, and operations.
+Highlights:
+
+- `confer` / `debate` / `coordinate` / `triangulate` — parallel panel calls,
+  structured deliberation, structured synthesis with dissent
+- `audit` — rubric-graded scoring; single-judge or multi-judge consensus
+  (median + std-dev disagreement detection, severity-aware obvious-failure flags)
+- `orchestrate` — planner-driven DAG of LLM subtasks with optional cheap-mode
+  tier-aware routing
+- `create` / `create_cheap` — lifecycle macros: scope → build → review →
+  audit, with retry-on-failure
+- `solve` — iterative propose → verify → retry with sandboxed shell verifiers
+- `verify` — deterministic property checks (text, shell, url_head)
+- `recall` / `session_memory` / `scoreboard` / `explain` — operational
+  introspection
+
+Cross-cutting features: scoreboard-driven router for panel selection,
+session circuit breakers (cost / tokens / wall / DAG breadth), cross-provider
+canary detection for indirect prompt-injection, early-stop on agreement,
+prompt canonicalisation cache, structured claims with supports/attacks edges.
+
+## Install
+
+```bash
+npm install -g crosscheck-mcp
+```
+
+This installs the `crosscheck-mcp` binary on your PATH.
+
+The package needs at least one LLM provider API key in the environment.
+Supported providers (set any subset):
+
+```bash
+export ANTHROPIC_API_KEY=...
+export OPENAI_API_KEY=...
+export XAI_API_KEY=...
+export GEMINI_API_KEY=...
+export MISTRAL_API_KEY=...
+export GROQ_API_KEY=...
+export DEEPSEEK_API_KEY=...
+```
+
+## Use it with an MCP host
+
+### Claude Code
+
+Add the server to your project's `.claude/settings.json` (or the user-level
+config):
+
+```json
+{
+  "mcpServers": {
+    "crosscheck": {
+      "command": "crosscheck-mcp",
+      "env": {
+        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
+        "OPENAI_API_KEY":    "${OPENAI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code; the `mcp__crosscheck__*` tools become available.
+
+Tip — type `xc` or `XC` at the start of a prompt to route it to crosscheck;
+the server ships an MCP `instructions` payload that teaches Claude Code the
+convention. Details in [`../../CROSSCHECK_USAGE.md`](../../CROSSCHECK_USAGE.md).
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "crosscheck": {
+      "command": "crosscheck-mcp",
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-...",
+        "OPENAI_API_KEY":    "sk-..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Tools appear under the hammer icon.
+
+### Cursor
+
+Cursor reads MCP servers from `~/.cursor/mcp.json`. Same shape:
+
+```json
+{
+  "mcpServers": {
+    "crosscheck": {
+      "command": "crosscheck-mcp",
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-...",
+        "OPENAI_API_KEY":    "sk-..."
+      }
+    }
+  }
+}
+```
+
+### Any other MCP host
+
+Spawn `crosscheck-mcp` over stdio. It speaks MCP JSON-RPC 2.0 — no custom
+protocol.
+
+## Optional configuration
+
+Environment variables:
+
+| Variable                          | Purpose                                                                                       |
+|-----------------------------------|-----------------------------------------------------------------------------------------------|
+| `CROSSCHECK_DB_PATH`              | SQLite path for scoreboard / claims / session memory / recall. Default: `.crosscheck/db.sqlite` |
+| `CROSSCHECK_DB_DISABLED=1`        | Skip storage entirely (storage-driven tools return graceful errors).                          |
+| `CROSSCHECK_TRANSCRIPTS_DIR`      | Where audit's session-id-only mode looks for transcripts.                                     |
+| `CROSSCHECK_PRICING_PATH`         | Path to `pricing.json` (used by cheap-mode tier picker).                                      |
+| `CROSSCHECK_REPO_ROOT`            | Override repo-root detection (used by `fetch` for evidence paths).                            |
+| `CROSSCHECK_REJECT_CONFIG_DRIFT=1`| Reject pinned-config drift instead of warning.                                                |
+| `CROSSCHECK_BRIDGE_PYTHON=1`      | OPT-IN: spawn the Python server as a parity-testing backstop (see below). |
+| `CROSSCHECK_EVENTS`               | Structured event emitter: `stderr` (default), `off`, `file`, `both`. See [Observability](#observability). |
+| `CROSSCHECK_EVENTS_PATH`          | Path for the `file` / `both` event sinks (ND-JSON, one event per line).                       |
+| `<PROVIDER>_API_KEY`              | At least one is required for LLM-using tools. Optional for `verify`-only flows.               |
+| `<PROVIDER>_MODEL`                | Override a provider's default model.                                                          |
+
+The Python backstop is OPTIONAL. **Every v1 feature path on every
+tool runs natively in TypeScript.** The bridge is useful for:
+1. Cross-language parity testing (the `test/parity/` fixtures check
+   that the TS implementation produces byte-equal output against
+   the Python oracle).
+2. The `reactive` opt on `orchestrate` (mid-flight DAG mutation),
+   which still defers to bridge.
+3. A few remaining advanced opts that no longer have a Node-side
+   implementation but kept the bridge as a fallback when host
+   integrations aren't wired (e.g. `worker_tools` without
+   `innerCallers`).
+
+Everything in the [Tools](#what-it-does) list above works without
+\`CROSSCHECK_BRIDGE_PYTHON\` being set.
+
+## Observability
+
+Every `tools/call` request emits one structured `tool_invoke` event
+through a pluggable event bus. The default sink is ND-JSON to
+stderr — MCP hosts already capture stderr into their session logs,
+so this lights up out of the box with no configuration.
+
+### Event shape
+
+```json
+{
+  "event":          "tool_invoke",
+  "id":             "1a3c0f5d",
+  "tool":           "confer",
+  "started_at":     "2026-06-06T19:42:11.231Z",
+  "duration_ms":    1842,
+  "status":         "ok",
+  "args_keys":      ["question", "providers", "untrusted_input"],
+  "result_keys":    ["answers", "question", "tool"],
+  "envelope_bytes": 12451
+}
+```
+
+Failure paths emit the same shape with `status: "error"` and an
+`error_message` (truncated to 512 chars). When a tool returns a
+domain-level error envelope (with `error_code`), the call still
+completes — `status` stays `"ok"` and `error_code` is mirrored to
+the event for easy filtering:
+
+```json
+{
+  "event": "tool_invoke", "id": "...", "tool": "audit",
+  "status": "ok",
+  "error_code": "AUDIT_NO_AUDITOR",
+  "...": "..."
+}
+```
+
+What's deliberately **not** in the event: argument values, response
+text, transcripts. Long prompts + multi-LLM debates would dwarf the
+signal and may carry sensitive content. Key inventory + envelope
+size is usually enough to triage a regression; pull the full
+envelope from a tool replay when you need it.
+
+### Routing
+
+| `CROSSCHECK_EVENTS=` | Effect                                                  |
+|----------------------|---------------------------------------------------------|
+| `stderr` (default)   | ND-JSON to stderr.                                      |
+| `off`                | Silent. Useful for noisy multi-tool benchmark runs.     |
+| `file`               | Append to `CROSSCHECK_EVENTS_PATH` only.                |
+| `both`               | Append to file AND write to stderr.                     |
+
+`CROSSCHECK_EVENTS_PATH` is required when `CROSSCHECK_EVENTS` is
+`file` or `both`. Parent directories are created on first emit.
+
+### Custom emitters (programmatic)
+
+```ts
+import { setEventEmitter } from "crosscheck-mcp";
+
+setEventEmitter({
+  emit(event) {
+    metrics.histogram("crosscheck.tool_duration_ms",
+      event.duration_ms, { tool: event.tool, status: event.status });
+  },
+});
+```
+
+The emitter is replaced for the whole process; for test isolation
+use the `RecordingEmitter` export and restore the original via
+`getEventEmitter()` / `setEventEmitter()` in `beforeEach` /
+`afterEach`.
+
+## Programmatic use
+
+```ts
+import { createServer, connectAndServe } from "crosscheck-mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = createServer({ /* providers, storage, pricing, repoRoot ... */ });
+await server.connect(new StdioServerTransport());
+```
+
+## Development
+
+```bash
+git clone https://github.com/fxspeiser/crosscheck-agent
+cd crosscheck-agent/servers/typescript
+npm install
+npm run build        # tsup → dist/{node-stdio,node-http,browser-ext}.{js,cjs}
+npm test             # vitest — 1,175 tests
+npm run typecheck    # tsc --noEmit
+npm run docs:usage   # regenerate the routing-convention doc from src/instructions.ts
+```
+
+End-to-end stdio handshake:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ping","arguments":{"echo":"hello"}}}' \
+  | node dist/node-stdio.js
+```
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE). Commercial licenses are tracked in
+[../../COMMERCIAL-LICENSES.md](../../COMMERCIAL-LICENSES.md); contact
+`frank@metafide.io` for inquiries.

package/dist/browser-ext.cjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/entrypoints/browser-ext.ts
+var browser_ext_exports = {};
+__export(browser_ext_exports, {
+  PLACEHOLDER: () => PLACEHOLDER
+});
+module.exports = __toCommonJS(browser_ext_exports);
+var PLACEHOLDER = "browser-ext transport \u2014 not yet implemented";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLACEHOLDER
+});
+//# sourceMappingURL=browser-ext.cjs.map

package/dist/browser-ext.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entrypoints/browser-ext.ts"],"sourcesContent":["// Browser-extension entrypoint — stub. Will host the\n// chrome.runtime.onMessage transport adapter (added in a later phase).\n// Tsup builds a bundle slot for it from day one so the dist/ surface\n// is stable.\n\nexport const PLACEHOLDER = \"browser-ext transport — not yet implemented\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAKO,IAAM,cAAc;","names":[]}

package/dist/browser-ext.d.cts

@@ -0,0 +1,3 @@
+declare const PLACEHOLDER = "browser-ext transport \u2014 not yet implemented";
+
+export { PLACEHOLDER };

package/dist/browser-ext.d.ts

@@ -0,0 +1,3 @@
+declare const PLACEHOLDER = "browser-ext transport \u2014 not yet implemented";
+
+export { PLACEHOLDER };

package/dist/browser-ext.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+// src/entrypoints/browser-ext.ts
+var PLACEHOLDER = "browser-ext transport \u2014 not yet implemented";
+export {
+  PLACEHOLDER
+};
+//# sourceMappingURL=browser-ext.js.map

package/dist/browser-ext.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entrypoints/browser-ext.ts"],"sourcesContent":["// Browser-extension entrypoint — stub. Will host the\n// chrome.runtime.onMessage transport adapter (added in a later phase).\n// Tsup builds a bundle slot for it from day one so the dist/ surface\n// is stable.\n\nexport const PLACEHOLDER = \"browser-ext transport — not yet implemented\";\n"],"mappings":";;;AAKO,IAAM,cAAc;","names":[]}

package/dist/node-http.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/entrypoints/node-http.ts
+var node_http_exports = {};
+__export(node_http_exports, {
+  PLACEHOLDER: () => PLACEHOLDER
+});
+module.exports = __toCommonJS(node_http_exports);
+
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/entrypoints/node-http.ts
+var PLACEHOLDER = "node-http transport \u2014 not yet implemented";
+if (importMetaUrl === `file://${process.argv[1]}`) {
+  process.stderr.write(
+    "crosscheck-agent: node-http entrypoint is not yet implemented (Phase 0).\n"
+  );
+  process.exit(2);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLACEHOLDER
+});
+//# sourceMappingURL=node-http.cjs.map

package/dist/node-http.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entrypoints/node-http.ts","../node_modules/tsup/assets/cjs_shims.js"],"sourcesContent":["// Node-HTTP entrypoint — stub. Will host the MCP Streamable HTTP transport\n// (added in a later phase). Lives here so tsup builds a bundle slot for it\n// from day one, and so the import surface in `dist/` is stable.\n\nexport const PLACEHOLDER = \"node-http transport — not yet implemented\";\n\nif (import.meta.url === `file://${process.argv[1]}`) {\n  process.stderr.write(\n    \"crosscheck-agent: node-http entrypoint is not yet implemented (Phase 0).\\n\",\n  );\n  process.exit(2);\n}\n","// Shim globals in cjs bundle\n// There's a weird bug that esbuild will always inject importMetaUrl\n// if we export it as `const importMetaUrl = ... __filename ...`\n// But using a function will not cause this issue\n\nconst getImportMetaUrl = () => \n  typeof document === \"undefined\" \n    ? new URL(`file:${__filename}`).href \n    : (document.currentScript && document.currentScript.tagName.toUpperCase() === 'SCRIPT') \n      ? document.currentScript.src \n      : new URL(\"main.js\", document.baseURI).href;\n\nexport const importMetaUrl = /* @__PURE__ */ getImportMetaUrl()\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,IAAM,mBAAmB,MACvB,OAAO,aAAa,cAChB,IAAI,IAAI,QAAQ,UAAU,EAAE,EAAE,OAC7B,SAAS,iBAAiB,SAAS,cAAc,QAAQ,YAAY,MAAM,WAC1E,SAAS,cAAc,MACvB,IAAI,IAAI,WAAW,SAAS,OAAO,EAAE;AAEtC,IAAM,gBAAgC,iCAAiB;;;ADRvD,IAAM,cAAc;AAE3B,IAAI,kBAAoB,UAAU,QAAQ,KAAK,CAAC,CAAC,IAAI;AACnD,UAAQ,OAAO;AAAA,IACb;AAAA,EACF;AACA,UAAQ,KAAK,CAAC;AAChB;","names":[]}

package/dist/node-http.d.cts

@@ -0,0 +1,3 @@
+declare const PLACEHOLDER = "node-http transport \u2014 not yet implemented";
+
+export { PLACEHOLDER };

package/dist/node-http.d.ts

@@ -0,0 +1,3 @@
+declare const PLACEHOLDER = "node-http transport \u2014 not yet implemented";
+
+export { PLACEHOLDER };

package/dist/node-http.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// src/entrypoints/node-http.ts
+var PLACEHOLDER = "node-http transport \u2014 not yet implemented";
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.stderr.write(
+    "crosscheck-agent: node-http entrypoint is not yet implemented (Phase 0).\n"
+  );
+  process.exit(2);
+}
+export {
+  PLACEHOLDER
+};
+//# sourceMappingURL=node-http.js.map

package/dist/node-http.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entrypoints/node-http.ts"],"sourcesContent":["// Node-HTTP entrypoint — stub. Will host the MCP Streamable HTTP transport\n// (added in a later phase). Lives here so tsup builds a bundle slot for it\n// from day one, and so the import surface in `dist/` is stable.\n\nexport const PLACEHOLDER = \"node-http transport — not yet implemented\";\n\nif (import.meta.url === `file://${process.argv[1]}`) {\n  process.stderr.write(\n    \"crosscheck-agent: node-http entrypoint is not yet implemented (Phase 0).\\n\",\n  );\n  process.exit(2);\n}\n"],"mappings":";;;AAIO,IAAM,cAAc;AAE3B,IAAI,YAAY,QAAQ,UAAU,QAAQ,KAAK,CAAC,CAAC,IAAI;AACnD,UAAQ,OAAO;AAAA,IACb;AAAA,EACF;AACA,UAAQ,KAAK,CAAC;AAChB;","names":[]}