md-redline

Comentarios de revisión en línea para especificaciones de markdown y documentos de diseño. Los agentes solicitan revisión humana durante la tarea a través de MCP y se pausan hasta que envíes comentarios.

GitHub

Prueba este MCPPatrocinado

Documentación

md-redline

Comentarios de revisión en línea para especificaciones de Markdown, prompts y documentos de diseño.

Resalta texto en un documento renderizado, deja comentarios, y tu agente de IA puede leerlos y abordarlos directamente. Los comentarios se almacenan como marcadores HTML invisibles en el propio archivo .md. Sin archivos auxiliares, sin base de datos, sin servicio externo. El archivo Markdown sigue siendo la fuente de verdad.

Con el servidor MCP integrado, la revisión funciona en ambas direcciones. Tu agente puede solicitar tu revisión a mitad de tarea y pausar hasta que envíes tus comentarios, o revisar un documento que escribiste y dejar comentarios anclados para ti. En cualquier caso: sin copiar y pegar, sin cambiar de contexto.

md-redline screenshot

Mira el flujo de revisión completo en 30 segundos:

https://github.com/user-attachments/assets/3a2bf20a-d4a0-403c-b023-e877130fd959

Funciona con Claude Code, Claude Desktop, Codex CLI, Gemini CLI y cualquier otro cliente MCP que admita servidores stdio. Como argumenta Sean Grove en las especificaciones son el nuevo código, las especificaciones se están convirtiendo en la unidad principal de trabajo en el desarrollo agéntico. mdr brinda a ese flujo de trabajo herramientas de revisión más cercanas a la revisión de código.

Inicio rápido

Requisito previo: Node 20 o más reciente.

npx md-redline /path/to/spec.md

Esto inicia la aplicación local si es necesario y la abre en tu navegador.

O instala globalmente:

npm install -g md-redline
mdr /path/to/spec.md        # Open a file
mdr /path/to/dir             # Open a directory
mdr --stop                   # Stop the running server

md-redline también funciona como alias para mdr.

Eso te da el visor y los comentarios. La integración con el agente (revisiones en ambas direcciones, preguntas ancladas) proviene del servidor MCP, registrado en la siguiente sección.

Actualización

mdr verifica npm una vez al día (desde su servidor local, sin bloquear nada) y muestra un pequeño aviso en el visor y en la terminal cuando hay una nueva versión disponible. Actualizar es un solo comando:

npm install -g md-redline@latest

El servidor en ejecución se reinicia solo en la siguiente invocación de mdr después de una actualización. Para deshabilitar por completo las comprobaciones de actualización, establece NO_UPDATE_NOTIFIER=1 (o ejecuta en CI, que se detecta automáticamente). Ten en cuenta que esto es una comprobación de presencia, siguiendo la convención del ecosistema: cualquier valor, incluso 0 o vacío, deshabilita las comprobaciones.

Configuración de MCP

Registra el servidor MCP con tu agente para que pueda solicitar revisiones a mitad de tarea.

Claude Code o Claude Desktop

mdr mcp install                   # register with both clients (default)
mdr mcp install --claude-code     # just Claude Code (via `claude mcp add`)
mdr mcp install --claude-desktop  # just Claude Desktop (JSON config file)

Codex CLI

codex mcp add md-redline -- mdr mcp

Gemini CLI

gemini mcp add --scope user md-redline mdr mcp

La bandera --scope user es importante. Gemini usa por defecto el ámbito por proyecto, que solo registra mdr para el directorio actual.

Otros clientes MCP

Agrega esta entrada de servidor al archivo de configuración MCP de tu cliente:

{
  "mcpServers": {
    "md-redline": {
      "command": "mdr",
      "args": ["mcp"]
    }
  }
}

Requisito previo: mdr debe estar en tu PATH (por ejemplo, mediante npm install -g md-redline). Si tu cliente genera subprocesos sin heredar el PATH de tu shell, usa la ruta absoluta de which mdr como valor de command.

Después de instalar, reinicia tu cliente MCP; la mayoría de los clientes solo descubren nuevos servidores al iniciar. Para verificar, pregúntale a tu agente "¿qué herramientas mdr tienes?" y debería listar mdr_request_review, mdr_review, mdr_ask y mdr_wait.

