개인 지식베이스 MCP 서버

실제 개인 소유 문서 코퍼스에 대한 시맨틱 검색을 제공하는, 채용 담당자에게 바로 보여줄 수 있는 MCP 서버입니다.

문제

키워드 검색은 표현이 다를 때 의미상 관련된 정보를 놓칩니다. 이 프로젝트는 개인 노트를 임베딩으로 인덱싱하고 Model Context Protocol을 통해 재사용 가능한 검색 도구를 제공합니다.

Related MCP server: research-mcp

제공 기능

• 호출 가능한 3가지 도구를 갖춘 FastMCP 서버:

  • search_notes(user_id, query, top_k) — 순위가 매겨진 청크 및 출처 인용

  • get_document(user_id, doc_id) — 인덱싱된 전체 문서 컨텍스트

  • list_sources(user_id) — 인덱싱된 소스

• PDF/Markdown/TXT 수집 및 중복을 고려한 청킹

• sentence-transformers/all-MiniLM-L6-v2 임베딩

• 사용자별 컬렉션을 갖춘 Qdrant 벡터 저장소

• 명시적인 no_confident_match을 포함한 유사도 임계값

• 회원가입/로그인, 업로드, 검색을 지원하는 FastAPI 다중 사용자 웹 데모

• 수동 라벨링된 검색 평가 스크립트

아키텍처

architecture.md를 참조하세요.

빠른 시작

1. 설치

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -r requirements.txt

2. Qdrant Cloud 구성

무료 Qdrant Cloud 클러스터를 만들고 URL/API 키를 복사한 뒤 .env.example에서 .env를 생성합니다.

QDRANT_URL=https://YOUR-CLUSTER.qdrant.io
QDRANT_API_KEY=YOUR_KEY

3. 실제 코퍼스 추가

corpus/에 직접 작성한 학기 노트 2~5개를 넣은 다음:

python ingest.py --user demo --path corpus

4. 웹 데모 실행

uvicorn api:app --reload

http://127.0.0.1:8000을 여세요.

5. MCP 서버 실행

python server.py

Claude Desktop의 경우 server.py의 절대 경로와 가상 환경의 동일한 Python 인터프리터를 사용하여 MCP 구성에 서버 명령을 추가합니다.

예시 형태:

{
  "mcpServers": {
    "personal-knowledge-base": {
      "command": "C:\\PATH\\TO\\.venv\\Scripts\\python.exe",
      "args": ["C:\\PATH\\TO\\personal-knowledge-base-mcp\\server.py"]
    }
  }
}

검색 품질

evaluation_queries.json에 각 쿼리가 올바른 doc_id에 매핑된 작은 수동 라벨링 셋을 만든 다음 실행하세요:

python evaluate.py --user demo

최종 README에는 실제 측정된 Precision@k를 보고하세요. 숫자를 만들어 내지 마세요.

데모

5분 라이브 데모 순서는 demo_script.md를 참조하세요.

기술 스택

Python · FastMCP · Qdrant Cloud · Sentence Transformers · FastAPI · SQLite · PDF/Markdown/TXT

유용성

MCP 계층은 프로토콜 수준입니다. 동일한 검색 기능은 맞춤형 챗봇 UI에 묶이지 않고 Claude Desktop 또는 다른 MCP 호환 클라이언트에서 호출할 수 있습니다.

한계

펠로우십/데모 구현입니다. 인증은 의도적으로 기본 수준이며, 프로덕션 배포에는 안전한 세션, 비밀번호 해싱, 권한 부여 미들웨어, 속도 제한, 암호화 저장소, 더 강력한 테넌트 격리를 추가해야 합니다.