Charlotte

Charlotte

Web を、読みやすく。

AI エージェントが Hacker News のトップページを見るだけでアクセシビリティツリーを約 50,000 文字消費するところを、Charlotte なら 364 文字で済みます。

Charlotte は、AI エージェントが構造化されたトークン効率の高い方法で Web にアクセスできるようにする MCP サーバーです。毎回アクセシビリティツリー全体を出力する代わりに、Charlotte はエージェントに必要な情報だけを返します。ページを開いた際の簡潔な概要、特定の要素を対象としたクエリ、そして明示的に要求された場合にのみ詳細全体を返します。コンテンツの多いページでは、この概要は Playwright MCP のアクセシビリティツリー全体のスナップショットより最大約 140 倍小さくなります。非常に小さなページでは、両者のサイズはほぼ同じです。

Charlotte を選ぶ理由

ほとんどのブラウザー MCP サーバーは、呼び出しのたびにアクセシビリティツリー全体を出力します。これは平坦なテキストの塊で、コンテンツの多いページでは 100 万文字を超えることがあります。エージェントは必要かどうかにかかわらず、そのすべての処理コストを負担します。

Charlotte は各ページを、ランドマーク、見出し、インタラクティブ要素、フォーム、コンテンツの概要などを含む、型付きの構造化表現に分解します。そして、3 段階の詳細レベルを使って、エージェントが受け取る情報量を制御できるようにします。エージェントが新しいページに移動すると、要素の全出力（約 50,000 文字）ではなく、簡潔な概要（Hacker News なら 364 文字）を受け取ります。詳細が必要な場合は、それを要求します。

ベンチマーク

Charlotte v0.8.0 と Playwright MCP v0.0.79 を比較し、実際のウェブサイトでツール呼び出しごとに返される文字数を測定しました（npx tsx benchmarks/run-benchmarks.ts --suite comparison）。測定日は2026-08-08です。このセクションは概要です。タスクごとのコストやリリースによる変動を含む正式なベンチマークページはcharlotte.mintlify.site/benchmarks、手法、測定ツール、生データはbenchmarks/をご覧ください。

初期把握のコスト（ページにアクセスしたエージェントが「ページを把握」するために必要なコスト）：

Charlotte の navigate は、ページ領域ごとにまとめたランドマーク、見出し、インタラクティブ要素の数を含む、実用的な初期把握情報を標準で返します。Playwright MCP で同等の情報を得るには、エージェントは完全なアクセシビリティツリーを返す browser_snapshot を呼び出します。（Playwright の browser_navigate だけでは短い確認メッセージしか返されず、ページの内容は含まれないため、同等の比較にはなりません。）

サイト	Charlotte navigate	Playwright browser_snapshot	削減率
example.com	415	465	1.1倍
httpbin form	619	1,847	3.0倍
GitHub repo	3,778	38,983	10倍
Wikipedia (AI article)	22,134	1,137,928	51倍
Hacker News	364	50,706	139倍

ページが複雑になるほど、この優位性は大きくなります。コンテンツの多いページでは、構造化された初期把握情報は完全なスナップショットよりも約10～140倍小さくなります。一方、example.com のような非常に小さなページでは両者の差は約20％以内です（これほど小さなページでは、構造化表現のほうが大きくなる場合もあります。要約して取り除くものがそもそもないためです）。Charlotte の価値が発揮されるのは、まさに Playwright のフラットな出力が最も負担になる場面です。エージェントが初期把握情報以上を必要とする場合は、ツリー全体のコストを先払いするのではなく、必要な部分だけを observe または find で呼び出します。

ツール定義のオーバーヘッド（API 呼び出しごとに発生する見えないコスト）：

プロファイル	ツール数	呼び出しあたりの定義トークン数	full との比較
full	43	8,500	—
browse (default)	23	4,372	約49％削減
core	7	2,186	約75％削減