Flujo de revisión

Con MCP registrado, la revisión funciona en ambas direcciones. Elige según quién da los comentarios:

	Tú revisas el documento del agente	El agente revisa tu documento
Momento típico	El agente acaba de redactar o editar una especificación; quieres marcarla antes de que continúe	Escribiste un PRD (o recibiste uno) y quieres una crítica
Lo que dices	"Déjame revisar specs/feature-x.md en mdr antes de que continúes."	"Usa mdr para revisar prd.md y deja comentarios."
Quién comenta	Tú	El agente
Cómo termina	Haces clic en Enviar y finalizar	Haces clic en Finalizar revisión

1. Tú revisas el documento del agente

El flujo común justo después de que un agente redacta un documento. Dile al agente:

"Déjame revisar docs/specs/feature-x.md en mdr antes de que continúes."

El agente llama a mdr_request_review y se pausa. mdr abre el archivo, tú resaltas texto y dejas comentarios, luego haces clic en Enviar N comentarios. El agente recibe tus comentarios como un prompt estructurado y comienza a abordarlos. Puedes seguir enviando lotes de seguimiento mientras trabaja; Enviar N y finalizar envía el último lote y cierra el ciclo. La revisión es opcional por solicitud. El agente solo se pausa cuando lo pides.

2. El agente revisa tu documento

La dirección inversa, para documentos que el agente no acaba de escribir: tu propio borrador, el PRD de un compañero, una especificación de otro repositorio. Dile al agente:

"Usa mdr para revisar prd.md y deja comentarios."

El agente llama a mdr_review. Sus hallazgos se convierten en comentarios en línea anclados al texto exacto, y el navegador se abre para que puedas leerlos a medida que llegan. Luego el agente espera (mediante mdr_wait) mientras trabajas con los comentarios: responde en cualquier tarjeta, edita el documento, elimina comentarios con los que no estés de acuerdo. Cuando termines, haz clic en Finalizar revisión en el banner. Ese clic es la señal para que el agente vuelva a leer el archivo y recoja tus respuestas y ediciones, por lo que la sesión permanece abierta hasta que lo presiones. El agente no está atascado; está escuchando.

https://github.com/user-attachments/assets/41339401-6096-40de-abbf-e93ef7ffd2c2

En cualquier dirección: el agente puede hacerte preguntas

Dentro de cualquier sesión activa, el agente puede llegar a una bifurcación donde tu respuesta cambia lo que debería hacer a continuación. En lugar de adivinar, puede llamar a mdr_ask para publicar preguntas ancladas en el documento y bloquearse hasta que respondas:

Recibes una notificación con un botón Ver, un chip en el banner ("N preguntas esperando tu respuesta") y un título de pestaña "(N preguntas)", para que lo notes incluso desde otra ventana.
Cada pregunta es una tarjeta de comentario normal anclada a la oración sobre la que trata. Responde directamente en la tarjeta.
En el momento en que cada pregunta tiene respuesta, el agente se desbloquea con el texto de tu respuesta. No se necesita Finalizar revisión.

Esto brilla durante las transferencias. Deja un comentario como "esto contradice lo que decidimos, arréglalo", y en lugar de adivinar, el agente pregunta "¿qué decisión: por asiento o tarifa plana?" anclado donde importa. También puedes solicitar el patrón directamente:

"Revisa prd.md con mdr. Para tus 2 preguntas abiertas principales, usa mdr_ask e incorpora mis respuestas antes de resumir."

Las preguntas y revisiones sobreviven en el archivo como marcadores de comentario ordinarios, por lo que nada se pierde si una sesión termina temprano: siempre se le dice al agente que vuelva a leer el archivo.

Sin MCP

Abre un archivo Markdown con mdr /path/to/spec.md.
Resalta texto y deja comentarios en línea.
Copia el prompt de transferencia.
Pega el prompt en tu agente de IA.
El agente edita el archivo, aborda los comentarios y elimina los marcadores de comentario que manejó.
Revisa el resultado en la vista de diferencias.

Opcional: flujo de resolución

