@paystage/mcp 0.5.0 → 0.6.0-canary.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -196,3 +196,20 @@ npx -y -p @paystage/mcp paystage-policy check policy.json
196
196
 
197
197
  Exit `0` valid, `1` invalid (one line per offending field), `2` unreadable. Offline, no key, no signup —
198
198
  the same schema the evaluator enforces, so a file that passes here is a file that will load there.
199
+
200
+ ## Explain a receipt in words
201
+
202
+ ```bash
203
+ npx -y -p @paystage/mcp paystage-explain receipt.json
204
+ ```
205
+
206
+ ```
207
+ Decision: do_not_pay
208
+ signature valid — this receipt is what PayStage issued
209
+ issued 2026-11-15T18:27:34Z by @paystage/hosted
210
+
211
+ · It asks for 1 USDC, and the policy allows at most 0.05 USDC.
212
+ ```
213
+
214
+ It verifies the signature first and says plainly when a receipt cannot be trusted. Rules it does not
215
+ recognise are **quoted, not paraphrased** — guessing at a refusal's meaning is worse than repeating it.
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=explain-cli.d.ts.map
@@ -0,0 +1,95 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `paystage-explain <receipt.json>` — turn a receipt's machine reasons into sentences.
4
+ *
5
+ * A receipt says *what* was decided and cites the rules. It is written for machines, and the person
6
+ * holding it is usually not the one who wrote the policy: "amount 1 USDC exceeds max_amount 0.05 USDC"
7
+ * is precise and still takes a second pass to read. This prints one sentence per reason, verifies the
8
+ * signature first, and says plainly when the receipt cannot be trusted.
9
+ *
10
+ * paystage-explain receipt.json # human output
11
+ * paystage-explain --json receipt.json # machine output
12
+ */
13
+ import { readFileSync } from "node:fs";
14
+ import { verifyReceipt } from "./verify.js";
15
+ const args = process.argv.slice(2);
16
+ const asJson = args.includes("--json");
17
+ const file = args.find((a) => !a.startsWith("-"));
18
+ if (!file) {
19
+ console.error("usage: paystage-explain <receipt.json> [--json]");
20
+ process.exit(2);
21
+ }
22
+ let receipt;
23
+ try {
24
+ receipt = JSON.parse(readFileSync(file, "utf8"));
25
+ }
26
+ catch (err) {
27
+ console.error(`cannot read ${file}: ${err instanceof Error ? err.message : String(err)}`);
28
+ process.exit(2);
29
+ }
30
+ /**
31
+ * One rule, one sentence. The patterns mirror what the evaluator emits — a reason this cannot translate
32
+ * is printed as-is rather than paraphrased, because guessing at a refusal's meaning is worse than
33
+ * quoting it.
34
+ */
35
+ function humanise(reason) {
36
+ let m;
37
+ if ((m = reason.match(/^amount (\S+) (\w+) exceeds max_amount (\S+) (\w+)$/))) {
38
+ return `It asks for ${m[1]} ${m[2]}, and the policy allows at most ${m[3]} ${m[4]}.`;
39
+ }
40
+ if ((m = reason.match(/^network (\S+) not in allowed_networks$/))) {
41
+ return `It settles on ${m[1]}, which the policy does not list as an allowed network.`;
42
+ }
43
+ if ((m = reason.match(/^asset (\S+) on (\S+) not in allowed_assets$/))) {
44
+ return `The token ${m[1]} on ${m[2]} is not an asset the policy accepts — often a lookalike.`;
45
+ }
46
+ if ((m = reason.match(/^payTo (\S+) not in allowed_pay_to \((deny|review)\)$/))) {
47
+ return m[2] === "deny"
48
+ ? `The payee ${m[1]} is not on the allow-list, and the policy refuses unknown payees.`
49
+ : `The payee ${m[1]} is not on the allow-list, so the policy asks a human to look before paying.`;
50
+ }
51
+ if (reason === "known drainer") {
52
+ return "The payee is on the known-drainer list — a cited list of addresses that take funds without delivering.";
53
+ }
54
+ if ((m = reason.match(/^maxTimeoutSeconds (\d+) exceeds policy max_timeout_seconds (\d+)$/))) {
55
+ return `The payment would stay valid for ${m[1]}s, longer than the ${m[2]}s the policy permits.`;
56
+ }
57
+ if ((m = reason.match(/^invalid atomic amount (\S*)$/))) {
58
+ return `The amount is not a whole number of atomic units ("${m[1] ?? ""}"), so it cannot be priced safely.`;
59
+ }
60
+ return reason;
61
+ }
62
+ const verdict = await verifyReceipt(receipt)
63
+ .then((v) => v)
64
+ .catch((err) => ({
65
+ ok: false,
66
+ status: "error",
67
+ reason: err instanceof Error ? err.message : String(err),
68
+ }));
69
+ const decision = receipt.verdict?.decision ?? "unknown";
70
+ const reasons = receipt.verdict?.reasons ?? [];
71
+ if (asJson) {
72
+ console.log(JSON.stringify({ decision, reasons, sentences: reasons.map(humanise), verification: verdict }, null, 2));
73
+ process.exit(0);
74
+ }
75
+ const trust = verdict.status === "signed-and-valid"
76
+ ? "signature valid — this receipt is what PayStage issued"
77
+ : verdict.status === "unsigned"
78
+ ? "UNSIGNED — useful as a record of a decision, but it proves nothing about who made it"
79
+ : `CANNOT BE TRUSTED — ${verdict.reason ?? verdict.status}`;
80
+ console.log(`Decision: ${decision}`);
81
+ console.log(` ${trust}`);
82
+ if (receipt.issued_at)
83
+ console.log(` issued ${receipt.issued_at} by ${receipt.service?.name ?? "unknown"}`);
84
+ console.log("");
85
+ if (reasons.length === 0) {
86
+ console.log(" No rules fired.");
87
+ }
88
+ else {
89
+ for (const r of reasons)
90
+ console.log(` · ${humanise(r)}`);
91
+ }
92
+ if (receipt.verdict?.summary)
93
+ console.log(`\n Summary: ${receipt.verdict.summary}`);
94
+ console.log("");
95
+ //# sourceMappingURL=explain-cli.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paystage/mcp",
3
- "version": "0.5.0",
3
+ "version": "0.6.0-canary.30",
4
4
  "description": "PayStage umbrella MCP: payment preflight, auth watch, HIP-3 trade preflight, and velocity rate/spend-pattern checks",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -20,7 +20,8 @@
