twzrd-mcp-server 0.2.4 → 0.2.6

package/README.md

@@ -1,10 +1,11 @@
 # twzrd-mcp-server - auto-pay MCP for the TWZRD Trust API
 
+<!-- mcp-name: xyz.twzrd/twzrd-mcp -->
+
 > Payment mechanism is mainnet-verified via the official x402 SDK (Python path,
-> $0.001 moved 2026-06-26 - see Status). As of v0.2.0 the bundled TypeScript path
-> uses the official x402 JS SDK (`@x402/core` + `@x402/svm` + `@x402/fetch`) and
-> is construct-verified against the live mainnet challenge; one real on-chain
-> settle remains before npm publish.
+> $0.001 moved 2026-06-26 - see Status). The Node package is published on npm as
+> `twzrd-mcp-server`; v0.2.5 source adds the single-shot payment guard required
+> before the next live paid proof.
 
 Auto-pay MCP server for TWZRD's Trust API, matching the competitor GTM shape
 (anchor-x402, Br0ski777, BitBooth all ship one). An agent adds one `mcpServers`
@@ -22,7 +23,8 @@ non-Solana challenge instead of mis-signing.
 - Cumulative session cap `TWZRD_MAX_USDC_TOTAL` (default 1.00)
 - Free discovery tools never enter the payment path
 - No cross-chain fallback — a non-`exact`/non-`solana:` challenge is rejected
-- Paid calls run the free preflight first; `decision=block` aborts the pay
+- Paid trust calls buy intel on the target wallet by design; use the free
+  `preflight` tool separately to vet a seller before paying it elsewhere.
 
 ## Status — payment path VERIFIED on mainnet 2026-06-26
 
@@ -38,8 +40,8 @@ Two authorized settles from dev wallet `2pHjZLqs…`:
    a no-data pubkey returned `422 charged:false` — the server's no-charge-on-empty
    guard works.
 
-**Conclusion: auto-pay works ONLY via the official x402 SDK, not a hand-rolled
-header.** Proven client wiring (Python):
+**Conclusion: auto-pay works through the official x402 SDK path.** Proven client
+wiring (Python):
 
 ```python
 from x402.client import x402ClientSync
@@ -52,16 +54,22 @@ session = x402_requests(client)
 session.get("https://intel.twzrd.xyz/v1/intel/quick/<wallet>")  # auto-pays $0.001
 ```
 
-### TypeScript path — integrated (v0.2.0)
-The hand-rolled `payAndRetry` is replaced with the official x402 JS SDK
-(`@x402/core` client + `@x402/svm` ExactSvmScheme + `@x402/fetch`
-`wrapFetchWithPayment`). `@x402/svm` reads the challenge `extra.feePayer` and builds
-the partially-signed sponsored transfer (verified no-spend against the live mainnet
-challenge: 496-byte tx, 2 signature slots), and the SDK encodes the `X-PAYMENT`
-header the server validates. Spend caps + preflight gate + free/paid split are
-preserved — caps are enforced in the payment selector before any signature.
-**Remaining:** one real $0.001 on-chain settle to confirm end-to-end, then npm
-publish + MCP-registry listing.
+### TypeScript path — integrated (v0.2.5)
+The TypeScript path uses the official x402 JS SDK (`@x402/core` client +
+`@x402/svm` ExactSvmScheme). `@x402/svm` reads the challenge
+`extra.feePayer` and builds the partially-signed sponsored transfer, and
+`x402HTTPClient` encodes the `X-PAYMENT` header the server validates. Spend caps +
+free/paid split are preserved — caps are enforced in the payment selector before
+any signature.
+
+Important: v0.2.5 uses a **single-shot** paid retry. The first SDK-backed E2E found
+that the generic `@x402/fetch` wrapper can re-pay after a transient-looking settle
+response, moving `$0.003` across two `$0.001` calls. This package now performs at
+most one signed retry per logical tool call; any second 402 is surfaced instead of
+silently paying again.
+
+**Next verification step:** one operator-authorized `$0.001` `quick_trust` settle
+through v0.2.5, followed by offline receipt verification.
 
 ## Install & Config
 
@@ -86,7 +94,11 @@ The **free** tools (`preflight`, `wallet_lookup`) need no wallet and no flags
 `TWZRD_MCP_PAYMENTS_ENABLED` unset and they work read-only. Only the paid tools need
 the keypair + `TWZRD_MCP_PAYMENTS_ENABLED=1`.
 
