md-redline

마크다운 사양, 프롬프트 및 디자인 문서를 위한 인라인 리뷰 댓글 도구입니다.

렌더링된 문서에서 텍스트를 강조 표시하고 댓글을 남기면, AI 에이전트가 이를 직접 읽고 처리할 수 있습니다. 댓글은 .md 파일 자체에 보이지 않는 HTML 마커로 저장됩니다. 사이드카 파일, 데이터베이스, 외부 서비스가 필요 없습니다. 마크다운 파일이 진실의 원천(source of truth)으로 유지됩니다.

내장된 MCP 서버를 사용하면 에이전트가 작업 중간에 검토를 요청하고 **검토 보내기(Send review)**를 클릭할 때까지 일시 중지할 수 있습니다. 사용자가 피드백을 남기면 에이전트가 중단된 지점부터 작업을 재개합니다. 복사-붙여넣기나 컨텍스트 전환이 필요 없습니다.

30초 만에 전체 검토 워크플로우 확인하기:

https://github.com/user-attachments/assets/7f493201-3aca-489c-86f0-3a7df454f693

Claude Code, Claude Desktop, Codex CLI, Gemini CLI 및 stdio 서버를 지원하는 모든 MCP 클라이언트와 호환됩니다. Sean Grove가 specs are the new code에서 주장하듯, 사양은 에이전트 기반 개발에서 주요 작업 단위가 되고 있습니다. mdr은 해당 워크플로우에 코드 리뷰와 유사한 검토 도구를 제공합니다.

빠른 시작

전제 조건: Node 20 이상.

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

이 명령은 필요한 경우 로컬 앱을 시작하고 브라우저에서 엽니다.

또는 전역으로 설치:

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은 mdr의 별칭으로도 작동합니다.

Related MCP server: md-feedback

MCP 설정

에이전트가 작업 중간에 검토를 요청할 수 있도록 MCP 서버를 등록하세요.

Claude Code 또는 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

--scope user 플래그가 중요합니다. Gemini는 기본적으로 프로젝트별 범위를 사용하므로, 현재 디렉토리에 대해서만 mdr을 등록합니다.

기타 MCP 클라이언트

클라이언트의 MCP 설정 파일에 다음 서버 항목을 추가하세요:

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

전제 조건: mdr이 PATH에 있어야 합니다(예: npm install -g md-redline을 통해). 클라이언트가 셸의 PATH를 상속하지 않고 하위 프로세스를 생성하는 경우, command 값으로 which mdr의 절대 경로를 사용하세요.

검토 워크플로우

MCP 사용 시 (권장)

등록 후 에이전트에게 검토를 요청하세요:

"계속하기 전에 mdr에서 docs/specs/feature-x.md를 검토해 줘."

에이전트가 mdr_request_review를 호출하면 mdr이 파일을 열고, 사용자가 텍스트를 강조 표시하고 댓글을 남긴 후 **검토 보내기(Send review)**를 클릭합니다. 에이전트는 피드백을 구조화된 프롬프트로 받아 댓글을 처리하기 시작합니다. 검토는 요청 시 선택적으로 진행됩니다. 에이전트는 사용자가 요청할 때만 일시 중지합니다.

MCP 미사용 시

1. mdr /path/to/spec.md로 마크다운 파일을 엽니다.

2. 텍스트를 강조 표시하고 인라인 댓글을 남깁니다.

3. 핸드오프 프롬프트를 복사합니다.

4. 프롬프트를 AI 에이전트에 붙여넣습니다.

5. 에이전트가 파일을 편집하고 피드백을 처리한 뒤 처리된 댓글 마커를 제거합니다.

6. diff 뷰에서 결과를 검토합니다.

선택 사항: 해결 워크플로우

설정에서 해결 모드를 활성화하여 명시적인 open 및 resolved 상태로 사람의 검토를 진행할 수 있습니다.

대상 사용자

• 파일 기반 AI 에이전트를 사용하여 로컬에서 사양, 프롬프트 또는 디자인 문서를 작성하는 분들

• 커밋하거나 더 넓은 범위의 검토를 위해 문서를 보내기 전에 검토하는 팀

• 일반 파일 내에서 구조화된 인라인 피드백을 원하는 사람 + 에이전트 편집 루프에 있는 모든 분들

비목표