ツール定義は API のラウンドトリップごとに送信されます。標準の browse プロファイルでは、Charlotte の定義オーバーヘッドは43個のツールすべてを読み込む場合より約49％少なく、最小構成の core プロファイルでは約75％削減されます。詳しい結果はプロファイルベンチマークレポートをご覧ください。

ワークフローの違い： Hacker News を見るたびに、Playwright エージェントは見出しを読む場合もログインボタンを探す場合も、約50,000文字の完全なスナップショットを受け取ります。Charlotte エージェントはページにアクセスした際に364文字を受け取り、必要な情報だけを取得するため find({ type: "link", text: "login" }) を呼び出すので、残りの情報にコストを払うことはありません。

仕組み

Charlotte は永続的なヘッドレス Chromium セッションを維持し、視覚的なウェブとテキストを基盤とするエージェントの推論との間の変換レイヤーとして機能します。すべてのページは、構造化された表現に分解されます。

┌─────────────┐     MCP Protocol     ┌──────────────────┐
│   AI Agent  │<────────────────────>│    Charlotte     │
└─────────────┘                      │                  │
                                     │  ┌────────────┐  │
                                     │  │  Renderer  │  │
                                     │  │  Pipeline  │  │
                                     │  └─────┬──────┘  │
                                     │        │         │
                                     │  ┌─────▼──────┐  │
                                     │  │  Headless  │  │
                                     │  │  Chromium  │  │
                                     │  └────────────┘  │
                                     └──────────────────┘

エージェントが受け取るのは、ランドマーク、見出し、型付きメタデータを備えたインタラクティブ要素、境界ボックス、フォーム構造、コンテンツの要約です。これらはすべて、ブラウザーが各ページについてすでに把握している情報から導き出されます。

機能

ナビゲーション — navigate、back、forward、reload

観察 — observe（3 段階の詳細レベル、構造ツリービュー）、find（空間検索＋セマンティック検索、CSS セレクターモード、大量の検索結果向けの output_file）、screenshot（永続的なアーティファクト管理機能付き）、screenshots、screenshot_get、screenshot_delete、diff（スナップショットとの構造比較）

操作（iframe 対応）— click、click_at（座標ベース）、type（低速入力に対応）、select、toggle、submit、scroll、hover、drag、key（要素指定での単一キー／キー列）、wait_for（非同期条件のポーリング）、upload（ファイル入力）、fill_form（フォームへの一括入力）、dialog（JS ダイアログの承認／却下）

モニタリング — console（すべての重大度レベル、フィルタリング、タイムスタンプ）、requests（HTTP 履歴全体、メソッド／ステータス／リソースタイプによるフィルタリング）

セッション管理 — tabs、tab_open、tab_switch、tab_close、viewport（汎用プリセット、または DPR、タッチ、ユーザーエージェントのエミュレーションに対応した「iPhone 15」などのデバイス名）、network（帯域制限、URL ブロック）、set_cookies、get_cookies、clear_cookies、set_headers、configure

開発モード — dev_serve（自動リロード機能付きの静的サーバー＋ファイル監視）、dev_inject（CSS／JS の挿入）、dev_audit（アクセシビリティ、パフォーマンス、SEO、コントラスト、リンク切れの監査）

ユーティリティ — evaluate（ページコンテキストで任意の JS を実行）

ツールプロファイル

Charlotte には 43 個のツール（登録済みツール 42 個と charlotte_tools メタツール）が含まれていますが、多くのワークフローで必要なのはその一部だけです。起動プロファイルではエージェントのコンテキストに読み込むツールを制御でき、定義によるオーバーヘッドを最大約 75% 削減できます。

charlotte --profile browse    # 23 tools (default) — navigate, observe, interact, tabs
charlotte --profile core      # 7 tools — navigate, observe, find, click, type, submit
charlotte --profile full      # 43 tools — everything
charlotte --profile interact  # 31 tools — full interaction + dialog + evaluate
charlotte --profile develop   # 34 tools — interact + dev_serve, dev_inject, dev_audit
charlotte --profile audit     # 14 tools — navigation + observation + dev_audit + viewport

