local-rag-mcp

로컬 문서 코퍼스에 대한 의미 검색을 위한 읽기 전용 MCP 서버 — 온디바이스 임베딩(Ollama), 로컬 Chroma 저장소, 호스트를 벗어나는 데이터 없음. 코퍼스 콘텐츠를 클라우드 API로 보낼 수 없는 환경을 위해 구축되었으며, 모든 MCP 클라이언트(Claude Code, Codex, 프로토콜을 말하는 모든 것)에 동일하게 제공됩니다.

이것은 claude-code-session-memory의 MCP 서비스 형제입니다: 동일한 임베딩 모델, 동일한 명령 접두사 체계, 동일한 측정 방법론 — 하나의 검색 기반, 두 소비자. session-memory README에는 전체 평가 스토리(사전 커밋된 기준, 적대적 쿼리 세트, 회귀 귀속)가 있으며, 이 저장소는 훅 대신 서버에 동일한 규율을 적용합니다.

도구

둘 다 읽기 전용으로 주석 처리됩니다. 실패는 구조화된 {"error": ...} 페이로드를 반환합니다 — 다운된 종속성은 도구를 저하시키지 세션을 저하시키지 않습니다.

빠른 시작

git clone https://github.com/wesglockzin/local-rag-mcp
cd local-rag-mcp
python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
ollama pull embeddinggemma

# Index the included sample corpus (or point RAG_CORPUS_DIR at your own)
./.venv/bin/python ingest.py

# Register with Claude Code — ABSOLUTE paths on both sides: the MCP client
# launches the server from its own working directory, so relative paths are
# the #1 install failure.
claude mcp add local-rag -- "$PWD/.venv/bin/python" "$PWD/server.py"

그런 다음 Claude Code에게 코퍼스가 아는 것을 물어보세요 — "sev-1에 누가 페이징되나요?" — 그리고 search_corpus를 호출하는 것을 지켜보세요.

구성은 세 가지 환경 변수입니다: RAG_CORPUS_DIR(기본값: ./sample-corpus), RAG_STORE_DIR(기본값: ~/.local-rag-mcp/store), OLLAMA_HOST.

가치를 지키는 설계 결정

• 서버는 읽기 전용이며 저장소를 생성하지 않습니다. 수집이 생성을 담당합니다. 빈 저장소를 조용히 초기화하는 읽기 전용 서버는 "수집을 잊었습니다"를 "검색 결과 없음"으로 바꿉니다 — 더 나쁜 실패입니다. 답처럼 보이기 때문입니다.

• 임베딩 후 교체 수집. 파일의 이전 청크는 모든 새 청크가 성공적으로 임베딩된 후에만 삭제됩니다. 파일 중간에 Ollama 실패가 발생해도 해당 파일이 인덱스에서 누락되지 않습니다.

• 폐기된 문서는 사후 필터링이 아닌 사전 필터링입니다. frontmatter에 lifecycle: superseded가 있는 문서는 벡터 검색 전에 where 절로 제외되므로 결과 슬롯을 차지하지 않습니다. 수집은 모든 청크에 lifecycle 키를 명시적으로 기록합니다 — 일부 저장소 버전에서는 누락된 키가 $ne를 통과할 수 있으므로 부재는 안전한 기본값이 아닙니다. (이 규칙의 원본은 재수집이 한 번 마커를 조용히 지워서 폐기된 문서가 결과에 다시 나타났기 때문에 존재합니다. 회귀 테스트가 이를 고정합니다.)

• get_file은 심볼릭 링크에 강합니다. 인덱싱된 경로만 읽을 수 있으며, 수집 시점과 다른 위치로 해석되는 경로는 거부됩니다 — 그렇지 않으면 코퍼스 파일을 심볼릭 링크로 교체할 수 있는 사람은 서버를 통해 코퍼스 외부를 읽을 수 있습니다. 파일이 디스크에 없으면(코퍼스 이동, 다른 머신), 인덱싱된 청크 텍스트가 청크 순서대로 제공됩니다.

• 저장소는 항상 머신 로컬입니다. 라이브 SQLite 기반 데이터베이스입니다. 클라우드 동기화는 트랜잭션 인식 없이 전체 파일 교체를 수행하며, 실패 모드는 쓰지 않은 머신에서 조용히 손상된 인덱스입니다. 코퍼스와 이 레시피를 동기화하세요. 각 머신은 자체 저장소를 구축합니다.

• 모든 수집은 코퍼스 git 커밋을 출력에 기록하므로 인덱스 빌드를 정확히 생성한 코퍼스 상태에 고정할 수 있습니다("커밋되지 않은 변경 사항 있음" 자체가 경고 라벨입니다).

• 비대칭 임베딩 접두사(EmbeddingGemma의 문서화된 쿼리/문서 명령 접두사)가 검색 양쪽에 적용되어, 동반 프로젝트의 측정된 체계와 일치합니다 — 접두사가 원시 검색보다 두 자릿수 우위를 보였으며, 혼합 접두사/원시 벡터는 보정되지 않은 대역에서 점수를 얻습니다.

코퍼스 규칙

*.md 파일의 모든 디렉토리가 작동합니다. 세 가지 선택적 frontmatter 키:

rag: false            # exclude this file from the index entirely
rag_chunk: headings   # heading-split a long document (default: whole-file)
lifecycle: superseded # keep the file, hide it from search

커밋된 sample-corpus/는 세 가지 모두와 일반 파일을 연습합니다 — tools/gen_sample_corpus.py로 생성된 여섯 개의 가상 플랫폼 팀 문서(CI는 커밋된 코퍼스가 생성기와 일치하는지 확인합니다).

테스트

pip install pytest && python -m pytest -q

Ollama도 저장소도 없음: 임베더는 스텁되고 컬렉션은 호출을 기록하는 가짜입니다. 테스트 대상은 계약입니다 — 인수 검증, lifecycle 사전 필터가 where 절로 저장소에 도달하는지, 읽기 전용 생성 금지 보장, 심볼릭 링크 거부, 임베딩 후 교체 순서(임베더 다운 경로 포함), mtime 허용 오차 건너뛰기, 청커의 병합 및 초과 크기 분할 동작.

알려진 제한 사항

• 신뢰 모델: 서버는 가리키는 모든 코퍼스를 읽으며, 클라이언트는 검색된 텍스트를 모델 컨텍스트에 주입합니다. 신뢰하는 콘텐츠만 인덱싱하세요 — 적대적 문서는 프롬프트 주입 벡터입니다. 서버는 검색만 하고 정화하지 않습니다. Stdio MCP에는 인증 계층이 없습니다. 실행한 프로세스의 신뢰를 상속합니다.

• 점수는 하나의 임베딩 체계 내에서만 비교 가능합니다. 보정된 "약한 일치" 기준은 코퍼스별로 다릅니다(동반 저장소에 보정 방법 문서화).

• 하나의 저장소, 하나의 컬렉션 — 다중 코퍼스 라우팅은 여기서 범위를 벗어납니다.

• 하이브리드 키워드+벡터 단계 없음; 의역 여유는 동반 저장소에서 측정되고 문서화됩니다.

라이선스

MIT — LICENSE 참조.

저자

Wes Glockzin