webEmbedding

webEmbedding

webEmbeddingは、AI コーディングエージェント向けのソース優先型ウェブサイトクローニングエンジンです。Playwright で稼働中のページをキャプチャし、HAR アーティファクトからネットワークの証拠を再生し、直接の再利用が妨げられる場合にのみ再構築を行い、結果を自己検証します。

Skill + MCP サーバーとして提供されます。スクリーンショットを基にモデルへ「このサイトをクローンして」と依頼するのではなく、URL を調査して再利用または再構築の経路を選択し、DOM／ランタイム HTML／スタイル／アセット／ネットワークトレースをキャプチャし、範囲を限定したフロントエンド再構築アーティファクトを生成したうえで、ビジュアル、DOM、計算済みスタイル、インタラクション、レスポンシブブレークポイントの各検証によって出力を確認します。

GitHub の掲載情報、ソーシャルプレビュー、ローンチ用コピーの推奨事項は、docs/github-listing.mdにあります。

現在の状況

現在のパイプラインは、静的および準静的なウェブページに最も適しています。

• 企業、ブランド、マーケティング、ドキュメントのページ
• 公開ランディングページ
• キャプチャベースの再構築が必要な、iframe によってブロックされたページ
• デスクトップ、タブレット、モバイルに対応するレスポンシブページのスナップショット

バックエンド全体やアプリのロジックをクローンするエンジンではありません。ログイン専用画面、アプリ優先のサービスやネイティブアプリが必須のサービス、CAPTCHA の多いサイト、地図、ゲーム、Canvas／WebGL を多用するページ、リアルタイムフィード、決済、予約フロー、非公開のサーバー動作には、引き続き個別の対応が必要です。

運用面では、このリポジトリは URL ベースのキャプチャと範囲を限定した再構築を行う、本番候補のクローンエンジンになっています。ジョブをキューに登録でき、HAR アーティファクトからネットワークの証拠を再生監査でき、ユーザー所有のブラウザー状態を使って認証済みダッシュボードの実行を操作できるほか、ローカルゲートによってルートコーパス、スコア検査、パッケージの内容、CI の設定を検証できます。残る大きな制約はサーバー側の製品動作であり、フロントエンドの証拠のキャプチャや再構築ではありません。

測定済みチェックポイント

このリポジトリで最近実行したローカルベンチマーク：

URL	経路	スコア
https://developer.mozilla.org/en-US/	iframe によってブロックされたページの範囲限定再構築	ルート 94、ビジュアル 95、モバイル 94、タブレット 94、ブレークポイント平均 94
https://www.mozilla.org/	範囲限定再構築	ルート 94、ビジュアル 100
https://www.python.org	より難易度の高い範囲限定再構築サンプル	ルート 90、ビジュアル 100
https://www.example.com	完全再利用	準備完了 はい

これらはローカルの自己検証パイプラインによって生成されたもので、手動で割り当てた評価ではありません。 再現可能なコマンドとスコアのしきい値は、docs/benchmark-evidence.jsonで管理されています。 本番対応の準備ゲートは、docs/production-pipeline-gates.jsonで管理されています。

主な機能

• ソース優先のルーティング：
  • 安全で、iframe への埋め込みが可能な場合は、iframe または embed を直接再利用します
  • 利用可能な場合は、元のプレビュー、エクスポート、リミックス、またはソースのルートを使用します
  • 完全な再利用ができない場合に限り、範囲を限定して再構築します
• ライブブラウザーキャプチャ：
  • DOM スナップショット
  • 実行時 HTML
  • ページ全体のスクリーンショット
  • 計算済みスタイルの概要
  • CSS 分析
  • アセット一覧
  • HAR に類似したネットワークメタデータ
  • インタラクション状態と再生トレース
  • セッション対応フロー向けのストレージ状態エクスポート
• ブロックされたサイトの再構築：
  • キャプチャした証拠に基づいて再構築することで、X-Frame-Options や CSP によりブロックされたページに対応します
  • キャプチャしたページ構造から、再利用可能なフロントエンド再構築アーティファクトを生成します
  • キャプチャできた範囲で、カスタムタグ、シャドウルートのホスト構造、セマンティックなドキュメント構造を保持します
