Modular RAG MCP Server

DIY 유학 서비스 팀 내부 컨설턴트를 위한 유학 지원 지식 검색 및 관측 가능한 RAG 인프라

Modular RAG MCP Server는 로컬 우선(local-first), 플러그 가능(pluggable), 관측 가능한(observable) 검색 증강 생성(RAG) 서비스입니다. 이 시스템은 Model Context Protocol(MCP)을 통해 AI 클라이언트에 지식 검색 기능을 제공하며, Streamlit Dashboard를 통해 문서, 수집 작업, 쿼리 체인 및 평가 결과를 관리합니다.

이 프로젝트는 대학 시절의 실제 협업 시나리오에서 시작되었습니다. 학내 DIY 유학 서비스 팀이 학생들에게 해외 대학 지원을 지원했으며, 이 시스템은 컨설턴트가 대학 요건, 지원 서류, 절차 규정, 과거 경험 사이를 반복적으로 찾아다니며 출처를 추적하기 어려운 문제를 해결하기 위해 사용되었습니다. 현재 시스템은 팀 내부 배포가 완료되었으며, 공개 저장소에는 익명 합성 샘플만 제공되며 실제 학생 데이터, 내부 문서 또는 운영 데이터는 포함되지 않습니다.

저장소의 예시 자료는 모두 익명 합성 데이터를 사용해야 합니다. 시스템 출력은 컨설턴트가 검증할 수 있는 검색 근거이며, 컨설턴트의 판단을 대체하지 않으며, 대학, 비자 또는 법률 조언을 구성하지 않습니다.

목차

• 비즈니스 배경

• 시스템 경계

• 핵심 기능

• 시스템 아키텍처

• 데이터 및 저장소 일관성

• MCP Tools

• Dashboard

• 빠른 시작

• 품질 보증

• 보안 및 운영 제약

• 현재 상태 및 발전 계획

Related MCP server: mcp-rag-assistant

비즈니스 배경

DIY 유학 컨설턴트는 지원을 처리할 때 학교 공식 웹사이트 안내, 프로젝트 매뉴얼, 서류 템플릿, 내부 운영 체크리스트 및 과거 사례를 동시에 참고해야 합니다. 원본 자료는 일반적으로 PDF 형태로 분산 저장되어 있으며 다음과 같은 문제가 있습니다:

• 동일한 요구 사항이 여러 자료에 다른 표현으로 나타날 수 있어, 순수 키워드 검색은 누락된 재현(recall)이 발생하기 쉽습니다.

• 대학, 전공, 학위, 입학 시즌 등의 고유 명사는 정확히 일치해야 하므로, 단순 벡터 검색은 오검색(false recall)이 발생하기 쉽습니다.

• PDF의 표, 흐름도, 스크린샷에는 중요한 정보가 포함되어 있어, 순수 텍스트 파싱은 컨텍스트를 잃게 됩니다.

• 컨설턴트는 답변이 어떤 자료의 어떤 조각에서 나왔는지 알고, 자료가 여전히 유효한지 판단해야 합니다.

• 문서가 업데이트된 후 벡터 저장소, BM25 인덱스, 이미지 인덱스 및 수집 기록이 일관성을 유지해야 합니다.

• 검색 효과는 주관적 경험이 아닌 안정적인 테스트 세트 회귀를 통해 검증해야 합니다.

시스템의 서비스 대상은 팀 내부 컨설턴트입니다. 일반적인 작업 흐름은 다음과 같습니다:

1. 대학 프로젝트 자료, 내부 체크리스트 및 익명 사례를 지정된 Collection에 수집합니다.

2. MCP Client 또는 명령줄을 통해 자연어 질문을 제출합니다.

3. 시스템이 Dense + BM25 이중 경로 재현, RRF 융합 및 선택적 Rerank를 실행합니다.

4. 출처 인용이 포함된 텍스트 조각을 반환하고, 이미지가 적중된 경우 멀티모달 콘텐츠 블록을 반환합니다.

5. Dashboard를 통해 수집 과정, 재현 결과, 소요 시간 및 평가 지표를 확인합니다.

시스템 경계

이 프로젝트는 지식 수집, 검색, 인용, 평가 및 체인 관찰을 담당하며, 다음을 담당하지 않습니다:

• 컨설턴트를 대신하여 학교 선택, 합격 확률 또는 비자 결론을 내리는 것.

