html-mcp-web

Prüfe die HTML-Folien oder den Bericht eines KI-Agenten in deinem Browser, zeige auf die genaue Stelle, die du meinst, und lass den Agenten deinen Kommentar lesen und über MCP beheben.

Der Agent schreibt eine einzelne HTML-Datei mit Seiten, die sich von selbst im Browser öffnet. Du öffnest sie in einer lokalen Review-Seite, wählst gerenderten Text aus und fügst einen Kommentar hinzu. Der Agent liest das verankerte Zitat und seinen Kontext über MCP, bearbeitet das Artefakt und antwortet im selben Thread. Das Speichern einer Datei aktualisiert nur den Artefakt-Rahmen, sodass deine Scrollposition, dein Kommentarentwurf und die Seitenleiste erhalten bleiben.

Dies folgt dem HTML-Artefakt-Workflow, beschrieben von Thariq Shihipar, und fügt einen persistenten Zeigekanal hinzu: Markierungen und Kommentarthreads gehen direkt an den Agenten, anstatt zurück in einen Prompt kopiert zu werden.

Was du bekommst

• Eine Browser-Review-Seite für HTML mit Seiten: 16:9-Folien oder A4-Bericht, ein section.page pro gedruckter Seite.

• Verankerte Kommentare, die Bearbeitungen überstehen, indem sie sich wieder am Zitat und seinem Kontext festmachen.

• Eine Layout-Prüfung, die Inhalte markiert, die über eine Seite hinausragen, abgeschnittene SVG-Zeichnungen und überlappende Beschriftungen – alles im eigenen Maßstab des Artefakts.

• Export als PDF (headless Firefox) und als bearbeitbares PPTX für Folien.

• Vorlagen: Schreibe eine kleine Inhaltsdatei und lass eine Vorlage das Cover, die Balken und die Seitenzahlen liefern.

Voraussetzungen

• Python 3.10 oder neuer.

• Firefox, nur wenn du PDF- oder PPTX-Export möchtest.

Installation

git clone https://github.com/MiiKiyoshi/html-mcp-web.git
cd html-mcp-web
python -m venv .venv
.venv/bin/pip install -e '.[mcp]'

Registriere den MCP-Server einmal bei deinem Agenten, und verwende dabei die ausführbare Datei im venv, damit sie ohne Aktivierung aufgelöst wird. Führe dies aus dem Repository-Verzeichnis aus:

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"

Der Befehl html-mcp-web (Projekteinrichtung) befindet sich ebenfalls in .venv/bin. Aktiviere das venv (source .venv/bin/activate), wenn du es ausführst, oder rufe es über diesen Pfad auf.

Schnellstart

Probiere die beiden mitgelieferten Beispiele aus:

cd html-mcp-web/examples
# Start Claude Code or Codex here, with the html-mcp server enabled.

Bitte den Agenten, inspect() aufzurufen. Die Review-Seite öffnet sich unter http://localhost:8766; die oberen Tabs wechseln zwischen den neutralen Folien- und neutralen Berichtsprojekten. Wähle einen Text aus, drücke Kommentar und bitte den Agenten, die Kommentare zu verarbeiten.

Eigenes Artefakt einrichten

Initialisiere im Verzeichnis, das dein Artefakt enthält (oder enthalten wird), ein Projekt und wähle ein Layout:

html-mcp-web init --layout slides --main artifact.html

Bitte dann den Agenten, inspect() aufzurufen. Vor der Einrichtung gibt er setup_required zurück und bleibt verbunden; nach init startet dieselbe Sitzung den Projekt-Server und die Review-Seite wird unter dem konfigurierten Port verfügbar. init schreibt .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 ordnet einer stabilen ID ihre Bezeichnung, das layout (slides oder report) und die main-Datei zu. watch-Muster aktualisieren Artefakte beim Speichern; ignore wird zuerst geprüft; port ist die lokale Serveradresse. Mehrere Agentensitzungen, die dieselbe Konfiguration finden, arbeiten an einem Projekt zusammen: Die erste bedient es, die übrigen teilen sich Server, Kommentare und Revisionen, und wenn der bedienende Prozess endet, übernimmt ein anderer bei seinem nächsten Aufruf.

Der Review-Zyklus

Wähle Text im Artefakt aus und drücke Kommentar; der Anker speichert das Zitat, umliegenden Text, DOM-Pfad und einen Digest, damit er sich nach Bearbeitungen wieder anheften kann. Der Seiten-Tab listet die Nummer und die erste Überschrift jeder Seite. Deine eigenen Nachrichten tragen einen Bearbeiten-Link, der sie an Ort und Stelle neu schreibt; Agentennachrichten sind schreibgeschützt. Auflösen und Verwerfen schließen einen Kommentar mit einem Klick.

Bitte den Agenten zum Beispiel:

Inspect and process the open html-mcp-web comments.

Die MCP-Werkzeuge sind:

• inspect(artifact): Projektübersicht oder die Pfade, Revision, Build-Status, Layout-Fehler und Kommentaranzahl eines Artefakts.

• list_comments(artifact, status, unanswered, since): kompakte Kommentarliste; unanswered=True behält Threads, deren letzter Eintrag von dir stammt, since=<ISO-Zeit> behält Threads mit einem menschlichen Eintrag danach, und jedes Element trägt last_human_at für den nächsten Aufruf.

