🔌 MCP Docs Assistant

Продакшн-конвейер RAG (Retrieval-Augmented Generation) на основе официальной документации Model Context Protocol — доступен через REST API, MCP-инструменты и Docker.

Задавайте вопросы на естественном языке о MCP (архитектура, создание серверов и клиентов, инструменты/ресурсы/промпты, безопасность) и получайте ответы, основанные на реальных документах — со встроенными гардрейлами, маскированием PII, реранжированием, семантическим кэшированием и проверкой галлюцинаций.

✨ Возможности

Related MCP server: FusionPact MCP Server

🏗️ Архитектура

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]

Каждый узел выше — это модуль в rag_pipeline/, объединённый в виде LangGraph StateGraph в rag_pipeline/graph.py. rag_core.py создаёт все зависимости один раз (как синглтон) и предоставляет небольшой стабильный API — chat(), search(), get_history(), cache_stats() — который одинаково используется и REST-слоем (main.py), и MCP-слоем (mcp_server.py). Благодаря этому единое векторное хранилище / кэш / история диалога используется совместно, независимо от того, через какой интерфейс приходит запрос.

📁 Структура проекта

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

🚀 Быстрый старт

Предварительные требования

• Python 3.11+

• API-ключи: Google AI Studio (Gemini, ×2), Groq (×2), Portkey (authorization + конфиг-ид)

1. Клонируйте репозиторий и создайте виртуальное окружение

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. Установите зависимости

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

3. Настройте переменные окружения

cp .env.example .env

Откройте .env и укажите ваши реальные ключи (GEMINI_API_KEY_1/2, GROQ_API_KEY_1/2, PORTKEY_API_KEY, PORTKEY_CONFIG_ID).

4. Запустите сервер

uvicorn main:app --reload

⏳ Только при первом запуске: векторного хранилища ещё не существует, поэтому сервер обрабатывает MCP-документацию и создаёт эмбеддинги отдельными лимитированными пакетами — это может занять 5–10 минут. При каждом последующем запуске он мгновенно загружает сохранённое хранилище из data/qadrant_mcp_db/.

Когда увидите Startup: RAG pipeline ready., откройте:

• http://localhost:8000/docs — интерактивный Swagger UI, попробуйте POST /chat

• http://localhost:8000/health — проверка состояния

📡 REST API

🔌 Использование в качестве MCP-сервера

Автономно (stdio) — для Claude Desktop

Запустите напрямую:

python mcp_server.py

Или укажите локальному MCP-хосту, например, в конфиге Claude Desktop (claude_desktop_config.json):

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

Удалённо (streamable-http) — через FastAPI

Когда запущен main.py, те же MCP-инструменты доступны по адресу:

http://localhost:8000/mcp

Доступные инструменты: ask_mcp_docs, search_mcp_docs, get_conversation_history, cache_stats.

🐳 Docker

Единственное предусмотртельное условие — Docker Desktop (в комплекте с Docker Compose) — не нужно отдельно устанавливать Python, pip-зависимости или модель spacy. Всё это автоматически происходит внутри образа при его сборке (см. Dockerfile — на этапе сборки выполняются pip install -r requirements.txt и python -m spacy download en_core_web_sm).

# 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

Эта одна команда собирает образ, устанавливает всё внутри него и запускает контейнер. Папка data/ смонтирована как том (см. docker-compose.yml), поэтому векторное хранилище сохраняется при перезапуске контейнера — первый долгий запуск инжеста вы платите один раз даже с Docker.

Сервер доступен так же, как и локально: http://localhost:8000/docs.

Чтобы остановить:

docker compose down

Чтобы пересобрать после изменений в коде или зависимостях:

docker compose up --build

🧪 Тестирование

Быстрые smoke-тесты — без API-ключей и сетевых вызовов (используются фейковые эмбеддинги):

pip install pytest
pytest tests/ -v

📊 Оффлайн-оценка (RAGAS)

Оценивает пайплайн по 25 вручную написанным MCP-вопросам с эталонными ответами, используя RAGAS:

python scripts/evaluate_ragas.py

Для этого не нужен запущенный сервер — пайплайн строится сам (тот же синглтон, что и в main.py/mcp_server.py) и выводится таблица метрик:

• Фактность — основан ли ответ на извлечённом контексте?

• Релевантность ответа — действительно ли ответ на заявленный вопрос?

• Точность контекста — релевантен ли извлечённый контекст?

• Полнота контекста — покрывает ли извлечённый контекст то, что нужно для эталонного ответа?

⏱️ Требуется несколько минут: каждый из 25 вопросов прогоняется через реальный поиск и генерацию, затем каждый качестве метрики дополнительно оценивается вызовом LLM-as-judge.

⚙️ Справочник по конфигурации

Вся конфигурация хранится в .env (см. .env.example). Основные переменные:

🛠️ Технологический стек

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

📄 Лицензия

MIT — см. LICENSE.