• 지원서 자동 제출, 이메일 발송 또는 학생 자료 수정.

• 학생용 계정, CRM, 결제 또는 지원 진행 관리 제공.

• 최신 대학 정책을 자동으로 수집하여 보유한다고 주장하는 것.

• 출처 근거가 없을 때 확정적인 비즈니스 결론을 생성하는 것.

핵심 기능

시스템 아키텍처

flowchart LR
    A["PDF 业务资料"] --> B["Ingestion Pipeline"]
    B --> C["Chroma 向量库"]
    B --> D["BM25 索引"]
    B --> E["SQLite 摄取历史"]
    B --> F["图片文件与索引"]
    G["顾问 / MCP Client"] --> H["MCP Server"]
    H --> I["Query Processor"]
    I --> J["Dense Retrieval"]
    I --> K["Sparse Retrieval"]
    J --> L["RRF Fusion"]
    K --> L
    L --> M["Optional Rerank"]
    M --> N["Response + Citations + Images"]
    B --> O["Ingestion Trace"]
    I --> P["Query Trace"]
    O --> Q["Streamlit Dashboard"]
    P --> Q

핵심 디렉터리:

src/
├── core/            # 数据契约、查询编排、响应构建、Trace、配置
├── ingestion/       # Chunk、Transform、Embedding、Storage 与 Pipeline
├── libs/            # LLM/Embedding/Loader/Reranker/Splitter/VectorStore 抽象
├── mcp_server/      # MCP 协议处理、Server 与 Tools
└── observability/   # Dashboard、评估与结构化日志

scripts/             # ingest、query、evaluate、Dashboard 启动入口
config/              # Provider、检索、重排、评估与摄取配置
tests/               # Unit、Integration、E2E 测试与固定样例

자세한 인터페이스, 데이터 흐름 및 모듈 제약은 DEV_SPEC.md를 참조하세요.

데이터 및 저장소 일관성

한 번의 수집은 여러 저장소 백엔드를 조정합니다:

파일 무결성 검사는 SHA256을 사용하여 이미 성공적으로 처리되었고 변경되지 않은 파일을 건너뜁니다. Chunk ID는 출처, 위치 및 내용에서 안정적으로 생성되며, 반복 수집은 멱등 Upsert를 사용합니다. DocumentManager는 Chroma, BM25, 수집 기록 및 이미지 인덱스 전반에 걸친 조정 삭제를 담당하며 부분 실패 정보를 반환합니다.

MCP Tools

현재 Server는 네 개의 Tools를 노출합니다. 처음 세 개의 범용 Tool은 원래대로 유지되며, 네 번째는 유학 비즈니스 어댑터 계층입니다:

MCP는 Stdio Transport를 사용합니다. stdout은 JSON-RPC 전용이며, 실행 로그는 stderr에 기록되어 프로토콜 프레임을 손상시키지 않습니다.

search_admissions_knowledge는 기본적으로 admissions_knowledge를 쿼리하며 항상 business_domain=study_abroad_admissions로 제한됩니다. 국가, 대학, 프로젝트, 학위 수준, 입학 시즌, 지원 라운드 및 출처 유형별 정확한 필터링을 지원합니다. 기본적으로 valid_until이 쿼리 비즈니스 날짜보다 이른 자료를 제외합니다. 유효 기간이 없거나 파싱할 수 없는 자료는 needs_review로 표시되며, 조용히 현재 규칙으로 간주되지 않습니다. 비즈니스 Tool은 매개변수 및 응답 어댑터 계층일 뿐이며, 하위 계층은 여전히 Dense + BM25, RRF, Cross-Encoder/LLM Rerank, 인용 및 멀티모달 반환을 실행합니다.

Dashboard

Dashboard는 6페이지 구조를 유지합니다:

1. Overview: 컴포넌트 구성, 데이터 자산, 실행 상태 및 유학 자료의 현재, 검토 대기, 만료 통계.

2. Data Browser: 문서, Chunk, Metadata 및 연관 이미지; 국가, 대학, 프로젝트, 학위, 입학 시즌, 지원 라운드, 출처 유형 및 시효 상태 조합 필터링 지원.

3. Ingestion Manager: 수집 트리거, 진행 상황 확인 및 문서 조정 삭제.

4. Ingestion Traces: 수집 단계, 처리 방법, 소요 시간 및 예외.

