Qdrant RAG Build

대화를 통해 완전한 RAG 파이프라인을 구축하는 Qdrant MCP 서버입니다.

비공식, 커뮤니티 제작 — Qdrant와 제휴 관계가 아니며 Qdrant의 보증을 받지 않았습니다.

공식 Qdrant MCP 서버는 2개의 도구(qdrant-store, qdrant-find)를 노출합니다. Qdrant RAG Build는 6개 네임스페이스에 걸쳐 33개의 도구를 노출합니다 — MCP 대화를 통해서만 완전히 관리되는 프로덕션급 RAG 시스템 — 그리고 한 번의 대화로 사용자를 0부터 시작해 문서 없이도 작동하고 잘 구성된 RAG 컬렉션으로 이끄는 대화형 설정 마법사도 제공합니다.

한 줄 소개: "AI를 Qdrant에 연결하고 한 번의 대화로 프로덕션급 RAG를 가동하세요." 또 하나의 Qdrant 래퍼가 아닙니다 — MCP를 통한 RAG-in-a-box.

패키지: qdrant-rag-build-mcp · 라이선스: Apache-2.0 · 상태: 기획 완료, 구현 시작 전.

목차

1. 비전과 시장 공백

2. 확정된 결정

3. 아키텍처

4. 도구 카탈로그

5. 대화형 마법사

6. 수집 파이프라인

7. 고급 검색

8. 품질 및 평가

9. GitHub 권위

10. 개발 단계

11. 물려받은 교훈과 리스크

12. 이름, 라이선스, 첫걸음

Related MCP server: RAG Knowledge Base MCP Server

1. 비전과 시장 공백

명제: 오늘날 MCP를 통해 LLM을 Qdrant에 연결하면 장난감 수준의 시맨틱 메모리만 얻습니다. 컬렉션 관리도, 파일 수집도, 하이브리드 검색도, rerank도, 인용도, 안내 구성도 없습니다. 그런 것들은 모두 주문형 엔터프라이즈 RAG 시스템에 있지만, 누구도 이를 한 번의 명령으로 설치하는 MCP 서버로 패키징하지 못했습니다.

2. 확정된 결정

범위. 전체 검색(retrieval) + Qdrant 관리 + 일반적 형식(PDF, DOCX, Excel, PPTX, MD, HTML, CSV, URL)에 대한 매우 높은 품질의 수집. 깨끗하고 RAG에 최적화된 콘텐츠가 이 프로젝트의 시그니처입니다.

대상 클라이언트. v1은 전체 Claude 제품군, 즉 **Claude Code, Claude Desktop, claude.ai(웹)**입니다. Code와 Desktop는 stdio 방식이고, 로컬이며 거의 원클릭 설치입니다(§3). claude.ai는 프로토콜상 원격 HTTP가 반드시 필요합니다(브라우저는 로컬 프로세스를 실행할 수 없기 때문). 하지만 그것은 큰 작업이 아니라 약간의 추가일 뿐입니다. 공식 SDK는 이미 스트리밍 HTTP를 지원하며, v1에는 전체 OAuth 2.1(§3)이 아니라 브토큰과 공개 HTTPS URL에 연결하는 배포 가이드 하나만 필요합니다. ChatGPT는 v1 범위에서 제외합니다. claude.ai와 달리 ChatGPT는 개발자 모드(위험을 명시적으로 수락해야 하는 경우)와 유료 플랜이 필요하며 무료 티어가 전혀 없습니다 — "Claude 우선"에 부합하지 않는 마찰이므로 v2로 연기합니다.

프로젝트 목표. 뛰어난 오픈소스 도구: 포트폴리오의 중심이며 GitHub에서 권위를 인정받는 수단. 문서, CI, 개발자 경험(DX)의 품질은 선택 사항이 아닙니다 — 그것 자체가 제품입니다.

범위 제외(v1). PST/이메일 수집, 대량 OCR, NER/엔티티 추출, 서버 측 LLM 생성(클라이언트가 곧 LLM인 곳) 아닌), 맞춤 UI. 각각의 제외 사유는 §11에 있습니다.

3. 아키텍처

하나의 파이썬 실행 파일, 세 개의 명확한 계층. MCP 서버는 가벼운 파사드일 뿐이며, 모든 로직은 MCP 의존성이 없는 테스트 가능한 코어에 있습니다(따라서 향후 CLI나 SDK를 추가해도 계속 지지하지 않음).

