Markdown Review

Markdown Review es una interfaz local-first de MCP Apps para revisar Markdown renderizado sin crear una segunda copia editable del documento. Selecciona un pasaje o elige una imagen, pon en cola comentarios anclados a líneas y envía la revisión completa a un agente de codificación en un solo lote. Codex App es el primer host interactivo publicado; los contratos, el estado y la interfaz de usuario centrales son intencionalmente neutrales respecto al host para futuros adaptadores de Claude, pi, terminal y Tauri.

Estado: desarrollo temprano. Codex App es el host interactivo publicado; la interfaz reutilizable y el transporte MCP siguen el estándar MCP Apps, por lo que se pueden añadir adaptadores de host adicionales sin reescribir el núcleo de revisión.

Qué ofrece

• Una vista previa de Markdown a pantalla completa, estilo GitHub, en el panel lateral.

• Selección y copia de texto normal, además de un menú de revisión para comentarios sobre texto seleccionado, imágenes y el documento completo.

• Objetivos de revisión de imágenes enfocables para comentarios con puntero, táctiles y de teclado.

• Controles de comentarios de imagen discretos que aparecen en la esquina inferior derecha de la imagen solo al pasar el cursor, al enfocar con teclado o al tocar activamente.

• Marcadores de comentarios en línea numerados #1, #2, etc.

• Una cola de revisión que envía todos los comentarios juntos para evitar ediciones conflictivas.

• Referencias entre comentarios en cola usando #N; escribe \#N o `#N` para texto literal.

• Renderizado de PNG, JPEG y WebP estáticos locales relativos con transporte de fragmentos acotado y privado.

• Revisión automática después de que Codex cree o edite materialmente un documento Markdown.

La fuente de Markdown siempre es canónica. El componente es una superficie de revisión de solo lectura; solo Codex edita el archivo fuente con sus herramientas normales de sistema de archivos.

Related MCP server: md-annotate

Cómo funciona

local .md file
    │
    ├── open_markdown_review ──► sanitized rendered component (private UI payload)
    │                                  │
    │                                  └── queued, line-anchored comments
    │                                                   │
    └◄──────────── Codex edits the original file ◄──────┘
                              one batch message

El servidor MCP es intencionalmente limitado:

1. open_markdown_review valida y renderiza una ruta absoluta .md o .markdown.

2. Las herramientas solo de componente hidratan el documento renderizado y transmiten imágenes rasterizadas locales aprobadas en fragmentos acotados.

3. El resultado de la herramienta visible para el modelo contiene metadatos del archivo, no el documento completo. El contenido renderizado se entrega de forma privada al componente.

4. La habilidad explica cómo debe interpretar Codex los comentarios de revisión y modificar el Markdown subyacente de forma segura.

Esta separación es la razón por la que el proyecto incluye MCP: el servidor conecta una invocación de herramienta de Codex con un componente interactivo de confianza. Un archivo HTML estático por sí solo no puede recibir el archivo fuente seleccionado, devolver comentarios de revisión estructurados a la tarea activa ni mantener este límite de contexto.

La implementación se divide en espacios de trabajo TypeScript neutrales respecto al host. contracts valida cada límite, core posee el estado de revisión puro, markdown-node lee y renderiza archivos locales, y review-ui se monta sobre puertos estrechos de documento, envío, presentación y estado. host-mcp-apps proporciona un runtime basado en estándares cuyo envío predeterminado es JSON estructurado; la composición del navegador de Codex añade explícitamente el formateador conciso $markdown-review. El estado de revisión se persiste localmente bajo su ID de sesión de revisión opaco, de modo que los comentarios en cola sobreviven a los remontajes del componente, sin publicarse nunca como contexto de widget heredado visible para el modelo. Un futuro shell de Tauri puede reutilizar los contratos, el núcleo y la interfaz, y proporcionar puertos IPC de Rust; Tauri no se incluye hoy.

Soporte de hosts

Los adaptadores no publicados y los seguimientos de aceptación del navegador se rastrean en ROADMAP.md.

Instalar desde el marketplace del repositorio

Requisitos:

• Codex en la aplicación de escritorio de ChatGPT con soporte de complementos.

• Node.js 22 o más reciente disponible como node.

• La CLI codex para añadir la fuente del marketplace.

Añade este repositorio como marketplace:

codex plugin marketplace add tjs-w/markdown-review --ref main

Reinicia la aplicación de escritorio, abre el Directorio de Complementos, selecciona Markdown Review e instala el complemento. Inicia una nueva tarea después de la instalación para que la tarea reciba el registro de herramientas del complemento.

Para actualizar una instalación existente:

codex plugin marketplace upgrade markdown-review

Reinicia la aplicación de escritorio e inicia una nueva tarea después de una actualización. Las tareas existentes conservan los registros de herramientas y habilidades con los que comenzaron.

Uso

Pídele a Codex que abra una ruta Markdown absoluta:

Open /absolute/path/to/document.md for Markdown review.

En la revisión:

1. Selecciona texto y cópialo normalmente si es necesario, o elige una imagen renderizada.

2. Haz clic derecho en el documento o elige Revisar para acciones de copiar y comentar. La acción + de la selección y cada objetivo de imagen siguen siendo accesos directos directos.

3. Pulsa Enter para poner el comentario en cola; usa Shift+Enter para una nueva línea.

4. Referencia un comentario anterior en cola con #1, #2, etc.

5. Selecciona Enviar cuando la ronda de revisión esté completa.

