scholar-rag-mcp

상태: 프리뷰 릴리스(v0.1.0). 인터페이스와 저장소 구조는 향후 버전에서 변경될 수 있습니다.

scholar-rag-mcp는 배포 가능한 학술 논문 지식 베이스 MCP 도구입니다. PDF 폴더를 지정하면 각 논문을 실제 파싱 파이프라인(MinerU)으로 처리하고, 메타데이터를 정규화하고, 섹션 구조에 주석을 달고, 텍스트를 청크로 나누어 임베딩한 다음, 모든 것을 Qdrant에 저장합니다. 이후 에이전트(또는 사용자)는 청크를 의미적으로 검색하고, PubMed 스타일 문서 쿼리를 실행하고, 전체 텍스트를 섹션별로 읽고, 개별 논문을 추가/제거하고, 지식 베이스를 관리할 수 있습니다. 이 모든 것은 stdio를 통한 11개의 MCP 도구로 이루어집니다. 임베딩, 주석, 재랭킹은 프로세스 내 폴백을 지원하는 OpenAI 호환 모델 서비스(vLLM)에서 실행됩니다.

기능

• 실제 수집 파이프라인: MinerU PDF 파싱(python/cli/api 백엔드) -> 메타데이터 추출(로컬 휴리스틱, CrossRef, 선택적 GROBID) -> 정제 -> 섹션 주석 -> 결정적 청킹(300/1500/100자 설정 가능) -> 임베딩.

• 대규모 고속 검색: 임베딩 1차 검색 + 크로스 인코더 재랭킹, 선택적 메타데이터 필터링(doc_id, section, year, journal, ...)은 Qdrant 인덱스 내부에서 평가됩니다. 100k 청크 기준 p95 쿼리 지연 시간 < 1초(docs/perf-report.md 참조).

• 비동기 작업: create_kb/add_document는 백그라운드 작업이며 진행 상황은 get_job으로 조회할 수 있습니다. 재시작에 안전합니다(중단된 작업은 복구되어 재실행 시 건너뜁니다).

• 컨텍스트 안전 읽기: 페이지네이션된 get_document_text와 하드 크기 상한; 개요 먼저, 페이지는 요청 시.

• stdio를 통한 11개 MCP 도구: list_kbs, create_kb, delete_kb(2단계), add_document, remove_document, get_document, get_document_text, list_documents, search_documents, search_chunks, get_job.

• 자체 포함 저장소: 지식 베이스는 단일 데이터 디렉터리(~/.scholar-rag) 아래에 위치합니다. Qdrant는 자동 실행(단일 바이너리, 버전 고정)되거나 외부 인스턴스에 연결됩니다.

Related MCP server: Athena

설치

pixi가 필요합니다. 저장소 루트에서:

pixi install                      # installs the default environment

이 프로젝트는 각각 다른 용도를 제공하는 세 개의 pixi 환경을 정의합니다:

내장 doctor로 환경을 확인하세요:

pixi run python scripts/doctor.py

모델 배포

환경('chat', 'embed', 'rerank' 클라이언트)은 OpenAI 호환 HTTP 엔드포인트를 기대합니다. scripts/serve_models.sh는 참조 모델 세트에 대해 세 개의 vLLM 인스턴스를 실행합니다:

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL, SCHOLAR_RAG_EMBED_MODEL, SCHOLAR_RAG_RERANK_MODEL은 필수입니다. 하나라도 설정되지 않으면 스크립트는 해당 변수를 나열하는 메시지와 함께 종료됩니다. 각 값은 로컬 HuggingFace 모델 디렉터리의 절대 경로여야 합니다. vLLM은 각 모델을 디렉터리 기본 이름과 같은 짧은 이름으로 제공하므로 클라이언트 설정은 해당 짧은 이름을 사용해야 합니다(제공되는 이름은 더 이상 전체 경로와 같지 않습니다). .env.example의 /path/to/... 자리 표시자를 그에 맞게 바꾸세요. 포트(CHAT_PORT/EMBED_PORT/RERANK_PORT)와 GPU ID는 선택 사항이며 기본값이 정상 작동합니다.

