🔌 MCP Docs Assistant

Pipeline de generación aumentada por recuperación (RAG) de nivel de producción sobre la documentación oficial de Model Context Protocol — servido a través de REST, herramientas MCP y Docker.

Haz preguntas en lenguaje natural sobre MCP (arquitectura, creación de servidores/clientes, herramientas/recursos/prompts, seguridad) y obtén respuestas fundamentadas en la documentación real, con guardrails, enmascaramiento de PII, reranking, caché semántico y detección de alucinaciones integrados.

✨ Características

Related MCP server: FusionPact MCP Server

🏗️ Arquitectura

flowchart TD
    A[User Question] --> B[Guard Input<br/>NeMo Guardrails]
    B -->|blocked| Z[Refusal message]
    B -->|allowed| C[Mask Input PII<br/>Presidio]
    C --> D[Condense Follow-up<br/>into standalone question]
    D --> E{Semantic<br/>Cache Hit?}
    E -->|yes| F[Return cached answer]
    E -->|no| G[Retrieve Top-15<br/>Qdrant Vector Store]
    G --> H[Rerank Top-5<br/>Cross-Encoder]
    H --> I[Fit to Token Budget]
    I --> J[Generate Answer<br/>Portkey: Gemini / Groq]
    J --> K[Guard Output<br/>leak / PII pattern check]
    K --> L[Hallucination Check<br/>LLM-as-judge]
    L --> M[Mask Output PII]
    M --> N[Cache + Store History]
    N --> O[Return Answer]

Cada nodo anterior es un módulo de rag_pipeline/, conectado como un StateGraph de LangGraph en rag_pipeline/graph.py. rag_core.py construye todas las dependencias una sola vez (como singleton) y expone una API pequeña y estable — chat(), search(), get_history(), cache_stats() — consumida por igual por la capa REST (main.py) y la capa MCP (mcp_server.py), de modo que se comparte un único almacén vectorial / caché / historial de conversación, sin importar la interfaz por la que llegue.

📁 Estructura del proyecto

mcp-docs-rag-assistant/
├── main.py                    # FastAPI app — REST endpoints + mounts MCP at /mcp
├── mcp_server.py               # MCP tools (stdio standalone, or mounted in main.py)
├── rag_core.py                 # Singleton facade wiring the whole pipeline together
├── rag_pipeline/
│   ├── config.py                 # Env vars / secrets (single source of truth)
│   ├── logging_setup.py          # Logging + Logfire
│   ├── gateway.py                 # Portkey multi-key LLM gateway
│   ├── errors.py                   # Retry + safe-node error handling
│   ├── ingestion.py                 # MCP docs loader + splitter
│   ├── vectorstore.py                # Embeddings + persistent Qdrant store
│   ├── reranker.py                    # Cross-encoder reranking
│   ├── pii_masking.py                  # Presidio PII masking
│   ├── guardrails.py                    # NeMo Guardrails (Colang 2.x)
│   ├── token_management.py               # Context window budgeting
│   ├── semantic_cache.py                  # Embedding-similarity cache
│   ├── query_condensation.py               # Follow-up question rewriting
│   ├── hallucination.py                     # Runtime hallucination judge
│   └── graph.py                              # LangGraph StateGraph — full pipeline
├── scripts/
│   └── evaluate_ragas.py        # Offline RAGAS evaluation (25 reference Q&A)
├── tests/
│   └── test_pipeline.py         # Fast smoke tests (no API keys needed)
├── configs/guardrails/           # Colang rail files (generated at first run)
├── data/                          # Persisted Qdrant vector store (gitignored)
├── notebooks/                      # Original development notebook
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env.example

🚀 Primeros pasos

Requisitos

• Python 3.11+

• Claves de API: Google AI Studio (Gemini, ×2), Groq (×2), Portkey (puerta de enlace + id de configuración)

1. Clona el repositorio y crea un entorno virtual

git clone https://github.com/<your-username>/mcp-docs-rag-assistant.git
cd mcp-docs-rag-assistant
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # macOS/Linux

2. Instala las dependencias

