html-mcp-web

Review an AI agent's HTML slides or report from the rendered page, on a desktop, tablet, or phone, while Claude Code or Codex edits the source. Hand the finished slides over as an editable PowerPoint deck.

Slides example

Report example

You comment on the rendered page itself: select the words you mean, the way you would mark a printout, and say what should change. The agent reads the comments, edits the HTML, and replies in the same thread, or proposes the exact change and leaves it to you to apply with one click. Saving a file refreshes only the artifact frame, so your scroll position and drafts stay put.

you:    select text -> write a comment -> press Call agent
                  |
agent:  read comments -> edit HTML, or propose a change -> reply
                  |
you:    read the refreshed page -> comment again

Install

Paste this into Claude Code or Codex:

Install html-mcp-web by following https://raw.githubusercontent.com/MiiKiyoshi/html-mcp-web/main/INSTALL.md

The agent checks for Python and Firefox, shows you what it will install, and registers html-mcp-web for every folder once you agree. Start the agent again afterwards.

Related MCP server: lucius

Init

Once per folder, start the agent in the folder that holds (or will hold) your artifact and say:

do html init

The agent asks whether it is slides (16:9) or a report (A4), proposes the file, a template, and a free port, and writes .html-mcp-web.yaml once you agree.

Listen

To review, say:

do html listen

Open http://localhost:<port> with the port you chose at init. Say it again after the agent restarts. Presses of Call agent made meanwhile wait for it.

Suggested edits

When the wording is yours to decide, the agent proposes it instead of making it. The thread shows the source it would change as a −/+ pair, the Source view marks the same text in red, and Apply suggestion writes the change the way saving does, so a templated slide rebuilds at once. Proposing again replaces the proposal, and nothing reaches the source until you apply it. If the change rewrites the words you selected, your comment moves to what replaced them.

Export to PowerPoint and PDF

Slides reviewed here leave as a PowerPoint deck you can keep editing: press PPTX in the topbar. Text stays editable text, tables stay tables, inline SVG drawings stay vector, math becomes an image, and the script under each slide becomes its speaker notes. A skin can name TrueType files to embed the deck font, as templates/SKINS.md explains. PDF prints every page, slides or report, at the layout's fixed size. Both run through headless Firefox.

On a tablet or phone

The review page adapts to the screen: held upright, the comments dock below the artifact and the bar between them drags with a finger. On a phone the comments start closed so the slide has the screen, and ⇥ opens them. Pinch to zoom into the slide, and Fit brings it back. On a touch screen the button that comments on selected text sits clear of your finger.

The server listens on 127.0.0.1 only, so reach it from another device through a forwarded port: an SSH tunnel, VS Code port forwarding, or tailscale serve.

Reviewing

• Select text on the rendered page and press the Comment button that appears beside it. This is the usual way to review: you point at what you see, and the agent finds the source behind it.

• Source and Split show the source as well, for when you want to point at the markup itself. A comment made there covers exactly the selected characters and follows them when the surrounding source moves. Drag the divider to resize. A templated artifact shows its smaller content file.

• + Note comments on the whole artifact, the Pages tab jumps between pages, and Edit fixes your own message.

• Press Call agent when your comments are ready.

• Resolving is yours: Resolve closes a thread. Reference sets one aside to read again, and it still takes replies and returns with Reopen or Resolve.

• The page flags content off the page, clipped SVG drawings, and overlapping labels, and reports them to the agent.

Comments are stored in .html-mcp-web/comments/<artifact>.json and hold the text you selected, so whether to track them in git is a privacy choice.

Templates

A template builds the artifact from a small content file, so you edit content while the cover, bars, and page numbers stay consistent. Pick one at init. This repo ships templates/neutral-slides/ and templates/neutral-report/, and the content format is in templates/README.md. Your own templates go in ~/.config/html-mcp-web/templates/<name>/, and a writing guideline the agent follows in ~/.config/html-mcp-web/guidelines/<name>/GUIDELINE.md.

Configuration

.html-mcp-web.yaml sits in the project folder. Ask the agent to change a field, or edit it.

Security

An agent-generated artifact runs JavaScript with the local page's privileges, so html-mcp-web is for trusted local artifacts and binds to 127.0.0.1 only.

Acknowledgements

MIT licensed. See LICENSE. The source editor uses Ace under the BSD license, and its license is included with the bundled files. Full-screen wheel navigation adapts the intent-detection strategy from Swiper's Mousewheel module by Vladimir Kharlampidi and the Swiper contributors, under the MIT license.