scholar-rag-mcp

Статус: предварительный релиз (v0.1.0). Интерфейсы и структура хранилища могут измениться в будущих версиях.

scholar-rag-mcp — это публикуемый MCP-инструмент для базы знаний по академическим статьям. Направьте его на папку с PDF-файлами, и он обработает каждую статью через настоящий конвейер разбора (MinerU), нормализует метаданные, разметит структуру разделов, разобьёт текст на фрагменты и создаст эмбеддинги, а затем сохранит всё в Qdrant — после чего агент (или вы) сможет семантически искать фрагменты, выполнять документные запросы в стиле PubMed, читать полный текст по разделам, добавлять и удалять отдельные статьи и управлять базами знаний — всё это через 11 MCP-инструментов поверх stdio. Эмбеддинги, разметка и реранжирование работают на OpenAI-совместимых сервисах моделей (vLLM) с внутрипроцессными запасными реализациями.

Возможности

• Настоящий конвейер обработки: разбор PDF через MinerU (бэкенды python/cli/api) -> извлечение метаданных (локальные эвристики, CrossRef, опционально GROBID) -> очистка -> разметка разделов -> детерминированное разбиение на фрагменты (настраивается: 300/1500/100 символов) -> эмбеддинги.

• Быстрый поиск в масштабе: первый проход по эмбеддингам + реранжирование кросс-энкодером, опциональная фильтрация по метаданным (doc_id, section, year, journal, ...), вычисляемая внутри индекса Qdrant. p95 задержка запроса при 100k фрагментов < 1 с (см. docs/perf-report.md).

• Асинхронные задачи: create_kb/add_document — фоновые задачи, ход выполнения которых можно запрашивать через get_job; безопасен перезапуск (прерванные задачи восстанавливаются и пропускаются при повторном запуске).

• Безопасное для контекста чтение: постраничный get_document_text с жёсткими ограничениями размера; сначала оглавление, страницы по запросу.

• 11 MCP-инструментов поверх stdio: list_kbs, create_kb, delete_kb (двухфазное), add_document, remove_document, get_document, get_document_text, list_documents, search_documents, search_chunks, get_job.

• Автономное хранилище: базы знаний находятся в едином каталоге данных (~/.scholar-rag); Qdrant либо запускается автоматически (один бинарный файл, фиксированная версия), либо подключается к внешнему экземпляру.

Related MCP server: Athena

Установка

Требуется pixi. Из корня репозитория:

pixi install                      # installs the default environment

Проект определяет три окружения pixi, каждое из которых служит своей цели:

Проверьте своё окружение встроенной диагностикой:

pixi run python scripts/doctor.py

Развёртывание моделей

Окружение (клиенты 'chat', 'embed' и 'rerank') ожидает HTTP-эндпоинты, совместимые с OpenAI. scripts/serve_models.sh запускает три экземпляра vLLM для эталонного набора моделей:

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL, SCHOLAR_RAG_EMBED_MODEL и SCHOLAR_RAG_RERANK_MODEL обязательны — если хотя бы одна не задана, скрипт завершится с сообщением, перечисляющим их. Каждое значение должно быть абсолютным путём к локальному каталогу модели HuggingFace; vLLM обслуживает каждую модель под коротким именем, равным имени каталога модели, поэтому в настройках клиента нужно использовать это короткое имя (обслуживаемое имя больше не равно полному пути). Соответственно замените заполнители /path/to/... в .env.example. Порты (CHAT_PORT/EMBED_PORT/RERANK_PORT) и идентификаторы GPU остаются опциональными с рабочими значениями по умолчанию.

Скрипт фиксирует точные флаги vLLM, проверенные для этих моделей (для модели эмбеддингов Jina требуется --trust-remote-code из-за её пользовательского кода; реранкер работает со своей задачей по умолчанию, без дополнительных флагов). Загрузка моделей занимает несколько минут; скрипт опрашивает статус здоровья, пока все три не ответят.

Минимальное окружение

Начните с .env.example и задайте как минимум эндпоинты моделей (используйте короткие имена, которые предоставляет скрипт запуска; они равны имени каталога каждой модели):

SCHOLAR_RAG_DATA_DIR=~/.scholar-rag
SCHOLAR_RAG_QDRANT_STORAGE_DIR=~/.local/share/scholar-rag/qdrant

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

Размерность модели эмбеддингов записывается в kb_meta.json при создании базы знаний, поэтому последующая смена модели эмбеддингов требует новой базы знаний.

Настройка MCP-клиента

Запустите точку входа сервера напрямую, чтобы убедиться, что она работает:

pixi run scholar-rag-mcp

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "pixi",
      "args": ["run", "scholar-rag-mcp"]
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["pixi", "run", "scholar-rag-mcp"]
    }
  }
}

Инструменты

Структура данных

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default ~/.scholar-rag
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
└── bin/                        # auto-downloaded Qdrant binary (v1.12.5)

Хранилище Qdrant находится вне data_dir, в QDRANT_STORAGE_DIR (по умолчанию ~/.local/share/scholar-rag/qdrant) — оно должно быть на локальной файловой системе, а не на 9p/сетевом монтировании.

Двухфазное удаление базы знаний

delete_kb никогда не удаляет случайно при первом вызове с неверными аргументами:

1. Вызовите delete_kb(kb="...") — вернёт статистику базы знаний и confirm_token сроком на 10 минут.

2. Вызовите delete_kb(kb="...", confirm_token="<token>"), чтобы фактически удалить коллекцию Qdrant, каталог базы знаний и её историю задач.

Разработка

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

Примечания к релизу

Известные ограничения и рекомендации по обновлению см. в docs/handoffs/release-notes-v0.1.0.md.

Известные ограничения, которые стоит повторить:

• Qdrant зафиксирован на версии v1.12.5 — это самая новая версия, работающая на glibc 2.35; автозапуск загружает её при первом использовании. На glibc >= 2.38 можно запустить более новую версию, но в этом релизе формат данных не совместим вперёд со старыми базами знаний.

• MinerU работает в собственном окружении pixi, потому что его версия transformers взаимоисключающа с версией vLLM. Поэтому для разбора PDF предпочтителен pixi run -e mineru.

• Веса MinerU (~3.2 ГБ) загружаются при первом разборе в ~/.cache/modelscope/.

• Эвристика заголовка метаданных: заголовки локально определяются только тогда, когда Markdown от MinerU начинается с заголовка #/##, поэтому начальный ## Abstract (и т.п.) может быть ошибочно принят за заголовок. Это влияет только на уровень метаданных на основе локальных эвристик; уровень CrossRef (используемый при обнаружении DOI) обычно исправляет это.

• Диспетчеризация инструментов: неизвестные дополнительные аргументы инструмента молча игнорируются, а не отклоняются.

• Ограничение 9p-хранилища: хранилище Qdrant должно находиться на локальной файловой системе.