map

MAP — Maraventano Agent Protocol

探索智能体商业。 找到任意商家。向任意商家付款。让别人找到你。

MAP 让任意智能体都能以统一格式读取开放网络上的商品，判断自己能否自主付款，并发布自己的商品目录。

Merchant Key · Addressability · Provision — MCP 服务下的三个最精简组成部分。

MAP 是一个包含三个部分的 MCP 服务。每个部分只做一件事，不说多余的话；三者合起来，消除了智能体与开放商业网络之间的守门人。

部分	名称	功能
read	Merchant Key	找到任意商家。 将任意商品 URL 解码为统一格式（CleanRead）。
pay	Provision	向任意商家付款。 提供课程，教智能体使用它已有的钱包。
publish	Addressability	让别人找到你。 让解码器反向工作；向其他智能体提供你自己的商品目录。

每个部分都是教师，而非管家。 MAP 负责读取、说明、持久化和提供服务。它绝不签名、付款、持有密钥、交易或存储银行卡。

它以 @maraventano/map 的名称发布到 npm。独立的 firstdollar 包仍采用 MIT 许可证并保持独立；此处捆绑的课程副本（Provision）则采用双重许可，详见 LICENSE。

---

Merchant Key — 找到任意商家 (read)

它读取开放网络上的任意 URL，而不仅是封闭花园中的内容。这正是它与 Perplexity / Google Shopping / Amazon 的区别：它们只能看到各自项目中的商家。MAP 从不假定商家已在任何地方注册。

decode-merchant

输入商品 url。返回一种格式（CleanRead）：

{
 "schemaVersion": "map/v1",
 "sourceUrl": "https://…",
 "what": "Void Latte — Meditation on emptiness and meaning…", // name + identity, one string
 "who": "underground.substratesymposium.com", // seller
 "price": { "total": 1.99, "currency": "USDC" }, // total if knowable, else null
 "available": "in_stock", // in_stock | out_of_stock | unknown
 "payable": { // can an agent pay this itself?
 "rail": "x402", // schema (rail-agnostic): x402 | ap2 | acp | coinbase | stripe | http-json | walletconnect | human_checkout | unknown. v1.0.x DETECTS x402 only; ap2/acp/ucp detectors on the v1.1 roadmap.
 "payTo": { "kind": "evm-address", "value": "0x…", "chain": "eip155:8453" },
 "instruction": "Agent-payable via x402 … see this kit's wallet lessons (read-this-challenge, how-do-i-pay)."
 },
 "outcome": "autonomous", // autonomous | human_checkout | unreadable
 "reason": null,
 "cuts": [] // 1-line actionable gaps
}

五项内容和一个判定。不多不少。 每次读取都采用相同格式，因此四次读取的结果可以相互比较。未知值为 null / "unknown"，绝不会省略。

三种结果：

• autonomous — 存在机器可付款通道（x402），价格已知，且商品有库存。智能体可以自行购买。
• human_checkout — 可以读取，但没有智能体可付款通道。仍会返回规范化的商品卡片。这是最常见的情况，也是成功结果——如今支持智能体付款的网络几乎为空。
• unreadable — 无法获取可用的价格或商品信息。会在 reason 中说明原因，不会猜测。

读取方式（v1）： JSON-LD（schema.org Product/Offer）→ OpenGraph 商品标签 → x402 402 挑战 → 否则为 unreadable。只读 GET。它会跟随一个同源重定向（在 cuts 中注明为 "followed 1 same-origin redirect"），因此 canonical→slug URL 可以正确解析；它会拒绝跨源重定向和重定向链（这些会记录为 cuts 注释，而不会静默跟随）——这样你就不会在不知情的情况下被重定向到商家自己的主机之外。

