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와 양방향으로 격리됩니다. 주석은 별도의 overlay 위에 그려지며, 제출 시 브라우저 측에서 요소 적중 검출(hit-testing)이 이루어집니다.

설치와 등록

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 클라이언트 타임아웃을 늘려두면 단일 wait_for_annotations 호출이 더 오래 대기할 수 있습니다(설정하지 않아도 동작은 하며, 단지 폴링이 더 자주 발생합니다). shell profile 또는 Claude Code settings의 env에 MCP_TOOL_TIMEOUT=600000을 설정하세요.

도구 개수(4개)

요소 클릭 선택하기(v2)

기본 「선택」 도구 상태에서 마우스를 올리면 커서 아래의 시맨틱 요소가 즉시 강조됩니다(matplotlib의 text_N/line2d_N/legend_N 등의 g[id] 그룹을 대상으로, 최소 면적의 요소를 구하며, 간단한 라벨 태그에 id+텍스트를 표시합니다). 클릭하면 요소 검사기가 나타납니다(사이드바에 id, 각 요소의 원문 텍스트, 조상 목록(브레드크럼)을 표시하고, 브레드크럼을 눌러 상위 그룹을 다시 선택할 수 있습니다. 예: text_3 → legend_1). 「수정 설명」란에 내용을 입력했을 때만 주석으로 가져옵니다(단순 클릭은 조사자일 뿐, 주석이 만들어지지 않음). Esc 키 또는 「선택(box)」 버튼으로 종료합니다. 요소 주석은 그림 위에 점선 상자 + 번호로 표현됩니다.

주석 반환 구조 (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_1/line_1 등 시맨틱 그룹) / text(요소 텍스트 그대로) / ancestors(예: ["figure_1","legend_1","text_54"] 등 조상 id 체인) / bbox_svg / coverage / d_prefix(해당 경로의 d 앞 30글자, SVG를 직접 수정할 때 grep 기준)를 포함. 전처리가 이미 되어 있습니다: 배경용 콘테이너는 제거되고, 시맨틱 그룹이 우선시되며(그룹 내부 요소는 중복하지 않음), 각 목록은 최대 10개.

• texts_in_region: 선택 영역 안의 모든 문자들(읽는 순서대로, 중복 제거) — 생성 스크립트에서 위치를 grep으로 찾는 첫 번째 단서가 됩니다.

무엇을 변경할지 결정하는 것은 Claude지정입니다: 주석에 source_script가 포함되어 있다면, 우선 스크립트에서 수정하고 스크립트를 다시 실행하는 것을 우선하세요(SVG 결과물을 변경하면 다음 실행 때 덮어쓰기 때문에). 스크립트가 없는 그림은 SVG 파일을 직접 변경하면 됩니다. 페이지는 변경 방법에 대해 어떤 가정도 하지 않으며, 파일의 mtime 변화만 감지합니다(500ms 폴링, 안정적인 중간 상태 확인, </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 을 추가하면 클릭/강조까지만 수행하며, 검사기 화면을 캡처할 때 사용). GXP3

환경 변수: SVG_ANNOTATE_NO_OPEN=1로 설정하면 open_svg가 브라우저를 자동으로 열지 않습니다(테스트 목적).

알려진 제약 (첫 번째 버전)

‘단일 세션’ 입니다(한 번에 한 장의 그림만 담으며, 다시 열면 이전 그림을 대체합니다. 다수의 Claude 세션은 각자의 서버 인스턴스로 동작해 간섭하지 않습니다); 주석 파일(annotations.json)은 만들지 않습니다(주석은 메모리로만 이전되며, 서버가 재시작되면 사라지므로 Claude의 컨텍스트에 보관을 의지합니다). SVG 내부에서 외부 링크(외부 소스)를 프록시하지 않습니다(open_svg 실행 시 경고가 표시될 수 있으나, matplotlib 산출물은 모두 인라인화되어 있어 경고를 발생하지 않습니다). 브라우저가 macOS의 open 명령으로만 열립니다. localhost에서는 인증(보안)이 없습니다.