Web Picker

ブラウザの localhost ページでUI要素を選択し、修正リクエストを入力すると、 MCPコーディングエージェント（Claude Code、Codexなど）がそれを取得してコードを編集します。

要素を言葉で説明するのはやめましょう。要素をクリックしてください。キャプチャには、エージェントがコードベース内でその正確な要素を見つけるために必要な最小限の手がかりが含まれています。機密値が漏れることはありません。

v1は設計上 localhost専用 です。クラウドなし、アカウントなし、APIキーなし。

仕組み

 Browser (localhost page)            Local machine                Coding agent
 ┌────────────────────────┐     ┌───────────────────────┐     ┌──────────────────┐
 │ content script         │     │ Daemon (127.0.0.1)    │     │ MCP adapter      │
 │  pick + mask + rank    │     │  durable queue        │     │  connect / list  │
 │          │ runtime msg │     │  extension HTTP       │     │  pull / resolve  │
 │ service worker ────────┼HTTP►│  token IPC /ipc      │◄────┤  (7 MCP tools)   │
 └────────────────────────┘     └───────────────────────┘ IPC └──────────────────┘

• デーモン は 127.0.0.1 のみにバインドします。拡張機能ワーカーはChrome検証済みのlocalhostタブからのメッセージのみを受け入れ、デーモン拡張機能エンドポイントは固定された chrome-extension://mnglicpibnccgcifnndemfpidkcgboli オリジン のみを受け入れます。MCPアダプタのIPCは実行ごとのトークンによって保護されています。

• エージェント中立: デーモンはエージェントがClaude CodeかCodexかを認識しません。登録ステップのみが異なります。

• マスキングは同一性を保持: 入力値、メールアドレス、トークンは決してエクスポートされません。短い可視ラベル、セレクタ、祖先、ランドマークは保持され、エージェントがターゲットを特定できるようにします。

Related MCP server: claude-annotate

要件

• Node.js >= 20.18.0（20.20.2でテスト済み）

• Google Chrome（MV3、展開して読み込み）

• MCPに対応したコーディングエージェント（Claude CodeまたはCodex）

インストール

./bootstrap.sh          # macOS/Linux  (installs deps + builds)
# or
pwsh ./bootstrap.ps1    # Windows

次に:

1. Chrome拡張機能を読み込む chrome://extensions → デベロッパーモード を有効化 → パッケージ化されていない拡張機能を読み込む → extension/ フォルダを選択。

2. MCPサーバーをエージェントに登録する:

   ./scripts/register-claude-code.sh   # Claude Code
   ./scripts/register-codex.sh         # Codex

   どちらもエージェントを scripts/run.cjs にポイントし、デーモンを遅延起動します。

5分間の判定パス（キーなし、アカウントなし）

デモページだけで往復全体を再現できます。自動検証は通常、Chromeがインストールされグラフィカルなデスクトップがあるマシンで5分以内に完了します。モデルAPIキーやPlaywrightブラウザのダウンロードは不要です。

1. セットアップ

   ./bootstrap.sh

2. デモページをlocalhostで配信する

   python3 -m http.server 3000 --directory test-page

   http://localhost:3000 を開きます。ヘッダー、メイン、フッターにすべて 저장 というラベルの付いた3つのボタンがあります。これは意図的なデコイセットです。

3. 拡張機能を読み込み（インストール手順1を参照）、エージェントを登録します（インストール手順2）。

4. 要素を選択する

   • 픽 ボタン（右下）をクリック → 요소 선택。

   • メインエリアの저장ボタン（プロフィールカード内）にホバーしてクリックします。

   • リクエストを入力します（例: 이 버튼을 파란색으로）、보내기 をクリックします。

   • 요청을 큐에 보냈습니다 と表示されるはずです。

5. エージェントから取得する Claude Code / Codexセッションで:

   • connect_web_picker → ピッカーを取得し、保留中の数を表示します。

   • list_web_requests → リクエストをIDとステータスとともに表示します。

   • そのIDで get_web_request → ターゲットの手がかりを表示します。landmark: section（およびセレクタ #profile-save）が、ヘッダー/フッターの 저장 デコイ（landmark: header / landmark: footer）と区別されることに注意してください。3つすべてが可視ラベル 저장 を共有している場合でも同様です。

   • IDで resolve_web_request → 解決済みとしてマークします。

