html-mcp-web

Revisa las diapositivas o el informe HTML de un agente de IA en tu navegador, señala el pasaje exacto al que te refieres y deja que el agente lea tu comentario y lo corrija a través de MCP.

El agente escribe un archivo HTML paginado que se abre por sí solo en un navegador. Tú lo abres en una página de revisión local, seleccionas el texto renderizado y adjuntas un comentario. El agente lee la cita anclada y su contexto circundante a través de MCP, edita el artefacto y responde en el mismo hilo. Al guardar un archivo, solo se actualiza el marco del artefacto, por lo que la posición de desplazamiento, el borrador del comentario y la barra lateral permanecen en su sitio.

Esto sigue el flujo de trabajo de artefactos HTML descrito por Thariq Shihipar y añade un canal de señalización persistente: los resaltados y los hilos de comentarios van directamente al agente en lugar de copiarse de nuevo en un prompt.

Qué incluye

• Una página de revisión en el navegador para HTML paginado: diapositivas 16:9 o informe A4, con una section.page por página impresa.

• Comentarios anclados que sobreviven a las ediciones volviéndose a enganchar a la cita y su contexto.

• Una comprobación de maquetación que señala el contenido que se desborda de una página, los dibujos SVG recortados y las etiquetas superpuestas, todo a la escala del propio artefacto.

• Exportación a PDF (Firefox sin interfaz) y a PPTX editable para diapositivas.

• Plantillas: escribe un pequeño archivo de contenido y deja que una plantilla proporcione la portada, las barras y los números de página.

Requisitos

• Python 3.10 o superior.

• Firefox, solo si quieres exportar a PDF o PPTX.

Instalación

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

Registra el servidor MCP en tu agente una sola vez, usando el ejecutable dentro del venv para que se resuelva sin activación. Ejecuta esto desde el directorio del repositorio:

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"

El comando html-mcp-web (configuración del proyecto) también se encuentra en .venv/bin. Activa el venv (source .venv/bin/activate) al ejecutarlo, o llámalo con esa ruta.

Inicio rápido

Prueba los dos ejemplos incluidos:

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

Pide al agente que llame a inspect(). La página de revisión se abre en http://localhost:8766; las pestañas superiores alternan entre los proyectos neutral slides y neutral report. Selecciona un texto, pulsa Comment y pide al agente que procese los comentarios.

Configura tu propio artefacto

En el directorio que contiene (o contendrá) tu artefacto, inicializa un proyecto y elige un diseño:

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

A continuación, pide al agente que llame a inspect(). Antes de la configuración, devuelve setup_required y permanece conectado; después de init, la misma sesión inicia el servidor del proyecto y la página de revisión queda disponible en el puerto configurado. init escribe .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 asigna un id estable a su etiqueta, layout (slides o report) y archivo main. Los patrones de watch actualizan los artefactos al guardar; ignore se comprueba primero; port es la dirección del servidor local. Varias sesiones de agente que encuentren la misma configuración colaboran en un proyecto: la primera lo sirve, las demás comparten su servidor, comentarios y revisiones, y si el proceso que sirve sale, otro toma el relevo en su siguiente llamada.

El bucle de revisión

Selecciona texto en el artefacto y pulsa Comment; el ancla guarda la cita, el texto cercano, la ruta DOM y un resumen para poder volver a engancharse tras las ediciones. La pestaña Pages enumera el número y el primer encabezado de cada página. Tus propios mensajes llevan un enlace Edit que los reescribe en el sitio; los mensajes del agente son de solo lectura. Resolve y Dismiss cierran un comentario con un clic.

Pide al agente, por ejemplo:

Inspecciona y procesa los comentarios abiertos de html-mcp-web.

Las herramientas MCP son:

• inspect(artifact): visión general del proyecto, o las rutas, revisión, estado de compilación, errores de maquetación y recuento de comentarios de un artefacto.

• list_comments(artifact, status, unanswered, since): lista de comentarios compacta; unanswered=True conserva los hilos cuya última entrada es tuya, since=<ISO time> conserva los hilos con una entrada humana posterior, y cada elemento lleva last_human_at para la siguiente llamada.

• read_comments(artifact, comment_ids): anclas e hilos completos de los comentarios elegidos.