• 証拠の制限に関する報告：
  • 再現結果とプロンプトで、直接キャプチャしたアーティファクトと、推測または欠落した証拠を区別します
  • アプリによる制限、認証による制限、ネイティブアプリ主体のサーフェスを、制限付きの証拠として示し、ユーザーのスクリーンショットまたは認証済みセッションのキャプチャを推奨します
• 運用上の失敗分類：
  • network-replay-limited、auth-session-missing、public-app-gate、canvas-visual-fallback などの型付きパイプラインアクションコードを報告します
  • キャプチャしたネットワーク証拠を再生可能な品質とみなす前に、HAR／ネットワークの replay_readiness を提示します
• 本番パイプライン用ヘルパー：
  • 永続的な JSON レコード、ワーカーロック、再試行スケジュール、キャンセル、マニフェストへの注釈付けに対応した、ファイルシステムベースの非同期クローンジョブキュー
  • 標準 HAR、HAR に近い形式、キャプチャした network/manifest.json アーティファクトに対応する、決定論的な HAR 再生エンジン
  • リポジトリ外でユーザーが指定した storage_state_path または user_data_dir を受け付ける、認証済みダッシュボードのライブコーパスランナー
• 自己検証：
  • スクリーンショットの類似度
  • DOM スナップショットの類似度
  • 計算済みスタイルの類似度
  • ホバー／フォーカス／クリック時のインタラクション状態の同等性
  • インタラクショントレースの同等性
  • デスクトップ／モバイル／タブレットのブレークポイントレポート
• レスポンシブベンチマークのサポート：
  • 主なデスクトップビューポート：1440x1200
  • タブレットプロファイル：768x1024
  • モバイルプロファイル：390x844
• 修復ループ：
  • 最初のスキャフォールドが準備完了のしきい値に達しない場合、範囲を限定した自己修復を実行できます

インストール

要件

• Node.js 18 以降
• Python 3.9 以降
• Playwright の実行時キャプチャ用に、ローカルで利用できる Chrome または Chromium

このパッケージは playwright-core を使用します。ブラウザーを自動でダウンロードすることはありません。

このプロジェクトをインストールすると、source-first-clone プラグインバンドル、exact-clone-intake スキル、および URL の検査、キャプチャ、再構築、検証ツールを公開する MCP サーバーが追加されます。

npm からインストール

npm install -g web-embedding
web-embedding install
web-embedding doctor

インストール後に公開 URL をクローンするには：

web-embedding clone \
  --url https://developer.mozilla.org/en-US/ \
  --output-dir ./.tmp/mdn-clone \
  --wait-seconds 2 \
  --timeout-seconds 35 \
  --breakpoints mobile tablet

以前のバージョンのプラグインをローカルにインストール済みの場合は、次のコマンドで上書きします：

web-embedding install --force
web-embedding doctor

グローバルインストールせずにインストーラーを実行することもできます：

npx web-embedding install

MCP サーバーとして使用

npm の stdio サーバーを起動できる MCP クライアントの場合：

{
  "mcpServers": {
    "source-first-clone": {
      "command": "npx",
      "args": ["-y", "web-embedding@latest", "mcp"]
    }
  }
}

ローカルでスモークテストを実行する場合：

npx web-embedding@latest mcp

MCP Registry の ID は io.github.jongko54/web-embedding です。レジストリの所有権確認に使われる server.json と package.json#mcpName は、常に同期されています。

ホスト型 Apps SDK 取り込みエンドポイント

Apps SDK Developer Mode 用の公開リモート MCP 取り込みエンドポイントは次のとおりです：

https://webembedding-jongkos-mcp.vercel.app/mcp

URL の検査、埋め込み候補の検出、クローンモードの分類、埋め込みスニペットの生成など、リスクの低いソース優先のルーティングツールを公開します。完全なブラウザーキャプチャ、HAR の再生、キュー、範囲を限定した再構築、1 回の実行でのクローン作成は、引き続き stdio MCP パッケージを介したローカル優先の機能です。

Apps SDK の審査ページは、エンドポイントと併せてホストされています： https://webembedding-jongkos-mcp.vercel.app/privacy.html、 https://webembedding-jongkos-mcp.vercel.app/terms.html、および https://webembedding-jongkos-mcp.vercel.app/submission.html。

サンドボックス化と承認

webEmbedding には、2 つの異なる実行境界があります。