flowchart LR
    subgraph Clients
      CC[Claude Code / Desktop<br/>stdio]
      WEB[claude.ai<br/>HTTPS + bearer token]
    end
    subgraph QRB["Qdrant RAG Build"]
      T[Transport<br/>stdio · streamable HTTP]
      F[MCP facade<br/>33 tools · validation]
      CORE[RAG core<br/>ingestion · retrieval · wizard]
      EMB[Embeddings<br/>local fastembed · external APIs]
    end
    Q[(Qdrant<br/>local · cloud)]
    CC --> T
    WEB --> T
    T --> F --> CORE
    CORE --> EMB
    CORE --> Q

기술 결정

마법사가 MCP elicitation이 아닌 상태 머신인 이유. Elicitation 지원은 MCP 클라이언트와 SDK 버전, 그리고 Claude 계열 내에서도 다릅니다. 일반적인 도구로 구동되는 단순한 상태 머신은 어디서나 동일하게 작동하며, 특별한 기능이 필요하지 않습니다. v2에서 다른 elicitation을 지원하는 클라이언트가 추가되어도 그대로 적용됩니다. 전송 범위와 무관하게 고정입니다.

v1 인증 결정. MCP에 대한 전체 OAuth 2.1(인가 서버, PKCE, 동적 클라이언트 등록/클라이언트 ID 메타데이터 문서, 발급자 검증, 리프레시 토큰)은 실제로 몇 주가 걸리는 엔지니어링 작업이며, v1 예산 마련 그 밖입니다 — 그리고 claude.ai의 자체 커넥터 설정은 OAuth를 필수가 아니라 선택적 고급 필드로 취급합니다. v1에는 프로필별 정적 Bearer Token을 사용합니다: 마법사가 생성하고, 프로필 YAML에 저장되며, Authorization: Bearer <token>으로 전송됩니다. stdio(Code, Desktop)는 인증이 전혀 필요하지 않습니다 — 로컬 프로세스이며 네트워크에 없기 때문입니다. 전체 OAuth 2.1은 문서화된 v2 업그레이드 항목으로 남아 있으며, 해당 생태계가 더 많이 사용되는 ChatGPT가 (개발 모드와 유료 플랜이 요구되면서) 범위에 포함될 때 재검토합니다.

배포 모델: 사용자 1명, 서버 1대

MCP는 추상적인 "AI"에 서버를 연결하는 것이 아니라, 모델을 호스팅하는 클라이언트 어플리케이션(Claude Desktop, Claude Code, claude.ai)에 연결합니다. 연결을 유지하고, 모델에게 사용 가능한 도구 목록을 전달하며, 모델의 도구 호출 결정을 가로채서 서버에 대해 실행하는 것은 바로 그 클라이언트입니다. 최종 사용자에게는 "Claude와 대화하는데 내 Qdrant를 관리한다"고 읽히며 — 무리한 단순화는 맞습니다 — 실제로 서버에 연결된 것은 모델이 아니라 클라이언트입니다.

v1 범위에는 공유/멀티테넌시 서버가 없습니다. 각 사용자가 자신의 서버를 실행하며, 동일한 로컬 프로세스가 세 가지 v1 클라이언트를 모두 지원합니다:

• Claude Code / Claude Desktop: 서버는 사용자 자신의 기기에서 로컬 stdio 하위 프로세스로 실행되며, 클라이언트가 자체 설정에서 시작합니다. 허용된 디렉터리로 범위가 제한된 실제 파일시스템 액세스 — 표준 MCP stdio 동작이며 이 프로젝트가 새로 만들 부분이 전혀 없습니다.

• claude.ai: 동일한 로컬 프로세스를 터널(cloudflared)의 HTTPS를 통해 노출하거나, 같은 Docker 이미지를 실행하는 소형 상시 가동 호스트($5 VPS, Fly.io, Railway)를 통해 노출합니다 — 별도의 클라우드 배포나 공유 서버가 아닙니다. 사용자 자신의 터널링 머신이라면 파일시스템 액세스는 로컬 경우와 완전히 동일합니다. 단지 도달하는 전송 방식만 다를 뿐입니다. Free(커넥터 1개)를 포함한 모든 claude.ai 플랜에서 사용 가능합니다.

• 결론: /dev/null이 아니라 ingest_directory / ingest_file은 사용자 자신의 서버(그리고 claude.ai의 경우 터널)가 실행 중인 한 세 클라이언트 모두에서 동일하게 동작합니다. 어디서도 파일 업로드 장치가 필요하지 않습니다. 설계상 서버는 항상 직접 디스크에 접근할 수 있기 때문입니다.

