@agentpickup/mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,63 +1,65 @@
-# @agentpickup/mcp
-
-An MCP server for [agentPickup](https://github.com/dav3trad3r/agentpickup) shops. It lets an AI agent see
-what a shop sells, order it, pay in USDC over x402, and hand its user the QR they show at the counter to
-collect.
-
-## Tools
-
-| Tool | What it does |
-|---|---|
-| `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 pickup QR |
-| `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) |
-
-## Use it
-
-Try it against the hosted demo shop first. It pays with the demo's own small wallet, within the demo's caps:
-
-```json
-{ "mcpServers": { "agentpickup": { "type": "http", "url": "https://agentpickup.app/mcp" } } }
-```
-
-Or run it locally against any agentPickup shop, with your own wallet:
-
-```json
-{
-  "mcpServers": {
-    "agentpickup": {
-      "command": "npx",
-      "args": ["-y", "@agentpickup/mcp"],
-      "env": {
-        "AGENTPICKUP_SHOP_URL": "https://orders.yourshop.com",
-        "AGENTPICKUP_WALLET_KEY": "0x…",
-        "AGENTPICKUP_MAX_PER_ORDER": "$25"
-      }
-    }
-  }
-}
-```
-
-| Setting | Default | |
-|---|---|---|
-| `AGENTPICKUP_SHOP_URL` | the demo shop | The shop to order from. Tool calls can also name another shop with `shop_url` |
-| `AGENTPICKUP_WALLET_KEY` | none | An EVM private key holding USDC. Without it, `pay_order` only quotes |
-| `AGENTPICKUP_MAX_PER_ORDER` | `$25` | The most the wallet pays for one order |
-| `AGENTPICKUP_NETWORKS` | `eip155:84532` | Networks the wallet may pay on. Base Sepolia (test USDC) unless you add `eip155:8453` for Base mainnet |
-
-Use a wallet that holds only what you're willing to let an agent spend. The tools tell the model to confirm
-items and the total with the user before paying.
-
-## Host it in your own server
-
-```ts
-import { createMcpHandler, walletPayer } from "@agentpickup/mcp";
-
-const mcp = createMcpHandler({ shopUrl: "https://orders.yourshop.com" }); // no wallet: pay_order quotes
-app.all("/mcp", (c) => mcp(c.req.raw)); // Streamable HTTP, stateless, any Request/Response runtime
-```
-
-Node 22.13 or later. Licence: FSL-1.1-ALv2 (free to use and self-host; becomes Apache-2.0 two years after
-each release).
+# @agentpickup/mcp
+
+An MCP server for [agentPickup](https://github.com/dav3trad3r/agentpickup) shops. It lets an AI agent find
+pickup shops near its user, see what they sell, order, pay in USDC over x402, and hand its user the QR they
+show at the counter to collect.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `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 |
+| `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) |
+
+## Use it
+
+Try it against the hosted demo shop first. It pays with the demo's own small wallet, within the demo's caps:
+
+```json
+{ "mcpServers": { "agentpickup": { "type": "http", "url": "https://agentpickup.app/mcp" } } }
+```
+
+Or run it locally against any agentPickup shop, with your own wallet:
+
+```json
+{
+  "mcpServers": {
+    "agentpickup": {
+      "command": "npx",
+      "args": ["-y", "@agentpickup/mcp"],
+      "env": {
+        "AGENTPICKUP_SHOP_URL": "https://orders.yourshop.com",
+        "AGENTPICKUP_WALLET_KEY": "0x…",
+        "AGENTPICKUP_MAX_PER_ORDER": "$25"
+      }
+    }
+  }
+}
+```
+
+| Setting | Default | |
+|---|---|---|
+| `AGENTPICKUP_SHOP_URL` | the demo shop | The shop to order from. Tool calls can also name another shop with `shop_url` |
+| `AGENTPICKUP_WALLET_KEY` | none | An EVM private key holding USDC. Without it, `pay_order` only quotes |
+| `AGENTPICKUP_MAX_PER_ORDER` | `$25` | The most the wallet pays for one order |
+| `AGENTPICKUP_NETWORKS` | `eip155:84532` | Networks the wallet may pay on. Base Sepolia (test USDC) unless you add `eip155:8453` for Base mainnet |
+| `AGENTPICKUP_DIRECTORY_URL` | `https://agentpickup.app/directory/v1/shops` | Where `find_shops` searches. `off` leaves the tool out |
+
+Use a wallet that holds only what you're willing to let an agent spend. The tools tell the model to confirm
+items and the total with the user before paying.
+
+## Host it in your own server
+
+```ts
+import { createMcpHandler, walletPayer } from "@agentpickup/mcp";
+
+const mcp = createMcpHandler({ shopUrl: "https://orders.yourshop.com" }); // no wallet: pay_order quotes
+app.all("/mcp", (c) => mcp(c.req.raw)); // Streamable HTTP, stateless, any Request/Response runtime
+```
+
+Node 22.13 or later. Licence: FSL-1.1-ALv2 (free to use and self-host; becomes Apache-2.0 two years after
+each release).