• Hosted Apps SDK の取り込み：読み取り専用の URL ルーティングと分類のみを行います。絶対 http および https URL を受け付けますが、Playwright は実行せず、ローカルファイルの読み取り、ブラウザープロファイルやストレージ状態の使用、キャプチャ成果物の永続化も行いません。
• ローカル stdio MCP と CLI：フルキャプチャ、HAR リプレイ、キュー、再構築のスキャフォールド、自己検証は、ユーザーのマシン上で、ユーザーのローカルエージェントとファイルシステムの権限のもとで実行されます。出力は、output_dir や queue_root など、呼び出し元が指定したパスにのみ書き込まれます。
• 認証済みキャプチャ：セッションを考慮した実行には、呼び出し元が意図的に storage_state_path または user_data_dir を指定する必要があります。webEmbedding は認証情報を収集せず、ログインの回避も行わず、公開されているログイン画面を非公開アプリの証拠として扱うこともありません。
• アクセス制御された画面：ペイウォール、CAPTCHA のフロー、非公開ダッシュボード、決済／チェックアウト／アカウント／管理者向けフロー、ネイティブアプリ主体の画面は、ユーザーが明示的な許可を得て必要な証拠を提供しない限り、ブロックするか、needs_session としてマークするか、手動レビューに回してください。

ローカル URL のエントリーポイントは file:// などの HTTP 以外のスキームを拒否するため、エージェントがクローン／キャプチャツールをローカルファイルリーダーとして使うことはできません。テレメトリーはデフォルトで無効です。有効にした場合も、対象 URL、ローカルパス、キャプチャした HTML、スクリーンショット、ストレージ状態、環境変数、API キー、コマンド出力は除外されます。

エージェントマーケットプレイス

このリポジトリには、2 つのローカルエージェント環境向けのマーケットプレイスメタデータが含まれています。

• Codex：.agents/plugins/marketplace.json は ./bundle/source-first-clone を参照しています。
• Claude Code：.claude-plugin/marketplace.json は同じバンドルを参照しており、バンドルには .claude-plugin/plugin.json が含まれています。

Claude Code ユーザーは、GitHub から次のようにマーケットプレイスを追加できます。

/plugin marketplace add jongko54/webEmbedding
/plugin install source-first-clone@webembedding

AI による自動選択の想定とゴールデンプロンプトは、docs/ai-distribution.md と evals/ai-selection/webembedding-golden-prompts.json にあります。

リリースからインストール

curl -fsSL https://github.com/jongko54/webEmbedding/releases/latest/download/install.sh | bash

このチェックアウトからインストール

git clone https://github.com/jongko54/webEmbedding.git
cd webEmbedding
npm install
node ./bin/web-embedding.mjs install
node ./bin/web-embedding.mjs doctor

一時的なホームディレクトリにインストール

実際のエージェントホームに触れずにテストする場合に便利です。

python3 python/web_embedding/installer.py install --target-home ./.tmp/home
python3 python/web_embedding/installer.py doctor --target-home ./.tmp/home
python3 python/web_embedding/installer.py uninstall --target-home ./.tmp/home

オプトイン方式のテレメトリー

テレメトリーはデフォルトで無効です。対話形式での初回インストール時に、web-embedding install が一度だけ確認し、デフォルトは No です。CI や curl | bash などの非対話型インストールでは、確認は表示されません。オプトインすると、web-embedding はユーザーが管理する JSON POST エンドポイントに、コマンド完了時の簡単な匿名イベントを送信します。対象 URL、ローカルパス、キャプチャした HTML、スクリーンショット、ストレージ状態、環境変数、API キー、コマンド出力は送信しません。

インストール時に有効にするには、次のようにします。

web-embedding install --telemetry --telemetry-endpoint https://your-collector.example/events

後から管理することもできます。

web-embedding telemetry enable --endpoint https://your-collector.example/events
web-embedding telemetry status
web-embedding telemetry disable
web-embedding telemetry reset-id

各イベントには、匿名インストール ID、パッケージバージョン、コマンド名、成功／失敗の状態、OS／ランタイムの基本情報、breakpoint_count や install_source などの大まかなオプションフラグが含まれます。

環境変数による設定：

