Nagora

Nagora MCP 服务

这是 nagora.shop 的官方 MCP 服务。nagora.shop 是一个所有交易都以 Nano（XNO）结算的 P2P 市场。

它为任何 MCP 客户端（Claude Desktop、Claude Code 或你自己的 Agent 运行时）提供工具，用于搜索商品、下单并享受托管保护、跟踪订单以及获取签名收据。你的 AI 助手可以代你购物，而托管机制会在购物过程中为你提供保障：资金存放在每笔订单专属的 Nano 账户中，只有在确认送达后才会释放给卖家。

工具

工具	身份验证	功能
search_listings	无	对在售商品进行全文搜索
get_listing	无	获取完整商品详情：变体、配送选项、Nano 定价
register_agent	无	一次调用即可创建 Agent 和 API 密钥，无需账户；密钥会保存在本地
whoami	API 密钥	验证密钥；查看消费上限和 webhook 密钥
create_purchase	API 密钥	下单；返回托管充值地址和金额
get_order	API 密钥	查询订单和托管状态、物流信息及收据 ID
confirm_delivery	API 密钥	确认送达并向卖家释放托管资金
cancel_order	API 密钥	取消尚未充值的订单
get_receipt	API 密钥	获取由 KMS 签名且包含链上付款区块的收据

设置

零安装替代方案： Nagora 也将这些相同的工具托管为远程 MCP 服务。 运行 claude mcp add --transport http nagora https://api.nagora.shop/mcp 即可完成设置。 缺点是：托管服务无法在本地保存你的密钥，因此 register_agent 只会返回密钥一次；你需要将它作为 apiKey 工具参数传入，或通过 --header "Authorization: Bearer nag_agt_..." 固定传入。这个本地软件包则会替你将密钥 保存到 ~/.nagora/credentials.json。

Claude Code

claude mcp add nagora -- npx -y @nagora/mcp

Claude Desktop

在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "nagora": {
      "command": "npx",
      "args": ["-y", "@nagora/mcp"]
    }
  }
}

从源代码运行（而非 npx）

cd nagora-mcp
npm install
npm run build
claude mcp add nagora -- node /path/to/nagora-mcp/dist/index.js

让 Agent 自行注册

设置就这么简单。无需 Nagora 账户，也无需复制密钥。助手首次需要购买商品时，会使用名称和退款 Nano 地址调用 register_agent；API 密钥只会返回一次，并保存到 ~/.nagora/credentials.json（权限模式为 600）。此后，其他所有工具都会自动读取该密钥。

自行注册的密钥默认采用较为保守的消费上限（目前为每笔交易 25 XNO、每天 100 XNO），并由服务端强制执行。需要更高的上限、多个密钥或管理面板？请在 nagora.shop 创建账户，并在 Settings → Agents 中管理 Agent；在那里创建的密钥同样可通过 NAGORA_API_KEY 使用。

配置

变量	默认值	说明
NAGORA_API_KEY	未设置	可选。覆盖通过 register_agent 保存的凭据
NAGORA_API_URL	https://api.nagora.shop	本地开发时可指向 http://localhost:5004

购买流程

1. search_listings / get_listing：查找商品并记下 Nano 总额。
2. create_purchase：下单。响应中包含 depositAddress（Nano 网络上每笔订单专属的托管账户）和 amountNano。
3. 为托管账户充值：从 Agent 自己的 Nano 钱包向 depositAddress 转入恰好为 amountNano 的金额。此服务刻意不持有任何密钥，也不会转移任何资金；请将其与 xno-mcp 等钱包工具搭配使用，或手动充值。Nano 转账免手续费，并且不到一秒即可结算。
4. 资金到账后，订单会自动进入 AwaitingShipment 状态。卖家发货并添加追踪信息。
5. 使用 get_order（或 Webhook，见下文）查看订单是否进入 Shipped 状态。
6. 商品送达后调用 confirm_delivery：托管资金会在链上释放给卖家。
7. 使用 get_receipt 获取包含付款区块哈希在内、可独立验证且经过签名的完整交易凭证。

如果卖家始终未发货，托管自动取消计时器会将款项退还给买家。如果订单有问题，请通过网站发起争议，由人工审核。

Webhook（可选）

无需轮询 get_order，你可以在 Agent 上注册一个 callbackUrl（Settings → Agents）。Nagora 会使用 HMAC-SHA256 为每个 Webhook 签名：计算 HMAC-SHA256("{X-Nagora-Timestamp}.{raw_body}", webhookSecret)，并将结果与 X-Nagora-Signature: sha256=<hex> 进行比对。webhookSecret 可通过 whoami 获取。

事件：订单进度更新时会触发 order.funded、order.shipped 等事件。

安全模型

• 服务采用无状态、无密钥设计：它无法支出 Nano，只能请求你随后充值（或不充值）的订单。
• 每个 API 密钥的支出上限都由服务端强制执行；失控的 Agent 会收到 429 错误，而不是动用你的钱包。
• 托管机制意味着 Agent 出错后仍可补救：未充值的订单可以取消，已充值的订单会受到保护，直到你确认送达。
• 你可以随时通过 Settings → Agents 撤销密钥；撤销会在 60 秒内生效。