@polygraphso/litmus 0.7.0 → 0.8.1

package/README.md

@@ -50,16 +50,43 @@ open and deterministic, so a re-run reproduces the grade — or refutes it.
 The package ships a stdio MCP server, `polygraphso-litmus-mcp`, so it works in any
 MCP-capable client. It exposes two tools:
 
-- **`run_litmus`** — actively grade a server *now* (runs the harness end-to-end),
-  and return the grade and the evidence.
+- **`run_litmus`** — actively grade a server *now* (runs the harness end-to-end)
+  and return the grade and the evidence. Optional **`bearer`** (and `header`
+  entries, each `"Key: Value"`) grade a token-gated `https://` MCP target — sent
+  to that origin only, ignored for stdio/local targets, the same plumbing as the
+  CLI's `--bearer` / `--header`.
 - **`verify_attestation`** — passively read a server's *already-published* grade
   before trusting or paying it.
 
+It also registers two **prompts** that show up as slash commands — in Claude Code,
+`/mcp__polygraph-litmus__grade <server_ref>` (run a fresh grade) and
+`/mcp__polygraph-litmus__check <server_ref>` (read a published grade); other
+clients surface the same prompts in their own UI. For a cleaner pair of commands
+in Claude Code — `/polygraph:grade` and `/polygraph:check` — install the plugin
+(below), which wires up this server and both commands in one step.
+
 **Prerequisites:** Node ≥ 18. Docker is optional (without it, C-02 egress is
 skipped and the grade caps at B). Set `POLYGRAPH_API_URL=https://polygraph.so` so
-`verify_attestation` can resolve a server's published grade.
+`verify_attestation` can look up published grades.
+
+> **Heads-up:** grade *publishing* is still rolling out, so `verify_attestation`
+> commonly returns `not_available` today — that means *unevaluated*, not a failing
+> grade. To grade a server right now, use `run_litmus`.
+
+### Claude Code: one-click plugin (recommended)
+
+The plugin bundles this MCP server **and** adds the `/polygraph:grade` and
+`/polygraph:check` commands — one install does everything:
+
+```
+/plugin marketplace add polygraphso/litmus
+/plugin install polygraph@polygraphso
+```
+
+Then just run `/polygraph:grade npm/@modelcontextprotocol/server-filesystem`.
 
-Add the server once, then just talk to your agent.
+Prefer to wire the server up by hand, or using another client? Add it once, then
+just talk to your agent.
 
 **Claude Code** — one command:
 
@@ -99,6 +126,31 @@ that's already published.
 `run_litmus` launches the target server's code to exercise it (egress-sandboxed
 when Docker is present). It needs no wallet or RPC.
 
