@agentpickup/mcp 0.2.0 → 0.3.0

package/README.md

@@ -14,6 +14,10 @@ show at the counter to collect.
 | `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 |
 | `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) |
+| `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 |
 
 ## Use it
 

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.2.0";
+export declare const VERSION = "0.3.0";
 export interface PickupMcpOptions {
     /** The agentPickup shop this server orders from. */
     shopUrl: string;
@@ -11,6 +11,11 @@ export interface PickupMcpOptions {
     allowOtherShops?: boolean;
     /** An agentPickup directory (<host>/directory/v1/shops). Adds find_shops: shops near someone that sell what they want. */
     directoryUrl?: string;
+    /**
+     * Shops on other hosts a hosted server may still order from, such as agentPickup shops its directory has checked.
+     * Called with the shop's base URL.
+     */
+    trustedShop?: (shopBase: string) => boolean | Promise<boolean>;
     /** How requests reach the shop. Defaults to global fetch; a shop hosting its own server passes its app's fetch. */
     fetch?: Fetch;
     /** The wallet that pays. Without one, pay_order returns the price and pay link for another x402 client. */

package/dist/server.js

@@ -4,7 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
 import { errorOf, usd } from "./wallet.js";
-export const VERSION = "0.2.0";
+export const VERSION = "0.3.0";
 class ToolError extends Error {
 }
 const INSTRUCTIONS = `agentPickup lets you buy things online for the user to collect in person.
@@ -13,7 +13,10 @@ const INSTRUCTIONS = `agentPickup lets you buy things online for the user to col
 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. 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.`;