-### Node (`npx twzrd-mcp-server`) — v0.2.0, x402 JS SDK
+### Node (`npx twzrd-mcp-server`) — x402 JS SDK
+```bash
+npx -y twzrd-mcp-server --help
+```
+
 ```json
 { "mcpServers": { "twzrd": {
   "command": "npx", "args": ["-y", "twzrd-mcp-server"],
@@ -100,9 +112,45 @@ the keypair + `TWZRD_MCP_PAYMENTS_ENABLED=1`.
 ```
 Auto-pay is enabled whenever `TWZRD_WALLET_SECRET_KEY` is present (set
 `TWZRD_MCP_PAYMENTS_ENABLED=0` to force paid tools off). Free tools need no wallet.
-Construct-verified against the live mainnet challenge; pending one real settle +
-npm publish (until published, `npx twzrd-mcp-server` is not yet resolvable — see
-the Python package above for a path that is live on PyPI today).
+The package is published on npm; v0.2.5 is the next source release that includes
+the single-shot double-settle guard.
+
+## One-command Agent Demo
+
+The packaged demo starts the MCP server over stdio, lists the tools, and runs a
+live **free** preflight. It is no-spend by default, even if your shell has a
+wallet secret:
+
+```bash
+npm run build
+npm run demo
+```
+
+Turn the same demo into the operator-authorized `$0.001` settle proof by changing
+one env var and setting tight caps:
+
+```bash
+TWZRD_DEMO_PAID=quick \
+TWZRD_WALLET_SECRET_KEY="<base58 Solana secret>" \
+TWZRD_RPC_URL="<mainnet RPC>" \
+TWZRD_MAX_USDC_PER_CALL=0.001 \
+TWZRD_MAX_USDC_TOTAL=0.001 \
+node examples/agent-drop-in.mjs
+```
+
+For the full signed-receipt path, use `TWZRD_DEMO_PAID=full` and set both caps to
+`0.05`; the demo verifies any returned receipt through the MCP `verify_receipt`
+tool. To additionally pipe that receipt into the standalone verifier package:
+
+```bash
+TWZRD_DEMO_PAID=full \
+TWZRD_DEMO_RUN_VERIFIER_SELF_TEST=1 \
+TWZRD_WALLET_SECRET_KEY="<base58 Solana secret>" \
+TWZRD_RPC_URL="<mainnet RPC>" \
+TWZRD_MAX_USDC_PER_CALL=0.05 \
+TWZRD_MAX_USDC_TOTAL=0.05 \
+node examples/agent-drop-in.mjs
+```
 
 ## Tools
 - `preflight` (free) — allow/warn/block + trust_score before you pay a **seller** you're about to transact with

package/dist/index.js

@@ -12,8 +12,8 @@
  * wallet (the challenge `extra.feePayer`) co-signs + pays the SOL fee server-side.
  * `@x402/svm`'s ExactSvmScheme reads `extra.feePayer` and builds exactly this
  * partially-signed transaction; the SDK also encodes the X-PAYMENT header the
- * server validates. (An earlier draft hand-rolled both and the server rejected
- * it — the hand-rolled header never matched the official x402 PaymentPayload.)
+ * server validates. This keeps the client payload byte-compatible with the
+ * server-side x402 validator instead of inventing a parallel header format.
  *
  * SAFETY GUARDRAILS (all enforced in the payment-requirements selector, BEFORE
  * any signature):
@@ -22,7 +22,8 @@
  *   - Free discovery tools are NEVER routed through the payment path
  *   - No cross-chain fallback: only a Solana "exact" requirement is selectable;
  *     anything else throws (refuse to pay) rather than mis-signing
- *   - Paid tools run the FREE preflight first; decision=block aborts the pay
+ *   - Paid tools buy intel on the target wallet by design; use the free
+ *     `preflight` tool separately to vet a seller before paying it elsewhere.
  *
  * STATUS: payment mechanism is SDK-backed and the payload construction is
  * verified against the live Solana "exact" challenge. The first real on-chain
@@ -40,11 +41,53 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { x402Client } from "@x402/core/client";
-import { wrapFetchWithPayment } from "@x402/fetch";
+import { x402Client, x402HTTPClient } from "@x402/core/client";
 import { ExactSvmScheme, SOLANA_MAINNET_CAIP2 } from "@x402/svm";
 import { createKeyPairSignerFromBytes } from "@solana/kit";
 import bs58 from "bs58";
