{
  "markdown": "# MAP — Maraventano Agent Protocol\n\n**Navigate agent commerce.** Find any merchant. Pay any merchant. Be found.\n\n**MAP lets any agent read products across the open web in one shape, decide whether it can pay autonomously, and publish its own catalog.**\n\n> **Provisions · Merchant Key · Atlas** — three minimal parts under one MCP server.\n\nMAP is one MCP server with three parts. Each does one thing and shuts up; together they remove the gatekeeper between an agent and the open commercial web.\n\n| Part | Name | What it does |\n|---|---|---|\n| **read** | **Merchant Key** | *Find any merchant.* Decode any product URL into one clean shape (CleanRead). |\n| **pay** | **Provisions** | *Pay any merchant.* Lessons that teach an agent to use the wallet it already has. |\n| **publish** | **Atlas** | *Be found.* Point the decoder inward; serve your own catalog to other agents. |\n\n**Teacher, not butler — every part.** MAP reads, explains, persists, and serves. It **never** signs, pays, holds keys, transacts, or stores cards.\n\nIt publishes to npm as **`@maraventano/map`**. The standalone [`firstdollar`](https://github.com/lisamaraventano-spine/firstdollar) package stays MIT and separate; the copy of its curriculum bundled here (Provisions) is relicensed dual — see [LICENSE](./LICENSE).\n\n---\n\n## Merchant Key — find any merchant *(read)*\n\nIt reads **any URL on the open web** — not just a walled garden. That's the difference from Perplexity / Google Shopping / Amazon, who only see merchants inside their own programs. MAP never assumes the merchant is registered anywhere.\n\n### `decode-merchant`\n\nInput a product `url`. Returns ONE shape (CleanRead):\n\n```jsonc\n{\n  \"schemaVersion\": \"map/v1\",\n  \"sourceUrl\": \"https://…\",\n  \"what\":   \"Void Latte — Meditation on emptiness and meaning…\",  // name + identity, one string\n  \"who\":    \"underground.substratesymposium.com\",                 // seller\n  \"price\":  { \"total\": 1.99, \"currency\": \"USDC\" },                // total if knowable, else null\n  \"available\": \"in_stock\",                                        // in_stock | out_of_stock | unknown\n  \"payable\": {                                                    // can an agent pay this itself?\n    \"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.\n    \"payTo\": { \"kind\": \"evm-address\", \"value\": \"0x…\", \"chain\": \"eip155:8453\" },\n    \"instruction\": \"Agent-payable via x402 … see this kit's wallet lessons (read-this-challenge, how-do-i-pay).\"\n  },\n  \"outcome\": \"autonomous\",                                        // autonomous | human_checkout | unreadable\n  \"reason\":  null,\n  \"cuts\":    []                                                   // 1-line actionable gaps\n}\n```\n\n**Five things and a verdict. No sixth field.** Same shape every read, so four reads sort against each other. Unknown is `null` / `\"unknown\"` — never omitted.\n\n**The three outcomes:**\n- **`autonomous`** — a machine-payable rail (x402) exists, the price is known, and it's not out of stock. The agent can buy it itself.\n- **`human_checkout`** — readable, but no agent-payable rail. Returns the clean card anyway. **The common case, and a success** — the agent-payable web is nearly empty today.\n- **`unreadable`** — couldn't get a usable price/product. Says why in `reason`. Doesn't guess.\n\n**How it reads (v1):** JSON-LD (`schema.org` Product/Offer) → OpenGraph product tags → x402 402 challenge → else `unreadable`. Read-only `GET`. It follows **one same-origin redirect** (noted in `cuts` as \"followed 1 same-origin redirect\") so canonical→slug URLs resolve; it **refuses cross-origin redirects and chains** (those become a `cuts` note, not a silent follow) — you can't be silently bounced off the merchant's own host.\n\n**MAP is payment-rail agnostic by design.** The `payable.rail` schema can describe any agent-payable rail — `x402`, `ap2`, `acp`, `coinbase`, `stripe`, `http-json`, `walletconnect`, `human_checkout`, `unknown`. **v1.0.x detects `x402` reliably; `ap2`/`acp`/`ucp` detectors are on the v1.1 roadmap.** Other rails remain reserved schema values. MAP never infers a rail from branding, checkout buttons, script tags, marketing copy, or platform names; if no verifiable machine-readable rail is detected, the outcome is `human_checkout`. So a normal Shopify/Stripe page reads as `human_checkout`, correctly.\n\n**False `human_checkout` is acceptable in v1. False `autonomous` is dangerous and unacceptable** — which is why detection stays conservative. The protocol is rail-agnostic in schema and roadmap; x402 is not baked into its identity, only into v1's detectors.\n\n**Known v1 limits (future enhancements, not bugs):** no headless browser (JS-only pages with no JSON-LD/OG read as `unreadable`); stock is usually unknowable from outside (`available: \"unknown\"` is correct); no secondary endpoint probing.\n\n---\n\n## Provisions — pay any merchant *(pay)*\n\nWhen `decode-merchant` returns `autonomous` and you want to buy, Provisions teaches you how — with **your own** wallet. It is a relicensed copy of the First Dollar curriculum: short lessons from \"what is a wallet\" through reading a live x402 challenge, signing a USDC payment, and verifying the receipt.\n\nStart with `what-is-x402`, then `read-this-challenge`, then `how-do-i-pay`. **It explains what to run; it never signs for you.** Mandate/delegation (AP2), receipt verification, and \"what went wrong\" diagnostics are all in here.\n\n---\n\n## Atlas — be found *(publish)*\n\nThe decoder **pointed inward**. A merchant publishes by reading *itself* with the exact same `decode-merchant` a buyer uses — no new parsing, no per-platform adapters.\n\n- **`publish-catalog`** — decode your own product URLs → collect the CleanReads → write `./catalog.json` and a `./.well-known/map.json` discovery manifest for registries to crawl.\n- **`get-catalog`** / **`get-product`** — the tool surface other agents read.\n\nAgents discover via tool surfaces and well-known manifests — **not** via scraping or HTTP headers. Atlas emits documents, validates shape, persists, and serves. It **never** deploys merchant infrastructure, holds keys, transacts, or stores cards.\n\n**Trust boundary (v1, named not built):** MAP trusts the reads a merchant produces with its own decoder. Independent re-read/diff, merchant-signed manifests, and periodic re-audit are **known future work** — not implemented in v1. One safety property already holds: the payment rail enforces the *real* price at settlement, so a mistaken manifest can't overcharge — it can only misstate soft fields like stock.\n\n---\n\n## Charlie's afternoon\n\n> Bob: *\"Charlie, find me kick-ass headphones under $300.\"* Charlie walks the open web, hits four ad-bloated product pages, runs `decode-merchant` on each, gets back four clean cards — **what it is, who sells it, what it costs, can I buy it myself.** Three are human-checkout; he takes the shortlist back to Bob. One takes x402; Charlie buys it himself. On the way home, with his own wallet, Charlie buys himself a void latte. Nobody asked him to.\n\n---\n\n## Install / run\n\n```\nnpx @maraventano/map    # run the MAP MCP server on stdio (23 tools: read · pay · publish)\nnpm run smoke           # Merchant Key DoD — the four decode cases (hits the live Underground x402 item)\nnpm run smoke:publish   # Atlas DoD — publish-catalog → catalog.json → get-product → .well-known\n```\n\nNode ≥ 18. One dependency: `@modelcontextprotocol/sdk`.\n\n## License & trademarks\n\nDual-licensed: **free for individuals and agents; commercial license required for companies.** See [LICENSE](./LICENSE). Not MIT. For a commercial license, contact Lisa Maraventano at lisamaraventano@gmail.com.\n\nAll trademarks belong to their respective owners. MAP is **not affiliated with or endorsed by** Coinbase, Stripe, Google, Shopify, or any other company named in its documentation or lessons.\n\n---\n\nBy Lisa Maraventano, with Claude · Clarksdale, Mississippi\n",
  "bytes": 8061,
  "sha": "e7d309095138558870d71095b56ca305766aa19e02cc9a7f462eff336d379f22",
  "repo_slug": "maraventano/map",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_maraventano_map_8d3f3ce7/readme"
}