WEB_EMBEDDING_TELEMETRY=1
WEB_EMBEDDING_NO_TELEMETRY=1
WEB_EMBEDDING_TELEMETRY_PROMPT=0
WEB_EMBEDDING_TELEMETRY_ENDPOINT=https://your-collector.example/events
WEB_EMBEDDING_TELEMETRY_LOG=./telemetry.jsonl

ローカルまたはセルフホスト可能な JSONL コレクターを実行する：

npm run telemetry:collector -- --host 127.0.0.1 --port 8765 --out ./telemetry.jsonl
WEB_EMBEDDING_TELEMETRY=1 \
WEB_EMBEDDING_TELEMETRY_ENDPOINT=http://127.0.0.1:8765/events \
web-embedding doctor

収集した使用状況を要約する：

npm run telemetry:summarize -- ./telemetry.jsonl

要約には、インストールとクローンの実行回数、コマンドの総実行回数、匿名インストール ID のユニーク数、コマンド数、バージョン数が含まれます。コレクターとアナライザーの詳細については、docs/telemetry.md を参照してください。

クイックスタート

URL を調査してルートのヒントを取得します。

node ./bin/web-embedding.mjs inspect \
  --url https://developer.mozilla.org/en-US/

キャプチャまたはクローンの前に、安全な事前監査を実行します。

node ./bin/web-embedding.mjs audit \
  --url https://developer.mozilla.org/en-US/

この監査では、参照先が完全一致／埋め込み再利用に適しているか、ローカルキャプチャが必要か、認証済みセッションが必要か、手動レビューが必要か、ブラウザーでのキャプチャやファイルシステムへの出力を実行する前にブロックすべきかを報告します。

クローンの全ワークフローを実行します。

node ./bin/web-embedding.mjs clone \
  --url https://developer.mozilla.org/en-US/ \
  --output-dir ./.tmp/mdn-clone \
  --wait-seconds 2 \
  --timeout-seconds 35 \
  --breakpoints mobile tablet

軽量な品質ベンチマークを実行します。

python3 scripts/check_clone_quality_bench.py \
  https://developer.mozilla.org/en-US/ \
  --output-root ./.tmp/clone-quality-bench \
  --wait-seconds 1 \
  --timeout-seconds 35 \
  --breakpoints mobile tablet

ベンチマークは、ルート、ビジュアル、ブレークポイントのスコアをコンパクトな行で出力します。すべての成果物は出力ディレクトリの下に書き込まれます。

CLI コマンド

node ./bin/web-embedding.mjs capabilities
node ./bin/web-embedding.mjs install
node ./bin/web-embedding.mjs doctor
node ./bin/web-embedding.mjs uninstall
node ./bin/web-embedding.mjs paths
node ./bin/web-embedding.mjs telemetry status

node ./bin/web-embedding.mjs inspect --url https://www.mozilla.org/

node ./bin/web-embedding.mjs audit --url https://www.mozilla.org/

node ./bin/web-embedding.mjs capture \
  --url https://www.mozilla.org/ \
  --output-dir ./.tmp/capture-mozilla \
  --breakpoints mobile tablet

node ./bin/web-embedding.mjs reproduce \
  --url https://www.mozilla.org/ \
  --output-dir ./.tmp/reproduce-mozilla \
  --breakpoints mobile tablet

node ./bin/web-embedding.mjs clone \
  --url https://www.mozilla.org/ \
  --output-dir ./.tmp/clone-mozilla \
  --breakpoints mobile tablet

node ./bin/web-embedding.mjs verify \
  --reference-bundle ./.tmp/reference/capture.json \
  --candidate-bundle ./.tmp/candidate/capture.json

出力アーティファクト

クローンの実行では、次のものが生成される場合があります。

