SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentsRetio-pagemap

Retio-pagemap

Compress web page HTML into compact structured maps that preserve actionable elements, so agents can read and interact with pages using fewer tokens.

Open website

About this tool

Purpose

PageMap is designed to solve the context window overflow problem when agents browse web pages. Playwright MCP outputs 50-540KB of accessibility snapshots per page, which blows up the context window after 2-3 navigations; although Firecrawl and Jina can convert HTML to markdown, they only support read-only access and cannot interact. PageMap converts raw HTML (over 100,000 tokens) into a structured, AI-readable page map (2-5K tokens), achieving about 97% token reduction, allowing agents to read and operate web pages with fewer tokens.

Main Capabilities

  • 13 MCP tools: Covering the complete browsing workflow, including get_page_map, execute_action, fill_form, scroll_page, wait_for, take_screenshot, get_page_state, navigate_back, batch_get_page_map, open_tab, switch_tab, list_tabs, close_tab. Agents can not only read, but also click buttons, fill out forms, select options, manage tabs, and navigate across pages.
  • Automatic detection of 16 page types: product_detail, listing, search_results, article, news, video, login, form, checkout, dashboard, help_faq, settings, error, documentation, landing, blocked, with optimized extraction applied for each type.
  • Deep e-commerce coverage: Built-in support for more than 30 major e-commerce websites, divided into four tiers—large global platforms (Amazon, eBay, AliExpress, SHEIN, Walmart, Rakuten), global fashion (Zara, H&M, Nike, Uniqlo, ASOS, Zalando, SSENSE, Farfetch, COS), South Korea (Coupang, Naver Shopping, Musinsa, 29CM, W Concept, SSG, 11st), Japan/China (ZOZO, Tmall, JD.com, Taobao). It can structurally extract prices, options (size/color), ratings, stock status, and automatically handle cookie consent and login barrier detection.
  • Barrier detection and prompts: Detects issues such as login requirements, bot blocking, out of stock, age verification, popup overlays, and adds a barrier field to provide diagnosis and suggested next steps.
  • Automatic cookie consent dismissal: Automatically detects 7 CMP providers (Cookiebot, OneTrust, TrustArc, Didomi, Quantcast, Usercentrics, and a generic fallback), using a 5-level dismissal cascade: CMP JS API → Reject → Accept → Dismiss → Close symbol, with a default GDPR reject-first policy.
  • Popup overlay detection: Two-stage detection based on AX tree role="dialog" and HTML regex, automatically closing promotional popups (such as newsletter, exit-intent).
  • Bot detection awareness: Identifies Cloudflare, Turnstile, reCAPTCHA, hCaptcha, and Akamai, reports the provider, and suggests wait/retry strategies.
  • Stale reference recovery: When DOM changes cause references to become invalid, returns clear guidance to re-fetch.
  • Content intelligence: Supports 8 JSON-LD schemas (Product, NewsArticle, VideoObject, FAQPage, Event, LocalBusiness, BreadcrumbList, ItemList); extracts metadata such as price, rating, reviews, description, images from structured data and DOM fallbacks; two-layer caching (cache hit about 10ms, content refresh about 500ms, full rebuild about 1.5s), with diff-based updates for unchanged parts; an optional to_delta_packet() serializer outputs summary-bound evidence units, claim candidates, sources, and authority flags for downstream memory/review systems, without changing the default MCP output.
  • Localization: Automatically detects language locale from the URL and adjusts token budgets for CJK text.

Usage

PageMap can be used as an MCP server, Python SDK and CLI usage. The default mode is a local MCP server, requiring no server setup. Chromium is installed automatically on first use, so there is no need to manually run playwright install.

MCP client configuration: can be added to Claude Code, Cursor, Windsurf, or Claude Desktop. Claude Desktop (macOS) requires the absolute path to uvx—run which uvx (for example /opt/homebrew/bin/uvx). VS Code (Copilot) uses "servers" instead of "mcpServers" in .vscode/mcp.json.

Docker images: multi-architecture images (amd64/arm64) are available on Docker Hub and GitHub Container Registry.

Offline processing (no browser): specific command details are not yet provided.

Use cases

  • Automation tasks where an agent needs to read and operate web pages (clicking, filling forms, navigating).
  • Extraction of structured data such as e-commerce prices, options, ratings, and inventory.
  • Web browsing agents that need to control token consumption.
  • Complex page scenarios that require handling cookie consent, pop-ups, login barriers, and similar issues.

Limitations

  • Login-restricted pages: PageMap does not manage sessions or cookies; authentication must be handled externally.
  • Strong bot detection (Cloudflare, Akamai): may block automated access. PageMap can detect the provider and suggest strategies, but cannot bypass active bot mitigation measures.
  • Private network access: blocked by default; use the --allow-local flag or set PAGEMAP_ALLOW_LOCAL=1.
  • iframes: cross-origin iframes are inaccessible due to browser security policies.
  • Users must comply with the target website's terms of service and all applicable laws themselves.

Security

PageMap treats all web page content as untrusted input: multi-layered SSRF defense; prompt injection defense (content boundaries, role prefix stripping, suspicious content marking); RFC 9309-compliant robots.txt compliance (can be disabled with --ignore-robots); resource guards (DOM node limits, HTML size limits, response size limits); session isolation (each session has independent cookies and storage, automatically cleaned up).

License and pricing

The local (STDIO) mode is permanently free, self-hosted, and open source under AGPL-3.0. The cloud API is a managed multi-tenant server with authentication, rate limiting, and credit-based billing; contact retio1001@retio.ai to obtain access. For commercial licensing options, contact the same email.

Troubleshooting

  • "spawn uvx ENOENT" (Claude Desktop on macOS): Claude Desktop does not inherit the shell PATH; run which uvx and use the absolute path in the configuration.
  • Slow homepage loading: Chromium cold start takes about 10-30 seconds for the first navigation, and subsequent pages take 1-3 seconds.
  • localhost is blocked: use the --allow-local flag or set PAGEMAP_ALLOW_LOCAL=1.
  • Chromium not found: run pip install retio-pagemap && playwright install chromium to install it manually.

Related tools

Browse category