Qdrant RAG Build

El servidor MCP de Qdrant que construye un pipeline RAG completo mediante conversación.

No oficial, creado por la comunidad: no está afiliado a Qdrant ni cuenta con su respaldo.

El servidor MCP oficial de Qdrant expone 2 herramientas (qdrant-store, qdrant-find). Qdrant RAG Build expone 33 herramientas en 6 espacios de nombres — un sistema RAG de nivel de producción gestionado por completo a través de una conversación MCP — además de un asistente de configuración conversacional que lleva al usuario de cero a una colección RAG operativa y bien configurada en un solo chat, sin necesidad de documentación.

Elevator pitch: «Conecta tu IA a Qdrant y ten un RAG de nivel de producción funcionando en una conversación». No es otro envoltorio de Qdrant — RAG-in-a-box vía MCP.

Paquete: qdrant-rag-build-mcp · Licencia: Apache-2.0 · Estado: planificación completada, implementación no iniciada.

Índice

1. Visión y brecha de mercado

2. Decisiones cerradas

3. Arquitectura

4. Catálogo de herramientas

5. El asistente conversacional

6. Pipeline de ingesta

7. Recuperación de élite

8. Calidad y evaluaciones

9. Autoridad en GitHub

10. Fases de desarrollo

11. Lecciones heredadas y riesgos

12. Nombre, licencia y primer paso

Related MCP server: RAG Knowledge Base MCP Server

1. Visión y brecha de mercado

Tesis: hoy en día, conectar un LLM a Qdrant mediante MCP te da una memoria semántica de juguete. No hay gestión de colecciones, ni ingesta de archivos, ni búsqueda híbrida, ni rerank, ni citas, ni configuración guiada. Todo eso existe en sistemas RAG empresariales hechos a medida — nadie lo ha empaquetado como un servidor MCP que se instala con un comando.

2. Decisiones cerradas

Alcance. Recuperación completa + gestión de Qdrant + ingesta de muy alta calidad de formatos comunes (PDF, DOCX, Excel, PPTX, MD, HTML, CSV, TXT, URL). Un contenido limpio y óptimo para RAG es la seña de identidad del proyecto.

Clientes objetivo. v1 es toda la familia Claude: Claude Code, Claude Desktop y claude.ai (web). Code y Desktop son stdio, locales y están muy cerca de una instalación en un clic (§3). claude.ai necesita HTTP remoto por necesidad del protocolo (un navegador no puede lanzar un proceso local), pero eso es una adición modesta, no una categoría nueva de trabajo: el SDK oficial ya habla HTTP transmitable por secuencias, y v1 solo necesita un token de portador, no un OAuth 2.1 completo (§3), además de una guía de despliegue para alcanzar una URL HTTPS pública. ChatGPT queda fuera de v1. A diferencia de claude.ai requiere Developer Mode (una advertencia de riesgo explícita que hay que aceptar) y un plan de pago, sin ningún nivel gratuito — una fricción que no sirve a «priorizar Claude», así que se pospone a v2.

Objetivo del proyecto. Una herramienta de código abierto sobresaliente: pieza central del portafolio y motor de autoridad en GitHub. La documentación, la CI y la calidad del DX no son opcionales: son el producto.

Fuera del alcance (v1). Ingesta de PST/correos electrónicos, OCR avanzado, extracción de entidades / NER, generación LLM en el servidor (el cliente es el LLM) y una interfaz de usuario a medida. Cada exclusión se justifica en §11.

3. Arquitectura

Un solo binario de Python, tres capas limpias. El servidor MCP es una fachada fina; toda la feature domain gold matrices está lógica reside en un núcleo Testable sin dependencia de MCP (lo que también habilita una futura CLI o SDK sin tocar nada).

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

Decisiones técnicas