Después de un envío exitoso, la cola se limpia y la siguiente ronda de revisión comienza de nuevo en #1. Deliberadamente no hay acción de envío individual: el procesamiento por lotes le da a Codex un objetivo de revisión coherente y reduce los conflictos de fuente.

Desarrollo local

git clone https://github.com/tjs-w/markdown-review.git
cd markdown-review
bun install --frozen-lockfile
bun run verify

El desarrollo y la CI usan la cadena de herramientas Bun 1.4 fijada. Los complementos instalados no requieren Bun: el repositorio incluye un server.cjs legible compatible con Node y paquetes de navegador minificados. Reconstruye después de cambiar el código fuente TypeScript:

bun run build

Ejecuta el arnés del navegador contra un archivo Markdown para el trabajo de interfaz:

bun run browser:harness -- /absolute/path/to/document.md

Establece MARKDOWN_REVIEW_PREVIEW_COMPOSER=1 para abrir el compositor de comentarios automáticamente en el arnés.

El complemento suprime el menú contextual nativo del host de forma predeterminada. Solo para depuración local de complementos, establece MARKDOWN_REVIEW_DEVTOOLS=1 en el entorno del servidor MCP y reinicia Codex; Shift+clic derecho entonces omite el menú de revisión y abre el menú nativo del host. El clic derecho normal continúa mostrando las acciones de revisión. La bandera se analiza estrictamente: solo el valor exacto 1 habilita la omisión, y nunca se habilita en el .mcp.json incluido.

Para probar este checkout como marketplace local, añade su directorio absoluto:

codex plugin marketplace add /absolute/path/to/markdown-review

Luego reinicia la aplicación de escritorio e instala el complemento desde la fuente del marketplace local.

Límites de seguridad y privacidad

• El componente no puede escribir el archivo Markdown.

• El menú contextual nativo del navegador se suprime dentro del complemento a menos que el servidor MCP local se inicie con la bandera de desarrollador explícita; esto es un endurecimiento de la interfaz, no un límite de seguridad alrededor de los menús o atajos de Codex App.

• El HTML renderizado se sanitiza antes de llegar al componente.

• No se cargan imágenes remotas, absolutas o fuera del directorio.

• Solo se admiten rutas relativas a archivos PNG, JPEG (.jpg/.jpeg) y WebP estáticos dentro del directorio del archivo Markdown. El servidor verifica la extensión, la firma, la estructura de contenedor acotada, las dimensiones y la política de animación antes de que el navegador realice la decodificación nativa. GIF, AVIF, SVG, APNG y WebP animado no se renderizan.

• El recurso del componente no declara dominios de red o recursos remotos y solo solicita acceso de escritura al portapapeles para la acción explícita Copiar texto seleccionado.

• Un archivo Markdown está limitado a 2 MiB.

• Una revisión procesa como máximo 64 referencias de imágenes locales—incluidas las inválidas—5 MiB por imagen única y 12 MiB de instantáneas de imágenes únicas en total, con límites estrictos de dimensiones decodificadas por imagen. Cada referencia válida se renderiza: el navegador comparte de manera justa un presupuesto de lienzo de 24 megapíxeles acotado en todo el documento y reduce la escala de las imágenes grandes para mostrarlas en lugar de omitirlas. Las referencias que se resuelven al mismo archivo canónico o al mismo digest comparten una instantánea inmutable y una decodificación de cliente verificada.

• Las rutas canónicas y las identidades de archivos abiertos se vuelven a verificar alrededor de cada lectura acotada. Estas verificaciones son defensa en profundidad, no un sandbox del sistema operativo contra otro proceso local que pueda reemplazar continuamente la jerarquía del directorio del documento durante una lectura.

• El acceso del componente usa capacidades de sesión de revisión opacas y con caducidad. Las sesiones se deslizan durante dos horas y están limitadas por un LRU de seis sesiones y una caché de imágenes agregada de 72 MiB.

• Los bytes de imagen y los digests SHA-256 se capturan en una sesión, por lo que las mutaciones posteriores del archivo no pueden cambiar una revisión en curso.

• El contenido completo del documento y los fragmentos de imagen se colocan en metadatos privados del componente en lugar de salida estructurada visible para el modelo.

Revisa solo archivos que tengas la intención de exponer al proceso local del complemento. Los comentarios enviados son comentarios de usuario accionables; las citas seleccionadas y otro contenido del documento revisado siguen siendo contexto no confiable, no instrucciones.

Estructura del proyecto

Solución de problemas

Los archivos del complemento existen, pero la herramienta de revisión no está registrada. Reinicia la aplicación de escritorio e inicia una nueva tarea. Una tarea no adquiere dinámicamente herramientas de un complemento instalado o actualizado después de que esa tarea comenzó.

Codex dice que una ruta de habilidad en caché se movió. Actualiza o reinstala el complemento del marketplace, reinicia la aplicación e invoca el nombre de habilidad estable $markdown-review en una nueva tarea. No dependas de una ruta de caché versionada.

El panel lateral está en blanco. Ejecuta bun run verify en el checkout del complemento, reconstruye con bun run build, actualiza la instalación del marketplace y vuelve a intentarlo en una nueva tarea.

Una imagen local no se renderiza. Usa una ruta relativa .png, .jpg, .jpeg o .webp estática ubicada dentro del directorio del archivo Markdown y confirma que esté dentro de los límites de tamaño y dimensiones documentados.

Documentación

• OpenAI: Empaqueta tu complemento

• Documentación de complementos de OpenAI

Este es un proyecto independiente y no es un producto oficial de OpenAI o GitHub. Los nombres de productos y marcas pertenecen a sus respectivos propietarios.