@agentpickup/mcp 0.3.1 → 0.3.3

package/README.md

@@ -1,6 +1,6 @@
 # @agentpickup/mcp
 
-An MCP server for [agentPickup](https://github.com/dav3trad3r/agentpickup) shops. It lets an AI agent find
+An MCP server for [agentPickup](https://agentpickup.app) shops. It lets an AI agent find
 pickup shops near its user, see what they sell, order, pay by card or in USDC over x402, and hand its user the
 QR they show at the counter to collect.
 
@@ -10,8 +10,8 @@ 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 |
-| `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 |
+| `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 |
+| `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) |
 | `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 |
@@ -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.1";
+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.1";
+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
@@ -74,7 +76,13 @@ export function createPickupMcpServer(opts) {
     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}.`) }
         : {};
-    const server = new McpServer({ name: "agentpickup", title: "agentPickup", version: VERSION }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({
+        name: "agentpickup",
+        title: "agentPickup",
+        version: VERSION,
+        websiteUrl: "https://agentpickup.app",
+        icons: [{ src: "https://agentpickup.app/logo.png", mimeType: "image/png", sizes: ["1024x1024"] }],
+    }, { instructions: opts.instructions ? `${INSTRUCTIONS}\n${opts.instructions}` : INSTRUCTIONS });
     if (opts.directoryUrl) {
         const directoryUrl = opts.directoryUrl;
         server.registerTool("find_shops", {
@@ -90,7 +98,7 @@ export function createPickupMcpServer(opts) {
                 open_now: z.boolean().optional().describe("Only shops open now (shops without listed hours stay in)."),
                 limit: z.number().int().min(1).max(50).optional(),
             },
-            annotations: { readOnlyHint: true, openWorldHint: true },
+            annotations: { title: "Find pickup shops", readOnlyHint: true, openWorldHint: true },
         }, guarded(async (args) => {
             if ((args.lat === undefined) !== (args.lng === undefined))
                 throw new ToolError("Send lat and lng together.");
@@ -141,7 +149,7 @@ export function createPickupMcpServer(opts) {
         title: "See what a shop sells",
         description: "What the shop sells (item ids and prices), where to collect, and which payments it takes.",
         inputSchema: { ...shopArg },
-        annotations: { readOnlyHint: true, openWorldHint: true },
+        annotations: { title: "See what a shop sells", readOnlyHint: true, openWorldHint: true },
     }, guarded(async (args) => {
         const shop = await shopFor(args.shop_url);
         const data = await call(shop, "/api/catalog");
@@ -179,12 +187,13 @@ 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: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { title: "Order for pickup", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, 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
@@ -192,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" },
@@ -219,7 +234,7 @@ export function createPickupMcpServer(opts) {
             ? `Pay an order in USDC over x402 from wallet ${opts.payer.address}. This spends money: confirm the items and total with the user first. Returns the pickup pass link.`
             : "No wallet is set up here, so this returns the price and pay link for another x402 client to pay.",
         inputSchema: { order_id: z.string(), ...shopArg },
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { title: "Pay for an order", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, guarded(async (args) => {
         const shop = await shopFor(args.shop_url);
         const status = (await call(shop, `/api/orders/${encodeURIComponent(args.order_id)}`));
@@ -239,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 });
@@ -253,7 +281,7 @@ export function createPickupMcpServer(opts) {
         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 },
-        annotations: { readOnlyHint: true, openWorldHint: true },
+        annotations: { title: "Check an order", readOnlyHint: true, openWorldHint: true },
     }, guarded(async (args) => {
         const shop = await shopFor(args.shop_url);
         const { order } = (await call(shop, `/api/orders/${encodeURIComponent(args.order_id)}`));
@@ -271,7 +299,7 @@ export function createPickupMcpServer(opts) {
         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 },
-        annotations: { readOnlyHint: true, openWorldHint: true },
+        annotations: { title: "Get the pickup pass", readOnlyHint: true, openWorldHint: true },
     }, 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.");
@@ -301,7 +329,7 @@ export function createPickupMcpServer(opts) {
             closes_in_minutes: z.number().int().min(5).max(240).optional().describe("Default 15"),
             ...shopArg,
         },
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { title: "Start a group order", 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", {
@@ -323,7 +351,7 @@ export function createPickupMcpServer(opts) {
             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 },
+        annotations: { title: "Join a group order", 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"));
@@ -344,7 +372,7 @@ export function createPickupMcpServer(opts) {
         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 },
+        annotations: { title: "Check a group order", readOnlyHint: true, openWorldHint: true },
     }, guarded(async (args) => {
         const shop = await shopFor(args.shop_url);
         const { group } = (await call(shop, `/api/groups/${encodeURIComponent(args.code)}`));
@@ -354,7 +382,7 @@ export function createPickupMcpServer(opts) {
         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 },
+        annotations: { title: "Close a group order now", 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`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpickup/mcp",
-  "version": "0.3.1",
+  "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",
@@ -39,12 +39,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dav3trad3r/agentpickup.git",
+    "url": "git+https://github.com/Tokenise-au/agentpickup-sdk.git",
     "directory": "packages/mcp"
   },
   "homepage": "https://agentpickup.app",
   "bugs": {
-    "url": "https://github.com/dav3trad3r/agentpickup/issues"
+    "url": "https://github.com/Tokenise-au/agentpickup-sdk/issues"
   },
   "author": "Dave Hallett",
   "license": "FSL-1.1-ALv2",