mdreview

npx add-mcp 'https://app.mdreview.space/mcp'

mdreview-service

Un microservicio de revisión de markdown contenerizado. Un agente envía markdown mediante POST, recibe una URL de revisión para un humano y consulta comentarios a través de HTTP. Un solo servicio gestiona muchas revisiones, aisladas por id. Sin procesos por instancia, sin sistema de archivos compartido con el agente.

Página de inicio: mdreview.space (servida desde GitHub Pages mediante .github/workflows/pages.yml; código fuente en web/site/).

Documentación: mdreview.space/docs: incorporación, instrucciones y solución de problemas, renderizada mediante el propio renderizador de markdown del servicio (código fuente en web/site/docs/).

Primeros pasos: alojado o autoalojado

Dos formas de usar mdreview; elige una.

1. Alojado (en línea). Una instancia gestionada se ejecuta en mdreview.space (aplicación en app.mdreview.space). Inicia sesión con cualquier dirección de correo electrónico (recibes un enlace de un solo uso; no hay lista de invitación). Tres formas de conectar tu agente.

Conector personalizado de claude.ai (sin token). En claude.ai abre Configuración, Conectores, Añadir conector personalizado e introduce:

https://app.mdreview.space/mcp

Claude abre el inicio de sesión de mdreview; introduce tu correo electrónico, sigue el enlace de un solo uso y aprueba la conexión en la página de consentimiento. Funciona en claude.ai en la web, en el escritorio y en el móvil. Revócalo en cualquier momento en la página de Cuenta.

Plugin de Claude Code. Dentro de Claude Code ejecuta:

/plugin marketplace add ranawaqas-ai/mdreview-service
/plugin install mdreview@mdreview

Solicita un token (genera uno en la página de Cuenta después de iniciar sesión) y lo guarda en tu llavero. Las actualizaciones del plugin llegan a través de /plugin update; el envoltorio no se actualiza a sí mismo dentro de un plugin.

Instalador. En la máquina que ejecuta tu agente (necesita la CLI de claude + python3), con un token de la página de Cuenta:

curl -fsSL https://mdreview.space/install.sh | MDREVIEW_TOKEN=mdr_xxx sh

Eso descarga el envoltorio MCP solo con stdlib en ~/.mdreview y lo registra con Claude Code a nivel de usuario; cierra y vuelve a abrir Claude Code y estarás conectado. Omite MDREVIEW_TOKEN=… para que se te solicite en su lugar. (Para configurarlo manualmente, o para un cliente MCP que no sea Claude Code, consulta Servidor MCP.)

2. Autoalojado (local). Clona y ejecútalo tú mismo (sin cuenta, sin autenticación, en localhost). Consulta Ejecutar y luego apunta el MDREVIEW_BASE de MCP de tu agente a http://localhost:8137. Esta es la vía si quieres tener todo en tu propia máquina.

Solo Python estándar (imagen pequeña, sin instalaciones con pip). Autocontenido: los renderizadores de marked, Mermaid, KaTeX, highlight.js y notas al pie están integrados y se sirven desde /static, por lo que el navegador no necesita CDN. El visor renderiza Markdown como lo haría un sitio Jekyll/MathJax: matemáticas LaTeX (en línea $…$ / \(…\), en bloque $$…$$ / \[…\]; prosa/moneda $ literal a la izquierda), diagramas Mermaid, notas al pie GFM (referencias [^id] → una sección ordenada de referencias inversas) y código en bloques con resaltado de sintaxis (un tema de doble esquema que se lee en paneles claros y oscuros).

Ejecutar

make up        # serves on http://localhost:8137
# or:
docker build -f infra/Dockerfile -t mdreview-service .
docker run -d -p 8137:8080 -v mdreview-data:/data mdreview-service

make up (compose) es la vía canónica local con Docker; sirve en el puerto 8137 y reutiliza el volumen nombrado mdreview-data, por lo que una reconstrucción/recreación conserva tus revisiones.

Comprobación de estado: curl localhost:8137/healthz -> {"ok":true}.

