docs-rag-mcp

이것은 문서를 위한 더 나은 검색 엔진이 아닙니다. 에이전트가 믿을 수 있는 내용에 대한 필터입니다: 대체된 결정은 사라지고, 임계값은 지어내는 대신 *"모르겠습니다"*라고 말하며, 결과가 왜 포함되었는지 항상 확인할 수 있습니다.

마크다운 문서 폴더를 모든 MCP 클라이언트(Claude Code, Claude Desktop, Codex, Cursor, Zed…)에 하나의 검색 도구인 search_notes로 노출하는 MCP 서버입니다. 모든 것은 사용자 머신에서 실행됩니다: 임베딩은 Ollama를 거치며, 인덱싱 시간이나 쿼리 시간에 어떤 것도 컴퓨터 밖으로 나가지 않습니다.

npx -y docs-rag-mcp init      # guided questions -> config.json
npx -y docs-rag-mcp index     # builds the index

검색할 문서를 작성 중이신가요? 마크다운 파일을 구성하는 방식에 따라 검색 가능성이 결정됩니다. **AUTHORING.md**를 참조하세요 — 검색이 잘 되는 문서 작성에 대한 짧은 가이드입니다. 5분만 투자하면 모든 검색이 개선됩니다.

무엇이 이 도구를 다르게 만드는가

이 도구가 하는 일의 대부분은 다른 로컬 RAG 서버들도 수행합니다. 진정으로 드문 부분은 **문서 수명주기(document lifecycle)**입니다: 인덱스는 문서가 대체되었음을 알고 있으며, 그에 따라 작동합니다.

• frontmatter에 status: superseded로 표시된 문서는 기본적으로 반환되지 않습니다. 명시적으로 이력을 요청했기 때문에 다시 반환될 때는 [superseded → reference/auth.md; 2026-03-01] 라벨이 붙어서, 후속 문서가 함께 전달됩니다.

• minScore 미만에서는 도구가 찾은 가장 가까운 노이즈를 넘겨주는 대신 **"관련 결과 없음 (최고 점수 0.41, 임계값 0.55)"**이라고 말합니다. 잘못된 매치를 받은 에이전트는 그것을 진실로 취급합니다; 인간이라면 망설였을 것입니다. 임계값은 바로 그 망설임이 존재하는 곳입니다.

• 모든 히트는 그것이 왜 거기에 있는지 보여줍니다: [semantic 0.712], [both 0.712], [exact match]. 신뢰해야만 하는 블랙박스가 아닙니다.

다른 모든 도구는 파일 신선도(file freshness)를 처리합니다 — 재동기화, 재인덱싱, 변경 감시. 아무도 **진실 신선도(truth freshness)**를 처리하지 않습니다. 이것이 이 도구의 존재 이유입니다.

나머지 — 로컬 전용, 제목 기준 청킹, SQLite 저장, 증분 인덱싱 — 은 이 분야의 기본 요건(table stakes)이지 차별점이 아닙니다. 아래 기능 표에 포함되어 있지만, 핵심 주장은 아닙니다.

Related MCP server: recall-mcp

이 도구가 필요 없는 경우

솔직한 버전입니다, 이 분야가 움직였기 때문입니다:

• 심볼의 정확한 일치에는 에이전트에게 이미 grep이 있습니다, 그리고 grep은 더 빠르고 인덱스가 필요 없습니다. 함수 이름, 오류 코드, 설정 키: 그것들을 위해 벡터 인덱스를 구축하지 마세요.

• 수십 개 미만의 문서에서는 에이전틱 검색(agentic search)으로 충분합니다. 에이전트가 파일 트리를 읽고, grep하고, 관련 있어 보이는 것을 엽니다. 그것으로 충분합니다.

• Anthropic은 Claude Code 내부에 벡터 DB를 가진 RAG를 출시했다가 제거했습니다 (2025년 5월), 에이전틱 검색이 그것을 능가했기 때문입니다. Cursor, Windsurf, Cline 등도 같은 길을 갔습니다. 그렇지 않은 척하는 것은 부정직한 일입니다.

