jongkwan.dev
프로젝트 목록으로

PKB — MCP 기반 개인 RAG 지식 베이스

Claude가 MCP 도구로 직접 검색·인덱싱하는 개인 지식 베이스 RAG

2025.10 - 현재·
Python
Elasticsearch
sentence-transformers
BGE Reranker
MCP
LangGraph
FastAPI
Docker

배경

수년간 쌓인 경력 노트·Obsidian Vault·공부 자료·이력서 초안이 여러 곳에 흩어져, 필요할 때마다 grep으로 긁어 오거나 기억에 의존해야 했다. Claude와 작업할 때마다 관련 자료를 직접 긁어 붙여넣는 흐름이 반복됐고, "이 개념과 연결되는 다른 내용"을 찾는 관계형 탐색은 grep으로 풀리지 않았다. 개인 지식을 RAG(Retrieval-Augmented Generation — 외부 문서를 검색해 LLM 답변에 근거를 더하는 방식)로 묶고, Claude가 MCP 도구로 질의·탐색할 수 있는 인터페이스가 필요했다.

시스템 구조

  • 하이브리드 검색: BM25 + 다국어 MiniLM 임베딩 kNN을 RRF(Reciprocal Rank Fusion)로 결합한 뒤, BGE Reranker v2-m3로 재랭킹해 상위 문서를 고른다.
  • 카테고리: about · career · study · writing · obsidian 5 카테고리, 10,000+ 청크.
  • MCP 서버: src/pkb/mcp_server.py가 14개 MCP 도구를 노출. search_knowledge, list_documents, get_document, reindex_document, add_document, write_file, sync_obsidian, search_concepts, explain_concept, related_concepts, graph_store_concepts, graph_list_chunks, doctor, convert_and_ingest.
  • 개념 그래프: LangGraph 기반 LLM 추출 파이프라인(graph/{builder, extract, store, schema})이 청크에서 개념과 관계를 뽑아 저장, search_concepts·related_concepts·explain_concept로 질의.

해결 과정

하이브리드 검색 설계. BM25(키워드 빈도 기반 전통 검색)는 의미 유사도에 약하고, kNN(임베딩 벡터 거리)은 정확한 키워드 매칭에 약하다. 두 결과를 RRF(Reciprocal Rank Fusion — 각 검색 결과의 순위를 역수로 합산해 결합)로 합치고, 상위 20개 후보를 BGE Reranker v2-m3로 재랭킹한다. scripts/reranker_model_benchmark.py로 재랭킹 모델 선택 근거를 기록.

카테고리별 인제스트. ingest.py가 파일 확장자별 파서(markdown, PDF, docx, pptx, xlsx)를 통해 청크 분할 → 다국어 MiniLM 임베딩 → Elasticsearch pkb_documents 인덱스에 적재한다. 청크는 500 토큰 단위, 100 토큰 오버랩으로 자르되 마크다운 섹션 경로(H1 > H2 > H3)를 유지해 검색 결과에서 출처 위치까지 같이 보여준다. data/ 하위 경로로만 저장해 Obsidian Vault와 작업 공간이 섞이지 않게 경계를 둔다.

MCP 서버. FastMCP 기반 mcp_server.py로 14개 도구를 노출한다. Claude Code는 search_knowledge로 질의, write_file로 노트를 추가, reindex_document로 수정된 문서를 재인덱싱한다. 이 포트폴리오 작업처럼 "코드 → PKB → 포트폴리오 mdx"로 흐르는 파이프라인이 MCP 도구 호출만으로 완결된다.

개념 그래프 확장. 청크 본문을 그대로 검색하는 것 외에, graph/extract.py가 LangGraph로 청크별 개념·관계를 추출한다. search_concepts로 의미적으로 유사한 개념을, related_concepts로 한 개념과 엮인 다른 개념을 찾을 수 있다.

도구화된 품질 점검. doctor MCP 도구가 ES 연결·인덱스·청크 수·임베딩/재랭커 설정을 리턴한다. scripts/golden_retrieval_eval.py로 검색 품질 회귀를 수치로 본다.

성과

  • Elasticsearch 8.17 단일 인덱스에 5 카테고리·10,000+ 청크 인덱싱, 평균 응답 수백 ms.
  • BM25 + kNN 하이브리드 + RRF 결합 + BGE Reranker v2-m3 재랭킹으로 검색 품질 상한 확보.
  • 14개 MCP 도구를 Claude Code·Claude Desktop에 노출, 작업 파이프라인에서 직접 호출 가능.
  • LangGraph 기반 개념 그래프 파이프라인(graph/{builder, extract, store})으로 관계형 탐색 지원.
  • write_file + reindex_document 조합으로 "작성 즉시 인덱싱"되는 PKB 문서 워크플로우 완결.