Site Inspector

ローカルで開発中の Web サイトをクリックして、AI コーディングエージェントに修正を依頼するツールです。HTML や CSS のクラス名を調べたり、スクリーンショットをチャットに貼り付けたりする必要はありません。

• Chrome 拡張で要素を選び、修正内容を書いて送信する

• ローカルホストが依頼・DOM・CSS・スクリーンショットを SQLite に保存する

• エージェントは MCP で依頼を取得し、セレクタ・テキスト・HTML 断片・computed style・画像を見てソースを直す

外部サーバー・アカウント・AI API キーは不要です。データはすべて PC 内に保存されます。

Chrome (ローカルのサイト + Inspector)
        │  chrome.runtime
        ▼
Chrome 拡張の Service Worker ──HTTP (127.0.0.1:3847)──▶ ローカルホスト (SQLite + PNG)
                                                             ▲
                                                   MCP      │ stdio: npx site-inspector mcp
                                                            │ HTTP : http://127.0.0.1:3847/mcp
                                                     AI コーディングエージェント

30 秒でつなぐ

1. 拡張を入れる — Releases の site-inspector-extension-v*.zip を展開し、chrome://extensions → デベロッパーモード → 「パッケージ化されていない拡張機能を読み込む」でそのフォルダを選ぶ

2. エージェントに 1 行で登録（例: Claude Code）

   claude mcp add site-inspector -- npx -y site-inspector mcp

3. サイトを開いて要素をクリックして依頼を送り、「Inspector の依頼を処理して」とエージェントに伝える

ホストの起動コマンドも、ポートやプロジェクトパスの設定も要りません。エージェントが MCP ツールを呼んだ瞬間に、ホストが自動でバックグラウンド起動します。

Related MCP server: web-picker

インストール

チェックアウトから使う場合も引数は同じです。npm install && npm run build のあと、npx site-inspector の代わりに node src/host/cli.ts ... を実行してください。

1. Chrome 拡張

公開リリースの zip を使うのが最短です。リポジトリからビルドする場合:

npm install
npm run build:ext
node src/host/cli.ts extension --open   # dist/extension を開く

chrome://extensions で「デベロッパーモード」をオンにし、「パッケージ化されていない拡張機能を読み込む」で dist/extension を選び、ツールバーの Site Inspector アイコンをピン留めします。

file:// の HTML を直接開いて使う場合は、拡張の「詳細」で 「ファイルの URL へのアクセスを許可」 をオンにしてください（オフのままだとページにパネルが入りません）。

2. エージェント

ホストは npm パッケージに同梱されています。エージェント側は npx -y site-inspector mcp を 1 つ登録するだけです。

Claude Code

claude mcp add site-inspector -- npx -y site-inspector mcp

Cursor — .cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（全体）

{
  "mcpServers": {
    "site-inspector": { "command": "npx", "args": ["-y", "site-inspector", "mcp"] }
  }
}

Claude Desktop — claude_desktop_config.json の mcpServers に同じ 1 エントリを足します。

VS Code (Copilot) — .vscode/mcp.json。キーが servers で、type が要る点だけ違います。

{
  "servers": {
    "site-inspector": { "type": "stdio", "command": "npx", "args": ["-y", "site-inspector", "mcp"] }
  }
}

URL しか受け付けないクライアント — Streamable HTTP のエンドポイントを指定します。

http://127.0.0.1:3847/mcp

この場合はホストが先に動いている必要があります。プロジェクトのフォルダで次を一度実行してください（Ctrl + C で停止、または別ターミナルから npx site-inspector stop）。

npx site-inspector

設定を書き出す

上の JSON を手で書かずに済ませたい場合:

npx site-inspector init --write   # .mcp.json / .cursor/mcp.json / .vscode/mcp.json

既存のサーバー設定は残したまま site-inspector のエントリだけを足します。すでに入っている場合はそのままにし、--force で置き換えます。書き出さずに中身を確認したいときは --write を外します。

リポジトリのチェックアウトから使う場合、init は node <リポジトリ>/src/host/cli.ts mcp の絶対パスを書きます（npx 不要）。手で登録するなら:

node /path/to/site-inspector/src/host/cli.ts mcp

プロジェクトの判定

ホストは「どのプロジェクトの DB に書くか」を次の順で決めます。設定は要りません。

1. すでに動いているホストのプロジェクト（拡張はそこに送っているので最優先）

2. --root / SITE_INSPECTOR_PROJECT（指定した場合はエージェントのルートを使わない）

3. MCP クライアントが申告するプロジェクトルート（roots/list。エージェントで開いているフォルダ）

4. MCP サーバーの作業ディレクトリ

別のプロジェクトに切り替えるときは、ホストを止めてから新しいフォルダで依頼してください。

npx site-inspector stop

使い方

1. サイトを npm run dev などで起動して http://localhost:5173 を開く（file:///.../index.html を直接開いてもよい）

2. ツールバーの Site Inspector アイコンを押す（マウスオーバーで要素が枠線で強調されます）

3. 修正したい要素をクリックし、右パネルに修正内容を書く。「撮影して確認」でスクリーンショットを確認できる

4. 「この内容で送信」を押す

5. エージェントに「Inspector の未処理依頼を修正して」と一度だけ伝える

6. エージェントが MCP で依頼を取得し、コードを直し、状態を「確認待ち」にする