그것을 견뎌내고 이것이 존재하는 이유: grep은 이름을 아는 것만 찾습니다. 문서가 "token refresh window"라고 부르고 사용자가 "session expiry"라고 부를 때, grep은 아무것도 반환하지 않고 시맨틱 검색은 문서를 반환합니다. 그리고 길고 계층적인 코퍼스에서 시맨틱 검색은 에이전트가 트리를 탐색하는 것보다 더 적은 왕복(round-trips)과 더 적은 토큰을 소비합니다 — "더 나은 결과"가 아니라 더 저렴한 결과입니다.

따라서 사용 범위는 좁고 구체적입니다: 대체된 자료를 포함하는, 마크다운으로 된 결정, 스펙, ADR의 길고 계층적인 코퍼스에서, 에이전트가 죽은 결정을 부활시키지 않아야 하는 경우.

사전 요구 사항

• Node.js ≥ 22.5 — 인덱스는 내장된 node:sqlite 모듈을 사용하므로 빌드할 네이티브 의존성이 없습니다. Node 버전에 따라 stderr에 한 줄 경고(ExperimentalWarning: SQLite is an experimental feature)가 표시될 수 있습니다; 무해합니다.

• 임베딩 모델이 있는 Ollama. 모델은 인덱스를 구축할 때 그리고 매 검색마다 필요합니다 — 쿼리는 즉석에서 임베딩되므로 Ollama는 인덱스 시간뿐만 아니라 MCP 서버가 사용되는 동안 항상 실행 중이어야 합니다.

  # install Ollama from https://ollama.com, then:
  ollama pull bge-m3

설치

게시된 패키지는 클론이나 빌드가 필요 없습니다:

npx -y docs-rag-mcp init      # guided questions -> writes config.json
npx -y docs-rag-mcp index     # builds the index

자동 재인덱스 훅을 사용할 계획이라면 전역으로 설치하세요:

npm i -g docs-rag-mcp

npx는 매 실행마다 패키지를 다시 해석하고 첫 사용 시 다운로드합니다. 세션당 한 번 시작되는 MCP 서버에게는 관련이 없지만, 훅은 0초에 종료되도록 설계되었고 모든 파일 편집 후에 실행됩니다 — 전역 설치는 그 오버헤드를 완전히 제거합니다. docs-rag scaffold는 전역 설치를 감지하고 더 짧은 명령 형식을 자동으로 작성합니다.

설정을 직접 편집하는 것을 선호하시나요? config.example.json을 config.json으로 복사하고 vaultPath를 설정하세요. 나머지는 모두 합리적인 기본값이 있습니다.

git clone https://github.com/andreaselmi/docs-rag-mcp
cd docs-rag-mcp
yarn install
yarn setup          # -> config.json
yarn index
yarn build          # compiles to dist/

yarn 스크립트는 하위 명령어와 일대일로 매핑됩니다 (setup→init, serve, index, search, scaffold). 소스 체크아웃에서 프로젝트를 스캐폴딩할 때 **--local**을 전달하세요: 생성된 파일에 게시된 패키지가 아닌 작업 트리를 해석할 npx 명령 대신 node /abs/path/dist/server.js를 작성합니다.

명령어

docs-rag init                 interactive wizard, writes config.json
docs-rag scaffold <dir>       give a project its own scoped instance
docs-rag index                build or update the index
docs-rag search "question"    query the index from the terminal
docs-rag serve                run the MCP server on stdio
docs-rag hook                 Claude Code hook entry point (auto re-index)

모든 명령어는 --config <path>를 허용합니다.

터미널에서 검색 테스트

docs-rag search "how do we handle authentication"

반환된 이유가 각각 표시된 일치 섹션을 볼 수 있습니다:

[semantic 0.712]  reference/auth.md › Auth > How the client refreshes the token
[both 0.688]      decisions/2026-01-session-length.md › Session length  [2026-01-14]
[exact match]     reference/errors.md › Error codes > ERR_TOKEN_EXPIRED

이것은 MCP 클라이언트가 사용할 검색과 정확히 동일합니다 — 먼저 여기서 확인하세요.