Por qué el asistente es una máquina de estados, no elicitación MCP. El soporte de elicitación varía según clientes MCP y versiones del SDK, incluso no dentro de la familia Claude. Una máquina de estados programada con herramientas normales funciona idéntico en todas partes, no requiere que ninguna capacidad esté en el protocolo y no cambia si v2 añade clientes con otro soporte de elicitación. Decisión fijada sea cual sea el transporte.

Decisión de autenticación para v1. Un OAuth de Ropsearse y privilegios. El OAuth 2.1 completo para MCP (servidor de autorización, PKCE, Dynamic Client Registration / Client ID Metadata Documents, validación del emisor, amortización de tokens refresh) es un trabajo de ingeniería real de muchas semanas sin presupuesto imperial but no; y la propia configuración del conector de claude.ai trata el OAuth mint como un campo avanzado opcional, no de un requisito. v1 implementa un token de portador estático por perfil para la ruta HTTP: cargado por el asistente, guardado en el perfil YAML y enviado como Authorization: Bearer <token>. La ruta stdio (Code, Desktop) no necesita autenticación en absoluto: es la hidna línea de la death orb full of bereques un proceso local sin exposición a la red. El OAuth 2.1 completo sigue siendo una mejora documentada para v2, que se recula si/whatever ChatGPT (siempre que echorea renovación) entra en alcance.

Modelo de despliegue: un usuario, un servidor

MCP no conecta un servidor "a la IA" en abstracto: se conecta a la aplicación cliente que aloja el modelo (Claude Desktop, Claude Code, claude.ai). Ese cliente es el que mantiene viva la conexión, entrega al modelo la lista de herramientas disponibles, intercepta las decisiones de llamada a herramientas del modelo y las ejecuta contra el servidor. Para el usuario final, esto se lee como "estoy hablando con Claude y anda administrando mi Qdrant" — una simplificación razonable — pero el cliente, no el modelo, es lo que realmente está conectado al servidor.

No hay un servidor compartido/multi-tenant en el alcance de v1. Cada usuario ejecuta su propio servidor, y el mismo proceso local atiende a los tres clientes de v1:

• Claude Code / Claude Desktop: el servidor se ejecuta como un proceso hijo local de tipo stdio en la propia máquina del usuario, lanzado por el cliente desde su configuración. Acceso real al sistema de archivos, limitado a directorios de la lista de permitidos: comportamiento estándar de MCP por stdio, no hay nada que este proyecto tenga que construir.

• claude.ai: el mismo proceso local, expuesto por HTTPS mediante un túnel (cloudflared) o un pequeño host siempre activo (una VPS de 5 $, Fly.io, Railway) que ejecuta la misma imagen de Docker — no es un despliegue en la nube aparte ni un servidor compartido. El acceso al sistema de archivos es idéntico al del caso local cuando se trata de la propia máquina tunelizada del usuario; solo cambia el transporte por el que se llega a él. Está disponible en todos los planes de Claude.ai, incluido Free (un conector).

• Consecuencia: ingest_directory / ingest_file se comportan igual en los tres clientes, siempre que el servidor del usuario (y, para claude.ai, el túnel) esté en marcha. No hace falta ningún mecanismo de subida de archivos en ningún caso: el servidor siempre tiene acceso directo al disco por construcción.

• Instalarlo, una sola vez:

  • Claude Desktop: arrastra un archivo .mcpb a Settings → Extensions. Cero terminal.

  • Claude Code: claude mcp add qdrant-rag-build -- uvx qdrant-rag-build-mcp. Una línea.

  • claude.ai: Settings → Connectors → Add, pega la URL HTTPS del servidor y el token de usuario. Tiene que estar ya en marcha el servidor (y el túnel, si se usa el método del portátil) — igual que con cualquier conector MCP remoto, por necesidad del protocolo, no por una decisión de este proyecto.

  • A partir de ahí, el asistente hace que configurar el RAG sea totalmente conversacional — crear colecciones, elegir embeddings, ingerir documentos, buscar — sin más pasos técnicos, en cualquiera de los tres.

