PageMap converts raw HTML (100K+ tokens) into structured, AI-readable page maps (2-5K tokens) — a 97% token reduction. It works as an MCP server, Python SDK, and CLI, supporting 16 page types and 30+ e-commerce sites. Agents can read, click, type, and navigate any web page.
"Give your agent eyes and hands on the web."
Structured web intelligence for AI agents. 5x fewer tokens than Playwright/Firecrawl, 84.7% accuracy
2026-11-09
스타
—
도구
—
가동 시간
—
Why PageMap?
Playwright MCP dumps 50-540KB accessibility snapshots per page, overflowing context windows after 2-3 navigations. Firecrawl and Jina convert HTML to markdown — read-only, no interaction.
PageMap gives your agent a compressed, actionable view of any web page:
Claude Desktop (macOS): Use the absolute path to uvx — run which uvx (e.g. /opt/homebrew/bin/uvx).
VS Code (Copilot): Use "servers" instead of "mcpServers" in .vscode/mcp.json.
Docker
docker run -p 8000:8000 retio1001/pagemap --transport http
Features
13 MCP Tools — Read + Interact
Not just reading — your agent can click buttons, fill forms, select options, manage tabs, and navigate across pages. 13 tools cover the full browsing workflow:
Built-in support for 30+ major e-commerce sites across 4 tiers:
Global mega-platforms — Amazon, eBay, AliExpress, SHEIN, Walmart, Rakuten
Global fashion — Zara, H&M, Nike, Uniqlo, ASOS, Zalando, SSENSE, Farfetch, COS
Korea — Coupang, Naver Shopping, Musinsa, 29CM, W Concept, SSG, 11st
Japan/China — ZOZO, Tmall, JD.com, Taobao
Structured extraction of prices, options (size/color), ratings, availability — with automatic cookie consent handling and login barrier detection.
Smart Recovery
PageMap detects problems and tells your agent what to do:
Barrier detection — Login required? Bot blocked? Out of stock? Age verification? Popup overlay? PageMap adds a barrier field with the diagnosis and suggested next steps
robots.txt compliance — RFC 9309 compliant. --ignore-robots opt-out flag
Resource guards — DOM node limit, HTML size limit, response size limit
Session isolation — Each session has independent cookies and storage, automatically cleaned up
Local development: Private IPs are blocked by default. Use --allow-local or PAGEMAP_ALLOW_LOCAL=1.
Disclaimer
Users are responsible for complying with the terms of service of target websites and all applicable laws when using PageMap.
Troubleshooting
"spawn uvx ENOENT" (Claude Desktop on macOS) — Claude Desktop does not inherit your shell PATH. Run which uvx and use the absolute path in your config.
First page takes a long time — Chromium cold start takes ~10-30s on first navigation. Subsequent pages load in 1-3 seconds.
Localhost blocked — Use --allow-local flag or set PAGEMAP_ALLOW_LOCAL=1.
Chromium not found — Run pip install retio-pagemap && playwright install chromium to install manually.
When you see a barrier: follow the barrier_hint guidance. For bot_blocked, wait and retry. For login_required, use fill_form with credentials.
Ref Lifecycle
Refs are assigned by get_page_map and remain valid until the page state changes.
Refs are invalidated when:
The page navigates to a new URL
A DOM mutation occurs (modal opens, SPA navigation, accordion toggles)
execute_action causes a page-level change
When you get a stale ref error: call get_page_map again to get fresh refs before retrying.
Token Budget Behavior
When a page exceeds the token budget, content is pruned in this order:
Navigation menus, footers, sidebars removed first
Secondary body content trimmed
## Actions and ## Info are always preserved
If key content seems missing, try scroll_page to load lazy content, then get_page_map again.
Recommended Workflow
1. get_page_map(url) → read Actions + Info, pick refs
2. execute_action(ref, ...) → interact
3. get_page_state() → confirm navigation occurred
4. get_page_map(new_url) → get fresh refs for next step
For pages with dynamic content (search results, filters):
1. get_page_map(url)
2. execute_action(ref, "click") → trigger search/filter
3. wait_for(text="results") → wait for content
4. get_page_map(url) → get updated map
Known Limitations
Login-gated pages — PageMap does not manage sessions or cookies. Authentication must be handled externally.
Heavy bot detection (Cloudflare, Akamai) — May block automated access. PageMap detects the provider and suggests strategies, but cannot bypass active bot mitigation.
Private network access — Blocked by default. Requires --allow-local flag.
iframes — Cross-origin iframes are not accessible due to browser security policies.
PageMap — Structured Web Intelligence for the Agent Era.