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 项目之间切换。选择一些文本，按 评论，然后让代理处理评论。

设置你自己的工件

在存放（或将存放）你的工件的目录中，初始化一个项目并选择布局：

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 是本地服务器地址。多个找到相同配置的代理会话在一个项目上协作：第一个提供服务，其余共享其服务器、评论和修订，如果服务进程退出，另一个会在下次调用时接管。

审阅循环

在工件中选择文本并按 评论；锚点存储引用、附近文本、DOM 路径和摘要，以便在编辑后重新附着。页面 标签列出每个页面的编号和第一个标题。你自己的消息带有 编辑 链接，可原地重写；代理消息是只读的。解决 和 关闭 可一键关闭评论。

例如，让代理：

检查并处理打开的 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>、留下四分之一框为空的 SVG，以及相互打印重叠的两个标签，都会在 inspect() 中报告页面编号。边缘的描边和箭头、形状上的标签以及仅接触的框则被忽略。检查在工件的固定尺寸下运行，因此报告的问题不依赖于你的窗口大小或缩放。

模板

模板将小型内容文件编译为被审阅的工件，这样你编辑内容时界面装饰（封面、条栏、页码）保持一致：

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

html-mcp 在每次内容保存时重建；构建失败在 inspect() 中显示为 build_error。模板是一个目录 templates/<name>/，包含 build.py <content> <out>。本仓库附带 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 许可证 发布。它处理方向变化、上升输入、分离的滚动脉冲和衰减的触控板动量，使连续手势保持响应，而不会让一个动量尾部跳过多个幻灯片。