v2: ChatGPT (deliberadamente fuera todavía)

ChatGPT necesita la misma forma de HTTP remoto que claude.ai — no hay nada nuevo ahí en lo técnico. Lo que lo mantiene fuera de v1 es la fricción específica de ChatGPT: hay que habilitar explícitamente el modo de desarrollador (con un aviso sobre ejecutar código de terceros), y los conectores personalizados exigen un plan de pago (Plus/Pro/Business/Enterprise/Edu) — no hay ninguna ruta gratuita de ChatGPT, a diferencia de los conectores de claude.ai que incluyen el nivel gratuito. Nada de eso sirve a "priorizar Claude". v2 añade una guía de conectores específica para ChatGPT y, si resulta relevante, revisa un OAuth 2.1 completamente desarrollado (el ecosistema de ChatGPT depende más de él que el de Claude).

4. Catálogo de herramientas

El corazón del proyecto. Seis espacios de nombres, nombres predecibles, descripciones escritas para el LLM (cuando, how to use a tool, not just what it does). Every destructive tool requires explicit confirmation, and there is a global read-only mode.

Colecciones

Ingesta

Búsqueda

Contexto RAG

Asistente

Administración

5. El asistente conversacional

El factor diferenciador. Una máquina de estados en el servidor: cada llamada a una herramienta devuelve la siguiente pregunta con sus opciones y una recomendación razonada; el LLM del cliente lo transmite al usuario de forma natural y le pasa la respuesta. No hace falta avisar, no depende de ningún cliente específico: la conversación es la interfaz.

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

Guion de preguntas (orden fijo, recomendación en cada paso)

Definición de éxito del asistente. Un usuario que no ha visto Qdrant, en una conversación de menos de 10 minutos, termina con: una colección bien esquematizada, embeddings funcionando, un perfil guardado, un documento de ejemplo introducido y una búsqueda de prueba con resultados citados. El informe final del smoke test es la prueba — y una grabación de esta conversación es la portada del README.

6. Pipeline de ingesta

La firma de calidad: contenido limpio y óptimo para RAG, según el formato, con un informe de calidad en cada ingesta. Nunca "vuelca lo que suelte el analizador".

Reglas transversales

• La estructura primero, los tokens después. Primer parseo (sección, hoja, diapositiva) y solo cuando una unidad excede el presupuesto de tokens, se subdivide (con solapamiento). Cada fragmento arrivastra un breadcrumb ("Manual › Capítulo 3 › Instalación").

• Desduplicación por hash de contención normalizado a nivel de Fragmento, además de idempotencia por documento: re-ingestir un archivo lo actualiza, nunca lo duplica.

• Contrato de citas mínimo y versionado. La carga de citas (documento, página/sección, fecha, fuente) es un conjunto de campos cerrado. Los metadatos internos del pipeline nunca alcanzan el contexto del LLM — este proyecto ha pagado dos veces el bug en que el exceso de metadatos truncaba las fuentes reales (§11).

• Informar siempre de los resultados de la ingesta. Fragmentos sinado, páginas desechadas y motivos, duplicados detestados. La transparencia parte de la calidad.

• Saneamiento del texto (caracteres de control, sustituciones, codificaciones corruptes) antes de embed: esto lo aprendimos a la fuerza con archivos PST reales.

7. Recuperación élite

• Hitable from sectories: denso (embeddings multilingües) + disperso (BM25/miniCOIL) con fusión RRF nativa usando la API de consulta de Qdrant (avance + fusion) — sin infraestructura extra.

• Revisión opcional con un cross-encoder sobre el top-50 → top-N. Local con fastembed, o API (Cohere, /v1/rerank de llama.cpp).

• MMR para diversidad, reutilizando los vectores que Qdrant ya devvuelve (with_vectors=true). Al recuperar, nunca vuelvas a embeber — ese error causó una realufactura de memoria en producción en el precedent de este proyecto.

