Markdown Review

Markdown Review — это локально-ориентированный интерфейс MCP Apps для просмотра отрендеренного Markdown без создания второй редактируемой копии документа. Выберите фрагмент или изображение, поставьте в очередь комментарии, привязанные к строкам, и отправьте полный обзор агенту кодирования одним пакетом. Codex App — первый выпущенный интерактивный хост; основные контракты, состояние и пользовательский интерфейс намеренно нейтральны к хосту для будущих адаптеров Claude, pi, терминала и Tauri.

Статус: ранняя разработка. Codex App — выпущенный интерактивный хост; переиспользуемый UI и транспорт MCP следуют стандарту MCP Apps, поэтому дополнительные адаптеры хостов можно добавлять без переписывания ядра обзора.

Что он предоставляет

• Полноэкранный предпросмотр Markdown в стиле GitHub на боковой панели.

• Обычное выделение текста и копирование, а также меню обзора для обратной связи по выделенному тексту, изображениям и всему документу.

• Фокусируемые цели для обзора изображений для комментариев с помощью указателя, касания и клавиатуры.

• Ненавязчивые элементы управления обратной связью по изображениям, которые появляются в правом нижнем углу изображения только при наведении, фокусе клавиатуры или активном касании.

• Встроенные маркеры комментариев с номерами #1, #2 и так далее.

• Очередь обзора, которая отправляет все комментарии вместе, чтобы избежать конфликтующих правок.

• Ссылки между поставленными в очередь комментариями с помощью #N; пишите \#N или `#N` для буквального текста.

• Отрисовка относительных локальных PNG, JPEG и статических WebP с ограниченной, приватной передачей фрагментов.

• Автоматический обзор после того, как Codex создаёт или существенно редактирует документ Markdown.

Исходный код Markdown всегда каноничен. Компонент — это поверхность обзора только для чтения; только Codex редактирует исходный файл своими обычными инструментами файловой системы.

Related MCP server: md-annotate

Как это работает

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

Сервер MCP намеренно узкий:

1. open_markdown_review проверяет и отображает абсолютный путь .md или .markdown.

2. Инструменты только для компонента гидратируют отрендеренный документ и передают одобренные локальные растровые изображения ограниченными фрагментами.

3. Результат инструмента, видимый модели, содержит метаданные файла, а не полный документ. Отрендеренное содержимое доставляется компоненту приватно.

4. Навык объясняет, как Codex должен интерпретировать отзывы обзора и безопасно изменять базовый Markdown.

Это разделение — причина, по которой проект включает MCP: сервер соединяет вызов инструмента Codex с доверенным интерактивным компонентом. Статический HTML-файл сам по себе не может получить выбранный исходный файл, вернуть структурированные комментарии обзора активной задаче или поддерживать эту границу контекста.

Реализация разделена на нейтральные к хосту TypeScript-рабочие области. contracts проверяет каждую границу, core владеет чистым состоянием обзора, markdown-node читает и отображает локальные файлы, а review-ui монтируется на узкие порты документа, отправки, представления и состояния. host-mcp-apps предоставляет среду выполнения на основе стандартов, чья отправка по умолчанию — структурированный JSON; браузерная композиция Codex явно добавляет краткий форматтер $markdown-review. Состояние обзора сохраняется локально под его непрозрачным идентификатором сеанса обзора, поэтому поставленные в очередь комментарии переживают повторные монтирования компонента, но никогда не публикуются как видимый модели контекст устаревшего виджета. Будущая оболочка Tauri сможет повторно использовать контракты, ядро и UI и предоставить порты Rust IPC; Tauri сегодня не включён.

Поддержка хостов

Невыпущенные адаптеры и последующие действия по приёмке в браузере отслеживаются в ROADMAP.md.

Установка из маркетплейса репозитория

Требования:

• Codex в настольном приложении ChatGPT с поддержкой плагинов.

• Node.js 22 или новее, доступный как node.

• CLI codex для добавления источника маркетплейса.

Добавьте этот репозиторий как маркетплейс:

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

Перезапустите настольное приложение, откройте Каталог плагинов, выберите Markdown Review и установите плагин. Начните новую задачу после установки, чтобы задача получила регистрацию инструмента плагина.

Чтобы обновить существующую установку:

codex plugin marketplace upgrade markdown-review

Перезапустите настольное приложение и начните новую задачу после обновления. Существующие задачи сохраняют регистрации инструментов и навыков, с которыми они были начаты.

Использование

Попросите Codex открыть абсолютный путь Markdown:

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

В обзоре:

1. Выделите текст и скопируйте его обычным способом, если нужно, или выберите отрендеренное изображение.

2. Щёлкните правой кнопкой мыши по документу или выберите Review для действий копирования и комментирования. Действие + для выделения и каждая цель изображения остаются прямыми ярлыками.

3. Нажмите Enter, чтобы поставить комментарий в очередь; используйте Shift+Enter для новой строки.

4. Ссылайтесь на ранее поставленный в очередь комментарий с помощью #1, #2 и так далее.

5. Выберите Submit, когда раунд обзора завершён.