• capture.json
• pipeline-run-manifest.json
• dom/snapshot.json
• dom/runtime.html
• styles/computed-summary.json
• styles/css-analysis.json
• network/manifest.json
• network/har.json
• network/har-like.json
• network/replay-report.json
• assets/inventory.json
• interactions/states.json
• interactions/trace.json
• screenshots/runtime.png
• session/storage-state.json
• reproduction/plan.json
• reproduction/evidence-limitations.json
• reproduction/rebuild-prompt.txt
• reproduction/rebuild/starter.html
• reproduction/rebuild/starter.css
• reproduction/rebuild/starter.tsx
• reproduction/rebuild/next-app/
• reproduction/self-verify/summary.json
• reproduction/self-verify/renderers/*/verification.json
• reproduction/self-verify/renderers/*/visual-qa.json
• reproduction/self-verify/renderers/*/breakpoints/*-verification.json

品質ベンチマーク

デフォルトの小規模ベンチマークを実行します。

npm run check:clone-bench:local

ユニバーサルルート回帰コーパスと期待値ゲートを実行します。

npm run check:benchmark-routes:local

軽量なクローンスコアゲートを実行します。

npm run check:clone-score-gate:local

コミット済みのベンチマーク証拠マニフェストを検証します。

npm run check:benchmark-evidence:local

本番パイプラインのゲートを検証します。

npm run check:production-readiness:local

運用スモークテストを個別に実行します。

npm run check:job-queue:local
npm run check:har-replay:local
npm run check:authenticated-corpus:local

ルートレポートから失敗／アクションコードを分類します。

npm run classify:pipeline-failures -- --report ./.tmp/universal-route-benchmark/universal-route-report.json

スコアの低い保存済みベンチマークアーティファクトを探します。

npm run summarize:benchmark-scores -- --root ./.tmp --min-score 60 --max-score 70

指定した URL を実行します。

python3 scripts/check_clone_quality_bench.py \
  https://www.example.com \
  https://www.mozilla.org/ \
  --no-breakpoints

レスポンシブベンチマークを実行します。

python3 scripts/check_clone_quality_bench.py \
  https://developer.mozilla.org/en-US/ \
  --breakpoints mobile tablet

開発チェック

python3 -m py_compile \
  bundle/source-first-clone/mcp/source_first_clone/*.py \
  scripts/check_integration_smoke.py \
  scripts/check_clone_quality_bench.py

npm run check:integration:local

git diff --check

リポジトリ構成

• bundle/source-first-clone インストール済みのプラグインバンドル、MCP サーバー、exact-clone 取り込みスキル。
• bundle/source-first-clone/mcp/source_first_clone キャプチャ、計画、再構築、修復、検証エンジン。
• bin/web-embedding.mjs Node CLI ラッパー。
• python/web_embedding/installer.py 共有インストーラーとコマンドディスパッチャー。
• scripts/check_clone_quality_bench.py URL クローン品質ベンチマークヘルパー。
• scripts/benchmark_routes.py ユニバーサルルート／キャプチャ深度回帰ベンチマークヘルパー。
• scripts/check_benchmark_report.py 完全一致、最小値、部分一致形式のチェックに対応するベンチマーク期待値バリデーター。
• scripts/check_benchmark_evidence.py ベンチマーク証拠マニフェストのバリデーター。
• scripts/check_job_queue_smoke.py ファイルシステム上の非同期クローンジョブキューのスモークテスト。
• scripts/check_har_replay_smoke.py 決定論的 HAR リプレイエンジンのスモークテスト。
• scripts/benchmark_authenticated_corpus.py ユーザー提供の認証済みダッシュボードコーパスの実行ツール。
• scripts/summarize_benchmark_scores.py 出力ルート配下で、スコアが低い、または高い保存済みベンチマークアーティファクトを探すユーティリティ。
• scripts/classify_pipeline_failures.py レポートとキャプチャアーティファクトを対象とした、運用上の失敗／アクション分類の要約ツール。
• scripts/check_production_readiness.py コーパス、失敗分類、CI の配線、ポリシー文書を対象とした本番準備状況ゲートのバリデーター。
• scripts/check_integration_smoke.py リリース、インストール、URL のみのクローンを対象としたスモークテスト。
• scripts/release_bundle.py リリースアーティファクトのビルダー。
• docs/ アーキテクチャに関するメモとユニバーサルベンチマークのドキュメント。

位置付け

このプロジェクトについて最も強く主張できるのは、次の点です。

Playwright のキャプチャ、HAR リプレイ、MCP ツール、自己検証を組み合わせ、iframe によってブロックされた公開ページを、再現可能なビジュアル、DOM、スタイル、インタラクション、レスポンシブのスコアで再構築する、ソース優先の Web サイトクローンエンジンです。

出力を、法律や所有権を回避する手段として扱わないでください。このエンジンは公開ページの構造を再構築できますが、許可、ライセンス、利用規約への準拠は依然として重要です。

ライセンス

MIT