+const VERSION = "0.2.5";
+function printHelp() {
+    console.log(`twzrd-mcp-server v${VERSION}
+
+TWZRD Trust API MCP server with Solana x402 auto-pay.
+
+Usage:
+  twzrd-mcp-server                 Start stdio MCP server
+  twzrd-mcp-server --help          Show this help
+  twzrd-mcp-server --version       Print version
+
+Free tools work with no wallet:
+  preflight, wallet_lookup, verify_receipt
+
+Paid tools require:
+  TWZRD_WALLET_SECRET_KEY=<base58 Solana secret key>
+  TWZRD_RPC_URL=<mainnet Solana RPC>
+  TWZRD_MAX_USDC_PER_CALL=0.05
+  TWZRD_MAX_USDC_TOTAL=1.00
+
+MCP config:
+  {
+    "mcpServers": {
+      "twzrd": {
+        "command": "npx",
+        "args": ["-y", "twzrd-mcp-server"],
+        "env": {
+          "TWZRD_RPC_URL": "<mainnet rpc>",
+          "TWZRD_WALLET_SECRET_KEY": "<base58 secret>"
+        }
+      }
+    }
+  }
+`);
+}
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    printHelp();
+    process.exit(0);
+}
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+    console.log(VERSION);
+    process.exit(0);
+}
 // ── Config ─────────────────────────────────────────────────────────────────
 const API_BASE = process.env.TWZRD_API_URL || "https://intel.twzrd.xyz";
 const RPC_URL = process.env.TWZRD_RPC_URL || "https://api.mainnet-beta.solana.com";
@@ -75,8 +118,11 @@ function selectSolanaExact(_x402Version, accepts) {
     spentUsdc += amountUsdc;
     return req;
 }
