html-mcp-web

AI 에이전트의 HTML 슬라이드나 리포트를 브라우저에서 검토하고, 정확히 지적하고 싶은 구절을 가리키면 에이전트가 MCP를 통해 댓글을 읽고 수정하게 하세요.

에이전트는 브라우저에서 단독으로 열리는 페이지 형식의 HTML 파일 하나를 작성합니다. 로컬 검토 페이지에서 이 파일을 열고, 렌더링된 텍스트를 선택한 뒤 댓글을 답니다. 에이전트는 MCP를 통해 인용된 문구와 주변 맥락을 읽고, 아티팩트를 수정한 뒤 같은 스레드에서 답변합니다. 파일을 저장하면 아티팩트 프레임만 새로고침되므로 스크롤 위치, 작성 중이던 댓글, 사이드바는 그대로 유지됩니다.

이 도구는 Thariq Shihipar가 설명한 HTML-아티팩트 워크플로를 따르면서, 지속적인 포인팅 채널을 추가합니다. 강조 표시와 댓글 스레드가 프롬프트에 복사되는 대신 에이전트로 직접 전달됩니다.

제공 기능

• 페이지 형식 HTML용 브라우저 검토 페이지: 16:9 슬라이드 또는 A4 리포트, 인쇄 페이지마다 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]'

venv 안의 실행 파일을 사용해 MCP 서버를 에이전트에 한 번 등록하세요. 활성화하지 않아도 경로가 해석됩니다. 저장소 디렉터리에서 실행하세요:

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) 해당 경로로 호출하세요.

빠른 시작

포함된 두 예제를 사용해 보세요:

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 프로젝트를 전환할 수 있습니다. 텍스트를 선택하고 Comment를 누른 다음, 에이전트에게 댓글을 처리하라고 하세요.

나만의 아티팩트 설정

아티팩트가 있거나 생성될 디렉터리에서 프로젝트를 하나 초기화하고 레이아웃을 선택하세요:

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는 로컬 서버 주소입니다. 같은 설정을 찾은 여러 에이전트 세션은 하나의 프로젝트에서 협업합니다. 첫 번째 세션이 서빙하고, 나머지는 서버, 댓글, 수정 사항을 공유하며, 서빙 프로세스가 종료되면 다음 호출에서 다른 세션이 인계받습니다.

검토 루프

아티팩트에서 텍스트를 선택하고 Comment를 누르세요. 앵커는 인용문, 주변 텍스트, DOM 경로, 다이제스트를 저장하여 수정 후에도 다시 연결할 수 있게 합니다. Pages 탭에는 각 페이지의 번호와 첫 번째 제목이 나열됩니다. 내 메시지에는 Edit 링크가 있어 그 자리에서 다시 작성할 수 있고, 에이전트 메시지는 읽기 전용입니다. Resolve와 Dismiss는 한 번의 클릭으로 댓글을 닫습니다.

예를 들어 에이전트에게 이렇게 요청하세요:

열려 있는 html-mcp-web 댓글을 검사하고 처리하세요.

MCP 도구는 다음과 같습니다:

• inspect(artifact): 프로젝트 개요 또는 한 아티팩트의 경로, 수정 버전, 빌드 상태, 레이아웃 오류, 댓글 수.

• 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): 시각적 확인을 위해 한 페이지를 이미지로 렌더링.

• measure_space(artifact, page, revision, clearance, target, min_width, min_height): 페이지 또는 블록 내부의 여유 공간을 CSS 픽셀로 측정.

• export_pptx(artifact, out): 슬라이드 아티팩트를 편집 가능한 pptx로 내보내기.

편집하거나 답변해도 댓글이 닫히지 않습니다. 요청은 현재 아티팩트에서 변경 사항이 확인된 후에만 해결되며, 질문은 답변이 달린 후에도 열려 있습니다. 댓글은 .html-mcp-web/comments/<artifact>.json에 저장되며 선택한 아티팩트 텍스트를 포함하므로, git에서 추적할지 여부는 개인정보 선택 사항입니다.

레이아웃 검사

페이지를 벗어난 항목, viewBox를 넘어서는 인라인 <svg>, 박스의 4분의 1을 비워 두는 SVG, 서로 겹쳐 인쇄된 두 개의 라벨이 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을 다시 읽습니다. 아티팩트, 템플릿, 감시, 무시 변경 사항은 실시간으로 적용되며, 포트 변경은 에이전트가 다시 시작될 때 적용됩니다.

보안

에이전트가 생성한 아티팩트는 로컬 페이지의 권한으로 JavaScript를 실행할 수 있습니다. html-mcp-web은 신뢰할 수 있는 로컬 아티팩트를 위한 것이며 127.0.0.1에만 바인딩됩니다.

라이선스

MIT; LICENSE를 참조하세요.

감사의 말

전체 화면 휠 내비게이션은 Vladimir Kharlampidi와 Swiper 기여자들이 MIT 라이선스로 공개한 Swiper의 Mousewheel 모듈의 의도 감지 전략을 차용했습니다. 방향 변경, 상승 입력, 분리된 휠 펄스, 감쇠하는 트랙패드 모멘텀을 처리하여 연속적인 제스처가 모멘텀 꼬리로 여러 슬라이드를 건너뛰지 않으면서도 반응성을 유지합니다.