@agentpickup/mcp 0.3.2 → 0.4.0

package/README.md

@@ -10,18 +10,28 @@ QR they show at the counter to collect.
 |---|---|
 | `find_shops` | Shops near a point (`lat`/`lng`), in a suburb (`place`) or selling something (`query`), from the agentPickup directory: each one's `shop_url`, address, hours, open now, distance and matching items |
 | `get_shop` | Items and prices, the pickup location, and how the shop takes payment |
-| `create_pickup_order` | Creates an order. Needs the user's email, where the shop sends the receipt and pickup QR. A test shop marks it paid straight away, with no money moving. Where the shop takes cards, `payment: "card"` returns a checkout link for the user to pay on instead |
+| `create_pickup_order` | Creates an order and returns a `claim` to keep with it. Needs the user's email, where the shop sends the receipt and pickup pass. A test shop marks it paid straight away, with no money moving. Where the shop takes cards, `payment: "card"` returns a checkout link for the user to pay on instead |
 | `pay_order` | Pays the order's x402 link from your wallet and returns the pass link. With no wallet set up, returns the price and pay link instead. For a card order, returns its checkout link |
-| `order_status` | Waiting for payment, paid, ready, collected or expired |
-| `get_pickup_pass` | Fetches the pass link, pickup code and QR again by signing in as the paying wallet (Sign-In-With-X) |
+| `order_status` | Waiting for payment, paid, ready, collected or expired. With the order's `claim`, a paid order's pass comes back too |
+| `get_pickup_pass` | Fetches the pass link, pickup code and QR again: with the order's `claim`, or by signing in as the paying wallet (Sign-In-With-X) |
 | `start_group_order` | Starts a group order (a coffee run) with a closing time; returns the code to share and a key to close it early |
 | `join_group_order` | Adds the user's items to a group order by its code; pay the share with `pay_order` before it closes |
 | `group_order_status` | Who's in, what they ordered, who has paid, and whether the shop's order is ready or collected |
 | `close_group_order` | Closes a group order early, as its organiser; the shop gets one combined order and the organiser its QR |
 
+## The pickup pass card
+
+In chat apps that draw [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) cards (Claude and ChatGPT
+among them), `create_pickup_order`, `order_status` and `get_pickup_pass` show the order as a card: a Pay button while
+it's unpaid, then the QR and pickup code, kept up to date until it's collected. When the shop marks it ready, the QR's
+tile turns lime. The card is one self-contained page (`ui://agentpickup/pass-<version>.html`) that loads nothing from
+anywhere else. In apps without cards, the agent gives the user the pass link and pickup code. The shop emails the pass
+either way.
+
 ## Use it
 
-Try it against the hosted demo shop first. It pays with the demo's own small wallet, within the demo's caps:
+Try it against the hosted demo shops first. The hosted server holds no wallet: its demo shops take a free test
+payment, the Square sandbox's test card, or USDC from the user's own x402 wallet:
 
 ```json
 { "mcpServers": { "agentpickup": { "type": "http", "url": "https://agentpickup.app/mcp" } } }
@@ -62,6 +72,7 @@ items and the total with the user before paying.
 import { createMcpHandler, walletPayer } from "@agentpickup/mcp";
 
 const mcp = createMcpHandler({ shopUrl: "https://orders.yourshop.com" }); // no wallet: pay_order quotes
+// `instructions` adds your own notes to what agents read on connecting, e.g. which of your shops take what.
 app.all("/mcp", (c) => mcp(c.req.raw)); // Streamable HTTP, stateless, any Request/Response runtime
 ```
 

package/dist/card.d.ts

@@ -0,0 +1,25 @@
+export declare const CARD_MIME_TYPE = "text/html;profile=mcp-app";
+/** Where tools hand their card data: the card reads it, the model doesn't need it. */
+export declare const CARD_META_KEY = "agentpickup/pass";
+/** What the card draws. Every field but orderId is optional: later results fill in or update what's there. */
+export interface PassCard {
+    v: 1;
+    orderId: string;
+    shopUrl?: string;
+    shopName?: string;
+    /** Lets the card call order_status itself while the order moves along. */
+    claim?: string;
+    status?: string;
+    rail?: string;
+    items?: string;
+    total?: string;
+    collectBy?: number | null;
+    collectedAt?: number | null;
+    checkoutUrl?: string;
+    passUrl?: string;
+    pickupCode?: string | null;
+    /** The QR as SVG, ink on transparent, so the tile behind it sets the colour. */
+    qrSvg?: string;
+}
+/** The card's page. Its version goes in the handshake, so a host's logs say which card it ran. */
+export declare function passCardHtml(version: string): string;

package/dist/card.js

