📄 Markdown RAG Search — VS Code Extension

마크다운 문서를 자연어로 검색하는 VS Code 사이드바 익스텐션이다. markdown-rag MCP 서버를 자식 프로세스로 띄우고 stdio 통신으로 검색한다. 백엔드(임베딩 + Milvus)는 그대로 두고, 익스텐션은 MCP 클라이언트 역할만 수행한다.

이 프로젝트는 markdown-fastrag-mcp의 프론트엔드 클라이언트이다.

현재 상태

완료: Phase 1 (스캐폴드 + MCP 연결)
완료: Phase 2 (단일 Webview 검색 UI + 결과 리스트 + 파일 열기)
완료: Phase 2.1 (검색 블럭 하이라이트 + 위치 이동)
예정: Phase 2.2 (파서 안정화 + 구조화 메타데이터 계약)
다음: Phase 3 (StatusBar + reindex 폴링)

아키텍처

익스텐션은 MCP 도구 호출만 담당한다. 직접 임베딩 호출이나 Milvus 쿼리는 하지 않는다.

graph LR
    subgraph VSCode["VS Code"]
        EXT["📄 Markdown RAG\nExtension"]
        WV["Search + Results\nSingle Webview"]
    end

    subgraph Server["Child Process"]
        MCP["markdown-rag\nPython/uv"]
    end

    EXT --> WV
    EXT -->|"callTool(search_documents)"| MCP
    EXT -->|"callTool(get_index_status)"| MCP
    MCP --> Milvus["Milvus"]

검색 UX

현재 검색은 사이드바 단일 뷰에서 동작한다.

사이드바 입력창에 쿼리 입력
Enter 또는 Search 버튼 클릭
결과 목록 렌더링
결과 클릭으로 파일 열기 + 블럭 위치 점프/하이라이트 (best-effort)

입력 중 자동검색은 비활성화되어 있다. 의도하지 않은 요청 폭주를 막기 위해 Enter 제출 방식으로 고정했다.

기술 스택

구성요소	기술
익스텐션	TypeScript + VS Code Extension API
MCP 클라이언트	`@modelcontextprotocol/sdk` (`StdioClientTransport`)
MCP 서버	`markdown-rag` (Python, uv, FastMCP)
UI	단일 Webview (`search-webview.ts`)
번들러	esbuild

마일스톤

#	이름	산출물	상태
M0	프로젝트 초기화 + MCP 연결	`listTools` 확인, 연결/종료 생명주기	완료
M1	검색 UI + 결과 + 파일 열기	단일 Webview, Enter 제출, 클릭 열기	완료
M2	인덱싱 UI	StatusBar 진행률 + reindex 폴링	예정
M3	안정화	SecretStorage, 재연결, 타임아웃	예정
M4	배포	패키징/마켓플레이스/CI	예정

빠른 시작

cd 700_projects/markdown-rag-vscode
npm install
npm run compile

루트 워크스페이스에서 F5 실행 시 Development Host로 디버깅 가능하다.

필수 설정

/.vscode/settings.json 또는 Insiders User settings에 아래 설정이 필요하다.

{
  "markdownRag.serverPath": "/absolute/path/to/markdown-fastrag-mcp",
  "markdownRag.envFile": "/absolute/path/to/.env",
  "markdownRag.maxResults": 5,
  "markdownRag.scopePath": ""
}

.env에는 EMBEDDING_PROVIDER, MILVUS_ADDRESS, MARKDOWN_WORKSPACE 등 서버 실행에 필요한 값을 넣는다.

알려진 제약

search_documents 응답이 포맷 문자열이라 파싱이 취약함
점프는 best-effort 매칭이며 start_line 메타데이터가 없어 100% 보장되지 않음
StatusBar/리인덱싱 UI는 Phase 3 범위

변경 기록

2026-02-18: 초기 문서 작성
2026-02-18: 단일 Webview + Enter 제출 UX 기준으로 README 전면 정리
2026-02-18: Phase 2.1 완료 상태 및 블럭 점프/하이라이트 반영

Markdown RAG Search

jun6161