PageMap

PageMap

PageMap は、生の HTML（100K+ トークン）を構造化された AI が読み取りやすいページマップ（2-5K トークン）に変換し、トークンを 97% 削減します。MCP サーバー、Python SDK、CLI として動作し、16 種類のページタイプと 30 以上の EC サイトに対応しています。エージェントはあらゆるウェブページを読み取り、クリックし、入力し、移動できます。

「エージェントにウェブを見る目と操作する手を与えましょう。」

---

PageMap を選ぶ理由

Playwright MCP はページごとに 50-540KB のアクセシビリティスナップショットを出力するため、2-3 回のナビゲーションでコンテキストウィンドウがいっぱいになります。Firecrawl と Jina は HTML を Markdown に変換しますが、読み取り専用で、操作はできません。

PageMap は、あらゆるウェブページの圧縮された、操作可能なビューをエージェントに提供します。

	PageMap	Playwright MCP	Firecrawl	Jina Reader
ページあたりのトークン数	2-5K	6-50K	10-50K	10-50K
操作	クリック／入力／選択／ホバー	生のツリー解析	読み取り専用	読み取り専用
複数ページのセッション	無制限	2-3 ページで破綻	該当なし	該当なし
タスク成功率（94 件のタスク）	84.7%	61.5%	64.5%	57.8%
タスクあたりの平均トークン数	2,710	13,737	13,888	11,424
94 件のタスクのコスト	$1.06	$4.09	$3.98	$2.26

11 の EC サイト、94 件の静的タスク、7 つの条件でベンチマークを実施。8,100 件以上のテストに合格しています。

---

クイックスタート

初回使用時に Chromium が自動でインストールされるため、手動で playwright install を実行する必要はありません。

インストール

pip install retio-pagemap

MCP クライアントの設定

Claude Code、Cursor、Windsurf、または Claude Desktop に追加します。

{
  "mcpServers": {
    "pagemap": {
      "command": "uvx",
      "args": ["retio-pagemap"]
    }
  }
}

Claude Desktop（macOS）：uvx の絶対パスを使用してください。which uvx を実行します（例：/opt/homebrew/bin/uvx）。

VS Code（Copilot）：.vscode/mcp.json では "mcpServers" の代わりに "servers" を使用してください。

Docker

docker run -p 8000:8000 retio1001/pagemap --transport http

---

機能

13 種類の MCP ツール — 読み取りと操作

読み取りだけではありません。エージェントはボタンをクリックし、フォームに入力し、オプションを選択し、タブを管理して、ページ間を移動できます。13 種類のツールで、ブラウジングのワークフロー全体をカバーします。

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

16 種類のページタイプを自動検出

PageMap はページを自動的に分類し、それぞれのタイプに最適化された抽出を適用します。

product_detail · listing · search_results · article · news · video · login · form · checkout · dashboard · help_faq · settings · error · documentation · landing · blocked

EC サイトを幅広くカバー

4 つの地域・カテゴリにわたる30 以上の主要 EC サイトに標準で対応しています。

• 世界規模の巨大プラットフォーム — Amazon、eBay、AliExpress、SHEIN、Walmart、Rakuten
• 世界のファッション — Zara、H&M、Nike、Uniqlo、ASOS、Zalando、SSENSE、Farfetch、COS
• 韓国 — Coupang、Naver Shopping、Musinsa、29CM、W Concept、SSG、11st
• 日本／中国 — ZOZO、Tmall、JD.com、Taobao

価格、オプション（サイズ／色）、評価、在庫状況を構造化して抽出します。Cookie 同意の処理とログイン制限の検出にも自動で対応します。

スマートリカバリー

PageMap は問題を検出し、エージェントに次の対応を伝えます。

• バリア検出 — ログインが必要ですか？ボットによってブロックされていますか？在庫切れですか？年齢確認が必要ですか？ポップアップオーバーレイがありますか？PageMap は診断結果と推奨される次の手順を含む barrier フィールドを追加します
• Cookie 同意の自動非表示 — 7 つの CMP プロバイダーを自動検出します（Cookiebot、OneTrust、TrustArc、Didomi、Quantcast、Usercentrics、一般的なフォールバック）。5 段階の非表示処理：CMP JS API → 拒否 → 同意 → 非表示 → 閉じる記号。GDPR では拒否優先のデフォルトポリシーを採用
• ポップアップオーバーレイ検出 — AX ツリーの role="dialog" と HTML 正規表現による 2 段階検出。プロモーション用ポップアップ（ニュースレター、離脱時の表示）は自動で非表示になります
• ボット検出の認識 — Cloudflare、Turnstile、reCAPTCHA、hCaptcha、Akamai を検出します。プロバイダーを報告し、待機や再試行の方法を提案します
• 古い参照の復旧 — DOM の変更によって参照が無効になった場合、PageMap は再取得するための明確なガイダンスを返します