MAP 在设计上与付款通道无关。 payable.rail 架构可以描述任何智能体可付款通道——x402、ap2、acp、coinbase、stripe、http-json、walletconnect、human_checkout、unknown。v1.0.x 可可靠检测 x402；ap2/acp/ucp 检测器已列入 v1.1 路线图。 其他通道仍是保留的架构值。MAP 绝不会根据品牌、结账按钮、脚本标签、营销文案或平台名称推断付款通道；如果未检测到可验证的机器可读通道，结果就是 human_checkout。因此，普通的 Shopify/Stripe 页面会被正确读取为 human_checkout。

v1 中出现错误的 human_checkout 可以接受；错误的 autonomous 则很危险，无法接受——因此检测保持谨慎。协议在架构和路线图层面与付款通道无关；x402 并非协议身份的一部分，只是 v1 检测器支持的通道。

已知的 v1 限制（未来增强项，而非缺陷）： 没有无头浏览器（仅依赖 JS、且没有 JSON-LD/OG 的页面会被读取为 unreadable）；通常无法从外部获知库存情况（available: "unknown" 是正确值）；不探测次级端点。

---

Provision — 向任何商家付款 (pay)

当 decode-merchant 返回 autonomous，而你想要购买时，Provision 会教你如何使用自己的钱包完成付款。它是 First Dollar 教程内容的重新授权副本：一系列简短课程，从“什么是钱包”到读取实时 x402 挑战、签署 USDC 付款，以及验证收据。

从 what-is-x402 开始，然后是 read-this-challenge，接着是 how-do-i-pay。**它会说明要运行什么；绝不会替你签名。**其中还涵盖了 Mandate/Delegation（AP2）、收据验证，以及“出了什么问题”的诊断。

---

Addressability — 让别人找到你 (publish)

解码器指向了内部。商家只需用买家使用的同一个 decode-merchant 读取自己，即可发布内容——无需新的解析方式，也无需针对不同平台编写适配器。

• publish-catalog — 解码自己的产品 URL → 收集 CleanReads → 写入 ./catalog.json 和 ./.well-known/map.json 发现清单，供注册表爬取。
• get-catalog / get-product — 其他 Agent 读取的工具接口。

Agent 通过工具接口和 well-known 清单发现内容——而非通过抓取或 HTTP 标头。Addressability 会生成文档、验证格式、持久化并提供服务。它绝不会部署商家基础设施、持有密钥、进行交易或存储卡片信息。

信任边界（v1，已明确但尚未实现）：MAP 信任商家使用自己的解码器生成的读取结果。独立重新读取并比对、商家签名的清单以及定期重新审核均属于已知的后续工作——v1 尚未实现。不过，已有一项安全保障：支付通道会在结算时强制执行真实价格，因此错误的清单不会导致多收款——它只能错误描述库存等非关键字段。

---

Charlie 的下午

Bob：“Charlie，帮我找一副不到 300 美元的耳机。” Charlie 浏览开放网络，访问四个广告泛滥的产品页面，对每个页面运行 decode-merchant，得到四张简洁卡片——**商品是什么、谁在售卖、价格多少、我能否自己购买。**其中三家需要人工结账；他把候选清单带回给 Bob。有一家支持 x402；Charlie 自己买下了它。回家路上，Charlie 用自己的钱包给自己买了一杯 Void Latte。

---

安装 / 运行

npx @maraventano/map # run the MAP MCP server on stdio (23 tools: read · pay · publish)
npm run smoke # Merchant Key DoD — the four decode cases (hits the live Underground x402 item)
npm run smoke:publish # Addressability DoD — publish-catalog → catalog.json → get-product → .well-known

Node ≥ 18。仅有一个依赖项：@modelcontextprotocol/sdk。

许可证与商标

采用双重许可：**个人和 Agent 可免费使用；公司则必须取得商业许可。**请参阅 LICENSE。并非 MIT 许可证。如需商业许可，请联系 Lisa Maraventano：[email protected]。

所有商标均属于各自所有者。MAP 与 Coinbase、Stripe、Google、Shopify 或文档和课程中提及的任何其他公司均无关联，亦未获其认可。

---

作者：Lisa Maraventano，与 Claude 合作 · 美国密西西比州克拉克斯代尔