@@ -0,0 +1,269 @@
+// The pickup pass as an MCP Apps card (ui:// resource, text/html;profile=mcp-app): chat apps that show cards (Claude,
+// ChatGPT) draw it beside the tool result. It shows the order, a Pay button while it's unpaid, then the QR and pickup
+// code, and keeps itself up to date (order_status with the order's claim) until it's collected. At "ready" the QR's
+// tile turns brand lime. One self-contained page: no scripts, fonts or images from anywhere else.
+//
+// The bridge is the MCP Apps postMessage protocol (JSON-RPC 2.0 with the host, protocol 2026-01-26), written out
+// here rather than bundling the 300 KB SDK: ui/initialize, ui/notifications/initialized, tool-result,
+// host-context-changed, resource-teardown, tools/call, ui/open-link and ui/notifications/size-changed.
+export const CARD_MIME_TYPE = "text/html;profile=mcp-app";
+/** Where tools hand their card data: the card reads it, the model doesn't need it. */
+export const CARD_META_KEY = "agentpickup/pass";
+const PAGE = String.raw `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Pickup pass</title>
+<style>
+:root{--bg:#ffffff;--surface:#f4f4f1;--text:#16161a;--muted:#66666d;--line:rgba(10,11,13,.12);--ok:#2e7d32;--lime:#b5f23d;--ink:#0a0b0d;color-scheme:light}
+:root[data-theme=dark]{--bg:#1d1d20;--surface:#2a2a2e;--text:#f2f2f4;--muted:#a3a3ab;--line:rgba(255,255,255,.14);--ok:#8fd47f;color-scheme:dark}
+@media (prefers-color-scheme:dark){:root:not([data-theme]){--bg:#1d1d20;--surface:#2a2a2e;--text:#f2f2f4;--muted:#a3a3ab;--line:rgba(255,255,255,.14);--ok:#8fd47f;color-scheme:dark}}
+html,body{margin:0;padding:0;background:transparent}
+body{font-family:var(--font-sans,ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif);color:var(--text);-webkit-font-smoothing:antialiased;padding:2px}
+.card{box-sizing:border-box;max-width:380px;margin:0 auto;background:var(--bg);border:1px solid var(--line);border-radius:16px;padding:16px 18px}
+.head{display:flex;justify-content:space-between;align-items:flex-start;gap:12px;margin-bottom:12px}
+.shop{font-weight:600;font-size:15px;margin:0}
+.items{font-size:13px;color:var(--muted);margin:2px 0 0}
+.badge{font-size:12px;line-height:1;padding:6px 10px;border-radius:999px;background:var(--surface);white-space:nowrap}
+.badge.ready{background:var(--lime);color:var(--ink);font-weight:600}
+.wrap{position:relative;border-radius:12px}
+.tile{position:relative;overflow:hidden;background:#ffffff;border-radius:12px;padding:14px;display:flex;justify-content:center;align-items:center;border:1px solid var(--line);min-height:120px}
+.tile svg{position:relative;display:block;width:100%;max-width:220px;height:auto}
+.pour{position:absolute;left:0;right:0;bottom:0;height:0;background:var(--lime);transition:height 1s cubic-bezier(.5,0,.2,1)}
+.wrap.ready .pour{height:100%}
+.wrap.ready .tile{border-color:var(--lime)}
+.wrap.ready::after{content:"";position:absolute;inset:0;border:2px solid var(--lime);border-radius:12px;animation:ring 1.8s ease-out infinite;pointer-events:none}
+@keyframes ring{from{transform:scale(1);opacity:.9}to{transform:scale(1.08);opacity:0}}
+.tile.plain{background:var(--surface)}
+.done{font-size:15px;color:var(--text);text-align:center}
+.done b{display:block;font-size:34px;line-height:1.2}
+.facts{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:10px;margin:12px 0 0}
+.fact{background:var(--surface);border-radius:10px;padding:8px 12px}
+.fact span{display:block;font-size:12px;color:var(--muted)}
+.fact b{display:block;font-size:20px;font-weight:600;overflow-wrap:anywhere}
+.code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;letter-spacing:2px}
+.steps{display:flex;justify-content:space-between;border-top:1px solid var(--line);padding-top:10px;margin-top:12px}
+.step{display:flex;align-items:center;gap:6px;font-size:12px;color:var(--muted)}
+.dot{width:10px;height:10px;border-radius:50%;border:1.5px solid currentColor;box-sizing:border-box}
+.step.past{color:var(--ok)}.step.past .dot{background:currentColor}
+.step.now{color:var(--text);font-weight:600}.step.now .dot{background:var(--ok);border-color:var(--ok)}
+.msg{font-size:13px;color:var(--muted);margin:10px 0 0;line-height:1.45}
+.test{font-size:12px;color:var(--muted);margin:6px 0 0}
+.row{display:flex;gap:12px;align-items:center;margin-top:12px;flex-wrap:wrap}
+button{font:inherit;font-size:14px;border-radius:10px;padding:10px 14px;cursor:pointer;border:1px solid var(--line);background:var(--surface);color:var(--text)}
+button.pay{background:var(--lime);color:var(--ink);border-color:var(--lime);font-weight:600}
+button.link{background:none;border:none;padding:0;color:var(--muted);text-decoration:underline;font-size:13px}
+.foot{font-size:11px;color:var(--muted);margin-top:12px;text-align:right}
+@media (prefers-reduced-motion:reduce){.pour{transition:none}.wrap.ready::after{animation:none;opacity:1}}
+</style>
+</head>
+<body>
+<div id="root"></div>
+<script>
+(function () {
+  var VERSION = "__VERSION__";
+  var LABELS = { awaiting_payment: "Waiting for payment", paid: "Paid", ready: "Ready", collected: "Collected", expired: "Expired", cancelled: "Cancelled" };
+  var FINAL = { collected: 1, expired: 1, cancelled: 1 };
+  var root = document.getElementById("root");
+  var state = null, canCall = false, canOpen = false, locale, timeZone;
+  var nextId = 1, pending = {}, timer = null, started = Date.now(), lastHtml = "", poured = false, lastHeight = -1, stopped = false;
+
+  // ---------- the bridge ----------
+  var host = window.parent;
+  function send(msg) { try { host.postMessage(msg, "*"); } catch (e) {} }
+  function request(method, params) {
+    var id = nextId++;
+    send({ jsonrpc: "2.0", id: id, method: method, params: params });
+    return new Promise(function (resolve, reject) {
+      pending[id] = { resolve: resolve, reject: reject };
+      setTimeout(function () { if (pending[id]) { delete pending[id]; reject(new Error("timed out")); } }, 30000);
+    });
+  }
+  function notify(method, params) { send({ jsonrpc: "2.0", method: method, params: params }); }
+  window.addEventListener("message", function (e) {
+    if (host !== window && e.source !== host) return;
+    var m = e.data;
+    if (!m || m.jsonrpc !== "2.0") return;
+    if (m.id != null && !m.method) {
+      var p = pending[m.id];
+      if (p) { delete pending[m.id]; if (m.error) p.reject(m.error); else p.resolve(m.result); }
+      return;
+    }
+    if (m.method === "ui/notifications/tool-result") return onResult(m.params);
+    if (m.method === "ui/notifications/host-context-changed") { applyContext(m.params || {}); return render(); }
+    if (m.method === "ui/resource-teardown") { stop(); if (m.id != null) send({ jsonrpc: "2.0", id: m.id, result: {} }); return; }
+    if (m.method === "ping" && m.id != null) return send({ jsonrpc: "2.0", id: m.id, result: {} });
+    if (m.id != null && m.method && m.method.indexOf("ui/notifications/") !== 0) {
+      send({ jsonrpc: "2.0", id: m.id, error: { code: -32601, message: "Method not found" } });
+    }
+  });
+  function applyContext(ctx) {
+    if (ctx.theme === "light" || ctx.theme === "dark") document.documentElement.setAttribute("data-theme", ctx.theme);
+    var vars = ctx.styles && ctx.styles.variables;
+    if (vars) for (var k in vars) if (k.indexOf("--") === 0 && typeof vars[k] === "string") document.documentElement.style.setProperty(k, vars[k]);
+    if (ctx.locale) locale = ctx.locale;
+    if (ctx.timeZone) timeZone = ctx.timeZone;
+  }
+  function openLink(url) {
+    if (!url) return;
+    if (canOpen) request("ui/open-link", { url: url }).catch(function () { window.open(url, "_blank", "noopener"); });
+    else window.open(url, "_blank", "noopener");
+  }
+
+  // ---------- results ----------
+  function cardOf(result) {
+    if (!result) return null;
+    var meta = result._meta && result._meta["agentpickup/pass"];
+    if (meta && meta.orderId) return meta;
+    // A host that drops _meta: the JSON after the tool's summary line still has the basics.
+    try {
+      var text = result.content && result.content[0] && result.content[0].text;
+      var data = JSON.parse(text.slice(text.indexOf("\n\n") + 2));
+      var id = data.orderId || data.id || (data.order && data.order.id);
+      if (!id) return null;
+      return { orderId: id, status: data.status, passUrl: data.passUrl, pickupCode: data.pickupCode, checkoutUrl: data.checkoutUrl, total: data.total, claim: data.claim, shopUrl: data.shop };
+    } catch (e) { return null; }
+  }
+  function onResult(result) {
+    var card = cardOf(result);
+    if (card) {
+      if (state && state.orderId !== card.orderId) state = null;
+      var next = state ? Object.assign({}, state) : {};
+      for (var k in card) if (card[k] !== undefined && card[k] !== null && card[k] !== "") next[k] = card[k];
+      if (card.status && card.status !== "awaiting_payment") delete next.checkoutUrl;
+      state = next;
+    }
+    render();
+    schedule();
+  }
+
+  // ---------- keeping up to date ----------
+  function stop() { stopped = true; clearTimeout(timer); }
+  function schedule() {
+    clearTimeout(timer);
+    if (stopped || !state || !state.claim || !canCall || FINAL[state.status]) return;
+    if (Date.now() - started > 4 * 3600 * 1000) return;
+    var wait = document.hidden ? 60000 : state.status === "awaiting_payment" ? 5000 : 15000;
+    timer = setTimeout(poll, wait);
+  }
+  function poll() {
+    var args = { order_id: state.orderId, claim: state.claim };
+    if (state.shopUrl) args.shop_url = state.shopUrl;
+    request("tools/call", { name: "order_status", arguments: args }).then(function (r) {
+      if (r && !r.isError) onResult(r); else schedule();
+    }, schedule);
+  }
+  document.addEventListener("visibilitychange", function () { if (!document.hidden && state) { clearTimeout(timer); poll(); } });
+
+  // ---------- drawing ----------
+  function esc(s) { return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) { return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]; }); }
+  function time(ms) {
+    var d = new Date(ms), o = { hour: "numeric", minute: "2-digit" };
+    if (timeZone) o.timeZone = timeZone;
+    try {
+      var s = d.toLocaleTimeString(locale, o);
+      if (Math.abs(ms - Date.now()) > 18 * 3600 * 1000) {
+        var od = { weekday: "short" };
+        if (timeZone) od.timeZone = timeZone;
+        s = d.toLocaleDateString(locale, od) + " " + s;
+      }
+      return s;
+    } catch (e) { return d.toLocaleTimeString(); }
+  }
+  function safeSvg(svg) { return typeof svg === "string" && /^<svg[\s>]/.test(svg) && !/<script|<foreignObject|\son[a-z]+=/i.test(svg) ? svg : ""; }
+  function message(s) {
+    var live = canCall && s.claim;
+    switch (s.status) {
+      case "awaiting_payment":
+        return s.checkoutUrl
+          ? "Pay on the checkout page. " + (live ? "This card turns into your pickup pass once it's paid." : "Then ask for the pickup pass.")
+          : "Waiting for the payment. " + (live ? "This card turns into your pickup pass once it's paid." : "");
+      case "paid": return "Paid. " + (live ? "This turns green when it's ready. " : "") + "The pass is in your email too.";
+      case "ready": return "Ready at the counter. Show the QR or say the code.";
+      case "collected": return s.collectedAt ? "Collected at " + time(s.collectedAt) + ". Enjoy." : "Collected. Enjoy.";
+      case "expired": return "This order expired before anyone collected it.";
+      case "cancelled": return "This order was cancelled.";
+      default: return "";
+    }
+  }
+  function view(s) {
+    var status = s.status || "awaiting_payment";
+    var label = LABELS[status] || status;
+    var live = status === "paid" || status === "ready";
+    var h = '<div class="card">';
+    h += '<div class="head"><div><p class="shop">' + esc(s.shopName || "Your pickup order") + "</p>";
+    if (s.items) h += '<p class="items">' + esc(s.items) + (s.total ? " · " + esc(s.total) : "") + "</p>";
+    h += '</div><span class="badge' + (status === "ready" ? " ready" : "") + '">' + esc(label) + "</span></div>";
+    var svg = safeSvg(s.qrSvg);
+    if (live && svg) {
+      h += '<div class="wrap' + (status === "ready" && poured ? " ready" : "") + '" id="wrap"><div class="tile"><div class="pour"></div>' +
+        svg.replace("<svg", '<svg role="img" aria-label="Pickup QR code"') + "</div></div>";
+    } else if (status === "collected") {
+      h += '<div class="wrap"><div class="tile plain"><div class="done"><b>&#10003;</b>Collected</div></div></div>';
+    }
+    if (live && (s.pickupCode || s.collectBy)) {
+      h += '<div class="facts">';
+      if (s.pickupCode) h += '<div class="fact"><span>Pickup code</span><b class="code">' + esc(s.pickupCode) + "</b></div>";
+      if (s.collectBy) h += '<div class="fact"><span>Collect by</span><b>' + esc(time(s.collectBy)) + "</b></div>";
+      h += "</div>";
+    }
+    if (live || status === "collected") {
+      var at = { paid: 0, ready: 1, collected: 2 }[status];
+      h += '<div class="steps">' + ["Paid", "Ready", "Collected"].map(function (name, i) {
+        return '<span class="step' + (i < at ? " past" : i === at ? " now" : "") + '"><span class="dot"></span>' + name + "</span>";
+      }).join("") + "</div>";
+    }
+    var msg = message(s);
+    if (msg) h += '<p class="msg">' + esc(msg) + "</p>";
+    if (s.rail === "test") h += '<p class="test">Test order: no money moved.</p>';
+    var actions = "";
+    if (status === "awaiting_payment" && s.checkoutUrl) actions += '<button class="pay" data-open="checkoutUrl">Pay' + (s.total ? " " + esc(s.total) : "") + " by card</button>";
+    if (live && s.passUrl) actions += '<button class="link" data-open="passUrl">Open the pass</button>';
+    if (actions) h += '<div class="row">' + actions + "</div>";
+    h += '<div class="foot">agentPickup</div></div>';
+    return h;
+  }
+  function render() {
+    var html = state ? view(state) : "";
+    if (html !== lastHtml) {
+      root.innerHTML = html;
+      lastHtml = html;
+      var buttons = root.querySelectorAll("[data-open]");
+      for (var i = 0; i < buttons.length; i++) buttons[i].addEventListener("click", function (e) { openLink(state[e.currentTarget.getAttribute("data-open")]); });
+    }
+    // The lime pours in once, the first time the card sees the order ready.
+    var wrap = document.getElementById("wrap");
+    if (wrap && state && state.status === "ready" && !poured) {
+      void wrap.offsetWidth;
+      wrap.classList.add("ready");
+      poured = true;
+      lastHtml = view(state);
+    }
+    reportSize();
+  }
+  function reportSize() {
+    var height = Math.ceil(document.body.getBoundingClientRect().height);
+    if (height !== lastHeight) { lastHeight = height; notify("ui/notifications/size-changed", { height: height }); }
+  }
+  if (window.ResizeObserver) new ResizeObserver(reportSize).observe(document.body);
+
+  // ---------- start ----------
+  request("ui/initialize", { appInfo: { name: "agentpickup-pass", version: VERSION }, appCapabilities: {}, protocolVersion: "2026-01-26" })
+    .then(function (r) {
+      var caps = (r && r.hostCapabilities) || {};
+      canCall = Boolean(caps.serverTools);
+      canOpen = Boolean(caps.openLinks);
+      applyContext((r && r.hostContext) || {});
+      notify("ui/notifications/initialized", {});
+      render();
+      schedule();
+    }, function () { render(); });
+})();
+</script>
+</body>
+</html>`;
+/** The card's page. Its version goes in the handshake, so a host's logs say which card it ran. */
+export function passCardHtml(version) {
+    return PAGE.replace("__VERSION__", version);
+}

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Fetch, type Payer } from "./wallet.js";
-export declare const VERSION = "0.3.2";
+export declare const VERSION = "0.4.0";
 export interface PickupMcpOptions {
     /** The agentPickup shop this server orders from. */
     shopUrl: string;
@@ -20,6 +20,8 @@ export interface PickupMcpOptions {
     fetch?: Fetch;
     /** The wallet that pays. Without one, pay_order returns the price and pay link for another x402 client. */
     payer?: Payer;
+    /** Notes added to the instructions agents read on connecting, e.g. which of this host's shops take what. */
+    instructions?: string;
 }
 export declare function createPickupMcpServer(opts: PickupMcpOptions): McpServer;
 /** A Streamable HTTP endpoint (stateless, JSON responses) for hosting the server, e.g. at /mcp. */

package/dist/server.js

@@ -2,25 +2,48 @@
 // shops near someone, see what they sell, order, pay over x402, and hand its user the QR to collect with.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import QRCode from "qrcode";
 import { z } from "zod";
+import { CARD_META_KEY, CARD_MIME_TYPE, passCardHtml } from "./card.js";
 import { errorOf, usd } from "./wallet.js";
-export const VERSION = "0.3.2";
+export const VERSION = "0.4.0";
+// The pickup pass card (MCP Apps). The version is in the URI so hosts that cache cards pick up a new one.
+const CARD_URI = `ui://agentpickup/pass-${VERSION}.html`;
+const CARD_TOOL_META = { ui: { resourceUri: CARD_URI }, "ui/resourceUri": CARD_URI };
+// Shop names for the card, so polling order_status needn't read the catalog each time. Shared across the
+// per-request servers a hosted endpoint makes.
+const shopNames = new Map();
+const rememberShop = (shop, name) => {
+    if (typeof name !== "string" || !name)
+        return;
+    if (shopNames.size > 500)
+        shopNames.clear();
+    shopNames.set(shop, name);
+};
+/** The QR in ink on transparent: the card's tile behind it is white, or lime once the order is ready. */
+const qrSvg = (content) => QRCode.toString(content, { type: "svg", errorCorrectionLevel: "M", margin: 0, color: { dark: "#0a0b0dff", light: "#00000000" } });
 class ToolError extends Error {
 }
 const INSTRUCTIONS = `agentPickup lets you buy things online for the user to collect in person.
 0. find_shops (when available): shops near the user that sell what they want. Pass a shop's shop_url to the other tools.
 1. get_shop: see what the shop sells, its pickup location and how it takes payment.
-2. create_pickup_order: needs the user's email, where the shop sends the pickup QR.
-3. pay_order: pays from the configured wallet in USDC over x402. Where the shop takes cards, payment: "card" on
-   create_pickup_order gives a checkout link for the user to pay on instead. Confirm the items and total with the user first.
-4. Give the user the pass link and pickup code. They show the QR at the counter to collect.
-get_pickup_pass fetches the pass again later; order_status says whether it's ready or collected.
+2. create_pickup_order: needs the user's email; the shop emails the pickup pass there too. It returns a claim:
+   keep it with the order id.
+3. pay_order: pays in USDC over x402 from the wallet set up here; with none, it hands back the pay link for the user's
+   own x402 wallet. Where the shop takes cards, payment: "card" on
+   create_pickup_order gives a checkout link for the user to pay on instead. Where it takes test payments (get_shop says
+   so), payment: "test" runs the whole flow with no money moving. Confirm the items and total with the user first.
+4. The pass: where the chat shows cards, the order appears as a card that becomes the pickup pass (QR and code)
+   once it's paid and keeps itself up to date until it's collected. Otherwise give the user the pass link and pickup
+   code. They show the QR at the counter, or say the code, to collect.
+get_pickup_pass (with the claim) fetches the pass again; order_status (with the claim) says whether it's ready.
 Group orders (a coffee run): start_group_order gives a code to share; each person's agent calls join_group_order and
 pays its own share with pay_order; at closing time the shop gets one combined order and the organiser gets its QR.
 group_order_status shows who's in; close_group_order closes it early.`;
 const money = (cents, currency) => new Intl.NumberFormat("en-US", { style: "currency", currency: currency.toUpperCase() }).format(cents / 100);
-const reply = (summary, data) => ({
+const reply = (summary, data, card) => ({
     content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(data, null, 2)}` }],
+    ...(card ? { _meta: { [CARD_META_KEY]: card } } : {}),
 });
 const failure = (message) => ({ content: [{ type: "text", text: message }], isError: true });
 /** A shop's base URL: shops can live under a path (https://host/v/cafe). A pasted API or pass link works too. */
@@ -71,6 +94,44 @@ export function createPickupMcpServer(opts) {
             return failure(`Couldn't reach the shop: ${err instanceof Error ? err.message : String(err)}`);
         }
     };
+    /** The pass, for whoever made the order. null while it isn't paid (or is a share of a group order). */
+    async function passByClaim(shop, orderId, claim) {
+        const res = await doFetch(new Request(`${shop}/api/orders/${encodeURIComponent(orderId)}/pass`, { headers: { "X-Pickup-Claim": claim } }));
+        if (res.status === 409)
+            return null;
+        if (!res.ok)
+            throw new ToolError(await errorOf(res, `The shop answered ${res.status}.`));
+        return (await res.json());
+    }
+    async function shopName(shop) {
+        if (!shopNames.has(shop)) {
+            const data = await call(shop, "/api/catalog").catch(() => null);
+            rememberShop(shop, data?.merchant?.name);
+        }
+        return shopNames.get(shop);
+    }
+    /** What the pass card draws for an order, with its QR once there's a pass. */
+    async function cardFor(shop, order, extra = {}, pass) {
+        return {
+            v: 1,
+            orderId: order.id,
+            shopUrl: shop,
+            shopName: shopNames.get(shop),
+            status: order.status,
+            rail: order.rail,
+            items: order.items.map((i) => `${i.qty}× ${i.name}`).join(", "),
+            total: money(order.totalCents, order.currency),
+            collectBy: order.collectBy,
+            collectedAt: order.collectedAt ?? null,
+            ...extra,
+            ...(pass ? { passUrl: pass.passUrl, pickupCode: pass.pickupCode, qrSvg: await qrSvg(pass.qrContent) } : {}),
+        };
+    }
+    const claimArg = z
+        .string()
+        .max(200)
+        .optional()
+        .describe("The claim create_pickup_order returned with the order. With it, a paid order's pass comes back too.");
     const shopArg = opts.allowOtherShops || opts.directoryUrl
         ? { shop_url: z.string().optional().describe(`An agentPickup shop's URL, as find_shops returns it. Defaults to ${home}.`) }
         : {};
@@ -80,7 +141,15 @@ export function createPickupMcpServer(opts) {
         version: VERSION,
         websiteUrl: "https://agentpickup.app",
         icons: [{ src: "https://agentpickup.app/logo.png", mimeType: "image/png", sizes: ["1024x1024"] }],
-    }, { instructions: INSTRUCTIONS });
+    }, { instructions: opts.instructions ? `${INSTRUCTIONS}\n${opts.instructions}` : INSTRUCTIONS });
+    server.registerResource("pickup-pass", CARD_URI, {
+        title: "Pickup pass",
+        description: "The order as a card: a Pay button while it's unpaid, then the QR and pickup code, kept up to date until it's collected.",
+        mimeType: CARD_MIME_TYPE,
+        _meta: { ui: { prefersBorder: false } },
+    }, async () => ({
+        contents: [{ uri: CARD_URI, mimeType: CARD_MIME_TYPE, text: passCardHtml(VERSION), _meta: { ui: { prefersBorder: false } } }],
+    }));
     if (opts.directoryUrl) {
         const directoryUrl = opts.directoryUrl;
         server.registerTool("find_shops", {
@@ -152,6 +221,7 @@ export function createPickupMcpServer(opts) {
         const shop = await shopFor(args.shop_url);
         const data = await call(shop, "/api/catalog");
         const merchant = data.merchant;
+        rememberShop(shop, merchant.name);
         const currency = String(data.currency ?? "usd");
         const items = data.items.map((i) => ({
             id: i.id,
@@ -175,32 +245,42 @@ export function createPickupMcpServer(opts) {
     }));
     server.registerTool("create_pickup_order", {
         title: "Order for pickup",
-        description: "Create an order to collect in person. Returns the order id and total; pay it with pay_order. " +
-            "The shop emails the pickup QR to `email` once it's paid. Where the shop takes cards, `payment: \"card\"` " +
-            "returns a checkout link for the user to pay on instead.",
+        description: "Create an order to collect in person. Returns the order id, total and a claim (keep it); pay it with pay_order. " +
+            "The shop emails the pickup pass to `email` once it's paid, and where the chat shows cards the order shows as one " +
+            "that becomes the pass. Where the shop takes cards, `payment: \"card\"` returns a checkout link for the user to pay on instead.",
         inputSchema: {
             items: z
                 .array(z.object({ id: z.string().describe("Item id from get_shop"), qty: z.number().int().min(1).max(20) }))
                 .min(1),
-            email: z.string().email().describe("The user's email. The pickup QR goes here."),
+            email: z.string().email().describe("The user's email. The pickup pass goes here too."),
             name: z.string().max(100).optional().describe("Name for the order, shown to staff"),
             payment: z
-                .enum(["agent", "card"])
+                .enum(["agent", "card", "test"])
                 .optional()
-                .describe("Who pays: agent (USDC over x402, or a test payment at a test shop) or card (the user pays on a checkout link). Default: agent where the shop takes it, else card."),
+                .describe("Who pays: agent (USDC over x402, or a test payment at a test shop), card (the user pays on a checkout link), " +
+                "or test (where the shop takes test payments: the whole flow with no money moving). Default: agent where the shop takes it, else card."),
             ...shopArg,
         },
         annotations: { title: "Order for pickup", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        _meta: CARD_TOOL_META,
     }, guarded(async (args) => {
         const shop = await shopFor(args.shop_url);
         // The agent pays over x402 where the shop takes it, a test shop marks the order paid straight away, and a
         // shop that takes cards gives the user a checkout link.
-        const { payments } = (await call(shop, "/api/catalog"));
+        const catalog = (await call(shop, "/api/catalog"));
+        rememberShop(shop, catalog.merchant?.name);
+        const { payments } = catalog;
         const agentRail = payments.x402 ? "x402" : payments.test ? "test" : null;
         const cardRail = payments.square ? "square" : payments.card ? "card" : null;
-        const rail = args.payment === "card" ? cardRail : args.payment === "agent" ? agentRail : (agentRail ?? cardRail);
-        if (!rail)
-            throw new ToolError(args.payment === "card" ? "This shop doesn't take cards." : "This shop doesn't take agent payments.");
+        const rail = args.payment === "test" ? (payments.test ? "test" : null)
+            : args.payment === "card" ? cardRail
+                : args.payment === "agent" ? agentRail
+                    : (agentRail ?? cardRail);
+        if (!rail) {
+            throw new ToolError(args.payment === "test" ? "This shop doesn't take test payments."
+                : args.payment === "card" ? "This shop doesn't take cards."
+                    : "This shop doesn't take agent payments.");
+        }
         const data = await call(shop, "/api/orders", {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -208,16 +288,31 @@ export function createPickupMcpServer(opts) {
         });
         const order = data.order;
         const next = data.next;
+        // Older shops don't hand out claims; everything else still works.
+        const claim = typeof data.claim === "string" ? data.claim : undefined;
+        const what = `${order.items.map((i) => `${i.qty}× ${i.name}`).join(", ")}, ${money(order.totalCents, order.currency)}`;
+        const keep = claim ? " Keep the claim: get_pickup_pass and order_status take it." : "";
         if (rail === "test") {
-            return reply(`Test order ${order.id}: ${order.items.map((i) => `${i.qty}× ${i.name}`).join(", ")}, ${money(order.totalCents, order.currency)}, ` +
-                `marked paid with no money moving. The shop emails ${args.email} the receipt and pickup QR; the pass is at ${next.passUrl}.`, { shop, orderId: order.id, status: order.status, test: true, total: money(order.totalCents, order.currency), items: order.items, passUrl: next.passUrl });
+            const pass = claim ? await passByClaim(shop, order.id, claim).catch(() => null) : null;
+            return reply(`Test order ${order.id}: ${what}, marked paid with no money moving. The pickup pass is at ${next.passUrl}` +
+                (pass ? ` (pickup code ${pass.pickupCode})` : "") +
+                `, and the shop emails it to ${args.email}.${keep}`, {
+                shop,
+                orderId: order.id,
+                claim,
+                status: order.status,
+                test: true,
+                total: money(order.totalCents, order.currency),
+                items: order.items,
+                passUrl: next.passUrl,
+                pickupCode: pass?.pickupCode,
+            }, await cardFor(shop, order, { claim, rail }, pass));
         }
         if (rail === "square" || rail === "card") {
-            return reply(`Order ${order.id}: ${order.items.map((i) => `${i.qty}× ${i.name}`).join(", ")}, ${money(order.totalCents, order.currency)}. ` +
-                `Give the user this link to pay by card: ${next.url}. Once they've paid, the shop emails ${args.email} the receipt and pickup QR.`, { shop, orderId: order.id, total: money(order.totalCents, order.currency), items: order.items, payBy: "card", checkoutUrl: next.url, collectBy: order.collectBy });
+            return reply(`Order ${order.id}: ${what}. Give the user this link to pay by card: ${next.url}. Once they've paid, the shop emails ` +
+                `${args.email} the receipt and pickup pass.${keep}`, { shop, orderId: order.id, claim, total: money(order.totalCents, order.currency), items: order.items, payBy: "card", checkoutUrl: next.url, collectBy: order.collectBy }, await cardFor(shop, order, { claim, rail, checkoutUrl: next.url }));
         }
-        return reply(`Order ${order.id}: ${order.items.map((i) => `${i.qty}× ${i.name}`).join(", ")}, ${money(order.totalCents, order.currency)}. ` +
-            `Confirm with the user, then call pay_order.`, { shop, orderId: order.id, total: money(order.totalCents, order.currency), items: order.items, payUrl: next.url, collectBy: order.collectBy });
+        return reply(`Order ${order.id}: ${what}. Confirm with the user, then call pay_order.${keep}`, { shop, orderId: order.id, claim, total: money(order.totalCents, order.currency), items: order.items, payUrl: next.url, collectBy: order.collectBy }, await cardFor(shop, order, { claim, rail }));
     }));
     server.registerTool("pay_order", {
         title: "Pay for an order",
@@ -245,24 +340,39 @@ export function createPickupMcpServer(opts) {
             const header = res.headers.get("PAYMENT-REQUIRED");
             const required = (header ? JSON.parse(Buffer.from(header, "base64").toString("utf8")) : await res.json());
             const accept = required.accepts?.[0];
-            return reply(`Waiting for payment: ${usd(accept?.amount)} USDC on ${accept?.network}. No wallet is configured here; ` +
-                `POST the pay link with any x402 client, or set AGENTPICKUP_WALLET_KEY.`, { orderId: args.order_id, payUrl, amount: usd(accept?.amount), network: accept?.network, asset: accept?.asset, payTo: accept?.payTo });
+            // Other ways to finish, for an agent with no wallet of its own (a chat app on the web, say).
+            const { payments } = (await call(shop, "/api/catalog").catch(() => ({ payments: {} })));
+            const others = [
+                ...(payments.square || payments.card ? ['payment "card" gives the user a checkout link to pay on'] : []),
+                ...(payments.test ? ['payment "test" runs the whole flow with no money moving'] : []),
+            ];
+            return reply(`Waiting for payment: ${usd(accept?.amount)} USDC on ${accept?.network}. No wallet is set up in this server: pay the link ` +
+                `from the user's own x402 wallet (such as Coinbase's agent wallet), or set AGENTPICKUP_WALLET_KEY where this server runs.` +
+                (others.length ? ` Or create the order again with create_pickup_order: ${others.join("; ")}.` : ""), { orderId: args.order_id, payUrl, amount: usd(accept?.amount), network: accept?.network, asset: accept?.asset, payTo: accept?.payTo });
         }
         const paid = await opts.payer.pay({ id: args.order_id, payUrl }, doFetch);
-        if (!paid.ok)
-            throw new ToolError(paid.error);
+        if (!paid.ok) {
+            // A demo or test shop can still show the user the whole flow, with a test payment instead.
+            const { payments } = (await call(shop, "/api/catalog").catch(() => ({ payments: {} })));
+            throw new ToolError(paid.error +
+                (payments.test
+                    ? ' This shop also takes test payments, which move no money: call create_pickup_order again with payment "test" to run the whole flow.'
+                    : ""));
+        }
         return reply(`Paid ${paid.amount ?? ""} USDC. Pickup pass: ${paid.passUrl}` +
             (paid.emailedTo ? ` (also emailed to ${paid.emailedTo})` : "") +
             `. The user shows its QR at the counter.`, { orderId: args.order_id, ...paid, ok: undefined });
     }));
     server.registerTool("order_status", {
         title: "Check an order",
-        description: "Whether an order is waiting for payment, paid, ready to collect, collected or expired.",
-        inputSchema: { order_id: z.string(), ...shopArg },
+        description: "Whether an order is waiting for payment, paid, ready to collect, collected or expired. With the order's claim, " +
+            "a paid order's pass comes back too, and the chat's card for it updates.",
+        inputSchema: { order_id: z.string(), claim: claimArg, ...shopArg },
         annotations: { title: "Check an order", readOnlyHint: true, openWorldHint: true },
+        _meta: CARD_TOOL_META,
     }, guarded(async (args) => {
         const shop = await shopFor(args.shop_url);
-        const { order } = (await call(shop, `/api/orders/${encodeURIComponent(args.order_id)}`));
+        const { order, checkoutUrl } = (await call(shop, `/api/orders/${encodeURIComponent(args.order_id)}`));
         const words = {
             awaiting_payment: "is waiting for payment",
             paid: "is paid and being prepared",
@@ -271,22 +381,35 @@ export function createPickupMcpServer(opts) {
             expired: "expired before anyone collected it",
             cancelled: "was cancelled",
         };
-        return reply(`Order ${order.id} ${words[order.status] ?? `is ${order.status}`}.`, order);
+        const pass = args.claim && (order.status === "paid" || order.status === "ready") ? await passByClaim(shop, order.id, args.claim).catch(() => null) : null;
+        return reply(`Order ${order.id} ${words[order.status] ?? `is ${order.status}`}.` + (pass ? ` Pickup code ${pass.pickupCode}, pass at ${pass.passUrl}.` : ""), pass ? { ...order, passUrl: pass.passUrl, pickupCode: pass.pickupCode } : order, await cardFor(shop, order, { claim: args.claim, checkoutUrl }, pass));
     }));
     server.registerTool("get_pickup_pass", {
         title: "Get the pickup pass",
-        description: "The pass link, pickup code and QR content for an order this wallet paid, by signing in with the wallet (Sign-In-With-X).",
-        inputSchema: { order_id: z.string(), ...shopArg },
+        description: "The pass link, pickup code and QR for a paid order: with the claim create_pickup_order returned" +
+            (opts.payer ? ", or by signing in with the wallet that paid (Sign-In-With-X)." : "."),
+        inputSchema: { order_id: z.string(), claim: claimArg, ...shopArg },
         annotations: { title: "Get the pickup pass", readOnlyHint: true, openWorldHint: true },
+        _meta: CARD_TOOL_META,
     }, guarded(async (args) => {
-        if (!opts.payer)
-            throw new ToolError("No wallet is set up here. The pass was emailed to the buyer when the order was paid.");
         const shop = await shopFor(args.shop_url);
-        const res = await opts.payer.signIn(`${shop}/api/orders/${encodeURIComponent(args.order_id)}/pass`, doFetch);
-        if (!res.ok)
-            throw new ToolError(await errorOf(res, `The shop answered ${res.status}.`));
-        const pass = (await res.json());
-        return reply(`Pickup pass: ${pass.passUrl}, pickup code ${pass.pickupCode}.`, pass);
+        let pass;
+        if (args.claim) {
+            pass = await passByClaim(shop, args.order_id, args.claim);
+            if (!pass)
+                throw new ToolError("This order isn't paid yet, so there's no pass. order_status says where it's at.");
+        }
+        else if (opts.payer) {
+            const res = await opts.payer.signIn(`${shop}/api/orders/${encodeURIComponent(args.order_id)}/pass`, doFetch);
+            if (!res.ok)
+                throw new ToolError(await errorOf(res, `The shop answered ${res.status}.`));
+            pass = (await res.json());
+        }
+        else {
+            throw new ToolError("Send the claim create_pickup_order returned with the order. The pass is also in the email the shop sent when it was paid.");
+        }
+        await shopName(shop);
+        return reply(`Pickup pass: ${pass.passUrl}, pickup code ${pass.pickupCode}. The user shows the QR at the counter, or says the code.`, { passUrl: pass.passUrl, pickupCode: pass.pickupCode, qrContent: pass.qrContent, status: pass.order?.status }, pass.order ? await cardFor(shop, pass.order, { claim: args.claim }, pass) : undefined);
     }));
     const closesIn = (g) => {
         const minutes = Math.max(0, Math.round((g.closesAt - Date.now()) / 60_000));

package/package.json

@@ -1,62 +1,63 @@
-{
-  "name": "@agentpickup/mcp",
-  "version": "0.3.2",
-  "description": "MCP server for agentPickup: let an AI agent find pickup shops near its user, order, pay by card or in USDC over x402, and hand its user the QR to collect in person.",
-  "mcpName": "io.github.dav3trad3r/agentpickup",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "agentpickup-mcp": "dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "source": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "LICENSE.md",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=22.13"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "x402",
-    "agentic-commerce",
-    "agent-payments",
-    "click-and-collect",
-    "pickup"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Tokenise-au/agentpickup-sdk.git",
-    "directory": "packages/mcp"
-  },
-  "homepage": "https://agentpickup.app",
-  "bugs": {
-    "url": "https://github.com/Tokenise-au/agentpickup-sdk/issues"
-  },
-  "author": "Dave Hallett",
-  "license": "FSL-1.1-ALv2",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.2",
-    "@x402/core": "2.29.0",
-    "@x402/evm": "2.29.0",
-    "@x402/extensions": "2.29.0",
-    "viem": "^2.57.14",
-    "zod": "^4.6.7"
-  }
-}
+{
+  "name": "@agentpickup/mcp",
+  "version": "0.4.0",
+  "description": "MCP server for agentPickup: let an AI agent find pickup shops near its user, order, pay by card or in USDC over x402, and hand its user the QR to collect in person.",
+  "mcpName": "io.github.dav3trad3r/agentpickup",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agentpickup-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "agentic-commerce",
+    "agent-payments",
+    "click-and-collect",
+    "pickup"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tokenise-au/agentpickup-sdk.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://agentpickup.app",
+  "bugs": {
+    "url": "https://github.com/Tokenise-au/agentpickup-sdk/issues"
+  },
+  "author": "Dave Hallett",
+  "license": "FSL-1.1-ALv2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@x402/core": "2.29.0",
+    "@x402/evm": "2.29.0",
+    "@x402/extensions": "2.29.0",
+    "qrcode": "^1.5.4",
+    "viem": "^2.57.14",
+    "zod": "^4.6.7"
+  }
+}