• read_comments(artifact, comment_ids): vollständige Anker und Threads für ausgewählte Kommentare.

• reply_comments(artifact, replies, edited_files): antworten, ohne den Status zu ändern.

• set_comment_status(artifact, comment_ids, status, message, edited_files): Status nach Verifizierung ändern; Nachricht optional.

• render_page(artifact, page, dpi, grayscale): eine Seite als Bild für eine visuelle Prüfung rendern.

• measure_space(artifact, page, revision, clearance, target, min_width, min_height): freien Platz auf einer Seite oder in einem Block messen, in CSS-Pixeln.

• export_pptx(artifact, out): ein Folien-Artefakt als bearbeitbares PPTX schreiben.

Bearbeiten oder Antworten schließt einen Kommentar nicht; eine Anfrage wird erst aufgelöst, nachdem ihre Änderung im aktuellen Artefakt verifiziert wurde, während eine Frage nach der Antwort offen bleibt. Kommentare liegen in .html-mcp-web/comments/<artifact>.json, die ausgewählten Artefakttext enthalten, daher ist die Entscheidung, ob sie in Git nachverfolgt werden, eine Frage des Datenschutzes.

Layout-Prüfung

Alles, was außerhalb einer Seite liegt, ein Inline-<svg>, dessen Formen über sein viewBox hinausreichen, ein SVG, das ein Viertel seiner Box leer lässt, und zwei übereinander gedruckte Beschriftungen werden mit der Seitennummer in inspect() gemeldet. Strich und Pfeilspitzen an einer Kante, eine Beschriftung über einer Form und Boxen, die sich nur berühren, werden ignoriert. Die Prüfung läuft in der festen Größe des Artefakts, sodass die gemeldeten Probleme nicht von deiner Fenstergröße oder Zoom abhängen.

Vorlagen

Eine Vorlage kompiliert eine kleine Inhaltsdatei in das überprüfte Artefakt, sodass du den Inhalt bearbeitest, während die Umrandung (Cover, Balken, Seitenzahlen) konsistent bleibt:

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

html-mcp baut bei jedem Speichern des Inhalts neu; Build-Fehler erscheinen als build_error in inspect(). Eine Vorlage ist ein Verzeichnis templates/<name>/ mit einem build.py <content> <out>. Dieses Repository enthält templates/neutral-slides/ und templates/neutral-report/; das Inhaltsformat ist in templates/README.md dokumentiert. Eigene Vorlagen kommen nach ~/.config/html-mcp-web/templates/<name>/ und überschreiben eine mitgelieferte Vorlage mit demselben Namen, sodass sie außerhalb dieses Repositorys bleiben.

Export

Die obere Leiste der Review-Seite exportiert jedes Artefakt als Datei. PDF druckt jede Seite in der festen Größe des Layouts über headless Firefox. PPTX (nur Folien) erstellt ein bearbeitbares Deck und lädt es herunter, wobei auch eine Kopie unter export/<artifact>.pptx hinterlassen wird.

Das PPTX behält jeden Block an der Stelle, an der das HTML ihn platziert hat: Text wird zu Textfeldern (mit Gewicht, Farbe, Größe, Links, Tief-/Hochstellung und <code>-Chips), ul/ol werden zu Aufzählungs- und nummerierten Listen, Tabellen werden zu PPTX-Tabellen, Bilder bleiben Bilder, und ein eigenständiges Inline-<svg> wird als echtes Vektorformat eingebettet (scharf in PowerPoint 2016+ und Mac 2019+) mit einem Screenshot-Fallback; KaTeX-Mathematik bleibt ein Screenshot. Ein Skin kann TrueType-Dateien benennen, um die Deck-Schriftart einzubetten, und sein skin.json-pptx-Block kann eine Vorlage liefern, deren Layouts die Umrandung tragen; siehe templates/README.md.

Konfiguration

Lies oder ändere die Projektkonfiguration aus dem Artefaktverzeichnis:

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-Flags: --layout {slides,report}, --main <datei>, --port <n> und --template <name> --content <datei> für ein vorlagenbasiertes Artefakt. Der Watcher liest .html-mcp-web.yaml nach jedem Speichern neu; Änderungen an Artefakt, Vorlage, Watch und Ignore werden live übernommen, während eine Portänderung erst beim Neustart des Agenten wirksam wird.

Sicherheit

Ein vom Agenten erzeugtes Artefakt kann JavaScript mit den Rechten der lokalen Seite ausführen. html-mcp-web ist für vertrauenswürdige lokale Artefakte gedacht und bindet nur an 127.0.0.1.

Lizenz

MIT; siehe LICENSE.

Danksagungen

Die Vollbild-Mausrad-Navigation übernimmt die Intent-Erkennungsstrategie aus Swiper's Mousewheel-Modul von Vladimir Kharlampidi und den Swiper-Mitwirkenden, veröffentlicht unter der MIT-Lizenz. Sie behandelt Richtungswechsel, steigende Eingaben, getrennte Radimpulse und abklingendes Trackpad-Momentum, sodass aufeinanderfolgende Gesten reaktionsschnell bleiben, ohne dass ein Momentum-Schwanz mehrere Folien überspringt.