Habilita el modo de resolución en Configuración para revisión humana con estados explícitos de open y resolved.

Para quién es esto

Personas que escriben especificaciones, prompts o documentos de diseño localmente con agentes de IA basados en archivos
Equipos que revisan documentos antes de confirmarlos o enviarlos para una revisión más amplia
Cualquiera en un bucle de edición humano + agente que quiera comentarios estructurados en línea en archivos simples

No objetivos

No es una herramienta colaborativa de edición multiusuario.
No es un reemplazo para las revisiones de PR de GitHub (úsalas una vez que el archivo esté en git).
No está diseñado para contenido no confiable. Esta es una herramienta de desarrollo local para tus propios archivos.

Cómo se almacenan los comentarios

Los comentarios se almacenan como marcadores HTML invisibles directamente en el Markdown, inmediatamente antes del texto al que se refieren, para que tanto humanos como agentes puedan trabajar desde el mismo archivo.

Some text <!-- @comment{
  "id":"uuid",
  "anchor":"highlighted text",
  "text":"Rewrite this section to be clearer.",
  "author":"User",
  "timestamp":"2026-03-26T12:00:00.000Z",
  "replies":[]
} -->highlighted text continues here.

Esto hace que los comentarios sean:

visibles para agentes de IA mediante una lectura simple del archivo
portables con el archivo Markdown
invisibles en renderizadores normales (GitHub, vista previa de VS Code)

Características

Revisión y comentarios

Comentarios en línea anclados al texto renderizado, incluidos comentarios superpuestos
Revisión bidireccional del agente mediante MCP: los agentes solicitan tu revisión, revisan tus documentos y hacen preguntas ancladas
Respuestas en hilos y estados de revisión opcionales open / resolved
Anclas ajustables con manijas de arrastre
Comentarios táctiles y con lápiz: selecciona con las manijas nativas, luego toca el botón flotante Comentar al terminar (no aparece nada mientras ajustas)
Vistas renderizada, cruda y de diferencias
Copia del prompt de transferencia para uno o varios archivos

Navegación y edición

Edición con múltiples pestañas, persistencia de sesión y menús contextuales de pestañas
Explorador de archivos, archivos recientes y selector de archivos nativo del sistema operativo
Buscar en el documento (Cmd+F) con navegación entre coincidencias
Tabla de contenidos con seguimiento de desplazamiento
Paleta de comandos (Cmd+K), atajos de teclado y panel de configuración (Cmd+,)
Paneles redimensionables y menús contextuales con clic derecho

Renderizado e integraciones

Recarga en tiempo real mediante SSE cuando los archivos cambian externamente
Renderizado de diagramas Mermaid con texto comentable
Frontmatter YAML y TOML renderizado como contenido comentable, no oculto
Incrustación de imágenes locales y enlaces clicables entre archivos Markdown
Plantillas de comentarios personalizables
8 temas: Claro, Oscuro, Sepia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

Plataformas compatibles

macOS: compatible
Linux: compatible; el selector de archivos del sistema requiere zenity
Windows: compatible; el selector de archivos del sistema usa PowerShell
Navegadores táctiles (iPad Safari y similares): compatibles para revisar y comentar; las selecciones hechas con táctil o lápiz usan el flujo del botón flotante Comentar

Permisos

De forma predeterminada, md-redline puede leer cualquier archivo Markdown en tu directorio de inicio. La primera vez que ejecutes mdr (o la primera vez después de actualizar desde una versión sin la función de raíces de confianza), tu carpeta de inicio se agrega a una lista de raíces de confianza en ~/.md-redline.json. Los archivos fuera de tu directorio de inicio (/tmp, volúmenes montados, rutas del sistema) requieren una concesión de permiso explícita mediante el selector de carpetas del sistema operativo la primera vez que los abras. Las carpetas concedidas se recuerdan entre reinicios.

Para usar el modelo estricto por carpeta en su lugar, ejecuta mdr --restrict una vez después de la instalación. Esto crea un ~/.md-redline.json sin confianza predeterminada, y concederás cada carpeta explícitamente la primera vez que abras un archivo en ella.

