svg-annotate-mcp

ブラウザ上で SVG 論文図に注釈を付けます——要素をクリック（ホバーするとセマンティック要素をハイライト、Claude Design 方式）または領域を囲んで選び、注釈（ヒットした SVG 要素情報を含む）を MCP 経由で Claude に返します。Claude がソースファイル（SVG または生成スクリプト）を修正し、ページがファイルの変更を監視して自動更新する——「注釈 → 修正 → 更新 → 再注釈」のクローズドループを形成します。

• バックエンド：Python＋公式 mcp SDK（MCPServer、stdio）。プロセス内で stdlib の HTTP スレッド（127.0.0.1、一時ポート）を起動します。

• フロントエンド：単一ファイル src/svg_annotate_mcp/web/index.html。SVG は fetch ＋ DOMParser で Shadow DOM に注入され（ページ側のスタイル・id と相互に隔離）、注釈は独立したオーバーレイに描画されます。送信時にはブラウザ側で要素のヒット判定を行います。

インストールと登録

cd ~/Projects/svg-annotate-mcp && uv sync
claude mcp add --scope user svg-annotate -- \
  uv run --directory /Users/boryant/Projects/svg-annotate-mcp svg-annotate-mcp

任意設定：MCP クライアントのタイムアウトを緩めて、1 回の wait_for_annotations をより長く待てるようにします（設定しなくても動作し、ループがより頻繁になるだけです）。シェルの profile または Claude Code settings の env に MCP_TOOL_TIMEOUT=600000 を設定してください。

ツール面（4 つ）

要素レベルのクリック選択（v2）

既定の「選択」ツールでは、ホバーするとカーソル下のセマンティック要素がリアルタイムにハイライトされます（matplotlib の text_N/line2d_N/legend_N など、g[id] のグループから最小面積のヒットを取得。ラベルチップに id と文字を表示）。クリックすると要素インスペクタに入ります（サイドバーに id・一字一句そのままのテキスト・祖先のパンくずリストを表示——パンくずをクリックすると選択を親グループに変更できます。例:text_54 → legend_1）。「変更説明」に内容を入力して初めて注釈が生成されます（クリックのみ＝インスペクタであり、ゴミ注釈は生まれません）。Esc または「選択を解除」で終了します。要素注釈は図上で点線の枠＋番号として描画されます。

注釈の返信構造（Claude が位置を特定する設計）

各注釈には次が含まれます：

• kind（element/rect/arrow/freehand/text）、note（ユーザーの変更説明）、number（キャンバス上の番号）；

• kind:"element" のときは target:要素をクリックした時の tag/id/text（一字一句）/ancestors/d_prefix/bbox_svg——これは最も強力な位置のアンカーなので、優先的に使ってください（id または text で生成スクリプト/SVG を直接 grep できます）；

• geometry_norm（0-1）と geometry_svg（viewBox 座標。サーバー側で変換済み）；

• hits[]: 選択領域でヒットした SVG 要素。それぞれに tag/id（matplotlib の text_N/line2d_N などのセマンティックグループ）/text（要素の文字、一字一句）/ancestors（祖先 id の連鎖。例:["figure_1","legend_1","text_54"]）/bbox_svg/coverage/d_prefix（path の d の先頭 30 文字。SVG を直接修正するときの grep アンカー）が含まれます。すでにデノイズ済み: 背景コンテナを除去、セマンティックグループ優先（グループ内の葉を重複して報告しない）、1 注釈あたり最大 10 件；

• texts_in_region: 選択領域内のすべての文字（説明順、重複なし）——生成スクリプトの中で grep して位置を特定する第一の手がかりです。

どこを修正するかは Claude が判断します: 注釈に source_script が付属していれば、スクリプトを修正して再実行するほうを優先します（修正 SVG の生成結果を直接修正すると、次の再実行で上書きされます）。スクリプトのない図は SVG ファイルを直接修正します。ページは修正の方法を一切を想定しません。ただファイルの mtime 変化のみを監視します（500ms ポーリング、2 回検証による安定化、</svg> の末尾チェックで書き込み途中の回避）。

注釈のライフサイクル

未送信のドラフトはページ更新後も保持されます。「Claude に送信」をクリックすると、その注釈は 35% の半透明で図に残ります（番号は維持され、対照しやすくなります）。Claude がファイルを修正してからトリガーされる次のページ更新で、半透明の注釈はクリアされます。

典型的なクローズドループ

用户: 帮我改 figure11,我来圈
Claude: open_svg("/path/figures/figure11.svg", source_script="/path/fig_tri_complement.py")
        wait_for_annotations()          # 挂起
用户: (浏览器里圈图例写「图例移到右上」,点提交)
Claude: 收到批注 → set_status("正在改 fig_tri_complement.py…")
        → 改脚本 → 重跑出图 → 页面自动刷新
        → wait_for_annotations()        # 等下一轮

テスト

uv run python tests/smoke_test.py     # 端到端:握手/HTTP/阻塞等待/坐标换算/SSE reload/复用 tab
uv run python tests/manual_driver.py <svg> [script]   # 起 server 供手动/浏览器自动化测试,批次落盘 tests/out/batches.jsonl

ページのデバッグ用パラメータ：?nosse=1 で SSE をスキップ（headless スクリーンショット用）；?autotest=x,y,w,h で読み込み後に自動的に長方形の注釈を描いて送信（0-1 正規化座標）；?autotest_click=x,y でその座標の要素をクリック選択して正式のまま送信（&autotest_stage=pick を付けると選択ハイライトまでに留め、インスペクタのスクリーンショット用）。

環境変数：SVG_ANNOTATE_NO_OPEN=1 を設定すると open_svg がブラウザを自動で開きません（テスト用）。

既知の制約（初版）

単一セッション（一度の図、次に open すると図を切り替え。複数の Claude セッション＝相互に干渉しない複数の server インスタンス）；annotations.json はエクスポートしません（注釈はメモリ経由でのみ返され、server 再起動で失われる。なので Claude の文脈に残ることに依存）；SVG 内の外部リンクリソースはプロキシしません（open_svg が warning を出します。matplotlib の生成物はすべてインラインなので、この条件は成立しません）；ブラウザを開くのは macOS の open のみ。localhost では認証なし。