-// Build the payment-enabled fetch once, if a key is present and payments aren't
-// force-disabled. Otherwise paid tools fail closed with a clear message.
+// Build a SINGLE-SHOT payment fetch once, if a key is present and payments
+// aren't force-disabled. We intentionally do not use @x402/fetch's
+// wrapFetchWithPayment here: its recovery branch can create a fresh payload and
+// re-pay after a transient-looking settle response. This wrapper makes exactly
+// one paid retry per logical tool call; any second 402 is surfaced to the caller.
 let paidFetch = null;
 let paymentInitError = "";
 if (SECRET && !PAYMENTS_DISABLED) {
@@ -86,7 +132,30 @@ if (SECRET && !PAYMENTS_DISABLED) {
         const scheme = new ExactSvmScheme(signer, { rpcUrl: RPC_URL });
         const client = new x402Client(selectSolanaExact);
         client.register(SOLANA_MAINNET_CAIP2, scheme);
-        paidFetch = wrapFetchWithPayment(fetch, client);
+        const httpClient = new x402HTTPClient(client);
+        paidFetch = (async (input, init) => {
+            const first = await fetch(input, init);
+            if (first.status !== 402)
+                return first;
+            let challengeBody;
+            try {
+                const text = await first.text();
+                if (text)
+                    challengeBody = JSON.parse(text);
+            }
+            catch {
+                // Header-only challenges are valid; the SDK can read those from headers.
+            }
+            const paymentRequired = httpClient.getPaymentRequiredResponse((name) => first.headers.get(name), challengeBody);
+            const payload = await client.createPaymentPayload(paymentRequired);
+            const headers = httpClient.encodePaymentSignatureHeader(payload);
+            const retry = new Request(input, init);
+            for (const [key, value] of Object.entries(headers)) {
+                retry.headers.set(key, value);
+            }
+            retry.headers.set("Access-Control-Expose-Headers", "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE");
+            return fetch(retry);
+        });
         console.error(`TWZRD MCP: auto-pay armed (payer ${signer.address}) caps $${MAX_PER_CALL}/call $${MAX_TOTAL}/session`);
     }
     catch (e) {
@@ -122,7 +191,7 @@ const TOOLS = [
     { name: "quick_trust", description: "PAID $0.001 (auto-pay, Solana x402): quick tier+score for a Solana wallet.", inputSchema: { type: "object", properties: { wallet: { type: "string" } }, required: ["wallet"] } },
     { name: "full_trust", description: "PAID $0.05 (auto-pay, Solana x402): full trust intel + signed V6 receipt.", inputSchema: { type: "object", properties: { wallet: { type: "string" }, seller_wallet: { type: "string" } }, required: ["wallet"] } },
 ];
-const server = new Server({ name: "twzrd-mcp-server", version: "0.2.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "twzrd-mcp-server", version: VERSION }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;

package/examples/agent-drop-in.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * TWZRD MCP drop-in demo.
+ *
+ * Default path is free and read-only:
+ *   npm run build
+ *   npm run demo
+ *
+ * Operator-authorized paid proof (spends exactly one capped x402 call):
+ *   TWZRD_DEMO_PAID=quick \
+ *   TWZRD_WALLET_SECRET_KEY=<base58-solana-secret> \
+ *   TWZRD_RPC_URL=<mainnet-rpc> \
+ *   TWZRD_MAX_USDC_PER_CALL=0.001 \
+ *   TWZRD_MAX_USDC_TOTAL=0.001 \
+ *   node examples/agent-drop-in.mjs
+ *
+ * Full receipt path (costs 0.05 USDC, verifies receipt if one is returned):
+ *   TWZRD_DEMO_PAID=full TWZRD_MAX_USDC_PER_CALL=0.05 TWZRD_MAX_USDC_TOTAL=0.05 ...
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverPath = process.env.TWZRD_MCP_SERVER_PATH || path.resolve(__dirname, "../dist/index.js");
+const demoWallet =
+  process.env.TWZRD_DEMO_WALLET || "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
+const paidMode = (process.env.TWZRD_DEMO_PAID || "off").toLowerCase();
+
+if (!["off", "quick", "full"].includes(paidMode)) {
+  throw new Error("TWZRD_DEMO_PAID must be one of: off, quick, full");
+}
+
+const childEnv = { ...process.env };
+if (paidMode === "off" && childEnv.TWZRD_MCP_PAYMENTS_ENABLED === undefined) {
+  // Free demo should stay free even if the shell happens to have a wallet secret.
+  childEnv.TWZRD_MCP_PAYMENTS_ENABLED = "0";
+}
+if (paidMode !== "off") {
+  if (!childEnv.TWZRD_WALLET_SECRET_KEY) {
+    throw new Error("Paid demo requires TWZRD_WALLET_SECRET_KEY (base58 Solana secret)");
+  }
+  childEnv.TWZRD_MAX_USDC_PER_CALL ||= paidMode === "quick" ? "0.001" : "0.05";
+  childEnv.TWZRD_MAX_USDC_TOTAL ||= childEnv.TWZRD_MAX_USDC_PER_CALL;
+}
+
+const child = spawn(process.execPath, [serverPath], {
+  env: childEnv,
+  stdio: ["pipe", "pipe", "pipe"],
+});
+
+let nextId = 1;
+let stdoutBuffer = "";
+const pending = new Map();
+
+child.stderr.on("data", (chunk) => {
+  process.stderr.write(`[twzrd-mcp] ${chunk}`);
+});
+
+child.stdout.on("data", (chunk) => {
+  stdoutBuffer += chunk.toString("utf8");
+  parseFrames();
+});
+
+child.on("exit", (code, signal) => {
+  const err = new Error(`MCP server exited code=${code} signal=${signal}`);
+  for (const { reject, timer } of pending.values()) {
+    clearTimeout(timer);
+    reject(err);
+  }
+  pending.clear();
+});
+
+function parseFrames() {
+  for (;;) {
+    const lineEnd = stdoutBuffer.indexOf("\n");
+    if (lineEnd < 0) return;
+
+    const line = stdoutBuffer.slice(0, lineEnd).replace(/\r$/, "");
+    stdoutBuffer = stdoutBuffer.slice(lineEnd + 1);
+    if (!line.trim()) continue;
+
+    const message = JSON.parse(line);
+    if (message.id !== undefined && pending.has(message.id)) {
+      const { resolve, reject, timer } = pending.get(message.id);
+      pending.delete(message.id);
+      clearTimeout(timer);
+      if (message.error) reject(new Error(JSON.stringify(message.error)));
+      else resolve(message.result);
+    }
+  }
+}
+
+function send(message) {
+  const body = JSON.stringify(message);
+  child.stdin.write(`${body}\n`);
+}
+
+function request(method, params) {
+  const id = nextId++;
+  send({ jsonrpc: "2.0", id, method, params });
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`Timed out waiting for ${method}`));
+    }, 15000);
+    pending.set(id, { resolve, reject, timer });
+  });
+}
+
+function notify(method, params = {}) {
+  send({ jsonrpc: "2.0", method, params });
+}
+
+function textFromTool(result) {
+  return result?.content?.find((part) => part.type === "text")?.text || "";
+}
+
+function parseJsonText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function printSection(title, value) {
+  console.log(`\n== ${title} ==`);
+  if (typeof value === "string") console.log(value);
+  else console.log(JSON.stringify(value, null, 2));
+}
+
+async function main() {
+  const init = await request("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "twzrd-agent-drop-in", version: "0.1.0" },
+  });
+  notify("notifications/initialized");
+  printSection("server", init.serverInfo);
+
+  const tools = await request("tools/list", {});
+  printSection(
+    "tools",
+    tools.tools.map((tool) => `${tool.name}: ${tool.description}`),
+  );
+
+  const preflight = await request("tools/call", {
+    name: "preflight",
+    arguments: {
+      seller_wallet: demoWallet,
+      resource_name: "agent-drop-in-demo",
+      price_usdc: paidMode === "quick" ? 0.001 : 0.05,
+    },
+  });
+  printSection("free preflight", parseJsonText(textFromTool(preflight)) || textFromTool(preflight));
+
+  if (paidMode === "quick") {
+    const quick = await request("tools/call", {
+      name: "quick_trust",
+      arguments: { wallet: demoWallet },
+    });
+    printSection("paid quick_trust", parseJsonText(textFromTool(quick)) || textFromTool(quick));
+  }
+
+  if (paidMode === "full") {
+    const full = await request("tools/call", {
+      name: "full_trust",
+      arguments: { wallet: demoWallet },
+    });
+    const body = parseJsonText(textFromTool(full)) || {};
+    printSection("paid full_trust", body || textFromTool(full));
+
+    const receipt = body.twzrd_receipt || body.receipt;
+    if (receipt?.leaf) {
+      printSection("receipt", {
+        leaf: receipt.leaf,
+        signature: receipt.signature,
+        signing_pubkey: receipt.signing_pubkey,
+        settlement_tx: receipt.preimage?.settlement_tx || body.settlement_tx,
+      });
+      const verified = await request("tools/call", {
+        name: "verify_receipt",
+        arguments: {
+          leaf: receipt.leaf,
+          signature: receipt.signature,
+          signing_pubkey: receipt.signing_pubkey,
+        },
+      });
+      printSection("receipt verification", parseJsonText(textFromTool(verified)) || textFromTool(verified));
+
+      if (process.env.TWZRD_DEMO_RUN_VERIFIER_SELF_TEST === "1") {
+        console.log("\n== receipt-verifier self-test ==");
+        const verifier = spawnSync(
+          "npx",
+          ["-y", "twzrd-receipt-verifier@1.2.0", "-", "--self-test"],
+          { input: JSON.stringify(receipt), stdio: ["pipe", "inherit", "inherit"] },
+        );
+        if (verifier.status !== 0) {
+          throw new Error(`twzrd-receipt-verifier self-test exited ${verifier.status}`);
+        }
+      }
+    } else {
+      console.log("\nNo receipt object returned, so receipt verification was skipped.");
+    }
+  }
+
+  console.log(`\nDemo complete. paid_mode=${paidMode}`);
+}
+
+main()
+  .catch((err) => {
+    console.error(`\nDemo failed: ${err.message}`);
+    process.exitCode = 1;
+  })
+  .finally(() => {
+    child.kill();
+  });

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "twzrd-mcp-server",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "TWZRD Trust API MCP server with Solana x402 auto-pay (official @x402 SDK, spend-capped, preflight-gated).",
   "type": "module",
   "bin": {
-    "twzrd-mcp-server": "./dist/index.js"
+    "twzrd-mcp-server": "dist/index.js"
   },
   "main": "./dist/index.js",
   "files": [
-    "dist",
+    "dist/index.js",
+    "examples/agent-drop-in.mjs",
     "README.md"
   ],
   "engines": {
@@ -31,6 +32,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "demo": "node examples/agent-drop-in.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
@@ -38,7 +40,6 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@x402/core": "^2.17.0",
     "@x402/svm": "^2.17.0",
-    "@x402/fetch": "^2.17.0",
     "@solana/kit": "^5.1.0",
     "bs58": "^6.0.0"
   },