5. Query Traces: Dense/Sparse 재현, 융합, 재순위 및 최종 결과.

6. Evaluation Panel: 평가 실행 및 지표와 과거 결과 확인.

빠른 시작

1. 환경 준비

Python 3.10–3.12 필요.

git clone https://github.com/xiaoxinbuxingyeyuan/MODULAR-RAG-MCP-SERVER.git
cd MODULAR-RAG-MCP-SERVER
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS / Linux:

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

pyproject.toml은 이 프로젝트의 현재 검증에 사용된 직접 의존성 버전을 고정했습니다. MCP, Ragas, LangChain 또는 저장소 컴포넌트를 업그레이드할 때는 별도로 업그레이드하고 오프라인 및 온라인 회귀를 다시 실행해야 합니다.

2. Provider 구성

config/settings.yaml을 편집하여 LLM, Embedding, Vision LLM, VectorStore, Reranker 및 평가 백엔드를 구성합니다. API Key는 안전한 구성 주입을 통해 제공되어야 하며 저장소에 커밋해서는 안 됩니다.

로컬에 모델 서비스가 없는 경우, 필수가 아닌 LLM 강화 및 Rerank를 비활성화하여 외부 서비스에 의존하지 않는 기본 체인을 검증할 수 있습니다.

3. 문서 수집

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/simple.pdf \
  --collection admissions_knowledge

디렉터리 수집:

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/ \
  --collection admissions_knowledge

유학 비즈니스 Manifest를 사용한 수집:

python scripts/ingest.py \
  --path examples/documents/synthetic/ \
  --collection admissions_knowledge \
  --manifest examples/admissions_manifest.example.jsonl

Manifest는 UTF-8 JSONL을 사용하며 각 줄은 PDF 하나에 해당합니다. 상대 document_path는 Manifest가 있는 디렉터리를 기준으로 해석됩니다. 필수 필드는 document_path, title, country 및 source_type입니다. 선택 필드에는 institution, program, degree_level, intake, application_round, published_at, valid_until, language, tags 및 access_scope가 포함됩니다. 전체 예시는 examples/admissions_manifest.example.jsonl을 참조하세요.

Manifest를 전달하면 각 수집 대상 PDF는 고유한 일치 항목이 있어야 합니다. 알 수 없는 필드, 중복 경로, 잘못된 열거형 및 날짜 역전은 저장소에 쓰기 전에 실패합니다. Manifest 메타데이터는 Document에서 Chunk 및 Chroma 레코드로 전파됩니다. Chunk 수준의 LLM 제목과 태그는 document_title 및 business_tags를 덮어쓰지 않습니다.

증분 판단은 PDF SHA256과 정규화된 비즈니스 메타데이터 SHA256을 동시에 비교합니다. 둘 다 변경되지 않은 경우에만 건너뜁니다. Manifest만 수정하면 자동으로 재수집되어 안정적인 Chunk ID에 해당하는 메타데이터를 덮어씁니다. PDF 내용이 변경되면 시스템은 먼저 새 버전을 쓴 다음 이전 doc_hash를 기준으로 Chroma Chunk, 이미지 및 이전 수집 기록을 정리합니다. BM25는 안정적인 소스 경로 접두사로 postings를 교체합니다. 이전 버전의 SQLite 수집 기록에는 수동 마이그레이션 없이 metadata_hash 필드가 자동으로 추가됩니다. --force는 여전히 명시적 재구축에 사용할 수 있지만 Manifest 업데이트 적용에 더 이상 필수는 아닙니다.

저장소에는 완전히 가상이고 개인 정보가 없는 세 개의 비즈니스 샘플이 제공되며, 각각 현재 자료, 유효 기간 누락 및 만료 자료를 다루고, 과정 가이드에는 멀티모달 체인 검증을 위한 흐름도가 포함되어 있습니다. 샘플 PDF를 다시 생성해야 하는 경우 다음을 실행합니다:

python examples/generate_synthetic_admissions_pdfs.py

4. 명령줄 쿼리

python scripts/query.py \
  --query "申请材料需要包含哪些证明？" \
  --collection admissions_knowledge \
  --verbose

5. Dashboard 시작

python scripts/start_dashboard.py

기본 주소는 http://localhost:8501입니다.

6. MCP Server 시작

python -m src.mcp_server.server

