html-mcp-web

ブラウザでAIエージェントのHTMLスライドやレポートをレビューし、該当箇所を正確に指摘。エージェントはMCP経由でコメントを読み取り、修正します。

エージェントは、ブラウザで単体で開くページ形式のHTMLファイルを1つ作成します。それをローカルのレビューページで開き、レンダリングされたテキストを選択してコメントを添付します。エージェントは、アンカーされた引用とその周辺のコンテキストをMCP経由で読み取り、アーティファクトを編集し、同じスレッド内で返信します。ファイルを保存するとアーティファクトのフレームだけが更新されるため、スクロール位置、下書きのコメント、サイドバーはそのまま維持されます。

これは Thariq Shihipar氏が解説するHTMLアーティファクトのワークフロー に従ったもので、永続的なポインティングチャネルを追加します。ハイライトとコメントスレッドは、プロンプトにコピーして戻すのではなく、エージェントに直接送られます。

得られるもの

• ページ形式HTML用のブラウザレビューページ: 16:9のスライドまたはA4のレポート。印刷される各ページに1つの section.page が対応します。

• 編集後も引用とそのコンテキストに再アタッチして存続するアンカーコメント。

• ページからはみ出したコンテンツ、クリップされたSVG図形、重なったラベルを、すべてアーティファクト固有のスケールで検出するレイアウトチェック。

• PDF(ヘッドレスFirefox)と、スライド用の編集可能なPPTXへのエクスポート。

• テンプレート: 小さなコンテンツファイルを書き、テンプレートに表紙、バー、ページ番号を任せられます。

要件

• Python 3.10以降。

• Firefox(PDFまたはPPTXエクスポートを利用する場合のみ)。

インストール

git clone https://github.com/MiiKiyoshi/html-mcp-web.git
cd html-mcp-web
python -m venv .venv
.venv/bin/pip install -e '.[mcp]'

MCPサーバーをエージェントに一度だけ登録します。venv内の実行ファイルを使用すると、アクティベーションなしで解決されます。リポジトリのディレクトリからこれを実行してください:

Claude Code:

claude mcp add --scope user html-mcp -- "$PWD/.venv/bin/html-mcp"

Codex:

codex mcp add html-mcp -- "$PWD/.venv/bin/html-mcp"

html-mcp-web コマンド(プロジェクトセットアップ用)も .venv/bin にあります。実行するときはvenvをアクティベートするか (source .venv/bin/activate)、そのパスで呼び出してください。

クイックスタート

同梱の2つのサンプルをお試しください:

cd html-mcp-web/examples
# Start Claude Code or Codex here, with the html-mcp server enabled.

エージェントに inspect() を呼び出すよう依頼します。レビューページが http://localhost:8766 で開きます。上部のタブでneutral slidesプロジェクトとneutral reportプロジェクトを切り替えられます。テキストを選択してコメントを押し、エージェントにコメントを処理するよう依頼してください。

独自のアーティファクトを設定する

アーティファクトを置く(または置く予定の)ディレクトリで、プロジェクトを1つ初期化し、レイアウトを選択します:

html-mcp-web init --layout slides --main artifact.html

次に、エージェントに inspect() を呼び出すよう依頼します。セットアップ前は setup_required を返し、接続を維持します。init の後、同じセッションがプロジェクトサーバーを起動し、レビューページが設定されたポートで利用可能になります。init は .html-mcp-web.yaml を書き出します:

artifacts:
  slides:
    label: Slides
    layout: slides
    main: artifact.html
watch: ['*.html', '*.css', '*.js', '*.svg', '*.png', '*.jpg', '*.jpeg', '*.gif', '*.webp']
ignore: []
port: 8765

artifacts は、安定したIDをそのラベル、layout (slides または report)、main ファイルに対応付けます。watch パターンは保存時にアーティファクトを更新します。ignore が最初にチェックされ、port はローカルサーバーのアドレスです。同じ設定を見つけた複数のエージェントセッションは、1つのプロジェクト上で協調します。最初のセッションが提供し、残りはそのサーバー、コメント、リビジョンを共有します。提供中のプロセスが終了すると、別のセッションが次の呼び出しで引き継ぎます。

レビューループ

アーティファクト内のテキストを選択してコメントを押します。アンカーは引用、周辺テキスト、DOMパス、ダイジェストを保存するため、編集後に再アタッチできます。ページタブには、各ページの番号と最初の見出しが一覧表示されます。自分のメッセージには、その場で書き換える編集リンクがあります。エージェントのメッセージは読み取り専用です。解決と却下はワンクリックでコメントを閉じます。

たとえば、エージェントにこう依頼します:

html-mcp-webで開いているコメントをinspectして処理してください。

MCPツールは以下のとおりです:

• inspect(artifact): プロジェクトの概要、または1つのアーティファクトのパス、リビジョン、ビルド状態、レイアウトエラー、コメント数。

