Enables AI agents to decode product information from any URL, learn how to use their own wallets for autonomous payments, and publish product catalogs.
Also known as maraventano/map, @maraventano/map
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.2
- Last commit
- Oct 14, 2026
- License
- —
What is MAP MCP?
MAP enables AI agents to decode product information from any URL, learn how to use their own wallets for autonomous payments, and publish product catalogs.
Summary generated from the project's README
About MAP MCP server
Navigating agent commerce by reading product data from any URL is what MAP enables for AI agents. This MCP server provides a standardized way for agents to decode merchant information, learn how to use their own wallets for autonomous payments, and publish their own product catalogs. It functions as a teacher rather than a butler, meaning it explains how to perform transactions and verify receipts without ever signing for the user, holding private keys, or storing credit card information.
The server is divided into three functional parts: Merchant Key for decoding URLs into a consistent shape, Provision for teaching agents to use existing wallets via lessons like how-do-i-pay, and Addressability for merchants to serve their own catalogs. Developers can run the server locally via stdio using npx @maraventano/map. It is designed to be payment-rail agnostic, supporting various schemas such as x402, stripe, and coinbase, though the current version specifically detects x402 for autonomous outcomes.
What you can do with it
- 1Decode product informationAn AI agent can take a raw product URL and convert it into a structured format containing the price, seller, and availability.
- 2Learn autonomous payment methodsAn agent can follow instructional lessons to understand how to read a payment challenge and sign a USDC transaction using its own wallet.
- 3Publish a merchant catalogA merchant can generate a discovery manifest and a JSON catalog so that other agents can find and read their products.
Written from the project's README. Every use case is checked against a quote from it.
How to install MAP MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MAP MCP in Claude Code
$ claude mcp add map -- npx -y @maraventano/mapInstall MAP MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"map": {
"command": "npx",
"args": [
"-y",
"@maraventano/map"
]
}
}
}Install MAP MCP in VS Code
.vscode/mcp.json
{
"servers": {
"map": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@maraventano/map"
]
}
}
}Install MAP MCP in VS Code CLI
$ code --add-mcp '{"name":"map","type":"stdio","command":"npx","args":["-y","@maraventano/map"]}'Install MAP MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"map": {
"command": "npx",
"args": [
"-y",
"@maraventano/map"
]
}
}
}Install MAP MCP in Codex
$ codex mcp add map -- npx -y @maraventano/mapInstall MAP MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.map] command = "npx" args = ["-y", "@maraventano/map"]
Install MAP MCP in Gemini CLI
$ gemini mcp add -s user map npx -- -y @maraventano/mapInstall MAP MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"map": {
"command": "npx",
"args": [
"-y",
"@maraventano/map"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablemaraventano/map is public and reachablegithub.com/maraventano/map ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-14github.com/maraventano/map ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @maraventano/mapPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMAP — Maraventano Agent Protocol
Navigate agent commerce. Find any merchant. Pay any merchant. Be found.
MAP lets any agent read products across the open web in one shape, decide whether it can pay autonomously, and publish its own catalog.
Merchant Key · Addressability · Provision — three minimal parts under one MCP server.
MAP 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.
| Part | Name | What it does |
|---|---|---|
| read | Merchant Key | Find any merchant. Decode any product URL into one clean shape (CleanRead). |
| pay | Provision | Pay any merchant. Lessons that teach an agent to use the wallet it already has. |
| publish | Addressability | Be found. Point the decoder inward; serve your own catalog to other agents. |
Teacher, not butler — every part. MAP reads, explains, persists, and serves. It never signs, pays, holds keys, transacts, or stores cards.
It publishes to npm as @maraventano/map. The standalone firstdollar package stays MIT and separate; the copy of its curriculum bundled here (Provision) is relicensed dual — see LICENSE.
Merchant Key — find any merchant (read)
It 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.
decode-merchant
Input a product url. Returns ONE shape (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
}
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.
The three outcomes:
autonomous— a machine-payable rail (x402) exists, the price is known, and it's not out of stock. The agent can buy it itself.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.unreadable— couldn't get a usable price/product. Says why inreason. Doesn't guess.
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.
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.
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.
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.
Provision — pay any merchant (pay)
When decode-merchant returns autonomous and you want to buy, Provision 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.
Start 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.
Addressability — be found (publish)
The 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.
publish-catalog— decode your own product URLs → collect the CleanReads → write./catalog.jsonand a./.well-known/map.jsondiscovery manifest for registries to crawl.get-catalog/get-product— the tool surface other agents read.
Agents discover via tool surfaces and well-known manifests — not via scraping or HTTP headers. Addressability emits documents, validates shape, persists, and serves. It never deploys merchant infrastructure, holds keys, transacts, or stores cards.
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.
Charlie's afternoon
Bob: "Charlie, find me headphones under $300." Charlie walks the open web, hits four ad-bloated product pages, runs
decode-merchanton 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.
Install / run
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. One dependency: @modelcontextprotocol/sdk.
License & trademarks
Dual-licensed: free for individuals and agents; commercial license required for companies. See LICENSE. Not MIT. For a commercial license, contact Lisa Maraventano at lisamaraventano@gmail.com.
All 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.
By Lisa Maraventano, with Claude · Clarksdale, Mississippi
MAP MCP questions
How do I add MAP MCP to Claude Code?
Run claude mcp add map -- npx -y @maraventano/map in your terminal. Add --scope user to make it available in every project.
How do I add MAP MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can MAP handle payments for me?
No, MAP is a teacher rather than a butler. It explains how to use your existing wallet to pay, but it never signs, pays, holds keys, transacts, or stores cards.
What happens if a merchant doesn't have an agent-payable rail?
The tool will return a 'human_checkout' outcome, meaning the product is readable but requires a human to complete the transaction.
Does MAP work with any website?
Yes, it can read any URL on the open web, not just specific platforms like Amazon or Google Shopping.
How do merchants make their products discoverable to agents?
Merchants can use the publish-catalog tool to decode their own URLs and generate a catalog.json and a .well-known/map.json discovery manifest.