20
20
  "bin": {
21
21
  "paystage-mcp": "dist/cli.js",
22
22
  "paystage-verify": "dist/verify-cli.js",
23
- "paystage-policy": "dist/policy-cli.js"
23
+ "paystage-policy": "dist/policy-cli.js",
24
+ "paystage-explain": "dist/explain-cli.js"
24
25
  },
25
26
  "files": [
26
27
  "dist",
@@ -55,11 +56,11 @@
55
56
  },
56
57
  "dependencies": {
57
58
  "@modelcontextprotocol/server": "^2.4.0",
58
- "@paystage/auth-watch": "0.2.0",
59
- "@paystage/policy": "0.2.1",
60
- "@paystage/preflight": "0.3.0",
61
- "@paystage/trade-preflight": "0.2.0",
62
- "@paystage/velocity": "0.2.0",
59
+ "@paystage/auth-watch": "0.2.1-canary.30",
60
+ "@paystage/policy": "0.2.1-canary.30",
61
+ "@paystage/preflight": "0.3.0-canary.30",
62
+ "@paystage/trade-preflight": "0.2.1-canary.30",
63
+ "@paystage/velocity": "0.2.1-canary.30",
63
64
  "zod": "^4.6.7"
64
65
  },
65
66
  "devDependencies": {
@@ -68,7 +69,7 @@
68
69
  "vitest": "^4.1.12"
69
70
  },
70
71
  "scripts": {
71
- "build": "tsc && chmod +x dist/cli.js dist/verify-cli.js dist/policy-cli.js",
72
+ "build": "tsc && chmod +x dist/cli.js dist/verify-cli.js dist/policy-cli.js dist/explain-cli.js",
72
73
  "test": "vitest run",
73
74
  "typecheck": "tsc --noEmit",
74
75
  "prepublishOnly": "npm run build"