Los guardados de archivos usan escritura atómica con cambio de nombre y detección de conflictos basada en mtime para prevenir la pérdida de datos por ediciones concurrentes. La salida SVG de Mermaid se sanitiza mediante DOMPurify antes de renderizar. Solo ejecuta md-redline en entornos en los que confíes.

Configuración

Todas estas variables de entorno son opcionales.

Variable	Predeterminado	Propósito
`MD_REDLINE_BROWSER`	Navegador predeterminado del sistema operativo	Comando usado para abrir la URL de revisión. Establécelo a un binario de navegador específico (por ejemplo, `MD_REDLINE_BROWSER=firefox`); se ejecuta con la URL como argumento. El `MDR_BROWSER` más antiguo aún funciona: se usa siempre que este no esté establecido o esté en blanco.
`MD_REDLINE_PORT` (o `PORT`)	`6373`	Puerto para el servidor API. Escanea hasta 10 puertos hacia arriba desde aquí si ese está ocupado. `MD_REDLINE_PORT` gana cuando ambos están establecidos; uno en blanco cede ante `PORT`.
`MD_REDLINE_VITE_PORT`	`5188`	Puerto para el cliente de desarrollo Vite (solo desarrollo).
`MD_REDLINE_HOME`	tu directorio de inicio del sistema operativo	Directorio base para el archivo de preferencias de md-redline (`.md-redline.json`, que almacena raíces de confianza y la caché de comprobación de actualizaciones).
`MD_REDLINE_REGISTRY_URL`	registro npm público	URL base del registro usada para la comprobación de actualizaciones en segundo plano.
`MD_REDLINE_ALLOWED_HOSTS`	sin establecer	Nombres de host adicionales separados por comas aceptados por la comprobación de encabezado Host, para que el servidor vinculado a loopback pueda estar detrás de un proxy inverso confiable. Lee Alcanzar md-redline desde otro dispositivo antes de establecerlo.
`NO_UPDATE_NOTIFIER` o `CI`	sin establecer	Si cualquiera está presente (cualquier valor, incluido vacío), la comprobación de actualizaciones en segundo plano está deshabilitada.

Alcanzar md-redline desde otro dispositivo

md-redline se vincula a 127.0.0.1 y no tiene autenticación de ningún tipo. Eso es seguro hoy porque solo tu propia máquina puede alcanzarlo. MD_REDLINE_ALLOWED_HOSTS te permite poner un proxy inverso delante de él (tailscale serve, nginx, Caddy) y revisar desde una tableta. No cambia la dirección de enlace, por lo que el proxy sigue ejecutándose en la misma máquina. Sí cambia el límite de seguridad, de "mi máquina" a "cualquier cosa que pueda alcanzar el proxy".

Lo que alcance el proxy puede leer y escribir cada archivo markdown bajo tus raíces de confianza, explorar esos directorios, ver sus rutas absolutas y tus archivos recientes, abrir selectores de archivos nativos y revelar archivos en Finder en tu máquina, responder sesiones de revisión de agentes y apagar el servidor. No hay inicio de sesión.

Así que si lo configuras:

Prefiere tailscale serve, accesible solo desde tu propia tailnet. No uses tailscale funnel, que publica en internet abierto.
Con nginx o Caddy, termina TLS y pon autenticación delante de md-redline tú mismo. No lo hará por ti.
Solo lista nombres de host que realmente controles. La defensa contra el rebinding de DNS sigue vigente para todo lo demás, porque el dominio de rebinding de un atacante nunca coincide con un nombre de host que listaste explícitamente.
Sírvelo por HTTPS si puedes. La API de portapapeles que necesita la copia del aviso de entrega solo funciona en un contexto seguro, así que por HTTP plano ese botón falla en la misma tableta para la que configuraste esto.

Un cliente accesible no puede ampliar su propio acceso al sistema de archivos: las raíces de confianza solo crecen cuando eliges un archivo o carpeta en el diálogo nativo, por lo que el conjunto legible se mantiene como lo que aprobaste localmente.

Detalles de configuración del proxy y cómo funcionan las comprobaciones de solicitudes

