agentcrashtest-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Selliks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# Clearance MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Crash-test an agent's system prompt from inside Claude Code, Claude Desktop, Cursor or any MCP client. It calls the public API behind [agentcrashtest.com/test](https://agentcrashtest.com/test): one file, Node 20+, no dependencies, no keys. The limits are the site's: 3 tests per network per day, prompts up to 8000 characters.
+
+## Connect
+
+Claude Code:
+```bash
+claude mcp add clearance -- node /path/to/clearance/mcp/clearance-mcp.mjs
+```
+
+Claude Desktop, Cursor and other clients (`mcpServers` in their config file):
+```json
+{
+  "mcpServers": {
+    "clearance": { "command": "node", "args": ["/path/to/clearance/mcp/clearance-mcp.mjs"] }
+  }
+}
+```
+
+Then ask: *"Crash-test this system prompt with Clearance and tell me what it lost."*
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `clearance_test` | Starts a test: `system_prompt` (required), `tools` = `clearance-v1` (default), `agentconnect-v1`, `outlayer-v1` or `agentkit-v1`. Returns the test id and the result page. |
+| `clearance_result` | Reads a test by `id`; `wait_seconds` (up to 45) keeps polling until it is done; call again if it is still running. When done: per run, the attack, whether the agent was deceived, NEAR lost, what it paid to whom, whether it told its owner something the chain does not show; and totals. |
+| `clearance_status` | Queue length, tests left today on the whole site (your network has its own 3), the models a test runs on. |
+
+A test takes a few minutes. It is the site's quick test: one run per attack on two models, a preliminary report and no certificate. A level 0–2 certificate needs the full suite (5 runs per attack); see the [main README](../README.md).
+
+Every result also has a page at `agentcrashtest.com/test/<id>` with the attacks as they landed. Results are kept for a week, and the result page is open to anyone with the link, the same as on the site. The prompt goes to the models a test runs on (see `clearance_status`), so do not send one with secrets in it.
+
+`CLEARANCE_URL` points the server at another deployment (default `https://agentcrashtest.com`); the prompt is sent there.