このデコイの往復は、ブラウザ不要の統合スイートと以下の実際のChrome E2Eの両方でカバーされています。

ブラウザなしで再現（完全自動）

npm test

test/integration.test.ts は3つのデコイキャプチャを投稿し、実際のMCPツールを connect → list → get → resolve で駆動して、選択された要素が一意に識別されることを検証します。また、dist/ からビルド済みデーモンをコールド起動します。

実際のChrome拡張機能で再現

npm run test:e2e はインストールされたGoogle Chromeを新しいヘッド付きプロファイルで開き、extension/ を展開して読み込み、実際のコンテンツUIを通じてプロフィールボタンの選択を実行し、MCPクライアントを通じてキューに入ったリクエストを検証および解決します。グラフィカルなデスクトップセッションが必要で、通常約10秒で完了します。ブラウザはダウンロードしません。

macOSまたはLinux:

npm run test:e2e

# For a non-standard Chrome install:
PLAYWRIGHT_CHROME_EXECUTABLE=/path/to/google-chrome npm run test:e2e

Windows PowerShell:

npm run test:e2e

# For a non-standard Chrome install:
$env:PLAYWRIGHT_CHROME_EXECUTABLE = 'C:\Path\To\chrome.exe'
npm run test:e2e

Chromeが存在しない場合、またはオーバーライドがインストール済みの実行可能ファイルを指していない場合、テストは次のエラーで失敗します:

Google Chrome is required for npm run test:e2e; install Chrome or set PLAYWRIGHT_CHROME_EXECUTABLE

セキュリティのデフォルト

• デーモンは 127.0.0.1 のみにバインド。

• 拡張機能は localhost / 127.0.0.1 / *.localhost ページでのみアクティブ化。

• 拡張機能ワーカーはChrome検証済みのlocalhostタブ送信者のみを受け入れます。拡張機能HTTPエンドポイントは正確に固定された拡張機能オリジンを要求します。IPCはトークン（定数時間で比較）を要求し、~/.web-picker/token に 0600 で保存されます。

• 入力値、メールアドレス、長い数字、またはトークン形状の文字列は決してエクスポートされません。同じフィルタがセレクタ、id、class、role、aria-label、name、祖先サマリー、マスクされたHTMLをカバーし、ターゲットの同一性のための安全なクラストークンは保持します。dataset はDOM正規化後に安全なキー名のみを送信します。値はページから決して離れません。

MCPツール

開発

npm test          # vitest (unit + jsdom + integration; excludes real Chrome)
npm run test:e2e  # headed installed-Chrome round trip
npm run build     # tsc -> dist/
npm run benchmark # deterministic target-disambiguation benchmark -> artifacts/
npm run sbom      # CycloneDX 1.5 inventory -> artifacts/sbom.cdx.json

npm run sbom は文書化されたエンジンの下限未満のNodeバージョンを拒否し、ロックファイル由来の整合性/開発/オプションのメタデータを復元し、最終的なCycloneDX JSONを検証し、npmの隠しロックキャッシュに依存しない正規バイトを書き込みます。

npm run benchmark は30の静的HTMLフィクスチャのみでターゲットの曖昧性解消を測定します。バランスの取れた曖昧なラベルと一意なラベルのコントロール、および成功と失敗の両方のロケータ解決を含みます。コーディングエージェントの生産性やソース取得の測定ではありません。結果はテキストのみの解決、Web Pickerロケータ解決、グローバルおよびカテゴリ×信頼度のキャリブレーション、ラベル層、およびシリアル化されたキャプチャペイロードのバイトサイズを artifacts/benchmark-results.json と artifacts/benchmark-results.md に記録します。

アーキテクチャ: 純粋なコア（src/daemon/state.ts）+ アプリケーションハンドラ（extension-api、ipc-api、tools）+ 薄いアダプタ（server.ts、src/shim/ の下のMCPアダプタソース、spawn.ts）。ポートは注入されるため、すべてがソケットなしでユニットテストされます。docs/architecture.md を参照してください。

提出エビデンス: docs/dependencies.md、docs/video-script.md、docs/submission-checklist.md。公開リポジトリとYouTubeのURLは、オーナーが公開して検証するまで明示的なチェックリストブロッカーとして残ります。

ライセンス

MIT。ロックされた依存関係のライセンスは、インストールされたパッケージメタデータから docs/dependencies.md に記録されています。GPLファミリーのランタイム依存関係は存在しません。