• Filtros de payload de primera clase: fecha (rangos bien delimitados, fino de día inclusivo en lte), fuente, tipo, autor — sobre los índices creados por el asistente.

• **get_context como herramienta por excelencia:**orquesta híbrido → revisión → MMR → presupuesto en tokens → bloque formateado, con [1]["Citations]. Guarantía dura: solo lo que realmente resolvió en el contexto se cita — nunca fuentes fantasma.

• La generación queda en el cliente. El servidor nunca llama a un LLM: entrega el mejor contexto posible y el propio del usuario (Claude, GPT) escribe la respuesta. Esto mantienen al servidor barato 、al vlozz, requiere constante, y sin clave de API de terceros forzosos.

8. Calidad y evaluación

• Corpus aureum in el repositório: 15 a 20 documentos livianos (PDF con tablas, una hoja de cálculo real, una página web ruidosa) + ~50 preguntas con anotaciones de fragmentos relevantes.

• Méicas de búsqueda en CI: recall@k, MRR y nDCG over el corpus aureum, con umbrales que rompen la build y unbor regression. Denso vs. híbrido vs. híbrido+reclasificado, publicado en la documentación — sono los números que vendo proyecto.

• Testes en capas: unit tests for the core (sin dependencia de Qdrant), integración against Qdrant in docker (testcontainers), and e2e for MCP with the SDK's test client. Torture files for each type (scorn: scanned PDF, Excel matrix con celdas fusionadas, HTML malformed).

• Matriz de compatibilidad verifiable por release: Claude Code, Claude Desktop y claude.ai, documentada con captures. In v2, ChatGPT also joins this matrix.

9. GitHub authority

For the portfolio goal, the repository is the product as much as the code. Launch checklist:

• A README that converts: a recording of the wizard building a RAG in one real conversation (vhs/asciinema), a uvx quickstart en 3 lines, a POS (CI/coverage/PyPI/licens), a comparison table against the official MCP, and released benchmarks.

• **A landing page.**a very well-dedicated, beautiful static page — separate from the README and the docs — with hero, comparison table against the official Qdrant MCP, demo record of the assistant, install CTAs for all three v1 clients, and F5's real metrics. The launch post and social links point to this.

• Documentation. An mkdocs-material site: a guide per client (Claude Code, Claude Desktop, claude.ai, with the whirlwind tour of the bearer-token connector), a Cook Book ("RAG over alexandria," "memory for the team"), a complete reference for all the 33 tools, public ADRs.

• Visible engineering. CI with ruff + mypy strict + pytest + coverage, automated semver releases (release-please), CHANCELOG, issue/template for PR, CONTRIBUTING, Code of Conduct, and GitHub Discussions toggled on.

• Distribution & launch. PyPI + Claude Desktop .mcpb bundle + single + docker-compose with Qdrant included. Exists in the official MCP registry, Smithery, Glama, PulseMCP y awesome-mcp-servers. Launch: technical overview + Show HN + r/LocalLLaMA (on X), with the wizard recording as hook.

10. Fases de desenvolvimento

Side-project pace (evening/weekends). Each phase end with something demonstrable — never two phases open at the same time.

| Phases | Focus | Defl | State | Done (Definition of done) | | ------- | ------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | F0 | Spec and skeleton | ~weeks | Repositorio + CI + package structure. JSON schemas of 33 tools frozen and reviewed (design all 33 from the outset, even if implemented later). ADRs for §3 decisions. uvx qdrant-rag-build-mcp starts, health responds from Claude Code (stdio) and from claude.ai (HTTP via tunnel). | | F1 | Qdrant core | ~2 weeks | Full collections namespace, ingest_text, search dense, config profiles, read-only mode. E2E demo at Claude Code: create a collection, save notes, search them. Already a superset of the official MCP. | | F2 | Professional ingestion | ~3 weeks | All 8 formats with their quality treatment, structural chunking, dedup, jobs with progress, ingestion reports. A mixed folder of 100 real documents ingested cleanly and with a honest report (reconciled counters) and idempotent re-ingestion. | | F3 | Perfect search | ~2 weeks | Hybrid RRF, rerank, MMR, filters, get_context and the UK citation contract. Golden-corpus evaluation shows blue+rerank > dense, zero phantom sources in references. | | F4 | Asistente Wizard | ~2 weeks | State machine, live validation of each response, setup_apply with smoke test, multiple profiles. An external tester builds their own RAG in less than 10 min. only by conversation, without ever opening docs. Record the demo at this point. | | F5 | Quality and observability | ~1,5 weeks | Eval suite in CI with thresholds, stats/estimate, snapshots, verified client compatibility matrix. CI green with blocking evals; in the docs, both HTMLs can be found. | | F6 | Launch | ~2,5 weeks | Complete docs, polished landing page, README with video demo, PyPI + .mcpd bundle + Docker image, MCP registries, launch post. Install with one command (or drag-and-drop) in all three v1 environments; registration in ≥4 catalogs; Show HN uploaded and submitted. |

Total: ~14.5 weeks (~3.5 months): a realistic deadline for side projects, with demonstrable milestones every 2 weeks to keep momentum.

11. Inherited lessons and risks

The double competitive advantage: this plan inherits paid errors from a real corporate RAG system handling terabytes. Each lesson is baked into the architecture from day one, not patched after.

Open risks

12. Nombre, licencia y primer paso

Nombre: Qdrant RAG Build (paquete qdrant-rag-build-mcp) — elegido para mantenerse cerca del nombre de trabajo de este propio repositorio en lugar de una marca inventada. La nomenclatura pasó por dos etapas previas: Quiver se descartó por colisionar con el espacio de nombres MCP de la no relacionada «Quiver Quantitative» (bolshchikov/quiver-mcp, pipeworx-io/mcp-quiver, jsconiers/quiver-quant-mcp); Vectorsmith se verificó que estaba libre, pero fue descartado por la preferencia explícita de mantener el nombre reconocible respecto al repositorio. Eso supone aceptar el equilibrio que el plan original ya había señalado — un nombre con prefijo «qdrant» puede leerse como proyecto oficial de Qdrant — mitigado al declarar «no oficial, construido por la comunidad» claramente en el titular del README de la documentación. El slug literal qdrant-rag-mcp ya es un proyecto activo no relacionado (ancoleman/qdrant-rag-mcp) y se evitó deliberadamente; qdrant-rag-build / qdrant-mcp-rag-build están verificados como libres en PyPI y GitHub (agosto de 2026).

Licencia: Apache-2.0 — la misma que Qdrant, con una patente, la licencia que las empresas que lean tu perfil esperan ver.

Primer paso concreto: F0 comienza escribiendo los esquemas JSON de las 33 herramientas antes de una sola línea de código de servidor. El catálogo de §4 es la especificación; fijarlo primero evita rediseños a mitad de camino y produce un documento de diseño publicable desde la primera semana.

Referencias: qdrant/mcp-server-qdrant (servidor oficial, 2 herramientas) · fastembed PR #602 (soporte de bge-m3, abierta) · kit de herramientas MCP Bundles (.mcpb) · conectores personalizados que usan MCP remoto (claude.ai) · lectura para v2: ChatGPT Developer Mode, MCP y conectores en OpenAI

Plan v1.3 · fijado el 2026-08-24 · v1 cubre la familia completa de Claude (Code de escritorio, Desktop, claude.ai — stdio + HTTP con token de portador); ChatGPT se difiera expresamente a v2 por la fricción de su propia Developer/plan de pago, no de una limitación técnica compartida con claude.ai. Redactado tomando como referencia las lecciones aprendidas del proyecto de RAG empresarial IA_EDA.