• 설치는 한 번만 합니다:

  • Claude Desktop: .mcpb 파일 하나를 Settings → Extensions로 끌어다 놓습니다. 터미널은 전혀 필요 없습니다.

  • Claude Code: claude mcp add qdrant-rag-build -- uvx qdrant-rag-build-mcp. 한 줄이면 됩니다.

  • claude.ai: Settings → Connectors → Add에서 서버의 HTTPS URL과 bearer 토큰을 붙여넣습니다. 서버(노트북 레시피를 쓴다면 터널)가 이미 실행 중이어야 합니다 — 프로토콜상 필요한 것이며, 이 프로젝트가 선택한 것이 아닙니다. 모든 원격 MCP 커넥터와 동일합니다.

  • 이후에는 위저드가 RAG 설정을 완전히 대화형으로 만듭니다 — 컬렉션 생성, 임베딩 선택, 문서 수집, 검색 — 세 클라이언트 어디서든 추가 기술적 단계 없이 가능합니다.

v2: ChatGPT(의도적으로 아직 범위 밖)

ChatGPT는 claude.ai와 동일한 원격 HTTP 방식이 필요합니다. 기술적으로 새로운 것은 없습니다. v1에서 제외되는 이유는 ChatGPT 자체와 관련된 특수한 제약입니다: Developer Mode를 명시적으로 활성화해야 하며(타사 코드 실행에 대한 경고 문구가 표시됨), 사용자 지정 커넥터는 **유료 플랜(Plus/Pro/Business/Enterprise/Edu)**이 필요합니다. claude.ai가 무료 티어에 커넥터를 포함하는 것과 달리 ChatGPT Free 경로는 전혀 없습니다. 그 어느 것도 "Claude 우선"이라는 원칙에 맞지 않습니다. v2는 ChatGPT 전용 커넥터 가이드를 추가하고, 필요 시 완전한 OAuth 2.1을 재검토합니다(ChatGPT 생태계는 claude.ai보다 더 그쪽을 선호합니다).

4. 도구 목록

프로젝트의 핵심입니다. 여섯 개의 네임스페이스, 예측 가능한 이름, LLM을 위해 작성된 설명(도구가 무엇을 하는지뿐 아니라 언제 사용해야 하는지). 모든 파괴적 도구는 명시적 확인을 요구하며, 전역 read-only 모드가 있습니다.

Collections

Ingestion

Search

RAG context

Wizard

Admin

5. 대화형 위저드

차별화 요소입니다. 서버 내부의 state machine: 모든 도구 호출은 다음 질문을 옵션과 근거 있는 추천과 함께 돌려줍니다. 클라이언트 LLM이 그 질문을 자연스럽게 사용자에게 전달하고 답변을 넘겨받습니다. 대화를 유도하지도 않고 특정 클라이언트에 의존하지도 않습니다 — 대화 자체가 인터페이스입니다.

stateDiagram-v2
    direction LR
    [*] --> Discover
    Discover --> Validate : setup_answer
    Validate --> Discover : next question
    Validate --> Summary : all answered
    Summary --> Apply : user confirms
    Apply --> SmokeTest
    SmokeTest --> [*] : report + saved profile

질문 스크립트 (고정 순서, 모든 단계에서 추천)

위저드 성공 정의. Qdrant라는 말조차 처음 듣는 사용자가 10분 미만 대화 끝에, 잘 스키마된 컬렉션, 정상 동작하는 임베딩, 저장된 프로필, 예시 문서 1회 수집, 그리고 인용된 결과를 돌려주는 테스트 검색까지 갖추는 것. 스모크 테스트의 최종 보고서가 증명이고 — 그 대화의 녹화는 README의 커버입니다.

6. Ingenstion 파이프라인

품질의 증거: 깨끗하고 RAG에 최적화된 내용을 형식별로 만들어 내고, 모든 수집에 품질 보고서를 붙입니다. "파서가 뱉어낸 것을 그대로 담는" 일은 결코 없앤니다.

공통 규칙

• 구조 우선, 토큰 다음. 문서 구조(절, 시트, 슬라이드)를 먼저 기준으로 자르고, 한 단위가 토큰 예산을 넘을 때만 겹침을 허용하면서 다시 나눈다. 모든 청크에는 "사용 설명서 › 3장 › 설치" 같은 브레드크럼을 남긴다.

• 내용 해시로 중복 제거를 청크 수준에서 적용하고, 문서별 멱등성도 보장한다. 파일을 다시 수집하면 업데이트되며 중복 생성되지 않는다.