После успешной отправки очередь очищается, и следующий раунд обзора снова начинается с #1. Намеренно нет действия индивидуальной отправки: пакетная обработка даёт Codex одну связную цель ревизии и уменьшает конфликты исходников.

Локальная разработка

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

Разработка и CI используют закреплённый инструментарий Bun 1.4. Установленные плагины не требуют Bun: репозиторий включает читаемый Node-совместимый server.cjs и минифицированные браузерные пакеты. Пересоберите после изменения исходников TypeScript:

bun run build

Запустите браузерный харнесс с файлом Markdown для работы над UI:

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

Установите MARKDOWN_REVIEW_PREVIEW_COMPOSER=1, чтобы автоматически открывать композер обратной связи в харнессе.

Плагин по умолчанию подавляет собственное контекстное меню хоста. Только для локальной отладки плагина установите MARKDOWN_REVIEW_DEVTOOLS=1 в среде сервера MCP и перезапустите Codex; Shift+правый клик тогда обходит меню обзора и открывает собственное меню хоста. Обычный правый клик продолжает показывать действия обзора. Флаг разбирается строго — только точное значение 1 включает обход — и никогда не включается в проверенном .mcp.json.

Чтобы протестировать этот чекаут как локальный маркетплейс, добавьте его абсолютный каталог:

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

Затем перезапустите настольное приложение и установите плагин из локального источника маркетплейса.

Границы безопасности и конфиденциальности

• Компонент не может записывать файл Markdown.

• Собственное контекстное меню браузера подавляется внутри плагина, если только локальный сервер MCP не запускается с явным флагом разработчика; это усиление UI, а не граница безопасности вокруг собственных меню или ярлыков Codex App.

• Отрендеренный HTML очищается перед тем, как попасть в компонент.

• Удалённые, абсолютные и внекаталожные изображения не загружаются.

• Поддерживаются только относительные пути к PNG, JPEG (.jpg/.jpeg) и статическим WebP-файлам внутри каталога файла Markdown. Сервер проверяет расширение, сигнатуру, ограниченную структуру контейнера, размеры и политику анимации перед тем, как браузер выполнит нативное декодирование. GIF, AVIF, SVG, APNG и анимированные WebP не отображаются.

• Ресурс компонента не объявляет сетевых или удалённых доменов ресурсов и запрашивает только доступ к буферу обмена для явного действия Copy selected text.

• Файл Markdown ограничен 2 МиБ.

• Обзор обрабатывает не более 64 ссылок на локальные изображения — включая недействительные ссылки — 5 МиБ на уникальное изображение и 12 МиБ уникальных снимков изображений в сумме, со строгими ограничениями на декодированные размеры каждого изображения. Каждая действительная ссылка отображается: браузер справедливо разделяет ограниченный бюджет холста в 24 мегапикселя по документу и уменьшает большие изображения для отображения, а не пропускает их. Ссылки, которые разрешаются в один и тот же канонический файл или идентичный дайджест, используют один неизменяемый снимок и проверенное клиентское декодирование.

• Канонические пути и идентичности открытых файлов перепроверяются вокруг каждого ограниченного чтения. Эти проверки — защита в глубину, а не песочница ОС против другого локального процесса, который может непрерывно заменять иерархию каталога документа во время чтения.

• Доступ компонента использует непрозрачные, истекающие возможности сеанса обзора. Сеансы скользят в течение двух часов и ограничены LRU из шести сеансов и совокупным кэшем изображений в 72 МиБ.

• Байты изображений и дайджесты SHA-256 снимкаются в сеанс, поэтому последующие мутации файлов не могут изменить текущий обзор.

• Полное содержимое документа и фрагменты изображений помещаются в приватные метаданные компонента, а не в видимый модели структурированный вывод.

Просматривайте только те файлы, которые вы намерены предоставить локальному процессу плагина. Отправленные комментарии — это действующая обратная связь пользователя; выбранные цитаты и другое просмотренное содержимое документа остаются недоверенным контекстом, а не инструкциями.

Структура проекта

Устранение неполадок

Файлы плагина существуют, но инструмент обзора не зарегистрирован. Перезапустите настольное приложение и начните новую задачу. Задача не получает динамически инструменты из плагина, установленного или обновлённого после начала этой задачи.

Codex говорит, что путь кэшированного навыка перемещён. Обновите или переустановите плагин маркетплейса, перезапустите приложение и вызовите стабильное имя навыка $markdown-review в новой задаче. Не полагайтесь на версионированный путь кэша.

Боковая панель пуста. Запустите bun run verify в чекауте плагина, пересоберите с помощью bun run build, обновите установку маркетплейса и повторите попытку в новой задаче.

Локальное изображение не отображается. Используйте относительный путь .png, .jpg, .jpeg или статический .webp, расположенный внутри каталога файла Markdown, и убедитесь, что он находится в пределах задокументированных ограничений размера и размеров.

Документация

• OpenAI: Package your plugin

• OpenAI plugin documentation

Это независимый проект и не является официальным продуктом OpenAI или GitHub. Названия продуктов и товарные знаки принадлежат их соответствующим владельцам.