porta-rag-mcp — RAG knowledge base как MCP-tools для AI-клиента

MCP-сервер, который выставляет RAG-базу знаний (поиск по документам) как tools для любого AI-клиента — Claude Desktop, Cursor, VS Code, ChatGPT. AI-агент сам решает когда искать по базе и как использовать найденное.

Архитектура — «обёртка»: тонкий слой FastMCP над RAG-движком, реализующим фиксированный интерфейс (retrieve / query / get_stats / diagnostic). Код RAG-движка не зависит от MCP и не меняется.

Демо-домен: база знаний по ВЭД (таможенные процедуры, ТН ВЭД, документы для импорта/экспорта). Система доменно-независима — на входе любые текстовые документы в rag_data/docs/.

---

Почему это интересно

Это пересечение RAG ( retrieval-слой) и MCP (стандарт подключения AI к внешним инструментам). Главное — оптимизация токенов: поиск разделён на два режима:

Tool	LLM	Назначение	Токены
search_knowledge_base	нет	retrieval-фаза RAG: топ-k чанков	дёшево
ask_knowledge_base	да	поиск + связный LLM-ответ с цитатами	дороже

search_knowledge_base — это RAG «без LLM»: чистый retrieval, возвращает релевантные фрагменты без вызова чат-модели. Для справочных lookups модель предпочитает его; ask_knowledge_base (с генерацией) — только когда нужен связный ответ. Это та самая оптимизация из бенчмарков (RAG ≈ $0.005/запрос vs MCP-only ≈ $0.17/запрос).

---

Tools (все read-only — ничего не меняют в индексе)

Tool	Параметры	Возвращает
search_knowledge_base	question, top_k=3	[{source, text, chunk_id, sim}, ...]
ask_knowledge_base	question, top_k=3	{answer, sources, empty, not_found, latency_ms}
kb_stats	—	{available, collection_count, files, models, ...}
kb_diagnostic	—	{available, store, chunks, embed_model, ...}

---

Два бэкенда

1. Demo (в этом репо) — TF-IDF, без ключей и LLM

rag_engine.py в корне репо — минимальный TF-IDF бэкенд на numpy. Запускается standalone, без API-ключей и без LLM. ask_knowledge_base в demo-режиме собирает ответ из топ-чанков с цитатами (без генерации). Это для демонстрации MCP-обёртки, не для продакшена.

2. Production — FAISS + BM25 + rerank (Porta)

В продакшене этот же mcp_porta_rag.py работает рядом с production-rag_engine.py (FAISS + BM25 + rerank, эмбеддинги BGE-M3/e5, чат-модель DeepSeek/Qwen). mcp_porta_rag.py не меняется — он импортирует rag_engine с тем же интерфейсом. Достаточно положить production-rag_engine.py рядом и положить документы/индекс в rag_data/.

---

Установка и запуск

pip install -r requirements.txt   # fastmcp, numpy

# 1. самопроверка бэкенда
python3 rag_engine.py

# 2. дебаг в MCP Inspector (браузерный UI, кликаешь tools мышкой)
fastmcp dev mcp_porta_rag.py

# 3. stdio-сервер для AI-клиента
fastmcp run mcp_porta_rag.py

Документы: положи .txt/.md в rag_data/docs/ — они индексируются при первом запросе (lazy). .env не требуется для demo-бэкенда.

---

Подключение к Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "porta-rag": {
      "command": "python3",
      "args": ["/path/to/porta-rag-mcp/mcp_porta_rag.py"]
    }
  }
}

Перезапустить Claude Desktop → модель видит 4 tools. Пример запроса: «найди в базе, какие документы нужны для импорта» → Claude вызывает search_knowledge_base и получает релевантные фрагменты.

---

Гибрид с Notion (опционально)

Если в тот же конфиг добавить официальный notion-mcp-server, Claude сможет комбинировать tools обоих серверов: «найди в ВЭД-базе про код ТН ВЭД 0702 и запиши саммари в Notion» → search_knowledge_base (этот сервер) + create_page (Notion). MCP-серверы не связаны друг с другом напрямую — они оба подключены к одному AI-клиенту, который оркестрирует между ними.

---

Структура

.
├── mcp_porta_rag.py        # MCP-сервер (FastMCP): 4 read-only tools
├── rag_engine.py           # demo TF-IDF бэкенд (без ключей/LLM)
├── rag_data/docs/          # исходные документы (.txt/.md)
│   ├── customs_procedures.txt
│   ├── tn_ved_payments.txt
│   └── ved_documents.txt
├── requirements.txt        # fastmcp, numpy
└── README.md

Интерфейс RAG-бэкенда (для замены на production)

def retrieve(question: str, k: int = 3, user_id=None) -> list[dict]
    # -> [{"source": str, "text": str, "chunk_id": int, "sim": float}, ...]
def query(question: str, k: int = 3, model=None, user_id=None, history=None) -> dict
    # -> {"answer": str, "sources": list, "empty": bool, "not_found": bool, "latency_ms": int}
def get_stats(user_id=None) -> dict
    # -> {"available": bool, "empty": bool, "collection_count": int, "files": [...], ...}
def diagnostic() -> dict

Стек

Слой	Технология
MCP	FastMCP 3.x (Python), stdio / Streamable HTTP
RAG (demo)	TF-IDF + косинус, numpy, без ключей
RAG (prod)	FAISS + BM25 + rerank, эмбеддинги BGE-M3/e5, DeepSeek/Qwen

Лицензия

MIT.