Ui Annotator Mcp

UI Annotator MCP

English | 廣東話

目に見えるものと AI が参照できるものの間をつなぎます — どのブラウザーでも、拡張機能は不要です。

すべての Web 要素に見やすいラベルを付ける唯一のツールです。任意の要素にカーソルを合わせると、その名前が表示されます。AI アシスタントに「sidebarを広げて」と伝えれば、対象の要素を正確に認識します。スクリーンショットも、CSS セレクターも、認識違いも必要ありません。

重要な理由

AI を活用した UI のデザインと反復作業を大幅に改善します。悩みの種は、AI に「検索バーの隣にあるボタンを移動して」と伝えても、AI がページを見られないためうまくいかないことです。UI Annotator がこれを解決します — 任意の要素にカーソルを合わせると、コンポーネント名がラベルとして表示されます。これで「SearchButtonをNavBarの下に移動して」と伝えれば、Claude がすぐに正しいコンポーネントを編集します。ブラウザー拡張機能は不要で、どのフレームワークでも動作します。ワークフローは次のようになります：ページを開く → 要素を特定するためにカーソルを合わせる → 実際のコンポーネント名を使って変更を伝える → Claude が編集する → ページを更新して繰り返す。苛立たしいやり取りを、スムーズなデザインの反復サイクルに変えます。

問題点

AI コーディングアシスタントと Web UI を確認するとき、最も難しいのはコードの変更ではなく、変更したい要素を説明することです。

「左側にあるあれ……2 行目の……いや、アイコンが付いているやつ……」

名前が分かりません。AI には、どれを指しているのか分かりません。開発を進める代わりに、意思疎通の齟齬に時間を費やしてしまいます。

解決策

アノテーターのプロキシ経由でページを開きます。任意の要素にカーソルを合わせると、その名前、CSS セレクター、寸法がすぐに表示されます。これで、お互いに同じ言葉でやり取りできます。

# Start the MCP server
npx @mcpware/ui-annotator

# Open in ANY browser
http://localhost:7077/localhost:3847

これだけです。 ブラウザー拡張機能は不要です。コードの変更も不要です。セットアップも不要です。Chrome、Firefox、Safari、Edge など、どのブラウザーでも動作します。

仕組み

Your app (localhost:3847)
        │
        ▼
┌─────────────────────┐
│  UI Annotator Proxy  │ ← Reverse proxy on port 7077
│  (MCP Server)        │
└─────────────────────┘
        │
        ▼
Proxied page with hover annotations injected
        │
        ├──► User sees: hover overlay + tooltip with element names
        └──► AI sees: structured element data via MCP tools

プロキシがページを取得し、軽量なアノテーションスクリプトを挿入して、ページを返します。このスクリプトは DOM をスキャンして、名前の付いた要素を識別し、それらを MCP サーバーに報告します。AI アシスタントはサーバーに問い合わせて、ページ上に何があるかを把握します。

機能

ホバーアノテーション

任意の要素にカーソルを合わせると、次の情報が表示されます：

• 要素名（ピンク）— 人が読みやすい識別名
• CSS セレクター（等幅フォント）— 技術的な参照情報
• コンテンツのプレビュー — 要素に含まれるテキスト
• 寸法 — ピクセル単位の幅 × 高さ

検査モード

ツールバーの検査ボタンをクリックします（または AI に切り替えてもらいます）。検査モードでは：

• 任意の要素をクリック → その名前をクリップボードにコピー
• ページ上のすべての操作が一時停止します（クリックしてもボタンやリンクは起動しません）
• もう一度「検査」をクリックすると通常モードに戻ります

折りたたみ可能なツールバー

ツールバーはページ上部の中央に表示され、次の内容が含まれます：

• 検査モード切り替えボタン
• 要素数
• 操作方法を説明する補助テキスト
• 必要ないときに最小化する折りたたみボタン（▲）

AI 向け MCP ツール

ツール	機能
annotate(url)	ユーザーが任意のブラウザーで開くためのプロキシ URL を返します
get_elements()	検出された UI 要素の名前、セレクター、位置をすべて返します
highlight_element(name)	特定の要素を点滅表示して、ユーザーが確認できるようにします
rescan_elements()	ページの変更後に DOM の再スキャンを強制します
inspect_mode(enabled)	検査モードをリモートで切り替えます

DevTools を使うだけではだめですか？

	ブラウザー DevTools	UI Annotator
対象ユーザー	DOM を理解しているフロントエンド開発者	誰でも — QA、PM、デザイナー、ジュニア開発者
学習曲線	DOM ツリー、CSS セレクター、ボックスモデルを理解する必要があります	ホバーして読むだけ — 学習は不要です
コミュニケーション	「2 番目の子要素の中にある div.flex.gap-4」	「sidebar」
用語	CSS/HTML の専門用語	人が読みやすい名前
セットアップ	DevTools を開いて DOM をたどる方法を教える必要があります	URL を開くだけです
AI 連携	なし — AI は調査中の内容を確認できません	MCP — AI はあなたと同じ要素名を確認できます

DevTools はデバッグ用です。 UI Annotator はコミュニケーション用です — 人間と AI が UI 要素について共通の語彙を使えるようにします。