+### ChatGPT and other remote clients
+
+ChatGPT's MCP support expects a remote **Streamable-HTTP** server; this package is
+**stdio-only**, so you can't point ChatGPT at it directly. If you self-host, bridge
+stdio over HTTP yourself — e.g.
+
+```bash
+npx -y supergateway --stdio "npx -y -p @polygraphso/litmus polygraphso-litmus-mcp" --port 8000
+```
+
+(or [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy)) — then point your client
+at that endpoint. polygraph does not host this for you; the bridge runs on your own
+machine.
+
+### Troubleshooting
+
+- **Two bins / `npx`:** `npx` needs `-p @polygraphso/litmus` *plus* the bin name
+  (`polygraphso-litmus` or `polygraphso-litmus-mcp`); plain `npx @polygraphso/litmus`
+  can't choose which to run. Installed globally? Use the bin name directly, no `-p`.
+- **Docker optional:** without Docker, C-02 (egress) is skipped and the grade caps
+  at **B** — the C-02 row reads `skipped` with reason `no sandbox (Docker
+  unavailable)`. Not a failure, just unverified.
+- **`verify_attestation` says `lookup_failed`:** the grade index or RPC was
+  unreachable — that's *unknown*, not *no grade*. Retry; check `POLYGRAPH_API_URL`.
+
 ## Library
 
 ```ts

package/dist/{chunk-EWLIQPXF.js → chunk-35UOPCBW.js}

@@ -2003,6 +2003,7 @@ function assembleBundle(input) {
 }
 
 // ../probes/src/harness.ts
+var PROGRESS_STEPS = 5;
 async function runLitmus(target, opts = {}) {
   const isolation = opts.isolation ?? (process.env.LITMUS_STDIO_ISOLATION === "docker" ? "docker" : "none");
   const ranAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -2025,6 +2026,7 @@ async function runLitmus(target, opts = {}) {
   });
   try {
     const runProbes = async () => {
+      const step = (done, label) => opts.onProgress?.(done, PROGRESS_STEPS, label);
       const listed = await enumerateTools(conn.client);
       const tools = listed.map((t) => ({
         name: t.name,
@@ -2033,6 +2035,7 @@ async function runLitmus(target, opts = {}) {
       }));
       assertGradableSurface(tools);
       const { fingerprint, canonical } = fingerprintToolDefs(tools);
+      step(1, "fingerprinted tool surface");
       const annotated = listed.map((t) => ({
         name: t.name,
         description: t.description ?? "",
@@ -2056,14 +2059,15 @@ async function runLitmus(target, opts = {}) {
         baselineAllowlist: []
       };
       assertEgressRanUnderIsolation(egress, isolation, isStdio);
-      const categories = [
-        await c01Injection(ctx),
-        c02Permission(probe21Declaration(annotated), egress),
-        await c03Sensitive(ctx, egress),
-        // C-04 runs LAST: its malformed/oversized inputs may crash the server, so
-        // it must not run before the other probes have used the live connection.
-        await c04Adversarial(ctx)
-      ];
+      const c01 = await c01Injection(ctx);
+      step(2, "C-01 tool-output injection");
+      const c02 = c02Permission(probe21Declaration(annotated), egress);
+      step(3, "C-02 permission / egress");
+      const c03 = await c03Sensitive(ctx, egress);
+      step(4, "C-03 sensitive-data handling");
+      const c04 = await c04Adversarial(ctx);
+      step(5, "C-04 adversarial-input handling");
+      const categories = [c01, c02, c03, c04];
       const grade = gradeFromCategories(categories);
       return assembleBundle({
         serverRef: conn.serverRef,

package/dist/{chunk-GJ7M7C46.js → chunk-BPS4YCDL.js}

@@ -1,9 +1,10 @@
 import {
+  parseAuthFlags,
   resolveTarget
-} from "./chunk-RAZNXIE5.js";
+} from "./chunk-VOPISHBU.js";
 import {
   runLitmus
-} from "./chunk-EWLIQPXF.js";
+} from "./chunk-35UOPCBW.js";
 import {
   CATEGORY_STATUS_UINT8,
   METHODOLOGY_VERSION
@@ -37,16 +38,43 @@ function rpcUrl(net = selectedNetwork()) {
   return override && override.length > 0 ? override : NETWORKS[net].rpc;
 }
 
-// ../onchain/src/eas-sdk.ts
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var sdk = require2(
-  "@ethereum-attestation-service/eas-sdk"
-);
-var { EAS, SchemaEncoder, SchemaRegistry } = sdk;
-
 // ../onchain/src/eas.ts
+import { AbiCoder } from "ethers";
 var LITMUS_SCHEMA = "string serverRef,bytes32 toolDefsFingerprint,uint8 gradeC01,uint8 gradeC02,uint8 gradeC03,string overallGrade,string reportCID,string methodologyVersion,uint64 ranAt,string resolvedVersion";
+var LITMUS_ABI_TYPES = [
+  "string",
+  // serverRef
+  "bytes32",
+  // toolDefsFingerprint
+  "uint8",
+  // gradeC01
+  "uint8",
+  // gradeC02
+  "uint8",
+  // gradeC03
+  "string",
+  // overallGrade
+  "string",
+  // reportCID
+  "string",
+  // methodologyVersion
+  "uint64",
+  // ranAt
+  "string"
+  // resolvedVersion
+];
+var LITMUS_ABI_NAMES = [
+  "serverRef",
+  "toolDefsFingerprint",
+  "gradeC01",
+  "gradeC02",
+  "gradeC03",
+  "overallGrade",
+  "reportCID",
+  "methodologyVersion",
+  "ranAt",
+  "resolvedVersion"
+];
 function categoryUint8(bundle, code) {
   const status = bundle.categories.find((c) => c.code === code)?.status;
   return status ? CATEGORY_STATUS_UINT8[status] : CATEGORY_STATUS_UINT8.skipped;
@@ -67,31 +95,36 @@ function litmusFields(bundle, reportCID) {
 }
 function encodeLitmusAttestation(bundle, reportCID) {
   const f = litmusFields(bundle, reportCID);
-  const enc = new SchemaEncoder(LITMUS_SCHEMA);
-  return enc.encodeData([
-    { name: "serverRef", value: f.serverRef, type: "string" },
-    { name: "toolDefsFingerprint", value: f.toolDefsFingerprint, type: "bytes32" },
-    { name: "gradeC01", value: f.gradeC01, type: "uint8" },
-    { name: "gradeC02", value: f.gradeC02, type: "uint8" },
-    { name: "gradeC03", value: f.gradeC03, type: "uint8" },
-    { name: "overallGrade", value: f.overallGrade, type: "string" },
-    { name: "reportCID", value: f.reportCID, type: "string" },
-    { name: "methodologyVersion", value: f.methodologyVersion, type: "string" },
-    { name: "ranAt", value: f.ranAt, type: "uint64" },
-    { name: "resolvedVersion", value: f.resolvedVersion, type: "string" }
-  ]);
+  return AbiCoder.defaultAbiCoder().encode(
+    [...LITMUS_ABI_TYPES],
+    [
+      f.serverRef,
+      f.toolDefsFingerprint,
+      f.gradeC01,
+      f.gradeC02,
+      f.gradeC03,
+      f.overallGrade,
+      f.reportCID,
+      f.methodologyVersion,
+      f.ranAt,
+      f.resolvedVersion
+    ]
+  );
 }
 function decodeLitmusAttestation(encoded) {
-  const enc = new SchemaEncoder(LITMUS_SCHEMA);
+  const values = AbiCoder.defaultAbiCoder().decode([...LITMUS_ABI_TYPES], encoded);
   const out = {};
-  for (const item of enc.decodeData(encoded)) {
-    out[item.name] = item.value.value;
-  }
+  LITMUS_ABI_NAMES.forEach((name, i) => {
+    out[name] = values[i];
+  });
   return out;
 }
 
 // ../onchain/src/read.ts
-import { JsonRpcProvider, ZeroHash } from "ethers";
+import { Contract, JsonRpcProvider, ZeroHash } from "ethers";
+var EAS_ABI = [
+  "function getAttestation(bytes32 uid) view returns ((bytes32 uid, bytes32 schema, uint64 time, uint64 expirationTime, uint64 revocationTime, bytes32 refUID, address recipient, address attester, bool revocable, bytes data))"
+];
 function litmusSchemaUID() {
   const uid = process.env.NEXT_PUBLIC_EAS_SCHEMA_UID;
   if (!uid) throw new Error("NEXT_PUBLIC_EAS_SCHEMA_UID is required \u2014 register the schema first.");
@@ -100,8 +133,7 @@ function litmusSchemaUID() {
 async function readAttestation(uid) {
   const cfg = networkConfig();
   const provider = new JsonRpcProvider(rpcUrl(), cfg.chainId);
-  const eas = new EAS(cfg.eas);
-  eas.connect(provider);
+  const eas = new Contract(cfg.eas, EAS_ABI, provider);
   const att = await eas.getAttestation(uid);
   if (!att || att.uid === ZeroHash) return null;
   if (String(att.schema).toLowerCase() !== litmusSchemaUID().toLowerCase()) return null;
@@ -124,27 +156,46 @@ import { z } from "zod";
 var RUN_LITMUS_TOOL_NAME = "run_litmus";
 var RUN_LITMUS_TOOL_TITLE = "Run a behavioral litmus on an MCP server";
 var RUN_LITMUS_TOOL_DESCRIPTION = [
-  `Run the open behavioral litmus (${METHODOLOGY_VERSION}) against an MCP server and return`,
-  "its grade. The harness connects like an agent would, fingerprints the tool",
-  "surface, and runs three probe categories: C-01 tool-output injection, C-02",
-  "permission overreach (egress in a hardened default-deny Docker sandbox, plus a",
-  "declared-permission honesty check), and C-03 sensitive-data handling (planted",
-  "canaries). It grades A\u2013F.",
+  `Grade an MCP server A\u2013F against the open behavioral litmus (${METHODOLOGY_VERSION}).`,
+  "The harness connects the way an agent would, fingerprints the tool surface, and",
+  "runs four checks: C-01 tool-output injection, C-02 permission/egress overreach",
+  "(egress in a hardened default-deny Docker sandbox, plus a declared-permission",
+  "honesty check), C-03 sensitive-data handling (planted canaries), and C-04",
+  "adversarial-input handling (malformed/oversized and jailbreak inputs).",
   "",
-  "This is ACTIVE: it launches the target server's code to exercise it (sandboxed",
-  "for egress when Docker is available). It is not a passive lookup \u2014 for that,",
-  "use `verify_attestation`. It needs no wallet or RPC.",
+  "This is ACTIVE: it launches the target server's code to exercise it (egress-",
+  "sandboxed when Docker is available) and takes ~20\u201360s. It is not a lookup \u2014 for",
+  "a server's already-published grade, use `verify_attestation`. No wallet or RPC",
+  "needed.",
   "",
-  "Input: server_ref \u2014 a registry ref (npm/@scope/server), an https:// MCP URL,",
-  "or a local path to an MCP entry file. If Docker is unavailable, C-02 is",
-  "skipped and the grade is capped at B for that run."
+  "server_ref examples: npm/@modelcontextprotocol/server-filesystem \xB7",
+  "https://example.com/mcp \xB7 ./build/index.js. For a token-gated https:// target,",
+  "pass `bearer`. If Docker is unavailable, C-02 is skipped and the grade is capped",
+  "at B for that run."
 ].join("\n");
 var runLitmusInputShape = {
-  server_ref: z.string().min(1).max(512).describe("What to grade: a registry ref (npm/@scope/server), an https:// MCP URL, or a local path to an MCP entry file.")
+  server_ref: z.string().min(1).max(512).describe("What to grade: a registry ref (npm/@scope/server), an https:// MCP URL, or a local path to an MCP entry file."),
+  bearer: z.string().min(1).max(8192).optional().describe("Bearer token for a token-gated https:// MCP server. Sent as `Authorization: Bearer <token>` to the target origin only. Ignored for stdio/local targets."),
+  header: z.array(z.string()).max(20).optional().describe('Extra HTTP headers for a gated https:// target, each "Key: Value" (e.g. "X-Api-Key: \u2026"). Overrides the bearer-derived Authorization for the same key. Ignored for stdio/local targets.')
 };
-async function handleRunLitmus({ server_ref }) {
+var PROGRESS_TOTAL = 5;
+async function handleRunLitmus({ server_ref, bearer, header }, extra) {
   try {
-    const bundle = await runLitmus(resolveTarget(server_ref));
+    const argv = [
+      ...bearer ? ["--bearer", bearer] : [],
+      ...(header ?? []).flatMap((h) => ["--header", h])
+    ];
+    const { headers } = parseAuthFlags(argv, {});
+    const progressToken = extra._meta?.progressToken;
+    const sendProgress = progressToken !== void 0 ? (progress, message) => void extra.sendNotification({
+      method: "notifications/progress",
+      params: { progressToken, progress, total: PROGRESS_TOTAL, message }
+    }) : void 0;
+    sendProgress?.(0, `Connecting to ${server_ref}\u2026`);
+    const bundle = await runLitmus(resolveTarget(server_ref), {
+      ...Object.keys(headers).length ? { headers } : {},
+      ...sendProgress ? { onProgress: (done, _total, label) => sendProgress(done, label) } : {}
+    });
     const payload = summarize(bundle);
     return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
   } catch (err) {
@@ -152,24 +203,28 @@ async function handleRunLitmus({ server_ref }) {
     return { isError: true, content: [{ type: "text", text: `run_litmus failed: ${message}` }] };
   }
 }
+var CATEGORY_LABEL = {
+  "C-01": "tool-output injection",
+  "C-02": "permission / egress overreach",
+  "C-03": "sensitive-data handling",
+  "C-04": "adversarial-input handling"
+};
 function summarize(b) {
   const find = (code) => b.categories.find((c) => c.code === code);
   const categories = ["C-01", "C-02", "C-03", "C-04"].map((code) => {
     const c = find(code);
     const findings = c?.status === "fail" ? c.probes.flatMap((p) => p.findings).filter((f) => f.severity === "high").slice(0, 5).map((f) => ({ tool: f.tool, kind: f.kind, match: truncate(f.match, 120), host: f.host, port: f.port })) : [];
-    return { code, status: c?.status ?? "unknown", reason: c?.reason ?? null, findings };
+    return { code, check: CATEGORY_LABEL[code], status: c?.status ?? "unknown", reason: c?.reason ?? null, findings };
   });
-  const dockerSkipped = !b.harness.dockerAvailable || find("C-02")?.status === "skipped";
   return {
     grade: b.grade,
-    gradeRationale: b.gradeRationale,
-    fingerprint: b.toolDefsFingerprint,
+    summary: b.gradeRationale,
     serverRef: b.serverRef,
     resolvedVersion: b.resolvedVersion,
+    fingerprint: b.toolDefsFingerprint,
     ranAt: b.ranAt,
     methodologyVersion: b.methodologyVersion,
-    categories,
-    ...dockerSkipped ? { dockerSkipped: "C-02 (egress) was not run because Docker was unavailable; the grade is capped at B for this run." } : {}
+    categories
   };
 }
 function truncate(s, n) {

package/dist/{chunk-RAZNXIE5.js → chunk-VOPISHBU.js}

@@ -44,7 +44,7 @@ async function runLitmusCli(args) {
     );
     return 2;
   }
-  const { runLitmus } = await import("./src-GJ2L6B7K.js");
+  const { runLitmus } = await import("./src-RSTPCEYU.js");
   const input = resolveTarget(target);
   try {
     const bundle = await runLitmus(input, { headers, allowStateChanging });

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runLitmusCli
-} from "./chunk-RAZNXIE5.js";
+} from "./chunk-VOPISHBU.js";
 import {
   parseServerRef,
   serverKey
@@ -104,7 +104,7 @@ examples:
   polygraphso-litmus litmus npm/@modelcontextprotocol/server-filesystem
   polygraphso-litmus litmus --json npm/@modelcontextprotocol/server-filesystem
 
-Set POLYGRAPH_API_URL to pin the evidence and get a mint hand-off link.
+Set POLYGRAPH_API_URL so check/list can look up a server's published grade.
 More at https://polygraph.so
 `;
 function readVersion() {

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { z } from 'zod';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 
 /**
  * Shared contract types for the litmus MVP. Web3-free.
@@ -272,6 +274,14 @@ interface RunLitmusOptions {
      * the `finally` tears the connection down, settling any in-flight calls.
      */
     timeoutMs?: number;
+    /**
+     * Optional progress callback, fired once per probe phase as the run proceeds:
+     * `(done, total, label)` are step counts plus a short human phase name. Purely
+     * observational — it never affects the grade or the bundle. The MCP server
+     * forwards these as `notifications/progress` so a ~20–60s run isn't a frozen
+     * tool call.
+     */
+    onProgress?: (done: number, total: number, label: string) => void;
 }
 declare function runLitmus(target: TargetInput, opts?: RunLitmusOptions): Promise<EvidenceBundle>;
 