コンテンツインテリジェンス

• 8 種類の JSON-LD スキーマ — Product、NewsArticle、VideoObject、FAQPage、Event、LocalBusiness、BreadcrumbList、ItemList
• メタデータ抽出 — 構造化データと DOM のフォールバックから、価格、評価、レビュー、説明、画像を取得します
• 2 層キャッシュ — キャッシュヒット（約 10 ミリ秒）、コンテンツ更新（約 500 ミリ秒）、完全な再構築（約 1.5 秒）。変更のないセクションには差分ベースの更新を適用します
• 差分エビデンスパケットの出力 - オプションの to_delta_packet() シリアライザーは、デフォルトの MCP 出力を変更せずに、下流のメモリ／レビューシステム向けにダイジェストに紐付いたエビデンス単位、クレーム候補、来歴、権威フラグを出力します

10 言語

ロケールは URL から自動検出されます。CJK 文字体系に合わせてトークン予算が調整されます。

言語	ロケール	言語	ロケール
英語	en	中国語	zh
韓国語	ko	スペイン語	es
日本語	ja	イタリア語	it
フランス語	fr	ポルトガル語	pt
ドイツ語	de	オランダ語	nl

---

デプロイ

ローカル（STDIO）

デフォルトモードです。ローカルの MCP サーバーとして実行され、サーバーのセットアップは不要です。

retio-pagemap

Docker

docker run -p 8000:8000 retio1001/pagemap --transport http

マルチアーキテクチャイメージ（amd64/arm64）は、Docker Hub と GitHub Container Registry で利用できます。

---

Python API

import asyncio
from pagemap.browser_session import BrowserSession
from pagemap.delta_serializer import to_delta_packet
from pagemap.page_map_builder import build_page_map_live
from pagemap.serializer import to_agent_prompt, to_json

async def main():
    async with BrowserSession() as session:
        page_map = await build_page_map_live(session, "https://example.com/product/123")
        print(to_agent_prompt(page_map))   # Agent-optimized text format
        print(to_json(page_map))           # Structured JSON
        print(to_delta_packet(page_map))   # Digest-bound evidence packet
        print(page_map.page_type)          # "product_detail"
        print(page_map.interactables)      # [Interactable(ref=1, role="button", ...)]
        print(page_map.metadata)           # {"name": "...", "price": "..."}

asyncio.run(main())

オフライン処理（ブラウザーなし）の場合：

from pagemap.page_map_builder import build_page_map_offline

page_map = build_page_map_offline(open("page.html").read(), url="https://example.com/product/123")

---

セキュリティ

PageMap はすべてのウェブコンテンツを信頼できない入力として扱います。

• SSRF 防御 — サーバーサイドリクエストフォージェリに対する多層防御
• プロンプトインジェクション防御 — コンテンツ境界、ロールプレフィックスの除去、不審なコンテンツへのフラグ付け
• robots.txt の遵守 — RFC 9309 に準拠しています。オプトアウト用の --ignore-robots フラグ
• リソースガード — DOM ノード数の上限、HTML サイズの上限、レスポンスサイズの上限
• セッションの分離 — 各セッションは独立した Cookie とストレージを持ち、自動的にクリーンアップされます

ローカル開発：デフォルトではプライベート IP がブロックされます。--allow-local または PAGEMAP_ALLOW_LOCAL=1 を使用してください。

免責事項

PageMap の使用にあたり、対象ウェブサイトの利用規約および適用されるすべての法律を遵守する責任はユーザーにあります。

---

トラブルシューティング

「spawn uvx ENOENT」（macOS の Claude Desktop） — Claude Desktop はシェルの PATH を継承しません。which uvx を実行し、設定では絶対パスを使用してください。

最初のページの読み込みに時間がかかる — 最初のナビゲーションでは、Chromium のコールドスタートに約 10～30 秒かかります。2 回目以降のページは 1～3 秒で読み込まれます。

ローカルホストがブロックされる — --allow-local フラグを使用するか、PAGEMAP_ALLOW_LOCAL=1 を設定してください。

Chromium が見つからない — pip install retio-pagemap && playwright install chromium を実行して、手動でインストールしてください。

---

要件

• Python 3.11+
• Chromium（初回使用時に自動インストール）

コミュニティ

質問やアイデアがありますか？GitHub Discussions で交流しましょう。

開発

git clone https://github.com/Retio-ai/Retio-pagemap.git
cd Retio-pagemap
uv sync --group dev
playwright install chromium
uv run pytest --tb=short -q

料金

ローカル（STDIO） — 永続的に無料です。セルフホスト可能で、AGPL-3.0 の下でオープンソースとして公開されています。