단일 쿼리에 대해 폴더를 건너뛰려면 --exclude를 전달하세요(쉼표로 구분된 경로 조각, 대소문자 구분 없음):

docs-rag search "how do we handle auth" --exclude archive,drafts

MCP 도구는 search_notes의 선택적 exclude 배열로 동일한 기능을 노출하므로, 대화에서 *"검색하되 archive 폴더는 무시해"*라고 요청할 수 있습니다.

일부 폴더(archive, plans — 기본값, defaultExclude 참조)는 --exclude를 전달할 때뿐만 아니라 모든 쿼리에서 건너뜁니다. 한 쿼리에 대해 그것들을 검색하려면 --all(CLI) 또는 searchAll: true(도구 매개변수)를 전달하세요. 동일한 플래그는 기본 검색에서도 숨겨지는 frontmatter의 superseded/archived 표시 문서도 다시 포함합니다.

두 가지 검색 트랙과 라벨

Dense 임베딩은 스펙에 가득한 바로 그 것들(약어, 오류 코드, 함수 이름, 버전 번호)에 약합니다. 따라서 각 쿼리는 두 개의 트랙을 실행하고 병합합니다.

• 시맨틱(semantic) 트랙은 코사인 유사도로 모든 청크를 순위화하고 임계값을 적용합니다.

• 어휘(lexical) 트랙은 쿼리의 희귀한 용어로 제한된 전문 검색(FTS5)입니다. "희귀함"은 사용자 자신의 인덱스를 기준으로 측정됩니다: 용어는 최대 max(5, lexicalMaxDocFreq × total chunks) 청크에, 그리고 절반 이하의 청크에 나타날 때 자격을 얻습니다. 모든 단어에 FTS를 실행하면 일반적인 용어의 일치로 결과가 넘쳐날 것입니다; 희귀성 게이트가 정밀도를 유지하는 요소입니다.

각 히트의 라벨은 어느 트랙이 그것을 넣었는지 알려줍니다:

어휘 전용 히트는 제한되고(2개 슬롯) 항상 시맨틱 히트 뒤에 옵니다, 그래서 희귀 용어 일치는 답변에 추가될 수는 있지만 답변을 압도하지는 않습니다.

임베딩 모델

Ollama에서 사용 가능한 모든 임베딩 모델이 작동합니다 — 설정에서 embedModel을 설정하세요. bge-m3가 기본값이며 임계값은 그것에 맞게 튜닝되어 제공됩니다.

지금 embedModel을 변경하면 전체 재구축이 강제됩니다. 인덱스는 어떤 모델이 구축했는지 기록합니다; 다른 모델로 열면 호환되지 않는 벡터에 대해 조용히 점수를 매기는 대신 거부됩니다. 이전 버전은 조용히 혼합하여 오류 없이 잘못된 결과를 반환했을 것입니다.

일부 모델은 입력에 작업 접두사가 필요합니다(nomic-embed-text는 search_query: / search_document:를 요구합니다). 그것들은 작은 레지스트리에 있으며 자동으로 적용됩니다. 레지스트리가 알지 못하는 모델을 선택하면 docs-rag index가 그렇게 알려줍니다 — 검색은 여전히 작동하지만, 접두사 규칙이나 임계값이 검증된 적은 없습니다.

보정 보고서

모든 인덱스 실행이 끝나면 다음과 같은 줄을 얻습니다:

Calibration: background noise p99 = 0.421 over 500 random pairs -> suggested minScore 0.45 (in use: 0.55, from the model registry).

자체 코퍼스에서 무작위 청크 쌍을 샘플링하며, 정의상 관련이 없는 쌍이 도달하는 유사도 점수를 보고합니다. 그것이 모델의 노이즈 바닥(noise floor)입니다: 그 아래로 점수를 매기는 것은 서로 아무 관련이 없는 두 문서와 구별할 수 없습니다.