Si necesitas la variable o no depende de tu proxy. tailscale serve y Caddy preservan el Host original, por lo que debes listar el nombre de host público. El proxy_set_header Host $proxy_host predeterminado de nginx lo reescribe a 127.0.0.1:6373, que ya pasa, por lo que solo necesitas la variable si reenvías el host original (proxy_set_header Host $host).

Desactiva el almacenamiento en búfer de respuestas para /api/watch. Las actualizaciones de archivos en vivo llegan a través de Server-Sent Events. md-redline envía X-Accel-Buffering: no, que nginx respeta; si tu proxy lo ignora, desactiva el almacenamiento en búfer para esa ruta o las ediciones no aparecerán hasta que se llene un búfer.

Por qué una página hostil no puede controlar estos endpoints. Cada endpoint que cambia algo es un POST o un PUT que requiere un tipo de contenido JSON, que una página web no puede enviar a otro origen sin que el navegador pida permiso a este servidor primero. Eso es lo que impide que una página que visitas, un enlace en un mensaje de chat, o una imagen incrustada en un archivo markdown que estás revisando dispare silenciosamente un endpoint aquí. md-redline además rechaza solicitudes que un navegador etiqueta como entre sitios, pero solo como segunda capa: los clientes que no envían esos metadatos, como el CLI y el servidor MCP, no se ven afectados deliberadamente.

La superficie completa, si quieres auditarla: GET/PUT /api/file, GET /api/browse, GET /api/files, GET /api/asset, GET/PUT /api/preferences, GET /api/config, GET /api/version, GET /api/platform, POST /api/pick-file, POST /api/pick-folder, POST /api/reveal, GET /api/watch, POST /api/shutdown, y /api/review-sessions/*. POST /api/grant-access solo vuelve a comprobar una ruta contra raíces que ya aprobaste en lugar de añadir nuevas.

Solución de problemas

El agente dice que no tiene herramientas mdr. Reinicia tu cliente MCP después de mdr mcp install; la mayoría de los clientes solo descubren nuevos servidores al iniciar. Para clientes que no son Claude, confirma que mdr está en el PATH que el cliente realmente usa (consulta la configuración de MCP arriba).
El navegador se abrió pero la página no carga. Un servidor obsoleto puede estar ocupando el puerto. Ejecuta mdr --stop y luego vuelve a abrir tu archivo.
Un banner de revisión está atascado en pantalla. Haz clic en Finalizar revisión (revisiones de agentes) o Cancelar revisión (tus revisiones). Las sesiones no sobreviven a un reinicio del servidor, pero los comentarios sí.
Algo salió mal a mitad de sesión. El archivo siempre es la fuente de verdad. Los comentarios y las preguntas del agente viven en el propio markdown como marcadores , por lo que puedes leerlos, editarlos o eliminarlos en cualquier editor, y siempre se le dice al agente que vuelva a leer el archivo cuando una sesión termina inesperadamente.

Desarrollo

Desde el código fuente

git clone https://github.com/dejuknow/md-redline.git
cd md-redline
npm install
npm run dev

Abre la URL local que imprime Vite (normalmente http://localhost:5188).

Scripts

npm run dev          # Start dev server
npm run lint         # Lint
npm test             # Production build + unit tests
npm run test:e2e     # Playwright E2E tests
npm run build        # Production build

Evaluación de agentes

El entorno de evaluación comprueba si los agentes de IA leen, abordan y eliminan correctamente los comentarios en línea.

npm run eval:dry valida los fixtures de evaluación
npm run eval ejecuta el entorno de evaluación completo
Consulta eval/README.md para más detalles

Arquitectura

bin/md-redline             CLI entry point (invoked as `mdr` or `md-redline`)
bin/cli.js                 CLI implementation behind that entry point
server/index.ts            Hono server for file I/O, browsing, SSE, and local integrations
src/App.tsx                Main application shell
src/components/            Viewer, sidebar, raw view, diff view, TOC, explorer, settings, etc.
src/hooks/                 State, persistence, selection, file watching, drag handles, tabs
src/lib/comment-parser.ts  Inline comment parsing and mutation helpers
src/markdown/pipeline.ts   Markdown rendering pipeline
eval/                      Eval harness for agent behavior against inline comments
e2e/                       Playwright end-to-end coverage

Licencia

MIT