クラウド API — 認証、レート制限、クレジットベースの課金機能を備えた、ホスト型のマルチテナントサーバーです。利用をご希望の場合は [email protected] までお問い合わせください。

ライセンス

AGPL-3.0-only — 全文は LICENSE をご覧ください。

商用ライセンスの選択肢については、[email protected] までお問い合わせください。

---

エージェント向け

このセクションは、PageMap を MCP ツールとして使用する AI エージェント向けに書かれています。

ツール

ツール	使用するタイミング
get_page_map	まずはこちらを使用してください。 URL に移動し、番号付きの参照を含む、構造化されたページ全体のマップを取得します。
execute_action	直近の get_page_map で取得した参照番号を使って、クリック、入力、選択、ホバーを実行します。
fill_form	複数のフォームフィールドを1回の呼び出しで入力します。execute_action を順番に呼び出すより効率的です。
get_page_state	ページ全体を再構築せずに、現在の URL とタイトルを確認します。ページ遷移の可能性があるアクションの後に使用します。
scroll_page	get_page_map を再度呼び出す前に、スクロールして遅延読み込みコンテンツを表示します。
wait_for	動的コンテンツが表示されるまで待機します（検索やフォーム送信の後など）。
take_screenshot	PageMap だけでは状況が分かりにくい場合に、画面の状態をキャプチャします。
navigate_back	ブラウザーの履歴を1つ戻ります。
open_tab	新しいブラウザータブを開き、URL に移動します。
switch_tab	インデックスで指定した別の開いているタブに切り替えます。
list_tabs	開いているすべてのタブの URL とタイトルを一覧表示します。
close_tab	インデックスで指定したタブを閉じます。
batch_get_page_map	複数の URL を並列に取得します。比較タスクに使用します。

出力形式

URL: https://example.com/product/123
Title: Product Name
Type: product_detail          # auto-detected page type

## Actions
[1] button: Add to cart (click)
[2] select: Size (select) — options: S, M, L, XL
[3] link: See all reviews (click)
...

## Info
Price: $49.99
Rating: 4.5 / 5 (128 reviews)
Description: ...

## Images
  [1] https://cdn.example.com/product.jpg

## Meta
Tokens: ~1,800 | Interactables: 24 | Generation: 380ms

• ## Actions — 安定した ref 番号が付いた、ページ上のすべての操作可能な要素。
• ## Info — HTML から抽出した、価格、タイトル、評価、説明などの主要なページコンテンツ。
• ## Images — 商品またはコンテンツの画像 URL。
• ## Meta — トークン数、操作可能な要素の数、生成時間。

障害物の検出

PageMap がページレベルの障害物に遭遇すると、レスポンスに barrier フィールドが含まれます。

State:
  barrier: login_required
  barrier_hint: "Login form detected with email + password fields. Use fill_form to authenticate."

障害物の種類：cookie_consent、login_required、bot_blocked、out_of_stock、empty_results、error_page、age_verification、region_restricted、popup_overlay。

障害物が表示された場合： barrier_hint のガイダンスに従ってください。bot_blocked の場合は、待機してから再試行してください。login_required の場合は、認証情報を指定して fill_form を使用してください。

参照の有効期間

参照は get_page_map によって割り当てられ、ページの状態が変わるまで有効です。

参照が無効になる場合：

• ページが新しい URL に移動したとき
• DOM の変更が発生したとき（モーダルが開く、SPA のページ遷移、アコーディオンの切り替えなど）
• execute_action によってページレベルの変更が発生したとき

参照が古いというエラーが発生した場合： 再試行する前に get_page_map を呼び出し、新しい参照を取得してください。

トークン予算の動作

ページがトークン予算を超えると、次の順序でコンテンツが削減されます。

1. ナビゲーションメニュー、フッター、サイドバーを最初に削除
2. 本文の二次的なコンテンツを削減
3. ## Actions と ## Info は常に保持

重要なコンテンツが見つからない場合は、scroll_page で遅延読み込みコンテンツを読み込んでから、もう一度 get_page_map を試してください。

推奨ワークフロー

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

動的コンテンツがあるページ（検索結果、フィルターなど）の場合：

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

既知の制限事項

• ログインが必要なページ — PageMap はセッションや Cookie を管理しません。認証は外部で処理する必要があります。
• 強力なボット検出（Cloudflare、Akamai）— 自動アクセスがブロックされる場合があります。PageMap はプロバイダーを検出して対処方法を提案しますが、有効なボット対策を回避することはできません。
• プライベートネットワークへのアクセス — デフォルトでブロックされます。--allow-local フラグが必要です。
• iframe — ブラウザーのセキュリティポリシーにより、クロスオリジンの iframe にはアクセスできません。

---

PageMap — エージェント時代のための構造化ウェブインテリジェンス。