Markdown Review

Markdown Review는 렌더링된 Markdown을 문서의 편집 가능한 사본을 만들지 않고 검토할 수 있는 로컬 우선(local-first) MCP Apps 인터페이스입니다. 구절을 선택하거나 이미지를 고르고, 줄 기준(line-anchored) 피드백을 큐에 넣은 다음, 전체 검토를 한 번에 코딩 에이전트에 제출합니다. Codex App이 첫 번째로 출시된 대화형 호스트이며, 핵심 계약, 상태, UI는 향후 Claude, pi, 터미널, Tauri 어댑터를 위해 의도적으로 호스트 중립적으로 설계되었습니다.

상태: 초기 개발 단계. Codex App이 출시된 대화형 호스트이며, 재사용 가능한 UI와 MCP 전송은 MCP Apps 표준을 따르므로 검토 코어를 다시 작성하지 않고도 추가 호스트 어댑터를 추가할 수 있습니다.

제공 기능

• 사이드 패널의 전체 화면 GitHub 스타일 Markdown 미리보기.

• 일반 텍스트 선택 및 복사, 선택 텍스트·이미지·전체 문서 피드백을 위한 검토 메뉴.

• 포인터, 터치, 키보드 주석을 위한 포커스 가능한 이미지 검토 대상.

• 호버, 키보드 포커스, 활성 터치 시에만 이미지 오른쪽 하단에 나타나는 눈에 거슬리지 않는 이미지 피드백 컨트롤.

• #1, #2 등으로 번호가 매겨진 인라인 주석 마커.

• 충돌하는 편집을 피하기 위해 모든 주석을 함께 제출하는 검토 큐.

• #N을 사용한 큐에 있는 주석 간 참조; 리터럴 텍스트는 \#N 또는 `#N`으로 작성.

• 제한된 크기의 비공개 청크 전송으로 상대 경로 로컬 PNG, JPEG, 정적 WebP 렌더링.

• Codex가 Markdown 문서를 생성하거나 실질적으로 편집한 후 자동 검토.

Markdown 소스는 항상 표준(canonical)입니다. 이 컴포넌트는 읽기 전용 검토 화면이며, 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 포맷터를 명시적으로 추가합니다. 검토 상태는 불투명한 검토 세션 ID 아래 로컬에 유지되어 큐에 있는 주석이 컴포넌트 재마운트를 넘어 생존하지만, 모델에 보이는 레거시 위젯 컨텍스트로 게시되지는 않습니다. 향후 Tauri 셸은 계약, 코어, UI를 재사용하고 Rust IPC 포트를 제공할 수 있습니다. Tauri는 현재 포함되지 않습니다.

호스트 지원

출시되지 않은 어댑터와 브라우저 승인 후속 작업은 ROADMAP.md에서 추적됩니다.

저장소 마켓플레이스에서 설치

요구 사항:

• 플러그인 지원이 있는 ChatGPT 데스크톱 앱의 Codex.

• node로 사용 가능한 Node.js 22 이상.

• 마켓플레이스 소스를 추가하기 위한 codex CLI.

이 저장소를 마켓플레이스로 추가:

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

UI 작업을 위해 Markdown 파일에 대해 브라우저 하네스를 실행:

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

하네스에서 피드백 작성기를 자동으로 열려면 MARKDOWN_REVIEW_PREVIEW_COMPOSER=1을 설정합니다.

플러그인은 기본적으로 호스트의 네이티브 컨텍스트 메뉴를 억제합니다. 로컬 플러그인 디버깅 전용으로 MCP 서버 환경에 MARKDOWN_REVIEW_DEVTOOLS=1을 설정하고 Codex를 다시 시작합니다. 그러면 Shift+오른쪽 클릭이 검토 메뉴를 우회하고 호스트 네이티브 메뉴를 엽니다. 일반 오른쪽 클릭은 계속 검토 작업을 표시합니다. 이 플래그는 엄격하게 구문 분석됩니다. 정확한 값 1만 우회를 활성화하며 체크인된 .mcp.json에서는 절대 활성화되지 않습니다.

이 체크아웃을 로컬 마켓플레이스로 테스트하려면 절대 디렉터리를 추가합니다:

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

그런 다음 데스크톱 앱을 다시 시작하고 로컬 마켓플레이스 소스에서 플러그인을 설치합니다.

안전 및 개인정보 보호 경계

• 컴포넌트는 Markdown 파일을 쓸 수 없습니다.