복사할 설정이 아니라 하한선으로 사용하세요. 제안된 값이 구성된 minScore보다 훨씬 위라면, 임계값이 노이즈를 허용하고 있는 것입니다. 훨씬 아래라면 더 엄격하게 설정할 자유가 있습니다. 구성된 값은 항상 우선합니다 — 보고서는 선택을 덮어쓰지 않으며, 측정한 것을 알려줄 뿐입니다.

프로젝트당 하나의 인스턴스 (권장)

일반적으로 프로젝트마다 별도의 지식 베이스를 원할 것입니다. 프로젝트마다 이 도구의 사본이 필요하지는 않습니다 — 한 번 설치한 다음 각 프로젝트에 자체 설정을 부여하고 프로젝트 범위로 등록하세요:

docs-rag scaffold /path/to/some-project     # asks a few questions (or pass flags)

해당 프로젝트에 대해 다음을 작성합니다:

• some-project/.rag/config.json — 해당 설정 (vaultPath는 프로젝트 루트; 인덱스는 그 옆의 .rag/index.db에 위치). 이미 스캐폴딩된 프로젝트에서 scaffold를 다시 실행하면 이 파일이 보존됩니다: 튜닝된 pathBoosts와 임계값은 유지되고, 해당 실행에서 플래그로 명시적으로 전달한 키만 덮어씁니다.

• some-project/.mcp.json — 프로젝트 범위 MCP 등록. 기존 서버는 보존됩니다. 명령이 머신별 경로를 포함하지 않으므로 이 파일은 커밋할 수 있습니다: 저장소를 클론하는 사람은 아무것도 수동으로 설치하지 않고 문서 검색을 사용할 수 있습니다.

• 프로젝트의 .gitignore에 .rag/index.db*와 레거시 .rag/index.json*을 추가합니다.

• --hook 사용 시: some-project/.claude/settings.local.json, 모든 마크다운 편집 후 재인덱스하는 Claude Code 훅(아래 참조).

그 다음:

docs-rag index --config /path/to/some-project/.rag/config.json

비대화형, 여러 저장소에 걸쳐 스크립트 가능:

docs-rag scaffold /path/to/proj --name proj-docs --include "**/docs/**/*.md" \
  --desc "What's in this project's docs" --hook --yes

--config 해석 방식

모든 명령어는 --config를 허용합니다. 설정 파일은 자체 인덱스를 "지니고" 있으므로(상대 indexPath는 설정 파일 옆에서 해석됨) 인스턴스가 서로 간섭하지 않습니다. 해석 순서:

1. 절대 경로가 항상 우선합니다.

2. CLAUDE_PROJECT_DIR — Claude Code가 자신이 실행하는 서버와 의 환경에서 프로젝트 루트로 설정하는 값.

3. 작업 디렉터리에서 위로 올라가 해당 경로가 존재하는 첫 번째 상위 디렉터리를 찾습니다. 이것이 자체 환경 변수를 설정하지 않는 클라이언트에서 --config .rag/config.json이 동작하게 만드는 이유입니다.

4. 그렇지 않으면 작업 디렉터리.

--config를 전혀 지정하지 않으면 같은 상향 탐색이 .rag/config.json을 찾으므로, 스폴드된 프로젝트 어디에서든 docs-rag search "…"를 실하면 바로 동작합니다.

${CLAUDE_PROJECT_DIR}를 직접 .mcp.json 인자에 쓰지 마세요. Claude Code는 그곳에서 변수를 확장하지 않으므로 문자 그대로 전달됩니다.

MCP 클라이언트에 연결하기

Claude Code

프로젝트 범위는 docs-rag scaffold가 설정하는 것입니다. 반대로 모든 세션에서 사용할 지식 베이스를 원한다면 사용자 범위로 등록하세요:

claude mcp add work-docs -s user -- npx -y docs-rag-mcp serve --config ~/vaults/work.json

claude mcp list로 연결을 확인한 다음, "search_notes: 왜 X를 선택했나요?" 같은 질문을 해 보세요.

Codex CLI, Cursor, Zed 및 기타 MCP 클라이언트

서버는 순수 stdio MCP이므로 프로토콜을 지원하는 어떤 클라이언트든 실할 수 있습니다. Codex CLI의 ~/.codex/config.toml에서는:

[mcp_servers.docs-search]
command = "npx"
args = ["-y", "docs-rag-mcp", "serve", "--config", "/absolute/path/to/.rag/config.json"]

Cursor와 Zed도 자체 MCP 설정에서 동일한 명령과 인자를 사용합니다.

여기서는 절대 경로 --config를 사용하는 형태가 맞습니다. 아무것에도 의존하지 않기 때문입니다. 상대 경로도 위에서 설명한 디렉터리 상향 탐색을 통해 동작하지만, 그 경로는 구섭 방식과 단위 테스트로 검증되었을 뿐 해당 클라이언트들에 대해서는 테스트되지 않았습니다. 그중 하나에서 실해 보셨다면 보고해 주시면 감사하겠습니다.

각 인스턴스에 고유한 serverName과 toolDescription을 지정하세요. 설명은 모델이 해당 도구를 호출할지 여부를 결정할 때 읽는 내용이므로, 도구가 무엇을 하는지가 아니라 이 지식 베이스에 무엇이 들어 있는지를 설명하세요.

인덱스를 최신 상태로 유지하기

인덱스는 빌드 산출물입니다. index.db는 WAL 모드의 SQLite 데이터베이스로, - wal 및 - shm 사이드카 파일을 갖습니다. 문서를 편집한 후에는 docs-rag index를 다시 실하세요. 이는 증분 방식이므로 mtime이 변경된 파일만 다시 임베딩합니다. 실 중인 MCP 서버는 재인덱스를 자동으로 반영하므로 재시작이 필요 없습니다. 오래된 인덱스는 오래된 내용으로 답합니다 — 놓치는 것보다 더 나니다.

자동 재인덱스(Claude Code 전용, 선택 사항)

--hook으로 스폴드하면 Claude Code PostToolUse 이(가) 해당 프로젝트에서 Claude가 마크다운 파일을 쓰거나 편집할 때마다 배경에서 증분 인덱서를 다시 실합니다. 최대 30초에 한 번으로 통합되며, 어떤 편집도 놓치지 않습니다. Claude Code 밖에서 이루어진 편집은 여전히 수동 실이 필요합니다.

훅은 프로젝트의 .claude/settings.local.json에 저장됩니다(개인용이며 커밋되지 않음). 비활성화하려면 PostToolUse 항목을 삭제하세요. 백그라운드 실행이 작동하지 않을 때 — 대개 Ollama가 실 중이지 않아서 — 세션의 에피소드당 한 번 경고하며, 저장할 때마다 경고하지 않습니다. 자세한 내용은 .rag/hook.log에 기록됩니다. 다른 MCP 클라이언트는 Claude Code 을 실하지 않으므로, 그곳에서는 수동으로 재인덱스하세요.

기존 인덱스 업그레이드

업그레이드 후 첫 docs-rag index는 평소의 1초 미만의 no-op이 아니라 일회성 전체 재임베딩입니다. 스키마에 모델 식별 테이블과 FTS5 테이블이 추가되었고, 이전 벡터는 그대로 옮겨 쓸 수 없기 때문입니다. 훅이 활성화되어 있으면 첫 편집 시 백그라운드에서 시작되므로, 그 첫 실행은 1초가 아니라 몇 분이 걸릴 것으로 예상하세요.

원래의 index.json에서 업그레이드하는 경우: index.json.bak으로 이름이 바고 처음부터 다시 빌드됩니다. 결과가 마음에 들면 .bak을 삭제하세요.

구성 참조

검색 튜닝

다섯 가지 선택 필드가 반환 결과를 제어합니다(괄호 안은 기본값):

• defaultExclude (["archive", "plans"]) — 모든 쿼리에서 제외되는 경로 하위 문자열. 호출자는 각 쿼리마다 searchAll: true(CLI: --all)로 다시 포함할 수 있습니다. 같은 플래그는 frontmatter에서 superseded/archived로 표시된 문서도 다시 포함합니다.