7. HMR で表示が更新されるので結果を確認する。気になれば同じ要素に追加依頼を出す

ショートカット

CLI

依頼の状態

pending（未対応）→ in_progress（対応中）→ awaiting_review（確認待ち）→ done（完了）。やり直しは redo（再修正）に戻します。ブラウザ上の同じページに、未完了の依頼が番号付きマーカーで表示されます。

MCP ツール

list_pending_requests と get_project_context は、AI 向けの作業手順（src/host/instructions.ts）も一緒に返します。

保存先

<hash> はプロジェクトの絶対パスから生成されます。中身は inspector.db（SQLite / WAL）と shots/（PNG）です。消せばリセットされます。

セキュリティとプライバシー

• 待ち受けるのは 127.0.0.1:3847 のみ。外部通信はしません

• Host ヘッダーを検証し、DNS リバインディングを拒否します

• 書き込みは chrome-extension://<id> の Origin を必須にしています（通常の Web ページからは書けません）

• MCP には CORS ヘッダーを付けていないため、ブラウザ上のページからは呼べません（ローカルのエージェント専用）

• 入力は zod で検証し、本文 32MB / 画像 8MB / PNG のみに制限しています

• フォームの入力値や Cookie は取得しません。要素のテキスト・HTML 断片・computed style のみです

• スクリーンショットは「撮影して確認」でプレビューでき、添付しない選択もできます

• 読み取り API は Origin なしのローカルプロセス（curl など）からも参照できます。必要な場合だけ起動してください

制限（MVP）

• ポートは 3847 固定です。拡張側にポート設定 UI はありません

• activeTab の寿命: スクリーンショットはツールバーのアイコンを押した時点の権限に依存します。ページをフルリロードすると権限が切れ、撮影に失敗します（パネルに案内が出ます）。もう一度アイコンを押してください

• 対応するのは http://localhost / http://127.0.0.1 / file:// のページだけです。LAN の IP・独自ホスト名・https は対象外

• file:// は拡張の詳細で「ファイルの URL へのアクセスを許可」をオンにしないと、パネルがページに入りません（アイコンに × が出て、ツールチップに案内が出ます）

• 撮影できるのは表示中のタブだけです。ウィンドウが最小化・非アクティブだと失敗します

• スクリーンショットは現在のビューポートのみ。ページ全体の長い画像やスマートフォン幅の別撮りは未対応です

• 参考画像の添付、複数要素の同時選択、範囲ドラッグ選択は未対応

• 拡張のアイコン画像は未同梱です。ツールバーには Chrome の既定アイコンが表示されます

• Canvas / WebGL / 別オリジンの iframe / 複雑な Shadow DOM の内部は対象外

• 同時に動かせるホストは 1 つです。複数プロジェクトを並行して使うときは site-inspector stop で切り替えます

• ホストを自動起動できるのは stdio の MCP 経路だけです。URL だけを渡すクライアントは、先に npx site-inspector を起動しておく必要があります

トラブルシューティング

• パネルが「未接続」: エージェントに一度ツールを呼ばせるとホストが上がります。上がらないときは npx site-inspector doctor で状態を確認

• port 3847 is already in use: 別のホストか別アプリが占有しています。npx site-inspector stop を試し、それでも駄目なら netstat -ano | findstr :3847 で PID を確認

• エージェントが見ているプロジェクトと DB がずれる: 起動済みホストのプロジェクトが優先されます。npx site-inspector stop してから呼び直してください

• file:// でパネルが出ない / × が出る: 拡張の詳細で「ファイルの URL へのアクセスを許可」をオンにして、ページを再読み込み

開発

npm test             # ホスト + MCP（stdio / HTTP）のテスト
npm run typecheck
npm run build        # CLI（dist/host）+ 拡張（dist/extension）
npm run build:ext    # 本番用（activeTab）
npm run build:ext:test # E2E 用（<all_urls>。スモークテスト専用）
npm run dev:ui       # パネル UI の確認（http://localhost:5199/dev/）

E2E（サンプルアプリ + ホスト + headless Edge）:

npm run build:ext:test
npm install --prefix sample-app
npm run sample                                   # 別ターミナル
(cd sample-app && node ../src/host/cli.ts start --root .)  # 別ターミナル
npm run e2e

npm run e2e は、ヘッドレス Edge に拡張を読み込ませ、要素クリック → 入力 → 送信 → SQLite と画像の保存 → MCP での取得・状態更新までを通します。スクリーンショットは .shots/e2e-inspector.png に保存されます。

リリースは v0.2.0 のようなタグを push すると、.github/workflows/release.yml が拡張の zip を作って GitHub Release に添付します。リポジトリの Secret に NPM_TOKEN を入れておくと npm にも公開します。

企画書との差分

• 通信方式: 企画書は Chrome Native Messaging を第一候補としていますが、インストールとデバッグの容易さを優先し、127.0.0.1 の HTTP にしました。外部には公開せず、Host / Origin / スキーマ検証で守っています

• 拡張のビルド: CRXJS や WXT ではなく、Vite の 2 バンドル（content / background）で十分なため、素の Vite 構成にしています

• MVP 外: 参考画像、モバイル幅の別撮影、IDE からの自動タスク開始、修正前後の比較は実装していません

ライセンス

MIT