pip install -r requirements.txt
python -m spacy download en_core_web_sm   # required by Presidio for PII detection

3. Configura las variables de entorno

cp .env.example .env

Abre .env y completa tus claves reales (GEMINI_API_KEY_1/2, GROQ_API_KEY_1/2, PORTKEY_API_KEY, PORTKEY_CONFIG_ID).

4. Ejecuta el servidor

uvicorn main:app --reload

⏳ Solo en la primera ejecución: el almacén vectorial no existe todavía, por lo que el servidor ingiere la documentación de MCP y la incrusta en lotes limitados de velocidad — esto puede tardar 5–10 minutos. En cada ejecución posterior carga el almacén persistido desde data/qdrant_mcp_db/ al instante.

Una vez que veas Startup: RAG pipeline ready., abre:

• http://localhost:8000/docs — interfaz interactiva de Swagger, prueba POST /chat

• http://localhost:8000/health — check de estado

📡 API REST

🔌 Usarlo como servidor MCP

Standalone (stdio) — para Claude Desktop

Ejecútalo directamente:

python mcp_server.py

O apunta un servidor MCP local a él, p. ej., en la configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-docs-assistant": {
      "command": "python",
      "args": ["E:\\mcp-docs-rag-assistant\\mcp_server.py"]
    }
  }
}

Remoto (streamable-http) — a través de FastAPI

Cuando main.py está en ejecución, las mismas noches MCP también están disponibles en:

http://localhost:8000/mcp

Herramientas disponibles: ask_mcp_docs, search_mcp_docs, get_conversation_history, cache_stats.

🐳 Docker

La única requisito previo es Docker Desktop (que incluye Docker Compose): no necesitas instalar por separado Python, las dependencias pip ni el modelo de spacy en tu máquina. Todo eso sucede automáticamente dentro de la imagen cuando la contruyes (ver el Dockerfile — que ejecuta pip install -r requirements.txt y python -m !spacy download en_core_web_sm como pasos de la compilación.

# 1. Make sure .env exists (same as the local setup, step 3 above)
cp .env.example .env   # then fill in real keys

# 2. Build and run
docker compose up --build

Ese único comando construye la imagen, instala todo en su interiro e lanza el contenedor. La carpeta data/ se monta como volúmen (ver docker-compose.yml), de manra que el almacén vectorial persiste entre reinirios del contenedor — solo pagas una vez el coste de lacta lenta de la primer ejecución, ple. Docker.

El servidor es acclandable igual que ejecutándolo localmente: http://localhost:8000/docs.

Para pararlo:

docker compose down

Para reconstrurlo después de cambir código o dependencias:

docker compose up --build

🧪 Pruebas

Pruebas de humo rápidas — sin claves de API ni llamadas de red (emplean embeddings falsos):

pip install pytest
pytest tests/ -v

📊 Evaluación offline (RAGAS)

Puntúa el pipeline contra 25 preguntas de MCP escritas a mano con respuestas de referencia, usando RAGAS:

python scripts/evaluate_ragas.py

Esto no necesita que el servidor esté en ejecución: construye el propio pipeline (mismo singleton como main.py/mcp_server.py) e imprime en una tabla de métricas:

• Fidelidad: ¿la respuesta está fundamentada en el contexto recuperado?

• Relevancia de la respuesta: ¿responde la respuesta realmente la pregunta?

• Precisión del contexto: ¿el contexto recuperado es relevante?

• Cobertura del contexto: ¿el contexto recuperado cubre lo que necesita la respuesta de referencia?

⏱️ Tarda unos minutes: cada una de las 25 preguntas pasa por un step real de recuperación + generación, y después todas las métricas se evalúan mediante una llamada de LLM-as-judge.

⚙️ Reference de configuración

Toda la configurtación reside en .env (ver .env.example). Variables principales:

🛠️ Stack tecnológico

FastAPI · LangChain · LangGraph · Qdrant · Portkey · Sentence-Transformers · Presidio · NeMo Guardrails · RAGAS · MCP Python SDK · Docker

📄 Licencia

MIT — ver LICENSE.