@@ -484,7 +494,10 @@ declare function decodeLitmusAttestation(encoded: string): Record<string, unknow
  * §7). Needs an RPC + a registered schema; the agent-gate calls this, then
  * re-checks the live fingerprint before paying.
  *
- * [verify] eas-sdk EAS.getAttestation return shape (uid / data / revocationTime).
+ * The read is a single EAS `getAttestation` view call. We hit the contract
+ * directly through a minimal ethers ABI fragment (below) rather than the
+ * eas-sdk `EAS` class — same on-chain struct, one fewer dependency (eas-sdk
+ * dragged hardhat into the production tree).
  */
 /** The registered litmus schema UID for the selected network (from env). */
 declare function litmusSchemaUID(): string;
@@ -573,10 +586,14 @@ declare const RUN_LITMUS_TOOL_TITLE = "Run a behavioral litmus on an MCP server"
 declare const RUN_LITMUS_TOOL_DESCRIPTION: string;
 declare const runLitmusInputShape: {
     server_ref: z.ZodString;
+    bearer: z.ZodOptional<z.ZodString>;
+    header: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 };
-declare function handleRunLitmus({ server_ref }: {
+declare function handleRunLitmus({ server_ref, bearer, header }: {
     server_ref: string;
-}): Promise<{
+    bearer?: string;
+    header?: string[];
+}, extra: RequestHandlerExtra<ServerRequest, ServerNotification>): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/index.js

@@ -14,11 +14,11 @@ import {
   rpcUrl,
   runLitmusInputShape,
   selectedNetwork
-} from "./chunk-GJ7M7C46.js";
+} from "./chunk-BPS4YCDL.js";
 import {
   parseAuthFlags,
   resolveTarget
-} from "./chunk-RAZNXIE5.js";
+} from "./chunk-VOPISHBU.js";
 import {
   assembleBundle,
   canaryMatch,
@@ -33,7 +33,7 @@ import {
   markdownTricks,
   runLitmus,
   stateChangingToolNames
-} from "./chunk-EWLIQPXF.js";
+} from "./chunk-35UOPCBW.js";
 import {
   BUNDLE_SCHEMA_VERSION,
   CATEGORY_STATUS_UINT8,

package/dist/mcp.d.ts

@@ -3,10 +3,11 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
  * `polygraphso-litmus-mcp` — the polygraph litmus MCP server. Stdio transport.
- * Exposes two tools to any MCP client (Claude Desktop, Cursor, …):
+ * Exposes to any MCP client (Claude Desktop, Cursor, …):
  *
- *   • `run_litmus`         — actively grade an MCP server A–F, then hand off to mint.
+ *   • `run_litmus`         — actively grade an MCP server A–F against the open harness.
  *   • `verify_attestation` — passively read a server's published onchain grade.
+ *   • prompts `grade` / `check` — one-line slash-command entry points to the two tools.
  *
  * Also exported as `@polygraphso/litmus/mcp` for embedding in a custom server.
  */

package/dist/mcp.js

@@ -7,9 +7,9 @@ import {
   readAttestation,
   runLitmusInputShape,
   selectedNetwork
-} from "./chunk-GJ7M7C46.js";
-import "./chunk-RAZNXIE5.js";
-import "./chunk-EWLIQPXF.js";
+} from "./chunk-BPS4YCDL.js";
+import "./chunk-VOPISHBU.js";
+import "./chunk-35UOPCBW.js";
 import {
   parseServerRef,
   serverKey
@@ -20,6 +20,7 @@ import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
 
 // ../mcp/src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -36,28 +37,63 @@ function canonicalRef(ref) {
 var VERIFY_TOOL_NAME = "verify_attestation";
 var VERIFY_TOOL_TITLE = "Verify a server's polygraph attestation";
 var VERIFY_TOOL_DESCRIPTION = [
-  "Read the onchain polygraph (litmus) attestation for an MCP server before an",
-  "agent trusts \u2014 or, in agentic commerce, pays \u2014 it.",
+  "Read a server's already-published polygraph (litmus) grade \u2014 without running",
+  "anything \u2014 before an agent trusts or, in agentic commerce, pays it.",
   "",
-  "Returns the behavioral grade (A\u2013F), the attestation UID, the evidence CID,",
-  "and the graded tool-surface fingerprint. The caller must still recompute the",
-  "LIVE fingerprint and require it to equal the attested one before paying \u2014 a",
-  "passing attestation can otherwise front for a tool surface the server no",
-  "longer serves (rug pull).",
+  "When a grade is published it returns the behavioral grade (A\u2013F), the attestation",
+  "UID, the evidence CID, and the graded tool-surface fingerprint. The caller must",
+  "still recompute the LIVE fingerprint and require it to equal the attested one",
+  "before paying \u2014 a passing attestation can otherwise front for a tool surface the",
+  "server no longer serves (rug pull).",
   "",
-  "Input: server_ref \u2014 e.g. npm/@modelcontextprotocol/server-filesystem. Returns",
-  "not_available when there is no attestation: treat that as unevaluated \u2014",
-  "neither safe nor unsafe."
+  "Grade publishing is still rolling out, so this commonly returns not_available",
+  "today: that means UNEVALUATED (neither safe nor unsafe), not a failing grade \u2014 to",
+  "grade the server yourself right now, use `run_litmus`. A `lookup_failed` result",
+  "means the lookup itself failed (the index or chain was unreachable); the grade is",
+  "unknown, which is not the same as unevaluated.",
+  "",
+  "Input: server_ref \u2014 e.g. npm/@modelcontextprotocol/server-filesystem."
 ].join("\n");
 var verifyInputShape = {
   server_ref: z.string().min(1).max(512).describe("Registry-prefixed server identifier, e.g. npm/@scope/server.")
 };
 async function handleVerify({ server_ref }) {
-  const uid = await resolveUid(server_ref);
-  const att = uid ? await readAttestation(uid) : null;
+  const found = await resolveUid(server_ref);
+  if (found.kind === "error") {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `lookup_failed \u2014 could not reach the polygraph grade index for ${server_ref} (${found.detail}). The lookup itself failed, so the grade is unknown \u2014 retry or report it as unchecked, NOT as unevaluated.`
+        }
+      ]
+    };
+  }
+  let att = null;
+  if (found.kind === "found") {
+    try {
+      att = await readAttestation(found.uid);
+    } catch (err) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `lookup_failed \u2014 the onchain read failed for ${server_ref} (${err instanceof Error ? err.message : String(err)}). Treat as unchecked (the chain/RPC was unreachable), not as "no grade".`
+          }
+        ]
+      };
+    }
+  }
   if (!att) {
     return {
-      content: [{ type: "text", text: `not_available \u2014 no polygraph attestation for ${server_ref}` }]
+      content: [
+        {
+          type: "text",
+          text: `not_available \u2014 no published polygraph grade for ${server_ref}. Grade publishing is still rolling out, so this is expected for most servers; it means unevaluated (neither safe nor unsafe), not a failing grade. To grade it now, use run_litmus.`
+        }
+      ]
     };
   }
   if (canonicalRef(att.serverRef) !== canonicalRef(server_ref)) {
@@ -90,11 +126,12 @@ async function resolveUid(serverRef) {
   const base = process.env.POLYGRAPH_API_URL ?? "https://polygraph.so";
   try {
     const res = await fetch(`${base}/api/attestations?ref=${encodeURIComponent(serverRef)}`);
-    if (!res.ok) return null;
+    if (res.status === 404) return { kind: "none" };
+    if (!res.ok) return { kind: "error", detail: `grade index returned HTTP ${res.status}` };
     const row = await res.json();
-    return row?.attestation_uid ?? null;
-  } catch {
-    return null;
+    return row?.attestation_uid ? { kind: "found", uid: row.attestation_uid } : { kind: "none" };
+  } catch (err) {
+    return { kind: "error", detail: err instanceof Error ? err.message : String(err) };
   }
 }
 
@@ -104,17 +141,21 @@ function buildServer() {
     { name: "polygraph-litmus", version: "0.1.0" },
     {
       instructions: [
-        "polygraph issues behavioral litmus grades (A\u2013F) for MCP servers.",
+        "polygraph runs an open behavioral test on an MCP server and reports a",
+        "letter grade A\u2013F, with the evidence behind it.",
         "",
-        "Use `run_litmus` to grade a server now: it runs the open harness against",
-        "the target and returns the grade, the evidence, and \u2014 when configured \u2014 a",
-        "mint hand-off URL the human opens to publish the grade onchain. It launches",
-        "the target's code (egress-sandboxed when Docker is present), so it is not a",
-        "passive read.",
+        "Use `run_litmus` to grade a server now. It connects the way an agent would",
+        "and exercises the target \u2014 so it runs the target's code (egress-sandboxed",
+        "when Docker is present), not a passive read; ~20\u201360s. No wallet or RPC",
+        "needed. Pass `server_ref` as an npm ref (npm/@scope/server), an https:// MCP",
+        "URL, or a local path to an MCP entry file; pass `bearer` for a token-gated",
+        "https target.",
         "",
-        "Use `verify_attestation` to read a server's already-published grade before",
-        "recommending, installing, or paying it. A server with no attestation is",
-        "unevaluated \u2014 neither safe nor unsafe; say so."
+        "Use `verify_attestation` to read a grade that was already published for a",
+        "server, without running anything. Grade publishing is still rolling out, so",
+        "it commonly returns not_available today \u2014 that means unevaluated (neither",
+        "safe nor unsafe), not a failing grade; to grade the server yourself, use",
+        "`run_litmus`."
       ].join("\n")
     }
   );
@@ -154,6 +195,48 @@ function buildServer() {
     },
     handleVerify
   );