既存のツールを使うだけではだめですか？

これらのツールはどれも、UI Annotator が実現する機能、つまりリバースプロキシ経由で、すべての要素にリアルタイムの視覚ラベルを表示することには対応していません。

ツール	アプローチ	異なる点
browser-use（82K⭐）	AI 自動化フレームワーク	ブラウザーを自動操作しますが、人間向けに要素へラベルを付けるものではありません。用途がまったく異なります。
Chrome DevTools MCP（31K⭐）	DOM スナップショット + 要素 UID	AI は調査できますが、人間には視覚的な注釈が表示されません。共通の語彙もありません。
Playwright MCP（29K⭐）	アクセシビリティツリーのスナップショット	構造化テキストを返しますが、視覚的なオーバーレイはありません。重要なコンテキストが切り詰められます。
OmniParser	スクリーンショット + CV 検出	スクリーンショットベースであり、ライブ DOM ではありません。難しいベンチマークでの精度は約 40% です。
MCP Pointer（526 ユーザー）	Chrome 拡張機能 + MCP	Chrome 拡張機能が必要です。人間がクリックして選択します — ホバーオーバーレイはありません。
Agentation	アプリに埋め込む npm パッケージ	コードの変更が必要です。React 18 以降への依存があります。設定不要ではありません。
Vibe Annotations	Chrome 拡張機能	拡張機能ベースの、開発者専用の注釈ワークフローです。

機能の比較

機能	UI Annotator	MCP Pointer	Agentation	Cursor	Chrome DevTools MCP
ホバー時の視覚的な注釈	はい	いいえ	一部対応	はい（IDE のみ）	いいえ
要素名の表示	はい	はい	はい	いいえ（概要レベル）	プログラム経由
寸法の表示	はい	はい	はい（詳細）	はい	プログラム経由
MCP サーバー	はい	はい	はい	いいえ	はい
ブラウザー拡張機能が不要	はい	いいえ	はい	該当なし	いいえ
コードの変更が不要	はい	はい	いいえ	該当なし	はい
任意のブラウザーで使用可能	はい	Chrome のみ	デスクトップのみ	Cursor のみ	Chrome のみ
依存関係なし	はい	Chrome 拡張機能	React 18 以降	Cursor	Chrome
クリックして要素名をコピー	はい	いいえ	いいえ	いいえ	いいえ

アーキテクチャ

外部依存関係ゼロ

• リバースプロキシ：Node.js 組み込みの http モジュール
• MCP サーバー：@modelcontextprotocol/sdk（stdio トランスポート）
• 通信：HTTP POST（ブラウザー → サーバー）+ GET ポーリング（サーバー → ブラウザー）
• WebSocket、Express、ブラウザー拡張機能は不要

プロキシの動作

1. ユーザーが localhost:7077/localhost:3847 にアクセスします
2. プロキシが http://localhost:3847 から取得します
3. HTML レスポンスの場合：
   • fetch() / XMLHttpRequest インターセプターを挿入します（API パスをプロキシ経由に書き換えます）
   • href="/..." と src="/..." 属性を書き換え、プロキシ経由でルーティングします
   • </body> の前に注釈スクリプトを挿入します
4. HTML 以外（CSS、JS、画像）の場合：そのまま転送します
5. スクリプトを挿入できるように、Content-Security-Policy ヘッダーを削除します

注釈の動作

1. スクリプトが DOM をスキャンし、id、class、セマンティックロール、またはインタラクティブロールを持つ要素を検出します
2. ホバー時：オーバーレイの境界線（border-radius に沿って表示）を配置し、ツールチップ（常にビューポート内に表示）を配置します
3. 検出したすべての要素を POST /__annotator/elements 経由でサーバーに報告します
4. サーバーからの指示（ハイライト、再スキャン、検査の切り替え）を GET /__annotator/commands で 1 秒ごとにポーリングします
5. MutationObserver が DOM の変更時に自動で再スキャンします

クイックスタート

Claude Code を使用する

# Add as MCP server
claude mcp add ui-annotator -- npx @mcpware/ui-annotator

# Then in conversation:
# "Annotate my app at localhost:3847"
# → AI returns proxy URL, you open it, hover elements, discuss changes by name

手動で実行する

npx @mcpware/ui-annotator
# Proxy starts on http://localhost:7077
# Open http://localhost:7077/localhost:YOUR_PORT

環境変数

変数	デフォルト	説明
UI_ANNOTATOR_PORT	7077	プロキシサーバーのポート

@mcpware のその他のプロジェクト

プロジェクト	機能	インストール
Instagram MCP	Instagram Graph API の23個のツール — 投稿、コメント、DM、ストーリー、分析	npx @mcpware/instagram-mcp
Claude Code Organizer	Claude Code のメモリ、スキル、MCP サーバー、フックのビジュアルダッシュボード	npx @mcpware/claude-code-organizer
Pagecast	MCP を介してブラウザーセッションを GIF または動画として記録	npx @mcpware/pagecast
LogoLoom	AI ロゴデザイン → SVG → ブランドキット一式をエクスポート	npx @mcpware/logoloom

ライセンス

MIT