エージェントは再起動せずに、セッションの途中でツールを追加で有効化できます。

charlotte_tools enable dev_mode    → activates dev_serve, dev_audit, dev_inject
charlotte_tools disable dev_mode   → deactivates them
charlotte_tools list               → see what's loaded

セルフホスティング（Charlotte Remote）

Charlotte をリモート MCP サーバーとして実行し、claude.ai に接続します。コマンドは 1 つだけです。

docker run --cap-add SYS_ADMIN --shm-size 2g -p 3737:3737 ghcr.io/ticktockbent/charlotte

公開コネクター URL とオペレータートークンが表示されます。claude.ai で、 Settings → Connectors → Add custom connector を開き、URL を貼り付けます。OAuth Client ID／Secret のフィールドは空欄のままにし、Charlotte の同意ページが表示されたらトークンを入力してください。これで閲覧を開始できます。

デモ URL とトークンは一時的なもので、再起動時にどちらも変更されます。 実際に運用する場合の、安定したドメイン、ご自身のトンネルまたはリバースプロキシ、docker compose については、 セルフホスティングをご覧ください。信頼モデルとネットワークガードについては、 セキュリティをご覧ください。コンテナーとサンドボックスの内部については、 Dockerをご覧ください。

クイックスタート

前提条件

• Node.js >= 20
• npm

インストール

Charlotte はMCP Registryに io.github.TickTockBent/charlotte として掲載され、npm では @ticktockbent/charlotte として公開されています。

npm install -g @ticktockbent/charlotte

Docker イメージは Docker Hub と GitHub Container Registry で入手できます。

# Alpine (default, smaller)
docker pull ticktockbent/charlotte:alpine

# Debian (if you need glibc compatibility)
docker pull ticktockbent/charlotte:debian

# Or from GHCR
docker pull ghcr.io/ticktockbent/charlotte:latest

または、ソースからインストールします。

git clone https://github.com/ticktockbent/charlotte.git
cd charlotte
npm install
npm run build

実行

Charlotte は MCP プロトコルを使用して stdio 経由で通信します。

# If installed globally (default browse profile)
charlotte

# With a specific profile
charlotte --profile core

# If installed from source
npm start

MCP クライアントの設定

Claude Code

プロジェクトのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "charlotte": {
      "type": "stdio",
      "command": "npx",
      "args": ["@ticktockbent/charlotte"],
      "env": {}
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

VS Code (Copilot)

.vscode/mcp.json に追加します。

{
  "servers": {
    "charlotte": {
      "type": "stdio",
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Cline

Cline の MCP 設定に追加します（Cline サイドバー > MCP Servers > Configure から）。

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Amp

~/.amp/settings.json に追加します。

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

開発モード、汎用 MCP クライアント、検証手順、トラブルシューティングを含む設定ガイドの全文については、docs-internal/mcp-setup.mdをご覧ください。

設定

Charlotte は、優先度の高い順に CLI 引数 → 環境変数 → 設定ファイル → 組み込みのデフォルト値 の4つのソースから設定を解決します。完全なリファレンスは docs/configuration.md を参照してください。

設定ファイル

--config で JSON 設定ファイルを指定するか、作業ディレクトリに charlotte.config.json を置くと、Charlotte が自動的に読み込みます。

charlotte --config charlotte.config.json

{
  "browser": { "headless": true, "noSandbox": false },
  "tools": { "profile": "browse" },
  "rendering": { "includeIframes": false, "iframeDepth": 3 },
  "output": { "dir": "./charlotte-output" },
  "limits": {
    "maxInteractiveElements": 2000,
    "maxFullContentChars": 200000,
    "maxResponseBytes": 1000000,
    "maxEvaluateBytes": 256000
  }
}

各セクションはすべて省略可能で、空の {} も有効です。このファイルは zod で検証されます。不明なキー、型の誤り、無効な列挙値がある場合は、stderr に明確な起動エラーが出力され、Charlotte はゼロ以外の終了コードで終了します。4つの設定には環境変数も用意されています：CHARLOTTE_NO_SANDBOX、CHARLOTTE_OUTPUT_DIR、CHARLOTTE_CDP_ENDPOINT、CHARLOTTE_INIT_SCRIPT。ページの JavaScript より前にすべての新しいドキュメントで実行するスクリプトは、browser.initScripts または --init-script <path>（複数回指定可能）に設定します。初期化スクリプトを参照してください。

Chromium サンドボックスはデフォルトで有効です

v0.7.0 の動作変更： 以前のリリースでは、すべての Chromium の起動時に --no-sandbox が組み込まれていました。v0.7.0 以降、Chromium サンドボックスはデフォルトで有効です。これは、信頼できないページと Charlotte が実行されるアカウントとの間を守る主な防御策です。カーネルサンドボックスを利用できない環境では、明示的に無効にする必要があります。

charlotte --no-sandbox                  # CLI flag
CHARLOTTE_NO_SANDBOX=1 charlotte        # environment variable
# or "browser": { "noSandbox": true }   in the config file

移行に関する注意（Docker／ベアメタル）： コンテナでは通常、カーネルサンドボックスを設定できないため、付属の Dockerfile は CHARLOTTE_NO_SANDBOX=1 を設定します。また、docker-compose.yml は Docker のデフォルトの seccomp フィルターを維持するようになりました（seccomp=unconfined では実行されなくなりました）。Charlotte をベアメタル環境で root として実行すると、Chromium はサンドボックスが有効な状態では起動を拒否します。root 以外のユーザーで実行する（推奨）か、--no-sandbox を指定してください。暗黙の --no-sandbox に依存していた既存の設定で、サンドボックスを初期化できない環境で実行する場合は、引き続き動作させるために CHARLOTTE_NO_SANDBOX=1（または同等のフラグ／設定）を指定する必要があります。

Charlotte Remote（HTTP モード）をネットワーク経由で実行すると、サンドボックスに加えて、信頼境界やネットワークガードに関する検討事項が生じます。セキュリティを参照してください。

出力サイズの上限

limits.* キーは、1回のツール応答で返せる量を制限します。これにより、極端なページ（リンクが10万件あるページ、無限スクロールのフィード、巨大なドキュメント本文）によってエージェントのコンテキストウィンドウがあふれるのを防ぎます。ページの応答が maxResponseBytes を超えると、簡潔な要約に切り替わり、output_file を使って結果全体をディスクに書き込むよう提案します。charlotte_evaluate の結果は maxEvaluateBytes で個別に上限が設定されます。切り捨てられた応答には truncation マーカーが付きます。キーとデフォルト値については、docs/configuration.md を参照してください。

クラッシュからの復旧

Chromium がクラッシュしても、サーバーが応答不能になることはなくなりました。次のツール呼び出し時にブラウザーが自動的に再起動し、終了したタブと CDP セッションのキャッシュがクリアされ、新しい空白のタブが開きます。そのため、レンダラーがクラッシュしても MCP サーバーを再起動せずに、エージェントは作業を続けられます。

使用例

接続すると、エージェントは Charlotte のツールを使用できます。

ウェブサイトを閲覧する

navigate({ url: "https://example.com" })
// → 612 chars: landmarks, headings, interactive element counts

find({ type: "link", text: "More information" })
// → just the matching element with its ID

click({ element_id: "lnk-a3f1c2" })

フォームに入力する

navigate({ url: "https://httpbin.org/forms/post" })
find({ type: "text_input" })
type({ element_id: "inp-c7e29b", text: "[email protected]" })
select({ element_id: "sel-e8a3f5", value: "option-2" })
submit({ form_id: "frm-b1d4e7" })

ローカル開発のフィードバックループ

dev_serve({ path: "./my-site", watch: true })
observe({ detail: "full" })
dev_audit({ checks: ["a11y", "contrast"] })
dev_inject({ css: "body { font-size: 18px; }" })

ページの表現

Charlotte は、エージェントがコンテキストの消費量を調整できるよう、詳細度が3段階の構造化された表現を返します。

最小（navigate のデフォルト）

ページ領域ごとに分類されたランドマーク、見出し、インタラクティブ要素の件数です。すべての要素を列挙せずに、「このページには何がありますか？」を把握するためのものです。

{
  "url": "https://news.ycombinator.com",
  "title": "Hacker News",
  "viewport": { "width": 1280, "height": 720 },
  "structure": {
    "headings": [{ "level": 1, "text": "Hacker News", "id": "hdg-a1b2c3" }]
  },
  "interactive_summary": {
    "total": 93,
    "by_landmark": {
      "(page root)": { "link": 91, "text_input": 1, "button": 1 }
    }
  }
}

要約（observe のデフォルト）

型付きメタデータを含むインタラクティブ要素の全リスト、フォーム構造、コンテンツの要約です。

{
  "url": "https://example.com/dashboard",
  "title": "Dashboard",
  "viewport": { "width": 1280, "height": 720 },
  "structure": {
    "landmarks": [
      { "id": "rgn-b2c1d0", "role": "banner", "label": "Site header", "bounds": { "x": 0, "y": 0, "w": 1280, "h": 64 } },
      { "id": "rgn-d4e5f6", "role": "main", "label": "Content", "bounds": { "x": 240, "y": 64, "w": 1040, "h": 656 } }
    ],
    "headings": [{ "level": 1, "text": "Dashboard", "id": "hdg-1a2b3c" }],
    "content_summary": "main: 2 headings, 5 links, 1 form"
  },
  "interactive": [
    {
      "id": "btn-a3f1c2",
      "type": "button",
      "label": "Create Project",
      "bounds": { "x": 960, "y": 80, "w": 160, "h": 40 },
      "state": {}
    }
  ],
  "forms": []
}

完全

要約のすべての情報に加え、ページ上で表示されているすべてのテキストコンテンツを含みます。

詳細レベル

レベル	トークン数	用途
minimal	~50-200	ナビゲーション後の概要把握。どの領域があるか？インタラクティブ要素はいくつあるか？
summary	~500-5000	ページ上での作業。すべての要素の一覧、フォーム構造、コンテンツの概要。
full	可変	ページコンテンツの閲覧。表示されているテキストをすべて含みます。

ナビゲーションツールのデフォルトは minimal です。observe ツールのデフォルトは summary です。どちらも、オプションの detail パラメーターで上書きできます。

要素 ID

要素 ID は、軽微な DOM の変更があっても安定しています。要素の種類、ARIA ロール、アクセシブルネーム、DOM パスのシグネチャを組み合わせたキーをハッシュ化して生成されます。

btn-a3f1c2  (button)    inp-c7e29b  (text input)
lnk-d4b910  (link)      sel-e8a3f5  (select)
chk-f1a204  (checkbox)  frm-b1d4e7  (form)
rgn-e0d2a8  (landmark)  hdg-0f4063  (heading)
dom-b2c3d9  (DOM element, from CSS selector queries)

v0.7.0 の ID 形式変更： 要素 ID のハッシュは、以前のリリースの 4 文字から 6 桁の 16 進数（例：btn-a3f1c2）になりました。これにより、大きなページで要素間のハッシュ衝突が大幅に減少します。4 文字の ID をハードコードしたり、パターンマッチングしたりしているエージェントは、アップグレード後、キャッシュ済みの ID を再利用せずに、find で要素を再検索してください。

無関係な DOM の変更や、同じコンテナー内での要素の並べ替えがあっても、ID は維持されます。エージェントが最小限の詳細レベル（個別の要素 ID なし）でナビゲーションするときは、find を使ってテキスト、種類、または空間的な近接性から要素を検索します。返される要素には、操作に使える ID が含まれます。

開発

# Run in watch mode
npm run dev

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Type check
npx tsc --noEmit

プロジェクト構成

src/
  browser/          # Puppeteer lifecycle, tab management, CDP sessions
  renderer/         # Accessibility tree extraction, layout, content, element IDs
  state/            # Snapshot store, structural differ
  tools/            # MCP tool definitions (navigation, observation, interaction, session, dev-mode)
  dev/              # Static server, file watcher, auditor
  types/            # TypeScript interfaces
  utils/            # Logger, hash, wait utilities
tests/
  unit/             # Fast tests with mocks
  integration/      # Full Puppeteer tests against fixture HTML
  fixtures/pages/   # Test HTML files

アーキテクチャ

レンダラーパイプラインが中核です。抽出器を順番に呼び出し、PageRepresentation を組み立てます。

1. アクセシビリティツリーの抽出（CDP Accessibility.getFullAXTree）
2. レイアウトの抽出（CDP DOM.getBoxModel）
3. ランドマーク、見出し、インタラクティブ要素、コンテンツの抽出
4. 要素 ID の生成（ハッシュベースで、再レンダリング後も安定）

すべてのツールは renderActivePage() を経由します。この関数がスナップショット、再読み込みイベント、ダイアログの検出、レスポンスのフォーマットを処理します。

サンドボックス

Charlotte には、パブリックインターネットに接続せずにすべてのツールを試せるテスト用ウェブサイトが tests/sandbox/ に含まれています。次のコマンドでローカルに配信できます。

dev_serve({ path: "tests/sandbox" })

5 つのページで、ナビゲーション、フォーム、インタラクティブ要素、ポップアップ、遅延読み込みコンテンツ、スクロールコンテナーなどを扱います。ページの詳細とツールごとの演習チェックリストについては、docs-internal/sandbox.md を参照してください。

既知の問題

Shadow DOM — オープン Shadow DOM は透過的に動作します。Chromium のアクセシビリティツリーはオープン Shadow 境界を越えて認識するため、ウェブコンポーネント（例：GitHub の <relative-time>、<tool-tip>）は特別な処理なしで、そのコンテンツが Charlotte の表現にレンダリングされます。クローズド Shadow Root はアクセシビリティツリーからは認識できず、キャプチャされません。

ロードマップ

セッションと設定

機能ロードマップ

動画録画 — インタラクションを動画として記録し、デバッグ、ドキュメント作成、レビューのために、エージェント主導のナビゲーションと操作の全過程をキャプチャします。

Playwright MCP との完全なギャップ分析（優先度の低い項目（ビジョンツール、テスト／検証、トレーシング、トランスポート、セキュリティ）や Charlotte が優位性を持つ領域を含む）については、docs-internal/playwright-mcp-gap-analysis.md を参照してください。

完全な仕様

すべてのツールパラメーター、ページ表現形式、要素識別戦略、アーキテクチャの詳細を含む完全な仕様については、docs-internal/CHARLOTTE_SPEC.md を参照してください。

ライセンス

MIT

コミュニティ

• 再現可能な不具合、リグレッション、または特定の MCP クライアントに関する問題については、バグレポートを作成してください。
• ワークフローの改善や新機能については、機能リクエストを作成してください。
• 新しいツール、パラメーターの仕様、またはプロファイルへの配置を提案する場合は、ツールのリクエストを作成してください。
• オープン中の Issueを確認して、現在進行中の作業や議論を見つけてください。
• メンテナーが初心者向けのタスクにラベルを付ける際は、予定されている初めての貢献に適した Issue のフィルターを確認してください。

コントリビューション

ガイドラインについては、CONTRIBUTING.mdをご覧ください。

コントリビューター

Charlotte に貢献してくださった皆さま、ありがとうございます！CONTRIBUTORS.mdをご覧ください。

---

文学作品にちなんだ名前を持つ、拡大中の MCP サーバースイートの一部です。github.com/TickTockBentで詳細をご覧ください。