@agentpickup/mcp 0.4.0 → 0.4.1

package/README.md

@@ -17,6 +17,7 @@ QR they show at the counter to collect.
 | `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 |
+| `share_agentpickup` | A QR and link for friends to add agentPickup to their assistant (as a card where the chat shows cards), for everyone or with one café picked |
 | `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
@@ -26,7 +27,8 @@ among them), `create_pickup_order`, `order_status` and `get_pickup_pass` show th
 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.
+either way. The card's "Invite a friend" link, and `share_agentpickup`'s own card, point at the add page
+(`addPageUrl`, default https://agentpickup.app/add) so friends can add it too.
 
 ## Use it
 

package/dist/card.d.ts

@@ -20,6 +20,8 @@ export interface PassCard {
     pickupCode?: string | null;
     /** The QR as SVG, ink on transparent, so the tile behind it sets the colour. */
     qrSvg?: string;
+    /** The add page's share mode, for "Invite a friend". */
+    inviteUrl?: 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

@@ -54,7 +54,8 @@ body{font-family:var(--font-sans,ui-sans-serif,system-ui,-apple-system,"Segoe UI
 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}
+.foot{font-size:11px;color:var(--muted);margin-top:12px;display:flex;justify-content:space-between;align-items:center;gap:8px}
+.foot button.link{font-size:12px}
 @media (prefers-reduced-motion:reduce){.pour{transition:none}.wrap.ready::after{animation:none;opacity:1}}
 </style>
 </head>
@@ -221,7 +222,7 @@ button.link{background:none;border:none;padding:0;color:var(--muted);text-decora
     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>';
+    h += '<div class="foot">' + (s.inviteUrl ? '<button class="link" data-open="inviteUrl">Invite a friend</button>' : "<span></span>") + "<span>agentPickup</span></div></div>";
     return h;
   }
   function render() {

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.4.0";
+export declare const VERSION = "0.4.1";
 export interface PickupMcpOptions {
     /** The agentPickup shop this server orders from. */
     shopUrl: string;
@@ -22,6 +22,11 @@ export interface PickupMcpOptions {
     payer?: Payer;
     /** Notes added to the instructions agents read on connecting, e.g. which of this host's shops take what. */
     instructions?: string;
+    /**
+     * The page where people add agentPickup to their assistant, which share_agentpickup and the pass card's
+     * "Invite a friend" link point to. Default https://agentpickup.app/add.
+     */
+    addPageUrl?: 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

@@ -5,11 +5,14 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import QRCode from "qrcode";
 import { z } from "zod";
 import { CARD_META_KEY, CARD_MIME_TYPE, passCardHtml } from "./card.js";
+import { SHARE_META_KEY, shareCardHtml } from "./share-card.js";
 import { errorOf, usd } from "./wallet.js";
-export const VERSION = "0.4.0";
+export const VERSION = "0.4.1";
 // 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 };
+const SHARE_URI = `ui://agentpickup/share-${VERSION}.html`;
+const SHARE_TOOL_META = { ui: { resourceUri: SHARE_URI }, "ui/resourceUri": SHARE_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();
@@ -20,6 +23,8 @@ const rememberShop = (shop, name) => {
         shopNames.clear();
     shopNames.set(shop, name);
 };
+/** A shop's name as the add page's ?shop= matches it: "Demo Café" -> "demo-cafe". */
+const slugOf = (name) => name.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 /** 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 {
@@ -37,6 +42,7 @@ const INSTRUCTIONS = `agentPickup lets you buy things online for the user to col
    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.
+share_agentpickup: when the user asks how to share agentPickup or get friends using it, shows a QR and link.
 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.`;
@@ -123,10 +129,22 @@ export function createPickupMcpServer(opts) {
             total: money(order.totalCents, order.currency),
             collectBy: order.collectBy,
             collectedAt: order.collectedAt ?? null,
+            inviteUrl: addLinks(shop).sharePageUrl,
             ...extra,
             ...(pass ? { passUrl: pass.passUrl, pickupCode: pass.pickupCode, qrSvg: await qrSvg(pass.qrContent) } : {}),
         };
     }
+    /** The add page for sharing: for one of this host's shops when given (?shop=<slug>), else everyone's. */
+    const addPage = (opts.addPageUrl ?? "https://agentpickup.app/add").replace(/\/$/, "");
+    function addLinks(shop) {
+        let slug = "";
+        if (shop) {
+            const u = new URL(shop);
+            slug = u.pathname.match(/\/v\/([^/]+)/)?.[1] ?? (u.pathname === "/" || u.pathname === "" ? slugOf(shopNames.get(shop) ?? "") : "");
+        }
+        const q = slug ? `shop=${encodeURIComponent(slug)}` : "";
+        return { url: `${addPage}${q ? `?${q}` : ""}`, sharePageUrl: `${addPage}?share=1${q ? `&${q}` : ""}` };
+    }
     const claimArg = z
         .string()
         .max(200)
@@ -411,6 +429,43 @@ export function createPickupMcpServer(opts) {
         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);
     }));
+    // ---------- sharing ----------
+    server.registerResource("share-agentpickup", SHARE_URI, {
+        title: "Share agentPickup",
+        description: "A QR and link for friends to add agentPickup to their assistant.",
+        mimeType: CARD_MIME_TYPE,
+        _meta: { ui: { prefersBorder: false } },
+    }, async () => ({
+        contents: [{ uri: SHARE_URI, mimeType: CARD_MIME_TYPE, text: shareCardHtml(VERSION), _meta: { ui: { prefersBorder: false } } }],
+    }));
+    server.registerTool("share_agentpickup", {
+        title: "Share agentPickup",
+        description: "A QR code and link the user can share so friends can add agentPickup to Claude, ChatGPT or Grok and order too. " +
+            "Use when the user asks how to share agentPickup, invite friends, or get others using it. Name a shop to share it with that café picked.",
+        inputSchema: { ...shopArg },
+        annotations: { title: "Share agentPickup", readOnlyHint: true, openWorldHint: false },
+        _meta: SHARE_TOOL_META,
+    }, guarded(async (args) => {
+        const shop = args.shop_url ? await shopFor(args.shop_url) : undefined;
+        const name = shop ? await shopName(shop) : undefined;
+        const links = addLinks(shop);
+        const card = {
+            v: 1,
+            ...links,
+            qrSvg: await QRCode.toString(links.url, { type: "svg", errorCorrectionLevel: "M", margin: 0, color: { dark: "#0a0b0dff", light: "#00000000" } }),
+            ...(name ? { shopName: name } : {}),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Share this link: ${links.url}. A friend opens it (or scans its QR off the user's screen), adds agentPickup to Claude, ChatGPT or Grok, ` +
+                        `then just asks for their usual${name ? ` at ${name}` : ""}. ${links.sharePageUrl} opens the phone's share sheet and has a sticker to print.`,
+                },
+            ],
+            _meta: { [SHARE_META_KEY]: card },
+        };
+    }));
     const closesIn = (g) => {
         const minutes = Math.max(0, Math.round((g.closesAt - Date.now()) / 60_000));
         return g.status === "open" ? `closes in ${minutes} min` : g.status === "sent" ? "closed and sent to the shop" : "cancelled";

package/dist/share-card.d.ts

@@ -0,0 +1,13 @@
+export declare const SHARE_META_KEY = "agentpickup/share";
+export interface ShareCard {
+    v: 1;
+    /** The add page, maybe for one café (?shop=). */
+    url: string;
+    /** The add page's share mode: the share sheet and the sticker. */
+    sharePageUrl: string;
+    /** The QR as SVG, ink on transparent, for the white tile. */
+    qrSvg: string;
+    /** A café to name, when the link is for one. */
+    shopName?: string;
+}
+export declare function shareCardHtml(version: string): string;

package/dist/share-card.js

@@ -0,0 +1,142 @@
+// The share card (MCP Apps): what share_agentpickup shows when someone asks how to get friends using agentPickup.
+// The counter sticker as a card: a QR to the add page that a friend scans off the screen, the link to copy, and
+// buttons that open the add page's share mode (the phone's share sheet, and the printable sticker). Self-contained,
+// like the pass card: no scripts, fonts or images from anywhere else, and the same small MCP Apps bridge.
+export const SHARE_META_KEY = "agentpickup/share";
+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>Share agentPickup</title>
+<style>
+:root{--bg:#0a0b0d;--text:#eef0f3;--muted:#b7bdc6;--dim:#8b929c;--line:#2a2f36;--lime:#b5f23d;--ink:#0a0b0d}
+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);padding:2px;-webkit-font-smoothing:antialiased}
+.card{box-sizing:border-box;max-width:420px;margin:0 auto;background:var(--bg);color:var(--text);border-radius:18px;padding:20px 20px 16px}
+.top{display:flex;align-items:center;gap:8px;font-weight:700;font-size:15px}
+.top svg{width:22px;height:22px;border-radius:5px}
+.top .dim{color:var(--dim)}
+h1{margin:14px 0 0;font-size:34px;line-height:.95;font-weight:850;letter-spacing:-.02em;text-transform:uppercase}
+h1 em{font-style:normal;color:var(--lime)}
+.sub{margin:8px 0 0;color:var(--muted);font-size:15px}
+.row{display:flex;gap:16px;align-items:flex-end;margin-top:16px}
+.tile{background:#fff;border-radius:14px;padding:12px;width:156px;height:156px;flex:none;box-sizing:border-box}
+.tile svg{display:block;width:100%;height:100%}
+ol{list-style:none;margin:0;padding:0;counter-reset:n;color:var(--muted);font-size:15px}
+li{counter-increment:n;margin:0 0 8px;display:flex;align-items:center;gap:8px}
+li::before{content:counter(n);width:22px;height:22px;border-radius:50%;border:1.5px solid var(--line);display:inline-flex;align-items:center;justify-content:center;font:600 12px ui-monospace,Menlo,monospace;color:var(--lime);flex:none}
+.link{margin-top:14px;display:flex;gap:8px;align-items:center}
+.link code{flex:1;min-width:0;overflow-wrap:anywhere;font:13px ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--text);background:#16191d;border:1px solid var(--line);border-radius:10px;padding:9px 10px;user-select:all;-webkit-user-select:all}
+button{font-weight:600;font-size:14px;font-family:inherit;border-radius:10px;padding:10px 14px;cursor:pointer;border:1px solid var(--line);background:transparent;color:var(--text);white-space:nowrap}
+button.lime{background:var(--lime);color:var(--ink);border-color:var(--lime)}
+.actions{display:flex;gap:8px;margin-top:10px;flex-wrap:wrap}
+.actions button{flex:1}
+.note{margin:10px 0 0;font-size:12px;color:var(--dim)}
+@media (max-width:360px){.row{flex-direction:column;align-items:flex-start}}
+</style>
+</head>
+<body>
+<div id="root"></div>
+<script>
+(function () {
+  var VERSION = "__VERSION__";
+  var root = document.getElementById("root");
+  var state = null, canOpen = false, nextId = 1, pending = {}, lastHeight = -1;
+  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; }
+    if (m.method === "ui/resource-teardown" && m.id != null) return send({ jsonrpc: "2.0", id: m.id, result: {} });
+    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) {
+    var vars = ctx.styles && ctx.styles.variables;
+    if (vars && typeof vars["--font-sans"] === "string") document.documentElement.style.setProperty("--font-sans", vars["--font-sans"]);
+  }
+  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");
+  }
+  function onResult(result) {
+    var data = result && result._meta && result._meta["agentpickup/share"];
+    if (data && data.url) state = data;
+    render();
+  }
+  function esc(s) { return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) { return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]; }); }
+  function safeSvg(svg) { return typeof svg === "string" && /^<svg[\s>]/.test(svg) && !/<script|<foreignObject|\son[a-z]+=/i.test(svg) ? svg : ""; }
+  function copy(text, button) {
+    var done = function () { button.textContent = "Copied"; setTimeout(function () { button.textContent = "Copy"; }, 1600); };
+    try {
+      if (navigator.clipboard && navigator.clipboard.writeText) return navigator.clipboard.writeText(text).then(done, function () { select(); });
+    } catch (e) {}
+    select();
+  }
+  function select() {
+    var code = document.getElementById("url");
+    if (!code || !window.getSelection) return;
+    var range = document.createRange();
+    range.selectNodeContents(code);
+    var sel = window.getSelection();
+    sel.removeAllRanges();
+    sel.addRange(range);
+  }
+  function render() {
+    if (!state) { root.innerHTML = ""; return reportSize(); }
+    var svg = safeSvg(state.qrSvg);
+    var shown = state.url.replace(/^https?:\/\//, "");
+    root.innerHTML =
+      '<div class="card">' +
+      '<div class="top"><svg viewBox="0 0 32 32" aria-hidden="true"><rect width="32" height="32" fill="#16191d"/><rect x="7" y="7" width="7" height="7" rx="1.5" fill="#fff"/><rect x="18" y="7" width="7" height="7" rx="1.5" fill="#fff"/><rect x="7" y="18" width="7" height="7" rx="1.5" fill="#fff"/><path d="M18.5 21.5l2.5 2.5 4.5-5" fill="none" stroke="#b5f23d" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/></svg><span><span class="dim">agent</span>Pickup</span></div>' +
+      "<h1>" + (state.shopName ? "Order from " + esc(state.shopName) + "<br>with your <em>AI</em>" : "Order ahead<br>from your <em>AI</em>") + "</h1>" +
+      '<p class="sub">Claude, ChatGPT or Grok</p>' +
+      '<div class="row">' + (svg ? '<div class="tile">' + svg.replace("<svg", '<svg role="img" aria-label="QR code to add agentPickup"') + "</div>" : "") +
+      "<ol><li>Scan</li><li>Add agentPickup</li><li>Ask for your usual</li></ol></div>" +
+      '<div class="link"><code id="url">' + esc(shown) + '</code><button type="button" id="copy">Copy</button></div>' +
+      '<div class="actions"><button class="lime" type="button" id="share">Share</button><button type="button" id="sticker">Get the sticker</button></div>' +
+      '<p class="note">A friend scans the QR off your screen, or you send them the link.</p>' +
+      "</div>";
+    document.getElementById("copy").addEventListener("click", function (e) { copy(state.url, e.currentTarget); });
+    document.getElementById("share").addEventListener("click", function () { openLink(state.sharePageUrl); });
+    document.getElementById("sticker").addEventListener("click", function () { openLink(state.sharePageUrl + (state.sharePageUrl.indexOf("?") >= 0 ? "&" : "?") + "sticker=1"); });
+    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);
+  request("ui/initialize", { appInfo: { name: "agentpickup-share", version: VERSION }, appCapabilities: {}, protocolVersion: "2026-01-26" })
+    .then(function (r) {
+      canOpen = Boolean(r && r.hostCapabilities && r.hostCapabilities.openLinks);
+      applyContext((r && r.hostContext) || {});
+      notify("ui/notifications/initialized", {});
+      render();
+    }, function () { render(); });
+})();
+</script>
+</body>
+</html>`;
+export function shareCardHtml(version) {
+    return PAGE.replace("__VERSION__", version);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpickup/mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",