map

MAP — Maraventano Agent Protocol

エージェントコマースをナビゲートします。 あらゆる販売者を見つけ、あらゆる販売者に支払い、見つけてもらえます。

MAP を使えば、あらゆるエージェントがオープンウェブ上の商品を統一された形式で読み取り、自律的に支払い可能かどうかを判断し、自身のカタログを公開できます。

Merchant Key · Addressability · Provision — 1 つの MCP サーバーに備わる、最小限の 3 つの要素です。

MAP は 3 つの要素を備えた 1 つの MCP サーバーです。それぞれが 1 つのことだけを行い、余計なことはしません。3 つを組み合わせることで、エージェントとオープンな商用ウェブの間にある門番をなくします。

要素	名前	機能
read	Merchant Key	あらゆる販売者を見つけます。 あらゆる商品 URL を、統一された形式（CleanRead）にデコードします。
pay	Provision	あらゆる販売者に支払います。 エージェントがすでに持っているウォレットの使い方を教えるレッスンです。
publish	Addressability	見つけてもらいます。 デコーダーを内向きにして、自分のカタログを他のエージェントに提供します。

どの要素も執事ではなく教師です。 MAP は読み取り、説明、永続化、提供を行います。署名、支払い、鍵の保有、取引、カードの保存は一切行いません。

npm には @maraventano/map として公開しています。単独の firstdollar パッケージは MIT のまま別途提供されます。ここにバンドルされているそのカリキュラムの複製（Provision）は、デュアルライセンスに変更されています。詳しくは LICENSE をご覧ください。

---

Merchant Key — あらゆる販売者を見つける (read)

オープンウェブ上のあらゆる URL を読み取ります。ウォールドガーデンだけではありません。自社のプログラムに参加する販売者しか見られない Perplexity／Google Shopping／Amazon との違いはここにあります。MAP は販売者がどこかに登録されていることを前提としません。

decode-merchant

商品 url を入力します。統一された 1 つの形式（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
}

項目は 5 つと判定結果のみ。6 つ目のフィールドはありません。 読み取りごとに同じ形式なので、4 件の読み取り結果を比較できます。不明な値は省略せず、null／"unknown" になります。

3 つの結果：

• autonomous — 機械が支払い可能な決済レール（x402）があり、価格が判明していて、在庫切れではありません。エージェント自身で購入できます。
• human_checkout — 読み取り可能ですが、エージェントが支払い可能な決済レールはありません。それでも整形された商品情報を返します。一般的なケースであり、成功です。現時点では、エージェントが支払い可能なウェブはほとんど存在しません。
• unreadable — 利用可能な価格や商品情報を取得できませんでした。reason に理由を示します。推測はしません。

読み取り方法（v1）： JSON-LD（schema.org の Product／Offer）→ OpenGraph の商品タグ → x402 の 402 チャレンジ → それ以外は unreadable。読み取り専用の GET です。同一オリジンへのリダイレクトを 1 回だけたどります（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 の制限事項（バグではなく、今後の拡張項目）： ヘッドレスブラウザーがないため、JSON-LD／OG のない JavaScript のみのページは unreadable になります。外部から在庫状況を知ることは通常できないため、available: "unknown" が正しい値です。二次エンドポイントのプローブは行いません。

Provision — あらゆる加盟店で支払う (支払い)

decode-merchant が autonomous を返し、購入したい場合、Provision があなた自身のウォレットを使った購入方法を案内します。これは First Dollar カリキュラムのライセンスを変更したコピーです。「ウォレットとは何か」から、実際の x402 チャレンジの読み取り、USDC 支払いへの署名、領収書の検証まで、短いレッスンで学べます。

まず what-is-x402、次に read-this-challenge、その後 how-do-i-pay に進んでください。実行方法は説明しますが、あなたに代わって署名することはありません。 委任（AP2）、領収書の検証、「何が問題だったのか」の診断もすべて含まれています。

---

Addressability — 見つけてもらう (公開)

デコーダーは内側を指していました。加盟店は、購入者が使うものとまったく同じ decode-merchant で自分自身を読み取ることで公開します。新たな解析処理やプラットフォームごとのアダプターは不要です。

• publish-catalog — 自分の商品 URL をデコード → CleanReads を収集 → ./catalog.json と、レジストリがクロールするための ./.well-known/map.json 検出マニフェストを書き込みます。
• get-catalog / get-product — 他のエージェントが読み取るツールのインターフェースです。

エージェントはツールのインターフェースと well-known マニフェストを通じて見つけます。スクレイピングや HTTP ヘッダーは使いません。 Addressability はドキュメントを出力し、形式を検証して保存し、提供します。加盟店のインフラをデプロイしたり、鍵を保管したり、取引を実行したり、カード情報を保存したりすることはありません。

信頼境界（v1、名称のみで未実装）： MAP は、加盟店が自分のデコーダーで生成した読み取り結果を信頼します。独立した再読み取りと差分確認、加盟店署名付きマニフェスト、定期的な再監査は、今後の課題として認識されていますが、v1 には実装されていません。すでに成り立っている安全性の特性が1つあります。決済レールは精算時に実際の価格を適用するため、マニフェストに誤りがあっても過剰請求はできません。誤って伝えられるのは、在庫などのソフト情報だけです。

---

チャーリーの午後

ボブ：「チャーリー、300ドル未満のヘッドホンを探して。」チャーリーはオープンウェブを巡り、広告だらけの商品ページを4つ開き、それぞれで decode-merchant を実行して、きれいなカードを4つ取得します。商品は何か、誰が販売しているか、価格はいくらか、自分で購入できるか。 3つは人間によるチェックアウトが必要なので、候補リストをボブに持ち帰ります。1つは x402 に対応しているため、チャーリー自身で購入します。帰り道、チャーリーは自分のウォレットを使って、自分のためにヴォイドラテを買います。

---

インストール／実行

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。依存関係は1つです：@modelcontextprotocol/sdk。

ライセンスと商標

デュアルライセンスです：個人およびエージェントは無料で利用できます。企業には商用ライセンスが必要です。 LICENSE をご覧ください。MIT ライセンスではありません。商用ライセンスについては、Lisa Maraventano（[email protected]）までお問い合わせください。

すべての商標は、それぞれの所有者に帰属します。MAP は、ドキュメントやレッスンに記載されている Coinbase、Stripe、Google、Shopify、その他のいかなる企業とも、提携しておらず、推奨も受けていません。

---

Lisa Maraventano 著、Claude と共に · ミシシッピ州クラークスデール