• 로컬 MCP 서버가 명시적 개발자 플래그로 시작하지 않는 한 플러그인 내부의 네이티브 브라우저 컨텍스트 메뉴는 억제됩니다. 이는 UI 강화이며 Codex App 자체 메뉴나 단축키에 대한 보안 경계가 아닙니다.

• 렌더링된 HTML은 컴포넌트에 도달하기 전에 삭제(sanitize)됩니다.

• 원격, 절대 경로, 디렉터리 밖의 이미지는 로드되지 않습니다.

• Markdown 파일 디렉터리 내부의 PNG, JPEG(.jpg/.jpeg), 정적 WebP 파일에 대한 상대 경로만 지원됩니다. 서버는 브라우저가 네이티브 디코딩을 수행하기 전에 확장자, 시그니처, 제한된 컨테이너 구조, 크기, 애니메이션 정책을 검증합니다. GIF, AVIF, SVG, APNG, 애니메이션 WebP는 렌더링되지 않습니다.

• 컴포넌트 리소스는 네트워크 또는 원격 리소스 도메인을 선언하지 않으며 명시적 Copy selected text 작업에 대해서만 클립보드 쓰기 권한을 요청합니다.

• Markdown 파일은 2 MiB로 제한됩니다.

• 검토는 잘못된 참조를 포함하여 최대 64개의 로컬 이미지 참조, 고유 이미지당 5 MiB, 총 12 MiB의 고유 이미지 스냅샷을 처리하며 이미지별 디코딩 크기 제한이 엄격합니다. 모든 유효한 참조는 렌더링됩니다. 브라우저는 문서 전체에 제한된 24메가픽셀 캔버스 예산을 공정하게 공유하고 큰 이미지를 생략하지 않고 표시용으로 축소합니다. 동일한 표준 파일 또는 동일한 다이제스트로 해석되는 참조는 하나의 불변 스냅샷과 검증된 클라이언트 디코드를 공유합니다.

• 표준 경로와 열린 파일 ID는 각 제한된 읽기 주변에서 다시 확인됩니다. 이러한 검사는 읽기 중에 문서 디렉터리 계층을 지속적으로 교체할 수 있는 다른 로컬 프로세스에 대한 OS 샌드박스가 아니라 심층 방어입니다.

• 컴포넌트 액세스는 불투명하고 만료되는 검토 세션 기능을 사용합니다. 세션은 2시간 동안 슬라이딩하며 6개 세션 LRU와 72 MiB 집계 이미지 캐시로 제한됩니다.

• 이미지 바이트와 SHA-256 다이제스트는 세션에 스냅샷되므로 이후 파일 변경이 진행 중인 검토를 변경할 수 없습니다.

• 전체 문서 콘텐츠와 이미지 청크는 모델에 보이는 구조화된 출력이 아닌 컴포넌트 전용 메타데이터에 배치됩니다.

로컬 플러그인 프로세스에 노출하려는 파일만 검토하세요. 제출된 주석은 실행 가능한 사용자 피드백이며, 선택된 인용문과 기타 검토된 문서 콘텐츠는 신뢰할 수 없는 컨텍스트로 유지되며 지침이 아닙니다.

프로젝트 구조

문제 해결

플러그인 파일은 존재하지만 검토 도구가 등록되지 않습니다. 데스크톱 앱을 다시 시작하고 새 작업을 시작합니다. 작업은 시작된 후 설치되거나 업데이트된 플러그인의 도구를 동적으로 획득하지 않습니다.

Codex가 캐시된 스킬 경로가 이동했다고 말합니다. 마켓플레이스 플러그인을 업그레이드하거나 재설치하고, 앱을 다시 시작하고, 새 작업에서 안정적인 스킬 이름 $markdown-review를 호출합니다. 버전이 지정된 캐시 경로에 의존하지 마세요.

사이드 패널이 비어 있습니다. 플러그인 체크아웃에서 bun run verify를 실행하고, bun run build로 다시 빌드하고, 마켓플레이스 설치를 새로 고치고, 새 작업에서 다시 시도합니다.

로컬 이미지가 렌더링되지 않습니다. Markdown 파일 디렉터리 내부에 있는 상대 경로의 .png, .jpg, .jpeg 또는 정적 .webp 경로를 사용하고 문서화된 크기 및 크기 제한 내에 있는지 확인합니다.

문서

• OpenAI: Package your plugin

• OpenAI plugin documentation

이 프로젝트는 독립 프로젝트이며 공식 OpenAI 또는 GitHub 제품이 아닙니다. 제품 이름과 마크는 각 소유자의 자산입니다.