proxy-shopping: buy anywhere with crypto through a proxy shopper

proxy-shopping MCP 服务

一个 MCP 服务，让 AI Agent 能够将 proxy-shopping P2P 网络用作工具：

• 通过代理代购者，使用加密货币从仅收现金或不支持的商店购物，并使用 2-of-3 托管。 你将 BTC 存入每笔订单专用的托管账户（由你、代购者和托管方共同控制）；代购者购买并发货；商品送达后，你释放 款项。如果出现问题，托管方将裁定如何分配款项；T2 时间锁到期后，你可以单独取回全部款项。
• 成为代理代购者赚取收入。 提供一份详尽的计划，指导你运行始终在线的代购者节点，并提供用于登记上榜的 注册表条目。

它作为一个参与方与 Agent 并行运行（stdio），并拥有自己的密钥。协议逻辑由 @proxy-shopping/core 提供，与 Web 应用运行的代码相同。服务运行期间，会话将保持连接，因此报价、物流更新和裁定会持续到达，并存储在数据目录中。注册表名称：io.github.pad01g/proxy-shopping。

公共网络 ps-main 尚处于起步阶段。 目前可能还没有可信的代购者（network_info 会显示可信的代购者 × 托管方组合数量）。该网络上的付款使用 BTC，并基于signet（一个没有市场价值的测试网络）。ps-main 暂不支持 USDC。

运行

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

其他客户端（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"]
    }
  }
}

/data 上的卷保存密钥和订单。请妥善保留：没有它，你会丢失控制所有未完成订单托管款项的密钥（使用 export_backup 进行备份）。每个数据目录对应一个身份；每个 Agent 或每个人都应使用单独的卷。

本地 Docker Compose 实验环境（proxy-shopping-go，演示服务地址为 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 软件包（适用于 Claude Desktop 和其他 MCPB 客户端：打开文件即可安装；需要 Node 22+）：从发布页获取 proxy-shopping-<version>.mcpb；运行 npm run build -w @proxy-shopping/core 后，通过 node packages/mcp/scripts/build-mcpb.mjs 构建。安装此服务的 Agent 请参阅：llms-install.md。

不使用 Docker（Node 22，在仓库根目录运行）：npm ci && npm run build -w @proxy-shopping/core -w @proxy-shopping/mcp，然后运行 node packages/mcp/dist/server.js（可执行文件 proxy-shopping-mcp）。

变量	默认值	含义
PS_NETWORK	ps-main	ps-main：公共 Nostr 中继（relay.damus.io、nos.lol、relay.primal.net），通过 mempool.space 使用 BTC signet；协调器和签名信任事件来自注册表。lab：通过演示服务连接 Compose 实验环境
PS_DATA_DIR	~/.proxy-shopping-mcp（镜像：/data）	助记词（mnemonic，权限模式 0600，首次运行时创建）和各网络的状态（state-<network>.json）
PS_LAB_URL	http://localhost:8888	仅限实验环境：演示服务（中继位于 /relay-1、/relay-2，以及 /esplora、/evm、/faucet、/rates、/deployments/31337.json）
PS_CONFIG_URL / PS_CONFIG_FILE	未设置	Web 应用的 config.json（格式同 proxy-shopping-go/lab/web-config.json：relays、coordinators、esplora、evm_rpc、deployments_url、rates、timelock_policy、……），用于覆盖预设配置
PS_COORDINATORS	未设置	以逗号分隔的协调器公钥，用于替换预设的信任根

工具

工具	功能
network_info	网络、中继、协调方、链、受信任的购物者 × 托管方组合数量，以及如实的状态
wallet	身份公钥、BTC signet 地址和余额（网络支持时显示 EVM/USDC）
lab_faucet	仅限实验环境：向此钱包提供测试 BTC / USDC、挖矿区块
find_offers	针对商店 URL、地区和支付方式的受信任购物者 × 托管方组合，包含费用、现金地区和来源（协调方 → 运营方列表）
request_quote	从一个组合下单并等待报价；返回其验证信息：与我们自己的来源相比的汇率偏差、重新计算的托管地址、时间锁
get_order / list_orders	状态、时间线和后续步骤；get_order 可以等待某个状态
accept_quote	接受有效报价（汇率偏差较大时需要 acknowledge_rate_deviation）
fund_order	转移资金：支付锁定款项和托管预付费（confirm: true）
confirm_receipt	转移资金：确认收到商品，并签署向购物者付款的交易（confirm: true）
open_dispute	请求托管方作出裁决；向其提供证据和访问你地址的密钥（confirm: true）
review_ruling / countersign_ruling	检查托管方的资金分配方案，然后共同签署（转移资金，confirm: true）
accept_refund_offer	转移资金：共同签署购物者提出的协商退款（confirm: true）
refund_after_timelock	转移资金：T2 之后，独自取回资金（confirm: true）
cancel_order	在付款前取消
report	向将购物者或托管方列入名单的运营方举报
export_backup	显示 12 个单词的助记词（confirm: true）
become_shopper	作为代理购物者赚取收入的方案：要求、费用、节点配置和 ps-main 的 compose 文件，以及如何加入名单
registry_entry	用于向 注册表 提交拉取请求的确切文件，格式如下：shoppers/<name>.json {pk, contact, description, regions (cash regions), payments, escrows}、escrows/<name>.json {pk, contact, description, sla_days}、operators/<name>.json {pk, contact, description, regions}、coordinators/<name>.json {pk, contact, description, url?, bundle?}

一次购买：network_info → wallet（为其充值）→ find_offers → request_quote → accept_quote → fund_order →（使用 get_order 直到状态为 delivered）→ confirm_receipt。

每个工具都会返回简短文本，以及相同数据的结构化 JSON。

安全

• 未提供 confirm: true 时，转移资金或披露机密的工具不会执行任何操作；它们会显示将要发生的情况（金额、收款方、费用）。Agent 应向用户展示这些信息，并在确认前征求同意。
• 验证失败的报价（组合不受信任、托管地址与我们自行计算的结果不符、时间锁超出策略范围、金额不相符）无法接受。汇率与我们自己的来源相差超过 10 % 时，需要明确确认。
• 付款签名仅适用于协议允许的模板（向购物者放款、退款给你、符合其资金分配方案的裁决）；只有链上显示付款后，才会报告为 completed / settled / refunded。
• 助记词不会离开数据目录，除非通过 export_backup 导出。收货地址会加密后提供给购物者；只有在你发起争议时，托管方才能读取该地址。
• 信任仅来自你配置的协调方（network_info 会列出它们及其来源）。订单的可靠性取决于运营方列入名单的购物者和托管方。

测试

# 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

单元测试通过 MCP 客户端，针对 core 的内存世界（中继、链、脚本化购物者和托管服务）驱动每个工具，并对 registry_entry 写入的文件运行 registry 自带的验证器（proxy-shopping-registry/scripts/registry.ts validate）；测试预期 ../proxy-shopping-registry 位于此仓库旁边（或通过 PS_REGISTRY_DIR 指定，或挂载到 /proxy-shopping-registry；设置 SKIP_REGISTRY=1 可跳过验证）。将 -v "$PWD/../proxy-shopping-registry":/proxy-shopping-registry:ro 添加到上方的 Docker 命令中。