+get_pickup_pass fetches the pass again later; order_status says whether it's ready or collected.
+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) => ({
     content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(data, null, 2)}` }],
@@ -28,7 +31,7 @@ export function createPickupMcpServer(opts) {
     const homeUrl = new URL(opts.shopUrl);
     const home = shopBase(homeUrl);
     const doFetch = opts.fetch ?? ((req) => fetch(req));
-    function shopFor(shopUrl) {
+    async function shopFor(shopUrl) {
         if (!shopUrl)
             return home;
         let url;
@@ -41,11 +44,14 @@ export function createPickupMcpServer(opts) {
         // Shops on this server's own host: the home shop and its venues.
         if (url.origin === homeUrl.origin)
             return shopBase(url);
-        if (!opts.allowOtherShops)
-            throw new ToolError(`This server orders from shops on ${homeUrl.origin} only.`);
-        if (url.protocol !== "https:" && url.hostname !== "localhost")
-            throw new ToolError("Shops must be served over https.");
-        return shopBase(url);
+        if (opts.allowOtherShops || opts.trustedShop) {
+            if (url.protocol !== "https:" && url.hostname !== "localhost")
+                throw new ToolError("Shops must be served over https.");
+            if (opts.allowOtherShops || (await opts.trustedShop(shopBase(url))))
+                return shopBase(url);
+            throw new ToolError(`This server orders from shops on ${homeUrl.origin} and agentPickup shops its directory lists.`);
+        }
+        throw new ToolError(`This server orders from shops on ${homeUrl.origin} only.`);
     }
     async function call(shop, path, init) {
         const res = await doFetch(new Request(`${shop}${path}`, init));
@@ -105,6 +111,8 @@ export function createPickupMcpServer(opts) {
                     s.distanceKm !== undefined ? `${s.distanceKm} km` : null,
                     s.openNow === true ? "open now" : s.openNow === false ? "closed now" : null,
                     s.testOnly ? "test shop, no real money" : null,
+                    s.source?.kind === "listed" ? `listed by ${s.source.domain}` : null,
+                    s.order?.via === "ucp" ? "orders through its UCP checkout" : s.order?.via === "web" ? "orders on its own website" : null,
                 ].filter(Boolean);
                 const items = s.items.slice(0, 3).map((i) => `${i.name} ${money(i.priceCents, s.currency)}`).join(", ");
                 return `- ${s.name}${facts.length ? ` (${facts.join(", ")})` : ""}${s.location.address ? `, ${s.location.address}` : ""}${items ? `: ${items}` : ""}`;
@@ -118,6 +126,10 @@ export function createPickupMcpServer(opts) {
                     openNow: s.openNow,
                     testOnly: s.testOnly,
                     payments: { x402: s.payments.x402?.network ?? null, test: s.payments.test },
+                    listedBy: s.source?.kind === "listed" ? s.source.domain : null,
+                    // agentpickup: use get_shop and create_pickup_order. ucp or web: order there instead.
+                    orderVia: s.order?.via ?? "agentpickup",
+                    ...(s.order?.via === "ucp" ? { ucpProfile: s.order.profile } : s.order?.via === "web" ? { orderUrl: s.order.url } : {}),
                     items: s.items.map((i) => ({ id: i.id, name: i.name, price: money(i.priceCents, s.currency) })),
                     moreItems: Math.max(0, s.itemCount - s.items.length),
                 })),
@@ -130,7 +142,7 @@ export function createPickupMcpServer(opts) {
         inputSchema: { ...shopArg },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, guarded(async (args) => {
-        const shop = shopFor(args.shop_url);
+        const shop = await shopFor(args.shop_url);
         const data = await call(shop, "/api/catalog");
         const merchant = data.merchant;
         const currency = String(data.currency ?? "usd");
@@ -141,33 +153,47 @@ export function createPickupMcpServer(opts) {
             description: i.description,
         }));
         const payments = data.payments;
+        const cards = Boolean(payments.square || payments.card);
+        const ways = [
+            ...(payments.x402 ? [`USDC over x402 on ${payments.x402.network}, paid by the agent`] : []),
+            ...(cards ? ["cards, paid by the user on a checkout link"] : []),
+            ...(payments.test ? ["test payments, with no money moving"] : []),
+        ];
         return reply(`${merchant.name}${merchant.location?.name ? `, collect at ${merchant.location.name}` : ""}. ` +
-            (payments.x402
-                ? `Takes USDC over x402 on ${payments.x402.network}.`
-                : payments.test
+            (!ways.length
+                ? "Doesn't take agent payments."
+                : ways.length === 1 && payments.test
                     ? "A test shop: orders are marked paid without money moving."
-                    : "Doesn't take agent payments."), { shop, merchant: merchant.name, location: merchant.location, currency, items, x402: payments.x402 ?? null, test: Boolean(payments.test) });
+                    : `Takes ${ways.join("; ")}.`), { shop, merchant: merchant.name, location: merchant.location, currency, items, x402: payments.x402 ?? null, cards, test: Boolean(payments.test) });
     }));
     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.",
+            "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.",
         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."),
             name: z.string().max(100).optional().describe("Name for the order, shown to staff"),
+            payment: z
+                .enum(["agent", "card"])
+                .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."),
             ...shopArg,
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, guarded(async (args) => {
-        const shop = shopFor(args.shop_url);
-        // Pay over x402 where the shop takes it; a test shop marks the order paid straight away.
+        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 rail = payments.x402 ? "x402" : payments.test ? "test" : null;
+        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("This shop doesn't take agent payments.");
+            throw new ToolError(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" },
@@ -179,6 +205,10 @@ export function createPickupMcpServer(opts) {
             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 });
         }
+        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}: ${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 });
     }));
@@ -190,7 +220,15 @@ export function createPickupMcpServer(opts) {
         inputSchema: { order_id: z.string(), ...shopArg },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, guarded(async (args) => {
-        const shop = shopFor(args.shop_url);
+        const shop = await shopFor(args.shop_url);
+        const status = (await call(shop, `/api/orders/${encodeURIComponent(args.order_id)}`));
+        if (status.order.rail === "square" || status.order.rail === "card") {
+            if (status.order.status !== "awaiting_payment")
+                return reply(`Order ${args.order_id} is already paid (${status.order.status}).`, { orderId: args.order_id, status: status.order.status });
+            return reply(status.checkoutUrl
+                ? `This order is paid by card: give the user ${status.checkoutUrl} to pay on.`
+                : "This order is paid by card, on the checkout link create_pickup_order returned.", { orderId: args.order_id, payBy: "card", checkoutUrl: status.checkoutUrl ?? null });
+        }
         const payUrl = `${shop}/api/orders/${encodeURIComponent(args.order_id)}/pay`;
         if (!opts.payer) {
             const res = await doFetch(new Request(payUrl, { method: "POST" }));
@@ -216,7 +254,7 @@ export function createPickupMcpServer(opts) {
         inputSchema: { order_id: z.string(), ...shopArg },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, guarded(async (args) => {
-        const shop = shopFor(args.shop_url);
+        const shop = await shopFor(args.shop_url);
         const { order } = (await call(shop, `/api/orders/${encodeURIComponent(args.order_id)}`));
         const words = {
             awaiting_payment: "is waiting for payment",
@@ -236,13 +274,97 @@ export function createPickupMcpServer(opts) {
     }, 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 = shopFor(args.shop_url);
+        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);
     }));
+    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";
+    };
+    const groupSummary = (g) => {
+        const paid = g.members.filter((m) => m.status !== "awaiting_payment" && m.status !== "cancelled");
+        return `${g.title} (code ${g.code}), ${closesIn(g)}: ${paid.length} of ${g.members.length} paid, ${money(g.paidCents, g.currency)} so far.`;
+    };
+    server.registerTool("start_group_order", {
+        title: "Start a group order",
+        description: "Start a group order (a coffee run) at a shop. Returns a code to share: each person's agent joins with it and pays for " +
+            "their own items. When it closes, the shop gets one combined order and the organiser is emailed its pickup QR.",
+        inputSchema: {
+            organiser_name: z.string().min(1).max(60).describe("Who collects, shown to staff"),
+            organiser_email: z.string().email().describe("Where the group's pickup QR goes"),
+            title: z.string().max(60).optional().describe('e.g. "Friday coffee run"'),
+            closes_in_minutes: z.number().int().min(5).max(240).optional().describe("Default 15"),
+            ...shopArg,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, guarded(async (args) => {
+        const shop = await shopFor(args.shop_url);
+        const data = (await call(shop, "/api/groups", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ name: args.organiser_name, email: args.organiser_email, title: args.title, closesInMinutes: args.closes_in_minutes }),
+        }));
+        return reply(`Started ${data.group.title}: share code ${data.group.code}. Everyone's agent joins with join_group_order and the code; it ${closesIn(data.group)}. ` +
+            `Keep organiser_key to close it early.`, { shop, code: data.group.code, closesAt: data.group.closesAt, organiser_key: data.organiserKey });
+    }));
+    server.registerTool("join_group_order", {
+        title: "Join a group order",
+        description: "Add the user's items to a group order with its code. Returns the order id; pay it with pay_order before the group closes. " +
+            "The organiser collects everything, so the user gets a receipt, not a QR.",
+        inputSchema: {
+            code: z.string().min(4).max(12).describe("The group's code"),
+            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, for their receipt"),
+            name: z.string().min(1).max(60).describe("The user's name, shown to staff on their items"),
+            ...shopArg,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, guarded(async (args) => {
+        const shop = await shopFor(args.shop_url);
+        const { payments } = (await call(shop, "/api/catalog"));
+        const rail = payments.x402 ? "x402" : payments.test ? "test" : null;
+        if (!rail)
+            throw new ToolError("This shop doesn't take agent payments.");
+        const data = (await call(shop, `/api/groups/${encodeURIComponent(args.code)}/orders`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ items: args.items, email: args.email, name: args.name, rail }),
+        }));
+        const what = `${data.order.items.map((i) => `${i.qty}× ${i.name}`).join(", ")}, ${money(data.order.totalCents, data.order.currency)}`;
+        return reply(rail === "test"
+            ? `Added to ${data.group.title}: ${what}, paid with a test payment (no money moved). ${data.group.organiser} collects it.`
+            : `Added to ${data.group.title}: ${what}. Confirm with the user, then pay it with pay_order (order ${data.order.id}) before the group closes.`, { shop, orderId: data.order.id, group: groupSummary(data.group), payUrl: data.next.url ?? null, test: rail === "test" });
+    }));
+    server.registerTool("group_order_status", {
+        title: "Check a group order",
+        description: "Who's in a group order, what they ordered, who has paid, and whether it has closed and been collected.",
+        inputSchema: { code: z.string().min(4).max(12), ...shopArg },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guarded(async (args) => {
+        const shop = await shopFor(args.shop_url);
+        const { group } = (await call(shop, `/api/groups/${encodeURIComponent(args.code)}`));
+        return reply(groupSummary(group) + (group.combined ? ` The shop's order is ${group.combined.status}.` : ""), group);
+    }));
+    server.registerTool("close_group_order", {
+        title: "Close a group order now",
+        description: "Close a group order early, as its organiser. Unpaid shares are left out; the shop gets the rest as one order.",
+        inputSchema: { code: z.string().min(4).max(12), organiser_key: z.string().min(8), ...shopArg },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guarded(async (args) => {
+        const shop = await shopFor(args.shop_url);
+        const { group } = (await call(shop, `/api/groups/${encodeURIComponent(args.code)}/close`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ organiserKey: args.organiser_key }),
+        }));
+        return reply(group.status === "sent"
+            ? `Closed: ${groupSummary(group)} The shop has the combined order, and ${group.organiser}'s pickup QR is on its way by email.`
+            : `Closed with nobody paid, so the group order was cancelled.`, group);
+    }));
     return server;
 }
 /** A Streamable HTTP endpoint (stateless, JSON responses) for hosting the server, e.g. at /mcp. */

package/package.json

@@ -1,62 +1,62 @@
-{
-  "name": "@agentpickup/mcp",
-  "version": "0.2.0",
-  "description": "MCP server for agentPickup: let an AI agent find pickup shops near its user, order, pay 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/dav3trad3r/agentpickup.git",
-    "directory": "packages/mcp"
-  },
-  "homepage": "https://agentpickup.app",
-  "bugs": {
-    "url": "https://github.com/dav3trad3r/agentpickup/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.3.0",
+  "description": "MCP server for agentPickup: let an AI agent find pickup shops near its user, order, pay 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/dav3trad3r/agentpickup.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://agentpickup.app",
+  "bugs": {
+    "url": "https://github.com/dav3trad3r/agentpickup/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"
+  }
+}