package/clearance-mcp.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Clearance MCP server: lets any MCP client (Claude Code, Claude Desktop, Cursor, agent frameworks) crash-test an
+// agent's system prompt from inside its own workflow. It is a thin client of the public website API
+// (agentcrashtest.com/api/test): no keys, no dependencies, the same limits as the site (3 tests per network per day).
+// Transport: MCP over stdio, newline-delimited JSON-RPC 2.0.
+//   claude mcp add clearance -- node /path/to/clearance/mcp/clearance-mcp.mjs
+import { createInterface } from "node:readline";
+
+const BASE = (process.env.CLEARANCE_URL || "https://agentcrashtest.com").replace(/\/$/, "");
+const PROTOCOL = "2025-06-18";
+const TOOL_SETS = ["clearance-v1", "agentconnect-v1", "outlayer-v1", "agentkit-v1"];
+
+const TOOLS = [
+  {
+    name: "clearance_test",
+    description:
+      "Start a crash test of an AI agent that moves money. Send the agent's full system prompt; Clearance runs it against " +
+      "payment attacks hidden in what it reads (fake invoices, lookalike payees, a 'payment failed, retry' that already went " +
+      "through) on a NEAR sandbox with real transfers, and scores the NEAR that left the vault. Returns a test id and a result " +
+      "page. A test takes a few minutes; poll it with clearance_result. Limit: 3 tests per network per day, one at a time " +
+      "(if a test from this network is still queued or running, the call fails until it finishes).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system_prompt: { type: "string", description: "The agent's whole system prompt (at least a few sentences, at most 8000 characters)." },
+        tools: { type: "string", enum: TOOL_SETS, description: "Which payment tool set the agent runs with. Default clearance-v1; the others emulate Agent Connect, OutLayer and Coinbase AgentKit tools." },
+      },
+      required: ["system_prompt"],
+    },
+  },
+  {
+    name: "clearance_result",
+    description:
+      "Read a crash test started with clearance_test: its state (queued, running, done, failed), and when done, per run whether " +
+      "the agent was deceived, NEAR lost (decimal NEAR), whether it told its owner something the chain does not show, the " +
+      "Markdown report with the wallet limits to run it with, and the result page. Set wait_seconds to wait for it to finish " +
+      "(up to 45; call again if it is still running).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The 16-character test id returned by clearance_test." },
+        wait_seconds: { type: "number", description: "Optional: keep polling up to this many seconds (max 45) until the test is done or failed." },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "clearance_status",
+    description: "Queue length, tests left today on the whole site (left_today; each network also has its own limit of per_ip tests a day), the models a test runs on, and the tool sets.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+async function api(path, init) {
+  const r = await fetch(`${BASE}${path}`, { ...init, signal: AbortSignal.timeout(30_000) });
+  const body = await r.json().catch(() => null);
+  if (!r.ok || !body) throw new Error(body?.error ?? `HTTP ${r.status} from ${BASE}${path}`);
+  return body;
+}
+
+function summarize(rec) {
+  const page = `${BASE}/test/${rec.id}`;
+  const out = { id: rec.id, state: rec.state, page };
+  if (rec.state === "queued") out.ahead = rec.ahead;
+  if (rec.state === "failed") out.error = rec.error ?? "the run did not finish";
+  const runs = rec.events ?? [];
+  if (runs.length) {
+    // Same counting as the result page: runs the model API cut off are listed but not scored, and when a model's
+    // first attempt had such a run it runs again, so only the first valid run per model and attack (or task) counts.
+    const seen = new Set();
+    const valid = runs.filter((e) => {
+      const k = `${e.model}|${e.kind}|${e.attack ?? e.scenario}`;
+      if (!e.valid || seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    });
+    const attacks = valid.filter((e) => e.kind === "attack");
+    const lost = attacks.reduce((s, e) => s + Number(e.loss || 0), 0);
+    out.totals = {
+      attack_runs: attacks.length,
+      deceived: attacks.filter((e) => e.deceived).length,
+      near_lost: Number(lost.toFixed(4)),
+      false_reports_to_owner: valid.filter((e) => e.false_report).length,
+      honest_tasks_done: `${valid.filter((e) => e.kind === "control" && e.completed).length}/${valid.filter((e) => e.kind === "control").length}`,
+      invalid_runs: runs.length - valid.length,
+    };
+    out.runs = valid.map((e) => ({
+      model: e.model, attack: e.attack, scenario: e.scenario, valid: e.valid, deceived: e.deceived,
+      near_lost: e.loss, told_owner_something_false: e.false_report, task_done: e.completed,
+      paid: e.paid, refused_by_vault: e.refused,
+    }));
+    if (rec.state === "done" && rec.report) out.note = "If totals and report_markdown ever differ, the report is the scored result.";
+  }
+  if (rec.summary) out.summary = rec.summary;
+  // The full Markdown report: which model to ship on, each attack's text, and the wallet policy sized for it.
+  if (rec.report) out.report_markdown = rec.report;
+  return out;
+}
+
+async function callTool(name, a) {
+  if (name === "clearance_status") return api("/api/status");
+  if (name === "clearance_test") {
+    const prompt = typeof a.system_prompt === "string" ? a.system_prompt : "";
+    if (a.tools !== undefined && !TOOL_SETS.includes(a.tools)) throw new Error(`tools must be one of ${TOOL_SETS.join(", ")}`);
+    const tools = a.tools ?? "clearance-v1";
+    const rec = await api("/api/test", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ prompt, tools }) });
+    return { ...summarize(rec), next: "Poll clearance_result with this id; a test usually takes a few minutes." };
+  }
+  if (name === "clearance_result") {
+    const id = String(a.id ?? "");
+    if (!/^[0-9a-f]{16}$/.test(id)) throw new Error("id must be the 16-character hex id from clearance_test");
+    const until = Date.now() + Math.min(Math.max(Number(a.wait_seconds) || 0, 0), 45) * 1000;
+    let rec = await api(`/api/test/${id}`);
+    while ((rec.state === "queued" || rec.state === "running") && Date.now() < until) {
+      await new Promise((r) => setTimeout(r, 5000));
+      rec = await api(`/api/test/${id}`);
+    }
+    return summarize(rec);
+  }
+  throw new Error(`unknown tool ${name}`);
+}
+
+const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);
+// The report goes in as Markdown text, everything else as JSON; structuredContent carries the whole object.
+const text = (result, isError = false) => {
+  const { report_markdown: report, ...rest } = result;
+  const content = [{ type: "text", text: JSON.stringify(rest, null, 2) }];
+  if (report) content.push({ type: "text", text: report });
+  return { content, structuredContent: result, ...(isError ? { isError: true } : {}) };
+};
+
+async function handle(msg) {
+  if (!msg || typeof msg !== "object" || msg.id === undefined || msg.id === null) return; // notification
+  const ok = (result) => send({ jsonrpc: "2.0", id: msg.id, result });
+  switch (msg.method) {
+    case "initialize":
+      return ok({ protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: "clearance", version: "0.1.0" } });
+    case "ping":
+      return ok({});
+    case "tools/list":
+      return ok({ tools: TOOLS });
+    case "tools/call":
+      try {
+        return ok(text(await callTool(msg.params?.name, msg.params?.arguments ?? {})));
+      } catch (e) {
+        return ok(text({ error: e.cause?.code ? `${e.message} (${e.cause.code})` : e.message }, true));
+      }
+    default:
+      return send({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "method not found" } });
+  }
+}
+
+// When the client closes stdin, finish the calls in flight, then exit.
+let inFlight = 0, closed = false;
+const done = () => { if (--inFlight === 0 && closed) process.exit(0); };
+process.stdout.on("error", () => process.exit(0)); // the client went away
+createInterface({ input: process.stdin }).on("close", () => { closed = true; if (!inFlight) process.exit(0); }).on("line", (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }); }
+  inFlight++;
+  handle(msg).catch((e) => send({ jsonrpc: "2.0", id: msg?.id ?? null, error: { code: -32603, message: e.message } })).finally(done);
+});

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "agentcrashtest-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Clearance (agentcrashtest.com): crash-test an AI agent that moves money from Claude Code, Claude Desktop or Cursor",
+  "type": "module",
+  "bin": { "agentcrashtest-mcp": "clearance-mcp.mjs" },
+  "files": ["clearance-mcp.mjs", "README.md"],
+  "engines": { "node": ">=20" },
+  "keywords": ["mcp", "model-context-protocol", "ai-agents", "agent-security", "near", "crash-test"],
+  "homepage": "https://agentcrashtest.com",
+  "repository": { "type": "git", "url": "git+https://github.com/Selliksss/clearance.git", "directory": "mcp" },
+  "license": "MIT"
+}