• 최소한이며 버전이 있는 인용 계약. 인용 페이로드(문서, 쪽/절, 날짜, 출처)는 닫힌 필드 집합이다. 내부 파이프라인 메타데이터는 LLM 컨텍스트에 절대 전달되지 않는다. 이 프로젝트 전신에서 메타데이터가 실제 소스를 잘라서 피해가 생긴 버그를 두 번 경험했다(§11).

• 수집 결과는 항상 보고한다. 생성된 청크 수, 품질 문제로 폐기한 페이지와 그 사유, 감지된 중복까지 표시한다. 투명성은 품질의 일부다.

• 임베딩 전 텍스트 정제(서브로게이트, 제어 문자, 깨진 인코딩)를 한 후 수행한다. 실전 PST 파일에서 고생해서 알게 된 점이다.

7. 고급 검색

• 기본은 하이브리드 검색: 밀집(다국어 임베딩) + 희소(BM25/miniCOIL) 결합이며, Qdrant Query API(프리페치 + 퓨전)의 네이티브 RRF 퓨전을 사용한다 — 추가 인프라 불허.

• 선택 재랭크: 상위 50개 → 상위 N개에 크로스 인코더 적용. 로컬 fastembed 옵션 또는 API(Cohere, llama.cpp의 /v1/rerank) 옵션.

• 다양성용 MMR은 Qdrant가 이미 반환한 벡터 그대로 재사용합니다(with_vectors=true). 검색 중 다시 임베딩하면 안 됩니다. 이 실수로 이전 프로젝트에서 실제 운영 OOM이 났었다.

• 일류 페이로드 필터: 날짜(경계가 명확하고 lte에서 종료일 포함), 출처, 유형, 작성자 — 위 재주 던지는 위저드가 생성한 인덱스를 대상으로 지원한다.

• get_context 도구가 핵심: 하이브리드 검색 → 재랭킹 → MMR → 토큰 예산 → 번호 매겨진 인용 [1][2] 형식 블록을 조합한다. 핵심에 사용된 항목만 인용할 수 있다. 기준: 실제 컨텍스트에 들어간 내용만 인용하고, 이적 출처/허상 인용은 하지 않는다.

• 생성은 클라이언트에 있다. 서버는 LLM을 호출하지 않는다. 서버는 최상의 컨텍스트만 제공하고, 사용자 모델(Claude, GPT)이 답변을 쓴다. 이로써 서버는 저렴하고 빠르고, 필수 제3자 API 키가 없다.

8. 품질과 평가

• 저장소에 골든 코퍼스 포함: 다양한 문서 15–20종(PDF 표, 실제 스프레드시트, 화질 낮은 웹 페이지) + 약 50문제와 NaN이라는 관련 청크 주석이 달려 있다.

• CI에서 검색 지표 실행: 골든 코퍼스 기반 recall@k, MRR, nDCG를 기준으로 회귀시 빌드가 실패하도록 임계값을 설정한다. 밀도/하이브리드/하이브리드+재랭킹 비교를 문서에 공개 — 이 숫자가 프로젝트를 보여준다.

• 계층 테스트: Qdrant가 필요 없이 코어 테스트, 컨테이너(testcontainers)의 Qdrant 통합 테스트, SDK 테스트 클라이언트를 사용한 MCP 프로토콜 장면 e2e 테스트. 형식을 위한 강성 테스트 파일(스캔 PDF, 병합 셀 Excel, 잘못된 HTML) 존재.

• 각 릴리스마다 호환성 매트릭스 확인: Claude Code/Claude Desktop/claude.ai를 스크린샷으로 문서화 v2에는 ChatGPT 추가.

9. GitHub 신뢰성

포트폴리오 목표에서 저장소는 코드만큼이나 제품 그 자체다. 출시 체크리스트:

• 설득력 있는 README: 한 번의 대화에서 위저드가 RAG를 만드는 데모 녹화(vhs/asciinema), 3줄짜리 uvx 퀵스타트, 배지(CI, 커버리지, PyPI, 라이선스), 공식 MCP와의 비교 표, 벤치마크 공개.

• 랜딩 페이지: README나 문서 사이트와 분리된 전용 정적 페이지 — 히어로, 공식 Qdrant MCP와 비교 표, 위저드 데모 영상, 세 가지 v1 클라이언트용 설치 CTA, F5의 벤치마크 수치. 이것이 론칭 포스트와 소셜 링크의 표현 대상이다.