스크립트는 이 모델들에 대해 검증된 정확한 vLLM 플래그를 고정합니다(Jina embed 모델은 사용자 정의 코드 때문에 --trust-remote-code가 필요합니다. reranker는 기본 태스크로 실행되며 추가 플래그가 없습니다). 모델 로드에는 몇 분이 걸립니다. 스크립트는 세 모델이 모두 응답할 때까지 헬스 체크를 폴링합니다.

최소 환경

.env.example에서 시작하여 최소한 모델 엔드포인트를 설정하세요(serve 스크립트가 노출하는 짧은 이름을 사용하세요. 각 모델 디렉터리의 기본 이름과 같습니다):

SCHOLAR_RAG_DATA_DIR=~/.scholar-rag
SCHOLAR_RAG_QDRANT_STORAGE_DIR=~/.local/share/scholar-rag/qdrant

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

임베드 모델 차원은 kb 생성 시 kb_meta.json에 기록되므로 나중에 임베딩 모델을 변경하려면 새 kb가 필요합니다.

MCP 클라이언트 설정

서버 진입점을 직접 시작하여 실행되는지 확인하세요:

pixi run scholar-rag-mcp

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "pixi",
      "args": ["run", "scholar-rag-mcp"]
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["pixi", "run", "scholar-rag-mcp"]
    }
  }
}

도구

데이터 구조

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default ~/.scholar-rag
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
└── bin/                        # auto-downloaded Qdrant binary (v1.12.5)

Qdrant 저장소는 data_dir 외부의 QDRANT_STORAGE_DIR(기본값 ~/.local/share/scholar-rag/qdrant)에 위치합니다. 로컬 파일시스템에 있어야 하며 9p/네트워크 마운트는 안 됩니다.

2단계 kb 삭제

delete_kb는 잘못된 인수로 첫 번째 호출에서 실수로 삭제하는 일이 없습니다:

1. delete_kb(kb="...")를 호출합니다 - kb 통계와 10분짜리 confirm_token을 반환합니다.

2. delete_kb(kb="...", confirm_token="<token>")를 호출하여 실제로 Qdrant 컬렉션, kb 디렉터리 및 해당 작업 기록을 삭제합니다.

개발

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

릴리스 노트

알려진 제한 사항과 업그레이드 지침은 docs/handoffs/release-notes-v0.1.0.md를 참조하세요.

반복할 가치가 있는 알려진 제약 사항:

• Qdrant는 v1.12.5로 고정되어 있습니다 - glibc 2.35에서 실행되는 가장 높은 버전입니다. 자동 실행 시 첫 사용에 다운로드됩니다. glibc >= 2.38에서는 더 새로운 버전을 실행할 수 있지만, 이 릴리스에서 데이터 형식은 이전 kb와 순방향 호환되지 않습니다.

• MinerU는 자체 pixi 환경에서 실행됩니다 - transformers 버전이 vLLM 버전과 상호 배타적이기 때문입니다. 따라서 PDF 파싱은 pixi run -e mineru를 선호합니다.

• MinerU 가중치(약 3.2GB)는 첫 파싱 시 ~/.cache/modelscope/에 다운로드됩니다.

• 메타데이터 제목 휴리스틱: 제목은 MinerU 마크다운이 #/## 제목으로 시작할 때만 로컬에서 선택되므로, 앞에 오는 ## Abstract 등이 제목으로 잘못 읽힐 수 있습니다. 이는 로컬 휴리스틱 메타데이터 계층에만 영향을 미칩니다. CrossRef 계층(DOI가 발견될 때 사용)은 일반적으로 이를 수정합니다.

• 도구 디스패치: 도구에 전달된 알 수 없는 추가 인수는 거부되지 않고 조용히 무시됩니다.

• 9p 저장소 제한: Qdrant 저장소는 로컬 파일시스템에 있어야 합니다.