• 협업형 다중 사용자 편집 도구가 아닙니다.

• GitHub PR 리뷰를 대체하지 않습니다(파일이 git에 올라가면 PR 리뷰를 사용하세요).

• 신뢰할 수 없는 콘텐츠를 위해 설계되지 않았습니다. 본인의 파일을 위한 로컬 개발 도구입니다.

댓글 저장 방식

댓글은 마크다운 내부에 보이지 않는 HTML 마커로, 참조하는 텍스트 바로 앞에 저장되므로 사람과 에이전트 모두 동일한 파일에서 작업할 수 있습니다.

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.

이 방식의 장점:

• 일반 파일 읽기를 통해 AI 에이전트가 확인 가능

• 마크다운 파일과 함께 이동 가능

• 일반 렌더러(GitHub, VS Code 미리보기)에서는 보이지 않음

기능

검토 및 댓글

• 렌더링된 텍스트에 고정된 인라인 댓글 (중첩 댓글 포함)

• 스레드형 답글 및 선택적 open / resolved 검토 상태

• 드래그 핸들로 조정 가능한 앵커

• 렌더링, 원본 및 diff 뷰

• 하나 또는 여러 파일에 대한 핸드오프 프롬프트 복사

탐색 및 편집

• 세션 유지 및 탭 컨텍스트 메뉴를 지원하는 다중 탭 편집

• 파일 탐색기, 최근 파일 및 기본 OS 파일 선택기

• 문서 내 찾기 (Cmd+F) 및 일치 항목 탐색

• 스크롤 스파이가 포함된 목차

• 명령 팔레트 (Cmd+K), 키보드 단축키 및 설정 패널 (Cmd+,)

• 크기 조절 가능한 패널 및 우클릭 컨텍스트 메뉴

렌더링 및 통합

• 외부에서 파일 변경 시 SSE를 통한 실시간 새로고침

• 댓글 작성이 가능한 텍스트를 포함한 Mermaid 다이어그램 렌더링

• 로컬 이미지 임베드 및 마크다운 파일 간 클릭 가능한 링크

• 사용자 정의 가능한 댓글 템플릿

• 8가지 테마: Light, Dark, Sepia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

지원 플랫폼

• macOS: 지원

• Linux: 지원; 시스템 파일 선택기는 zenity 필요

• Windows: 지원; 시스템 파일 선택기는 PowerShell 사용

권한

기본적으로 md-redline은 홈 디렉토리의 모든 마크다운 파일을 읽을 수 있습니다. mdr을 처음 실행할 때(또는 trusted-roots 기능이 없는 버전에서 업그레이드한 후 처음 실행할 때), 홈 폴더가 ~/.md-redline.json의 신뢰할 수 있는 루트 목록에 추가됩니다. 홈 디렉토리 외부의 파일(/tmp, 마운트된 볼륨, 시스템 경로)은 처음 열 때 OS 폴더 선택기를 통해 명시적인 권한 부여가 필요합니다. 부여된 폴더는 재시작 후에도 기억됩니다.

엄격한 폴더별 모델을 사용하려면 설치 후 mdr --restrict를 한 번 실행하세요. 그러면 기본 신뢰가 없는 ~/.md-redline.json이 생성되며, 파일을 처음 열 때마다 각 폴더에 대해 명시적으로 권한을 부여하게 됩니다.

파일 저장은 원자적 쓰기 후 이름 바꾸기(atomic write-then-rename) 및 mtime 기반 충돌 감지를 사용하여 동시 편집으로 인한 데이터 손실을 방지합니다. Mermaid SVG 출력은 렌더링 전 DOMPurify를 통해 살균됩니다. 신뢰할 수 있는 환경에서만 md-redline을 실행하세요.

개발

소스에서 빌드

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

Vite가 출력하는 로컬 URL(보통 http://localhost:5188)을 여세요.

스크립트

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

에이전트 평가

평가 하네스는 AI 에이전트가 인라인 댓글을 올바르게 읽고, 처리하고, 제거하는지 테스트합니다.

• npm run eval:dry는 평가 픽스처를 검증합니다.

• npm run eval은 전체 평가 하네스를 실행합니다.

• 자세한 내용은 eval/README.md를 참조하세요.

아키텍처

bin/md-redline             CLI entry point (invoked as `mdr` or `md-redline`)
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

라이선스

MIT