• 문서화: mkdocs-material 기반 사이트. 각 클라이언트용 가이드(Claude Code, Claude Desktop, claude.ai — bearer-token 커넥터 절차 포함), 쿡북("자체 문서 위에서 RAG", "팀 메모리"), 총 33개 도구 전체 레퍼런스, 공개 ADR 포함.

• 미세보기 엔지니어링: CI에 ruff + mypy strict + pytest + coverage, release-please 자동 시맨틱 버전, CHANGELOG, issue/PR 템플릿, CONTRIBUTING, 행동 강 Lower, GitHub Discussions 활성화.

• 배포와 출시: PyPI + Claude Desktop .mcpb 번들 + Docker 이미지 + compose 스택(Qdrant 포함). 공식 MCP 레지스트리, Smithery, Glama, PulseMCP, awesome-mcp-servers에 등록. 출시: 기술 포스트 + Show HN + r/LocalLLaMA + X, 위저드 시연 영상이 도입부 역할.

10. 개발 단계

사이드 프로젝트 페이스(저녁/주말). 모든 단계는 데모 가능한 결과로 끝난다. 단계를 동시에 벌이지 않는다.

총 기간: 약 14.5주(약 3.5개월), 현실적인 사이드 플젝트 페이스를 유지하면서 2주마다 시연 가능한 마(estones)로 전진해나간다.

5. 물론교훈과 리스크

숨겨진 강점: 이 계획은 테라급 프로덕션 RAG를 다뤄 이미 *비용 지불에 오류들을 그대로 상속한다. 고치는 것이 아니라 처음부터 설계에 담았다.

공개된 잔여 위험

12. 이름, 라이선스, 첫 구체적 단계

이름: Qdrant RAG Build (패키지 qdrant-rag-build-mcp) — 새로운 브랜드를 만들지 않고 이 리포지토리의 기존 작업 이름을 유지하려고 선택한 이름입니다. 이름느 두 차례의 선정 라운드를 거쳤습니다: Quiver는 관련 없는 "Quiver Quantitative" MCP 네임스페이스(bolshchikov/quiver-mcp, pipeworx-io/mcp-quiver, jsconiers/quiver-quant-mcp)와 충돌하여 제외되었고, Vectorsmith는 중복 검사를 통과했으나 리포지토리와 연결되는 이름을 유지하자는 명확한 요구에 따라 제외되었습니다. 원래 계획에서 지적했던 트레이드오프 — "qdrant" 접두사가 붙은 이름이 공식 Qdrant 프로젝트처럼 보일 수 있다는 점 — 를 받아들이며, README 태그라인과 문서 사이트에 "비공식, 커뮤니티 제작"임을 분명하게 밝혀 완화합니다. 문자 그대로의 slug인 qdrant-rag-mcp는 이미 활성화된 다른 프로젝트(ancoleman/qdrant-rag-mcp)가 사용 중이고, qdrant-rag-build / qdrant-mcp-rag-build는 PyPI와 GitHub에서 중복 없음을 확인했습니다(2026년 8월).

라이선스: Apache-2.0 — Qdrant와 동일하며, 특허 포기를 포함하고, 기업들이 여러분의 프로필을 읽을 때 기대하는 라이선스입니다.

첫 번째 구체적 단계: F0은 서버 코드를 단 일의 줄을 짯도 전에 33개 도구 전체의 JSON 스키마를 작성하는 것에서 시작합니다. §4의 카탈로그가 스펙사양이며, 먼저 그 스펙을 확정함으로써 중간에 설계를 얼지 않게 되고, 1주차부터 공개 가능한 설계 문서를 만들 수 있습니다.

참고 문헌: qdrant/mcp-server-qdrant (공식 서버, 도구 두 가지) · fastembed PR #602 (bge-m3 지원, 오픈 상태) · MCP Bundles(.mcpb) 툴킷 · 원격 MCP 커스텀 커넥터(claude.ai) · v2 권장 자료: ChatGPT Developer Mode, OpenAI의 MCP 및 커넥터

플랜 v1.3 · 2026-08-24 확정 고정 · v1은 전체 Claude 제품군(Code, Desktop, claude.ai — stdio + bearer-token HTTP)을 대상으로 하며, ChatGPT는 별도의 Developer Mode/유료 플랜 제약 때문에 v2에만 적용됩니다(claude.ai와 공유되는 기술 제약이 아닙니다). IA_EmailsContext 엔터프라이즈 RAG 프로젝트에서 얻은 경험을 참고하여 작성했습니다.