+  server.registerPrompt(
+    "grade",
+    {
+      title: "Grade an MCP server",
+      description: "Run the open behavioral litmus against an MCP server and report its grade A\u2013F with the evidence.",
+      argsSchema: {
+        server_ref: z2.string().min(1).max(512).describe("npm/@scope/server, an https:// MCP URL, or a local path to an MCP entry file")
+      }
+    },
+    ({ server_ref }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Run the polygraph litmus on ${server_ref} using the run_litmus tool. Report the letter grade, the one-line summary, and any failed category with its findings. If the grade is capped at B because Docker was unavailable, say so plainly.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "check",
+    {
+      title: "Check a server's published grade",
+      description: "Read a server's already-published polygraph grade without running anything.",
+      argsSchema: {
+        server_ref: z2.string().min(1).max(512).describe("Registry-prefixed server identifier, e.g. npm/@scope/server")
+      }
+    },
+    ({ server_ref }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Use the verify_attestation tool to read the published polygraph grade for ${server_ref}. If it returns not_available, say the server is unevaluated (neither safe nor unsafe) and offer to run a live grade with run_litmus. If it returns lookup_failed, say the lookup itself failed so the grade is unknown \u2014 do not call it unevaluated.`
+          }
+        }
+      ]
+    })
+  );
   return server;
 }
 async function main() {

package/dist/{src-GJ2L6B7K.js → src-RSTPCEYU.js}

@@ -12,7 +12,7 @@ import {
   markdownTricks,
   runLitmus,
   stateChangingToolNames
-} from "./chunk-EWLIQPXF.js";
+} from "./chunk-35UOPCBW.js";
 import "./chunk-ZR6XRGMQ.js";
 export {
   assembleBundle,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraphso/litmus",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Behavioral litmus harness for MCP servers — grade a server A–F (tool-output injection, egress, sensitive-data, adversarial-input) with reproducible, content-addressed evidence. Ships a CLI and an MCP server with a run_litmus tool for AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://polygraph.so",
@@ -52,7 +52,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ethereum-attestation-service/eas-sdk": "^2.9.1",
     "ethers": "^6.16.0",
     "zod": "^3.23.8",
     "tsx": "^4.19.0"
@@ -62,12 +61,12 @@
     "tsup": "^8.3.0",
     "typescript": "^5.9.3",
     "vitest": "^2.1.0",
-    "@polygraph/probes": "0.0.0",
     "@polygraph/core": "0.0.0",
     "@polygraph/onchain": "0.0.0",
     "@polygraph/agent": "0.0.0",
-    "@polygraph/cli": "0.0.0",
-    "@polygraph/mcp": "0.0.0"
+    "@polygraph/probes": "0.0.0",
+    "@polygraph/mcp": "0.0.0",
+    "@polygraph/cli": "0.0.0"
   },
   "publishConfig": {
     "access": "public"