@quackai/q402-mcp 0.1.3 → 0.2.1

package/README.md

@@ -41,11 +41,17 @@ You'll get a ranked breakdown immediately — no API key, no signup, no funds at
 | Tool | Auth | Purpose |
 |---|---|---|
 | `q402_quote` | none | Compare gas cost and supported tokens across chains. Read-only. |
-| `q402_balance` | API key | Verify the API key, show tier (live vs sandbox), and remaining quota. |
+| `q402_balance` | API key | Verify the API key and report its plan tier + remaining quota credits (live vs sandbox). |
 | `q402_pay` | API key + private key + flag | Send a gasless payment. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
+| `q402_receipt` | none | Look up a Trust Receipt by `rct_…` id and locally verify its ECDSA signature against the relayer EOA. Returns the public settlement record + a `verified` boolean. *receiptId-only today; tx-hash lookup reserved for a future release.* |
 
 `q402_pay` follows a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address, amount, chain, and token.
 
+`q402_receipt` is the natural follow-up: after `q402_pay` returns a `receiptUrl`, hand the agent the `rct_…` id and ask *"verify this receipt"* — the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser, so the verification doesn't depend on trusting any UI. Example prompts that work today:
+
+> *"Pay 0.10 USDT on BNB to vitalik.eth, then verify the receipt."*  
+> *"Is `rct_afa5f50bc49a65ebba3b28ab` a real Q402 receipt? Verify the signature."*
+
 > Per-chain gas tank balances and full transaction history live in the [dashboard](https://q402.quackai.ai/dashboard) — those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.
 
 ---

package/dist/index.js

@@ -561,7 +561,7 @@ async function runBalance() {
 }
 var BALANCE_TOOL = {
   name: "q402_balance",
-  description: "Verify the configured API key and show its tier (live vs sandbox) and remaining subscription quota. Read-only. For per-chain gas tank balances, point the user at https://q402.quackai.ai/dashboard \u2014 that data needs a wallet signature, not a bare key.",
+  description: "Verify the configured API key and report its plan tier (live vs sandbox). Read-only. For remaining daily quota and per-chain gas tank balances, point the user at https://q402.quackai.ai/dashboard \u2014 those need a wallet signature, not a bare key.",
   inputSchema: {
     type: "object",
     properties: {},
@@ -569,9 +569,172 @@ var BALANCE_TOOL = {
   }
 };
 
+// src/tools/receipt.ts
+import { z as z4 } from "zod";
+import { keccak256, toUtf8Bytes, getBytes, verifyMessage } from "ethers";
+var ReceiptShape = z4.object({
+  receiptId: z4.string(),
+  createdAt: z4.string(),
+  txHash: z4.string(),
+  blockNumber: z4.number().optional(),
+  chain: z4.string(),
+  payer: z4.string(),
+  recipient: z4.string(),
+  token: z4.enum(["USDC", "USDT"]),
+  tokenAmount: z4.string(),
+  tokenAmountRaw: z4.string(),
+  method: z4.enum(["eip7702", "eip3009", "eip7702_xlayer", "eip7702_stable"]),
+  gasCostNative: z4.string().optional(),
+  apiKeyTier: z4.string().optional(),
+  // hidden by default in publicView
+  showTier: z4.boolean(),
+  sandbox: z4.boolean(),
+  webhook: z4.object({
+    configured: z4.boolean(),
+    event: z4.string(),
+    deliveryStatus: z4.enum(["pending", "delivered", "failed", "not_configured"]),
+    attempts: z4.number().optional(),
+    lastStatusCode: z4.number().optional(),
+    lastError: z4.string().optional(),
+    deliveredAt: z4.string().optional(),
+    payloadSha256: z4.string().optional(),
+    signatureSha256: z4.string().optional()
+  }),
+  signature: z4.string(),
+  signedBy: z4.string(),
+  signedAt: z4.string()
+});
+function canonicalize(fields) {
+  const sorted = {};
+  for (const k of Object.keys(fields).sort()) {
+    sorted[k] = fields[k];
+  }
+  return JSON.stringify(sorted);
+}
+function digest(canonical) {
+  return keccak256(toUtf8Bytes(canonical));
+}
+function verifyReceiptSignature(r) {
+  try {
+    const fields = {
+      receiptId: r.receiptId,
+      createdAt: r.createdAt,
+      txHash: r.txHash,
+      chain: r.chain,
+      payer: r.payer,
+      recipient: r.recipient,
+      token: r.token,
+      tokenAmount: r.tokenAmount,
+      tokenAmountRaw: r.tokenAmountRaw,
+      method: r.method,
+      sandbox: r.sandbox
+    };
+    const recovered = verifyMessage(getBytes(digest(canonicalize(fields))), r.signature).toLowerCase();
+    return recovered === r.signedBy.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+var ReceiptInputSchema = z4.object({
+  receiptId: z4.string().regex(/^rct_[0-9a-f]{24}$/, "receiptId must match rct_<24-hex>").optional(),
+  txHash: z4.string().regex(/^0x[0-9a-fA-F]{64}$/, "txHash must be a 0x-prefixed 32-byte hex").optional()
+}).refine((v) => !!v.receiptId || !!v.txHash, {
+  message: "Provide receiptId OR txHash (at least one)"
+});
+var EXPLORERS = {
+  bnb: (h) => `https://bscscan.com/tx/${h}`,
+  eth: (h) => `https://etherscan.io/tx/${h}`,
+  avax: (h) => `https://snowtrace.io/tx/${h}`,
+  xlayer: (h) => `https://www.oklink.com/xlayer/tx/${h}`,
+  stable: (h) => `https://stable-explorer.io/tx/${h}`,
+  mantle: (h) => `https://mantlescan.xyz/tx/${h}`,
+  injective: (h) => `https://blockscout.injective.network/tx/${h}`
+};
+function receiptApiBase() {
+  return CONFIG.relayBaseUrl;
+}
+function pageBase() {
+  return CONFIG.relayBaseUrl.replace(/\/api\/?$/, "");
+}
+async function runReceipt(input) {
+  const apiBase = receiptApiBase();
+  const receiptId = input.receiptId ?? null;
+  if (!receiptId && input.txHash) {
+    return {
+      receiptId: null,
+      url: null,
+      pageUrl: null,
+      verified: false,
+      explorerUrl: null,
+      receipt: null,
+      notFound: true
+    };
+  }
+  if (!receiptId) {
+    return {
+      receiptId: null,
+      url: null,
+      pageUrl: null,
+      verified: false,
+      explorerUrl: null,
+      receipt: null,
+      notFound: true
+    };
+  }
+  const resp = await fetch(`${apiBase}/receipt/${receiptId}`);
+  if (resp.status === 404) {
+    return {
+      receiptId,
+      url: null,
+      pageUrl: null,
+      verified: false,
+      explorerUrl: null,
+      receipt: null,
+      notFound: true
+    };
+  }
+  if (!resp.ok) {
+    throw new Error(`receipt fetch failed: HTTP ${resp.status}`);
+  }
+  const raw = await resp.json();
+  const receipt = ReceiptShape.parse(raw);
+  const pUrl = `${pageBase()}/receipt/${receipt.receiptId}`;
+  const explorer = EXPLORERS[receipt.chain];
+  const explorerUrl = explorer ? explorer(receipt.txHash) : null;
+  const verified = verifyReceiptSignature(receipt);
+  return {
+    receiptId: receipt.receiptId,
+    url: pUrl,
+    pageUrl: pUrl,
+    verified,
+    explorerUrl,
+    receipt
+  };
+}
+var RECEIPT_TOOL = {
+  name: "q402_receipt",
+  description: "Look up a Q402 Trust Receipt by its rct_\u2026 receiptId and return the settlement record + a locally-verified ECDSA boolean (the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser). Read-only; no API key required. Use after q402_pay to give the user a shareable verified-by-Q402 URL, or to independently verify a receipt id someone shared with you. **receiptId is required**; passing only txHash returns notFound (tx \u2192 receiptId lookup is reserved for a future release).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      receiptId: {
+        type: "string",
+        pattern: "^rct_[0-9a-f]{24}$",
+        description: "Receipt id (rct_ + 24 hex chars). Returned by q402_pay; also visible at the end of any /receipt/ URL. This is the only path that resolves today."
+      },
+      txHash: {
+        type: "string",
+        pattern: "^0x[0-9a-fA-F]{64}$",
+        description: "Reserved for a future tx \u2192 receipt index. Today this is unimplemented and the tool returns notFound when only txHash is provided. Pass receiptId instead."
+      }
+    },
+    additionalProperties: false
+  }
+};
+
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.1.3";
+var PACKAGE_VERSION = "0.2.1";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }
@@ -581,7 +744,7 @@ async function main() {
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [QUOTE_TOOL, BALANCE_TOOL, PAY_TOOL]
+    tools: [QUOTE_TOOL, BALANCE_TOOL, PAY_TOOL, RECEIPT_TOOL]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
@@ -599,6 +762,10 @@ async function main() {
           const parsed = PayInputSchema.parse(args ?? {});
           return { content: [jsonText(await runPay(parsed))] };
         }
+        case "q402_receipt": {
+          const parsed = ReceiptInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runReceipt(parsed))] };
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.1.3",
-  "description": "MCP server for Q402 — gasless stablecoin payments across 7 EVM chains, callable directly from Claude Desktop and any MCP-compatible AI agent.",
+  "version": "0.2.1",
+  "description": "MCP server for Q402 — gasless USDC and USDT payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
     "mcp",