Los comentarios y el código fuente persisten en el volumen /data entre reinicios.

Migrar un contenedor heredado ejecutado manualmente

Si tienes una instancia anterior iniciada manualmente (docker run en un puerto no estándar como :8139), muévela al flujo canónico de compose sin perder datos: el volumen mdreview-data se reutiliza tal cual:

docker rm -f mdreview     # stop the hand-run container (the mdreview-data volume survives)
make up                   # compose recreates it on 8137, mounting the same mdreview-data volume

Debido a que el volumen de compose ahora se declara con un name: mdreview-data explícito (no un infra_mdreview-data con prefijo de proyecto), make up monta exactamente el volumen que poseía tu contenedor antiguo. Confirma con curl localhost:8137/healthz y comprueba que tus revisiones siguen apareciendo.

El flujo

1. Agente: POST /api/reviews {markdown, title} -> {id, review_url, feedback_url, ...}
2. El agente entrega review_url a un humano.
3. El humano lo abre, selecciona texto o hace clic en un número de párrafo, escribe notas (guardado automático).
4. El agente consulta GET /api/reviews/{id}/status y luego GET /api/reviews/{id}/feedback.
5. El agente aplica ediciones y PUT /api/reviews/{id}/source {markdown} -> la página del humano se recarga en vivo y las notas abordadas se tachan. Repite según sea necesario.

Configuración (env)

Variable	Predeterminado	Significado
PORT	8080	puerto de escucha dentro del contenedor
MDREVIEW_DATA	/data	directorio de almacenamiento (monta un volumen)
MDREVIEW_PUBLIC_BASE	vacío	si se establece (p. ej. https://review.example.com), review_url/feedback_url lo usan; de lo contrario, se usa el encabezado Host de la solicitud
MDREVIEW_ENABLE_LATEX	desactivado	opt-in: habilita el modo de revisión de artículos LaTeX (ver más abajo). Requiere la imagen mdreview-service-latex (Tectonic); la imagen slim predeterminada no tiene cadena de herramientas LaTeX

Guías para operadores

Los runbooks que solían estar aquí se han movido para que esta página siga siendo legible:

Guía	Qué cubre
API HTTP	Cada ruta, forma de solicitud y respuesta
Servidor MCP	Ejecutar el servidor stdio, pruebas de humo
Revisión de artículos LaTeX	Habilitarlo, plantillas, el bucle de compilación, el runbook de la imagen
Watcher	El watcher del agente, modo de base confiable, ejecuciones contenerizadas
Sistema de diseño	§01-§10, las reglas de UI que citan los tickets
Ejecuciones autónomas	Cómo los agentes envían cambios aquí

Notas

• Multiinquilino por id, por lo que las revisiones concurrentes nunca colisionan. Sin autenticación (destinado a redes confiables/locales); colócalo detrás de un proxy inverso con autenticación si lo expones.
• El panel (/) y GET /api/reviews enumeran todas las revisiones: está bien para la postura de red confiable, pero es una razón para mantener la autenticación al frente cuando se expone.
• El envoltorio MCP anterior se diseñó en docs/future-mcp.md, conservado como su registro de diseño/decisión.
• Para detalles de integración con agentes, consulta CLAUDE.md.
• Una versión CLI no Docker, por archivo, vive en ../mdreview (escribe comentarios en un archivo junto al código fuente). Este servicio es la forma en red y de múltiples sesiones.

Licencia

Licencia Apache 2.0.

Política de privacidad

El servicio alojado en app.mdreview.space almacena el correo electrónico de tu cuenta, tus revisiones y comentarios, y los registros de seguridad de inicio de sesión. No utiliza cookies de análisis ni de seguimiento, no vende tus datos y no los utiliza para entrenar modelos de IA. La política completa, incluida la retención, eliminación y servicios de terceros, está en https://mdreview.space/privacy/. Las preguntas van a rana.waqas.works@gmail.com. Una instancia autoalojada mantiene todos los datos en tu máquina.