package/dist/cli.js

@@ -17,6 +17,9 @@ const payer = key
         networks: env.AGENTPICKUP_NETWORKS?.split(",").map((n) => n.trim()).filter(Boolean),
     })
     : undefined;
-const server = createPickupMcpServer({ shopUrl, allowOtherShops: true, payer });
+// The public agentPickup directory, for find_shops. "off" leaves the tool out.
+const directory = env.AGENTPICKUP_DIRECTORY_URL || "https://agentpickup.app/directory/v1/shops";
+const directoryUrl = directory === "off" ? undefined : directory;
+const server = createPickupMcpServer({ shopUrl, allowOtherShops: true, payer, directoryUrl });
 await server.connect(new StdioServerTransport());
 console.error(`agentPickup MCP · shop ${shopUrl} · ${payer ? `wallet ${payer.address}` : "no wallet (pay_order returns the pay link)"}`);

package/dist/server.d.ts

@@ -1,11 +1,16 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Fetch, type Payer } from "./wallet.js";
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.2.0";
 export interface PickupMcpOptions {
     /** The agentPickup shop this server orders from. */
     shopUrl: string;
-    /** Let tool calls name another agentPickup shop. Leave off for hosted servers, so callers can't point it anywhere. */
+    /**
+     * Let tool calls name any agentPickup shop. Leave off for hosted servers, so callers can't point it anywhere:
+     * they can still name shops on the same host (venues at /v/<slug>), as find_shops returns them.
+     */
     allowOtherShops?: boolean;
+    /** An agentPickup directory (<host>/directory/v1/shops). Adds find_shops: shops near someone that sell what they want. */
+    directoryUrl?: string;
     /** 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

@@ -1,25 +1,32 @@
-// The agentPickup MCP server: lets any MCP client (Claude, ChatGPT, Cursor, an agent framework) find what a
-// pickup shop sells, order it, pay over x402, and hand its user the QR to collect with.
+// The agentPickup MCP server: lets any MCP client (Claude, ChatGPT, Cursor, an agent framework) find pickup
+// 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 { z } from "zod";
 import { errorOf, usd } from "./wallet.js";
-export const VERSION = "0.1.1";
+export const VERSION = "0.2.0";
 class ToolError extends Error {
 }
-const INSTRUCTIONS = `agentPickup lets you buy things online for the user to collect in person.
-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. 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.
+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. 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.`;
 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)}` }],
 });
 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. */
+const shopBase = (url) => {
+    const path = url.pathname.replace(/\/+$/, "");
+    return url.origin + (path.match(/^(.*)\/(?:api|p|c)\/.+$/)?.[1] ?? path.replace(/\/staff$/, ""));
+};
 export function createPickupMcpServer(opts) {
-    const home = new URL(opts.shopUrl).origin;
+    const homeUrl = new URL(opts.shopUrl);
+    const home = shopBase(homeUrl);
     const doFetch = opts.fetch ?? ((req) => fetch(req));
     function shopFor(shopUrl) {
         if (!shopUrl)
@@ -31,13 +38,14 @@ export function createPickupMcpServer(opts) {
         catch {
             throw new ToolError(`"${shopUrl}" isn't a URL.`);
         }
-        if (url.origin === home)
-            return home;
+        // 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 one shop only: ${home}.`);
+            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 url.origin;
+        return shopBase(url);
     }
     async function call(shop, path, init) {
         const res = await doFetch(new Request(`${shop}${path}`, init));
@@ -56,10 +64,66 @@ export function createPickupMcpServer(opts) {
             return failure(`Couldn't reach the shop: ${err instanceof Error ? err.message : String(err)}`);
         }
     };
-    const shopArg = opts.allowOtherShops
-        ? { shop_url: z.string().optional().describe(`An agentPickup shop's URL. Defaults to ${home}.`) }
+    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 });
+    if (opts.directoryUrl) {
+        const directoryUrl = opts.directoryUrl;
+        server.registerTool("find_shops", {
+            title: "Find pickup shops",
+            description: "Find agentPickup shops to order from: near a point (lat/lng), in a suburb or city (place), or selling something (query). " +
+                "Returns each shop's shop_url, pickup address, hours, whether it's open now, distance, and matching menu items.",
+            inputSchema: {
+                query: z.string().max(100).optional().describe('What the user wants, e.g. "flat white" or "croissant". Leave out to list everything.'),
+                place: z.string().max(100).optional().describe('A suburb, street or city to match against shop addresses, e.g. "Surry Hills".'),
+                lat: z.number().min(-90).max(90).optional().describe("Where the user is: latitude. Send with lng."),
+                lng: z.number().min(-180).max(180).optional().describe("Where the user is: longitude. Send with lat."),
+                radius_km: z.number().positive().max(100).optional().describe("With lat/lng: how far to look. Default 10."),
+                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 },
+        }, guarded(async (args) => {
+            if ((args.lat === undefined) !== (args.lng === undefined))
+                throw new ToolError("Send lat and lng together.");
+            const url = new URL(directoryUrl);
+            const params = { q: args.query, place: args.place, lat: args.lat, lng: args.lng, radius_km: args.radius_km, limit: args.limit };
+            for (const [k, v] of Object.entries(params))
+                if (v !== undefined && v !== "")
+                    url.searchParams.set(k, String(v));
+            if (args.open_now)
+                url.searchParams.set("open_now", "true");
+            const res = await doFetch(new Request(url));
+            if (!res.ok)
+                throw new ToolError(await errorOf(res, `The directory answered ${res.status}.`));
+            const { shops } = (await res.json());
+            if (!shops.length)
+                return reply("No agentPickup shops match. Try a wider radius, another place, or no query.", { shops: [] });
+            const lines = shops.map((s) => {
+                const facts = [
+                    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,
+                ].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}` : ""}`;
+            });
+            return reply(`${shops.length} shop${shops.length === 1 ? "" : "s"}:\n${lines.join("\n")}\nPass a shop's shop_url to get_shop or create_pickup_order.`, {
+                shops: shops.map((s) => ({
+                    shop_url: s.url,
+                    name: s.name,
+                    location: { name: s.location.name, address: s.location.address, hours: s.location.hours },
+                    distanceKm: s.distanceKm,
+                    openNow: s.openNow,
+                    testOnly: s.testOnly,
+                    payments: { x402: s.payments.x402?.network ?? null, test: s.payments.test },
+                    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),
+                })),
+            });
+        }));
+    }
     server.registerTool("get_shop", {
         title: "See what a shop sells",
         description: "What the shop sells (item ids and prices), where to collect, and which payments it takes.",
@@ -78,7 +142,11 @@ export function createPickupMcpServer(opts) {
         }));
         const payments = data.payments;
         return reply(`${merchant.name}${merchant.location?.name ? `, collect at ${merchant.location.name}` : ""}. ` +
-            (payments.x402 ? `Takes USDC over x402 on ${payments.x402.network}.` : "Doesn't take x402 payments."), { shop, merchant: merchant.name, location: merchant.location, currency, items, x402: payments.x402 ?? null });
+            (payments.x402
+                ? `Takes USDC over x402 on ${payments.x402.network}.`
+                : 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) });
     }));
     server.registerTool("create_pickup_order", {
         title: "Order for pickup",
@@ -95,13 +163,22 @@ export function createPickupMcpServer(opts) {
         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 { 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/orders", {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ items: args.items, email: args.email, name: args.name, rail: "x402" }),
+            body: JSON.stringify({ items: args.items, email: args.email, name: args.name, rail }),
         });
         const order = data.order;
         const next = data.next;
+        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 });
+        }
         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 });
     }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentpickup/mcp",
-  "version": "0.1.1",
-  "description": "MCP server for agentPickup: let an AI agent order from a shop, pay over x402, and hand its user the QR to collect in person.",
+  "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",