@agentpickup/mcp 0.3.2 → 0.3.3

package/README.md

@@ -62,6 +62,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/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.3.3";
 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

@@ -4,15 +4,17 @@ 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.3.2";
+export const VERSION = "0.3.3";
 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.
+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. 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.
 Group orders (a coffee run): start_group_order gives a code to share; each person's agent calls join_group_order and
@@ -80,7 +82,7 @@ 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 });
     if (opts.directoryUrl) {
         const directoryUrl = opts.directoryUrl;
         server.registerTool("find_shops", {
@@ -185,9 +187,10 @@ export function createPickupMcpServer(opts) {
             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"])
+                .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 },
@@ -198,9 +201,15 @@ export function createPickupMcpServer(opts) {
         const { payments } = (await call(shop, "/api/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" },
@@ -245,12 +254,25 @@ 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 });

package/package.json

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