• minScore (0.55) — 절대 코사인 하한. 이 값보다 낮으면 결과가 제거되고, 도구는 "No relevant results"라고 답하며 거부된 최고 점수를 함께 제시합니다. 노이즈를 반환하는 대신입니다. 값을 고르는 방법은 위의 보정 보고서를 참조하세요.

• relativeCutoff (0.88) — 가장 높은 점수의 이 비율 미만으로 득점한 결과를 제거합니다.

• lexicalMaxDocFreq (0.01) — 어휘 트랙을 발동시키기 위해 쿼리 용어가 얼마나 희귀해야 하는지. 용어가 max(5, ratio × total chunks) 청크 이하에 나타나면 자격을 얻고, 말뭉치의 절반 이상에 나타나면 절대 자격을 얻지 못합니다. 값을 올리면 더 많은 용어가 통과하고(더 많은 정확 일치, 더 많은 노이즈), 내리면 진정으로 희귀한 식별자에게만 트랙을 예약합니다.

• pathBoosts ({}) — 경로 하위 문자열에 따른 순서 전용 배율. 예: {"reference/": 1.15, "decisions/": 1.1}처럼 사용해 노트보다 정리된 문서를 선호할 수 있습니다. 부스트는 임계값을 절대 덮어쓰지 않으며 보고되는 점수도 변경하지 않습니다.

minScore와 relativeCutoff는 bge-m3에 맞게 조정된 상태로 제공됩니다. 다른 모델을 사용한다면 기본값을 신하기 전에 docs-rag index를 실하고 보정 라인을 읽으세요.

동작 방식

약 2,000줄의 TypeScript이며, 빌드 마법이나 프레임워크가 없습니다. 실제 검색 경로 — 청크 분할, 임베딩, 랭킹 — 는 그중 약 500줄이고, 처음부터 끝까지 읽을 수 있습니다.

• src/chunk.ts — 마크다운을 헤딩 기준으로 분할하고, 헤딩 이동 경로를 유지하며, 임베딩 텍스트에서 코드 펜스를 제거합니다.

• src/frontmatter.ts — status / date / superseded_by를 파싱하고 인덱스 텍스트에서 제거합니다.

• src/embed.ts + src/models.ts — Ollama의 /api/embed와 모델별 접두사 레지스트리.

• src/store.ts — SQLite 스키마, 버전 관리, 모델 식별, FTS5 미러.

• src/index-docs.ts — 볼트를 순회하며 청크 분할, 임베딩, 증분 기록을 수행합니다.

• src/calibrate.ts — 제안된 minScore 뒤에 있는 노이즈 바닥 측정.

• src/lexical.ts — 희귀성 게이트: 어떤 쿼리 용어가 정확 검색에 적합한지.

• src/search.ts — 쿼리를 임베딩하고 코사인으로 순위를 매기며 임계값, 제외 및 부스트를 적용하고 어휘 트랙을 병합합니다.

• src/server.ts — stdio를 통해 search_notes를 노출하는 MCP 서버.

• src/scaffold.ts — 프로젝트별 인스턴스 생성기.

• src/hook.ts — 자동 재인덱스 훅(디바운스, 잠금, 실패 알림).

• src/cli.ts — docs-rag 실행 파일; 하위 명령 테이블만 있을 뿐입니다.

의도적으로 범위 밖에 둔 것들

• 두 트랙에 대한 상호 순위 융합(RRF). RRF는 절대 점수를 버리는데, minScore — "모르겠다" 임계값 — 은 절대 점수를 기반으로 합니다. 트랙을 분리해 두면 그 약속이 유지됩니다.

• 단일 인스턴스에서 여러 볼트 사용 (대신 여러 구성을 사용하세요).

• 플러그형 임베딩 제공자 — 로컬 전용 약속을 지키기 위해 Ollama만 지원.

• 사람을 위한 UI, 협업, 다중 문서 종합. 이 프로젝트는 코드를 작업하는 에이전트가 여러분의 결정을 알 수 있도록 존재하지, 팀이 문서를 읽는 장소가 아닙니다.

라이선스

MIT — LICENSE를 참조하세요.