• list_comments(artifact, status, unanswered, since): コンパクトなコメント一覧。unanswered=True は最新のエントリが自分のスレッドを保持し、since=<ISO time> はその後に人間によるエントリがあるスレッドを保持します。各項目には次回呼び出し用の last_human_at が含まれます。

• read_comments(artifact, comment_ids): 選択したコメントの完全なアンカーとスレッド。

• reply_comments(artifact, replies, edited_files): ステータスを変更せずに返信します。

• set_comment_status(artifact, comment_ids, status, message, edited_files): 検証後にステータスを変更します。messageはオプションです。

• render_page(artifact, page, dpi, grayscale): 視覚的な確認のため、1ページを画像としてレンダリングします。

• measure_space(artifact, page, revision, clearance, target, min_width, min_height): ページ上または1つのブロック内の空きスペースをCSSピクセル単位で測定します。

• export_pptx(artifact, out): スライドアーティファクトを編集可能なpptxとして書き出します。

編集や返信ではコメントは閉じません。リクエストは、現在のアーティファクトで変更が検証された後にのみ解決されます。一方、質問は返信後も開いたままです。コメントは .html-mcp-web/comments/<artifact>.json に保存され、選択されたアーティファクトのテキストが含まれます。したがって、gitで追跡するかどうかはプライバシーの選択です。

レイアウトチェック

ページの外にあるもの、viewBox を超えて図形がはみ出すインライン <svg>、ボックスの4分の1が空のSVG、互いに重なって印刷された2つのラベルは、inspect() でページ番号とともに報告されます。エッジのストロークと矢印、シェイプの上にあるラベル、単に接触しているだけのボックスは対象外です。チェックはアーティファクトの固定サイズで実行されるため、報告される問題はウィンドウサイズやズームに依存しません。

テンプレート

テンプレートは小さなコンテンツファイルをレビュー対象のアーティファクトにコンパイルするため、クローム(表紙、バー、ページ番号)を一貫させたままコンテンツを編集できます:

html-mcp-web init --layout slides --main slides.html --template neutral-slides --content content.html

html-mcpはコンテンツが保存されるたびに再ビルドします。ビルド失敗は inspect() で build_error として表示されます。テンプレートは、build.py <content> <out> を持つディレクトリ templates/<name>/ です。このリポジトリには templates/neutral-slides/ と templates/neutral-report/ が同梱されています。コンテンツ形式は templates/README.md に文書化されています。独自のテンプレートは ~/.config/html-mcp-web/templates/<name>/ に置きます。同じ名前の同梱テンプレートを上書きするため、このリポジトリの外に保持されます。

エクスポート

レビューページの上部バーは、各アーティファクトをファイルとしてエクスポートします。PDFは、ヘッドレスFirefoxを通じてレイアウトの固定サイズですべてのページを印刷します。PPTX(スライドのみ)は、編集可能なデッキをビルドしてダウンロードし、export/<artifact>.pptx にもコピーを残します。

pptxは、htmlが配置した場所に各ブロックを維持します。テキストはテキストボックス(太さ、色、サイズ、リンク、上付き/下付き文字、<code>チップを含む)になり、ul/ol は箇条書きリストと番号付きリストになり、テーブルはpptxテーブルになり、画像は画像のままになります。自己完結型のインライン <svg> は実際のベクター(PowerPoint 2016+ と Mac 2019+ で鮮明)として埋め込まれ、スクリーンショットのフォールバック付きです。KaTeXの数式はスクリーンショットのままです。スキンはTrueTypeファイルを指定してデッキのフォントを埋め込むことができ、その skin.json の pptx ブロックは、レイアウトがクロームを担うテンプレートを提供できます。templates/README.md を参照してください。

設定

アーティファクトディレクトリからプロジェクト設定を読み取るか変更します:

html-mcp-web config                                  # print the whole config
html-mcp-web config artifacts.slides.layout report   # change one value
html-mcp-web config port 8766
html-mcp-web config watch '*.html,assets/**'

init のフラグ: --layout {slides,report}、--main <file>、--port <n>、テンプレートアーティファクト用の --template <name> --content <file>。ウォッチャーは保存のたびに .html-mcp-web.yaml を再読み込みします。アーティファクト、テンプレート、watch、ignoreの変更はライブで適用され、ポートの変更はエージェントの再起動時に有効になります。

セキュリティ

エージェントが生成したアーティファクトは、ローカルページの権限でJavaScriptを実行できます。html-mcp-webは信頼できるローカルアーティファクトを対象としており、127.0.0.1 にのみバインドします。

ライセンス

MIT。 LICENSE を参照してください。

謝辞

全画面ホイールナビゲーションは、SwiperのMousewheelモジュール(Vladimir Kharlampidi氏とSwiperコントリビューターによる、MITライセンスで公開)の意図検出戦略を採用しています。これは、方向の変化、増加する入力、分離されたホイールパルス、減衰するトラックパッドのモメンタムを処理するため、1つのモメンタムテールが複数のスライドをスキップすることなく、連続したジェスチャーに応答し続けられます。