• reply_comments(artifact, replies, edited_files): responde sin cambiar el estado.

• set_comment_status(artifact, comment_ids, status, message, edited_files): cambia el estado tras verificar; message es opcional.

• render_page(artifact, page, dpi, grayscale): renderiza una página como imagen para una comprobación visual.

• measure_space(artifact, page, revision, clearance, target, min_width, min_height): mide el espacio libre en una página o dentro de un bloque, en píxeles CSS.

• export_pptx(artifact, out): escribe un artefacto de diapositivas como pptx editable.

Editar o responder no cierra un comentario; una solicitud se resuelve solo después de verificar su cambio en el artefacto actual, mientras que una pregunta permanece abierta tras la respuesta. Los comentarios viven en .html-mcp-web/comments/<artifact>.json, que contienen texto seleccionado del artefacto, por lo que rastrearlos o no en git es una decisión de privacidad.

Comprobación de maquetación

Cualquier elemento fuera de una página, un <svg> en línea cuyas formas sobrepasen su viewBox, un SVG que deje un cuarto de su caja vacío y dos etiquetas superpuestas se notifican con el número de página en inspect(). El trazo y las puntas de flecha en un borde, una etiqueta sobre una forma y las cajas que solo se tocan se ignoran. La comprobación se ejecuta al tamaño fijo del artefacto, por lo que los problemas notificados no dependen del tamaño de la ventana ni del zoom.

Plantillas

Una plantilla compila un pequeño archivo de contenido en el artefacto revisado para que edites el contenido mientras el marco (portada, barras, números de página) se mantiene coherente:

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

html-mcp se reconstruye en cada guardado de contenido; los fallos de compilación aparecen como build_error en inspect(). Una plantilla es un directorio templates/<name>/ con un build.py <content> <out>. Este repositorio incluye templates/neutral-slides/ y templates/neutral-report/; el formato de contenido está documentado en templates/README.md. Tus propias plantillas van en ~/.config/html-mcp-web/templates/<name>/ y sobrescriben una plantilla incluida del mismo nombre, de modo que quedan fuera de este repositorio.

Exportación

La barra superior de la página de revisión exporta cada artefacto como archivo. PDF imprime cada página al tamaño fijo del diseño mediante Firefox sin interfaz. PPTX (solo diapositivas) crea una presentación editable y la descarga, dejando también una copia en export/<artifact>.pptx.

El pptx mantiene cada bloque donde el html lo colocó: el texto se convierte en cuadros de texto (con peso, color, tamaño, enlaces, subíndices/superíndices y chips <code>), ul/ol se convierten en listas con viñetas y numeradas, las tablas se convierten en tablas pptx, las imágenes siguen siendo imágenes, y un <svg> en línea autocontenido se incrusta como vector real (nítido en PowerPoint 2016+ y Mac 2019+) con una captura de pantalla como respaldo; las matemáticas de KaTeX siguen siendo una captura. Una piel puede nombrar archivos TrueType para incrustar la fuente de la presentación, y su bloque pptx de skin.json puede proporcionar una plantilla cuyos diseños lleven el marco; consulta templates/README.md.

Configuración

Lee o cambia la configuración del proyecto desde el directorio del artefacto:

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/**'

Banderas de init: --layout {slides,report}, --main <file>, --port <n> y --template <name> --content <file> para un artefacto con plantilla. El vigilante vuelve a leer .html-mcp-web.yaml tras cada guardado; los cambios de artefacto, plantilla, watch e ignore se aplican en caliente, mientras que un cambio de puerto surte efecto cuando se reinicia el agente.

Seguridad

Un artefacto generado por un agente puede ejecutar JavaScript con los privilegios de la página local. html-mcp-web está pensado para artefactos locales de confianza y solo se vincula a 127.0.0.1.

Licencia

MIT; consulta LICENSE.

Agradecimientos

La navegación a pantalla completa con la rueda adapta la estrategia de detección de intención del módulo Mousewheel de Swiper de Vladimir Kharlampidi y los colaboradores de Swiper, publicado bajo la Licencia MIT. Gestiona los cambios de dirección, la entrada creciente, los pulsos de rueda separados y el impulso decreciente del trackpad para que los gestos consecutivos sigan respondiendo sin que una cola de impulso se salte varias diapositivas.