MCP Client마다 구성 형식이 약간 다르며, 핵심 프로세스 구성은 다음과 같습니다:

{
  "command": "<project>/.venv/Scripts/python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project>"
}

macOS / Linux에서는 Python 경로를 <project>/.venv/bin/python으로 바꿉니다.

7. 평가 실행

python scripts/evaluate.py \
  --test-set examples/admissions_golden_test_set.json \
  --collection admissions_knowledge

외부 검색 환경이 없는 경우 다음을 실행할 수 있습니다:

python scripts/evaluate.py --no-search

품질 보증

프로젝트는 3계층 테스트 구조를 사용합니다:

• Unit: 데이터 계약, 알고리즘, Factory, Tool Handler 및 저장소 어댑터.

• Integration: 수집, 혼합 검색, MCP, Provider 및 Trace 조합 동작.

• E2E: CLI 수집, MCP Client, Dashboard smoke 및 Recall 회귀.

python -m pytest tests/unit
python -m pytest tests/integration
python -m pytest tests/e2e
python -m pytest

위 명령은 기본적으로 online으로 표시된 모든 테스트 케이스를 건너뛰며 실제 Provider를 호출하지 않습니다. 실제 Azure, OpenAI 또는 Ollama 서비스가 필요한 경우 해당 자격 증명과 서비스를 사용할 수 있는 환경에서 명시적으로 실행합니다:

python -m pytest --run-online -m online

OpenAI 호환 게이트웨이는 OPENAI_API_KEY, OPENAI_BASE_URL 및 OPENAI_MODEL을 통해 주입할 수 있으며 저장소 구성을 수정하거나 자격 증명을 커밋할 필요가 없습니다. 구성되지 않은 Provider 테스트 케이스는 건너뛴 상태를 유지해야 합니다.

온라인 테스트 케이스가 올바르게 분류되었는지만 확인하고 호출하지 않으려면 python -m pytest --collect-only -m online을 실행할 수 있습니다. 오프라인 및 온라인 결과는 별도로 기록해야 합니다. --run-online은 건너뛰기 제한만 해제하며 Provider 구성을 대체하지 않습니다.

평가 계층은 Custom Evaluator와 Ragas를 계속 지원합니다. 비즈니스 Golden Test Set은 조합 필터, 비즈니스 날짜, 만료 정책, 예상 출처 및 참조 답변을 추가로 기록합니다. 오프라인 비즈니스 승인은 이러한 필드와 MCP 비즈니스 어댑터의 시효 동작을 동시에 확인합니다. 범용 평가 인터페이스와 기존 Golden Test Set은 수정되지 않았습니다.

보안 및 운영 제약

• 기본적으로 로컬 Stdio 및 로컬 저장소를 사용하며 네트워크 포트를 열지 않습니다.

• 로그, Trace, 테스트 고정 데이터 또는 Git 기록에 API Key와 학생 개인 정보를 저장하지 않습니다.

• 비즈니스 자료는 지식 베이스에 들어가기 전에 권한 확인 및 개인정보 비식별화를 완료해야 합니다.

• 검색 결과는 출처 인용을 유지해야 하며, 신뢰할 수 있는 근거를 찾을 수 없는 경우 빈 결과를 반환하거나 수동 검증을 안내해야 합니다.

• 대학 요건은 시효성이 있습니다. 비즈니스 Tool은 기본적으로 valid_until이 지난 자료를 제외하고 유효 기간 누락 항목을 명시적으로 표시하지만, 컨설턴트는 여전히 공식 출처를 확인해야 합니다.

• 현재 아키텍처는 단일 사용자 로컬 서비스이며 인증, 권한 격리 또는 멀티테넌시 보장을 제공하지 않습니다.

현재 상태 및 발전 계획

기존 main은 완전한 범용 RAG, MCP, Dashboard, Trace 및 평가 골격을 갖추고 있습니다. 유학 분야 개편은 증분 방식으로 진행되며 기존 기술 역량을 삭제하거나 단순화할 수 없습니다.

모든 단계의 구현은 PDF 전체 체인 수집, Dense + BM25, RRF, Rerank, 멀티모달, 다중 저장소 협업, 증분 및 삭제, 기존 세 개의 MCP Tools, 6페이지 Dashboard, 이중 체인 Trace, Custom + Ragas, 3계층 테스트 및 모든 플러그 가능 인터페이스를 유지해야 합니다.