MCP

proxy-shopping MCP server

An MCP server that lets an AI agent use the proxy-shopping P2P network as tools:

• Buy from cash-only or unsupported shops with crypto through a proxy shopper, with a 2-of-3 escrow. You pay BTC into a per-order escrow (you, the shopper, an escrow); the shopper buys and ships; you release the payment when the items arrive. If something goes wrong the escrow rules a split, and after the T2 timelock you can take everything back alone.
• Earn as a proxy shopper. A precise plan for running the always-online shopper node, and the registry entry for getting listed.

It runs next to the agent (stdio) as one participant with its own key. Protocol logic is @proxy-shopping/core, the same code the web app runs. The session stays up while the server runs, so quotes, shipping updates and rulings keep arriving and are stored in the data directory. Registry name: io.github.pad01g/proxy-shopping.

The public network ps-main is new. There may be no trusted shoppers yet (network_info says how many shopper × escrow combinations are trusted). Payments there are BTC on signet, a test network whose coins have no market value. USDC is not available on ps-main yet.

Run

Claude Code:

claude mcp add proxy-shopping -- docker run -i --rm -v proxy-shopping-mcp:/data ghcr.io/pad01g/proxy-shopping-mcp:0.1.2

Other clients (mcp.json):

{
  "mcpServers": {
    "proxy-shopping": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "proxy-shopping-mcp:/data", "ghcr.io/pad01g/proxy-shopping-mcp:0.1.2"]
    }
  }
}

The volume at /data holds the key and the orders. Keep it: without it you lose the key that controls the escrow of every open order (back it up with export_backup). One data dir = one identity; use a separate volume per agent or per person.

The local docker compose lab (proxy-shopping-go, demo server on http://localhost:8888):

claude mcp add proxy-shopping-lab -- docker run -i --rm --add-host=host.docker.internal:host-gateway \
  -v proxy-shopping-mcp-lab:/data -e PS_NETWORK=lab -e PS_LAB_URL=http://host.docker.internal:8888 \
  ghcr.io/pad01g/proxy-shopping-mcp:0.1.2

MCPB bundle (Claude Desktop and other MCPB clients: open the file to install; needs Node 22+): proxy-shopping-<version>.mcpb from the releases; build it with node packages/mcp/scripts/build-mcpb.mjs after npm run build -w @proxy-shopping/core. Agents installing the server: llms-install.md.

Without Docker (Node 22, from the repository root): npm ci && npm run build -w @proxy-shopping/core -w @proxy-shopping/mcp, then node packages/mcp/dist/server.js (bin proxy-shopping-mcp).

Tools

A purchase: network_info → wallet (fund it) → find_offers → request_quote → accept_quote → fund_order → (get_order until delivered) → confirm_receipt.

Every tool answers with a short text plus the same data as structured JSON.

Safety

• Tools that move money or disclose secrets do nothing without confirm: true; without it they show what would happen (amounts, recipients, fees). An agent should show that to its human and ask before confirming.
• A quote that fails validation (combination not trusted, escrow address that does not match our own computation, timelocks outside the policy, amounts that do not add up) cannot be accepted. A rate more than 10 % away from our own sources needs an explicit acknowledgement.
• Payouts are signed only for the template the protocol allows (release to the shopper, a refund to you, a ruling that matches its split); completed / settled / refunded are reported only once the chain shows the payment.
• The mnemonic never leaves the data dir except through export_backup. The delivery address is encrypted for the shopper; the escrow can read it only when you open a dispute.
• Trust comes only from the coordinators you configure (network_info lists them and where they came from). Orders are only as good as the shoppers and escrows that operators list.

Test

# from the repository root, in Docker (no host Node needed)
docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm \
  sh -c "npm ci && npm run build -w @proxy-shopping/core && npm test -w @proxy-shopping/mcp"

# end to end against the running compose lab: a BTC order through MCP tool calls over stdio
docker run --rm --add-host=host.docker.internal:host-gateway -v "$PWD":/src -v ps-npm:/root/.npm -w /src/packages/mcp \
  -e PS_LAB_URL=http://host.docker.internal:8888 node:22-bookworm npm run test:lab

The unit tests drive every tool through an MCP client against core's in-memory world (relays, chain, a scripted shopper and an escrow), and run the registry's own validator (proxy-shopping-registry/scripts/registry.ts validate) on the files registry_entry writes; they expect ../proxy-shopping-registry next to this repository (or PS_REGISTRY_DIR, or mounted at /proxy-shopping-registry; SKIP_REGISTRY=1 skips it). Add -v "$PWD/../proxy-shopping-registry":/proxy-shopping-registry:ro to the Docker command above.