Modular RAG MCP Server

Ориентированная на внутренних консультантов DIY-команды по обучению за рубежом инфраструктура поиска знаний по поступлению и наблюдаемый RAG

Modular RAG MCP Server — это локально-ориентированный, подключаемый и наблюдаемый сервис генерации с дополнением поиска (RAG). Система предоставляет возможности поиска знаний AI-клиентам через Model Context Protocol (MCP) и управляет документами, задачами приёма, цепочками запросов и результатами оценки через Streamlit Dashboard.

Этот проект возник из реального сценария сотрудничества во время учёбы в университете: DIY-команда по обучению за рубежом внутри колледжа помогала студентам с подачей заявок в зарубежные вузы. Система решает проблему консультантов, которым приходилось многократно искать информацию о требованиях вузов, материалах для подачи, процедурных нормах и историческом опыте, а также сложность отслеживания источников. В настоящее время система развёрнута внутри команды; публичный репозиторий содержит только анонимизированные синтетические примеры и не включает реальные данные студентов, внутренние документы или эксплуатационные данные.

Все примеры материалов в репозитории должны использовать анонимизированные синтетические данные; выходные данные системы предназначены для проверки консультантами и не заменяют их суждение, а также не являются рекомендациями по вузам, визам или юридическими консультациями.

Содержание

• Бизнес-контекст

• Границы системы

• Ключевые возможности

• Архитектура системы

• Согласованность данных и хранилищ

• MCP Tools

• Dashboard

• Быстрый старт

• Обеспечение качества

• Безопасность и эксплуатационные ограничения

• Текущее состояние и план развития

Related MCP server: mcp-rag-assistant

Бизнес-контекст

Консультанты по DIY-обучению за рубежом при обработке заявок должны одновременно обращаться к официальным описаниям вузов, руководствам по программам, шаблонам материалов, внутренним контрольным спискам и историческим кейсам. Исходные материалы обычно хранятся в виде PDF-файлов, разбросанных по разным местам, и имеют следующие проблемы:

• Одно и то же требование может быть сформулировано по-разному в нескольких документах, и чисто ключевой поиск легко пропускает релевантные результаты.

• Специфические термины, такие как вузы, специальности, степени и сезоны поступления, требуют точного сопоставления, и чисто векторный поиск легко даёт ложные срабатывания.

• Таблицы, диаграммы и скриншоты в PDF содержат важную информацию, и чисто текстовый анализ теряет контекст.

• Консультантам нужно знать, из какого документа и какого фрагмента получен ответ, и оценивать, актуален ли документ.

• После обновления документа векторное хранилище, индекс BM25, индекс изображений и записи о приёме должны оставаться согласованными.

• Эффективность поиска должна проверяться с помощью стабильного набора тестов, а не субъективного опыта.

Система предназначена для внутренних консультантов команды. Типичный рабочий процесс включает:

1. Приём материалов о вузах и программах, внутренних контрольных списков и анонимизированных кейсов в указанную коллекцию.

2. Отправка вопросов на естественном языке через MCP Client или командную строку.

3. Система выполняет двухканальный поиск Dense + BM25, слияние RRF и опциональный Rerank.

4. Возврат текстовых фрагментов с указанием источников и мультимодальных блоков при обнаружении изображений.

5. Проверка процесса приёма, результатов поиска, времени выполнения и метрик оценки через Dashboard.

Границы системы

Этот проект отвечает за приём знаний, поиск, цитирование, оценку и наблюдение за цепочками, но не отвечает за:

• Замену консультанта в выводах о выборе вуза, вероятности поступления или визовых решениях.

• Автоматическую подачу заявок, отправку писем или изменение материалов студентов.

• Предоставление студенческих аккаунтов, CRM, платежей или управления статусом заявок.

• Автоматический сбор и заявление о владении актуальной политикой вузов.

• Формирование определённых бизнес-выводов при отсутствии подтверждающих источников.

Ключевые возможности

Архитектура системы

flowchart LR
    A["PDF 业务资料"] --> B["Ingestion Pipeline"]
    B --> C["Chroma 向量库"]
    B --> D["BM25 索引"]
    B --> E["SQLite 摄取历史"]
    B --> F["图片文件与索引"]
    G["顾问 / MCP Client"] --> H["MCP Server"]
    H --> I["Query Processor"]
    I --> J["Dense Retrieval"]
    I --> K["Sparse Retrieval"]
    J --> L["RRF Fusion"]
    K --> L
    L --> M["Optional Rerank"]
    M --> N["Response + Citations + Images"]
    B --> O["Ingestion Trace"]
    I --> P["Query Trace"]
    O --> Q["Streamlit Dashboard"]
    P --> Q

Основные каталоги:

src/
├── core/            # 数据契约、查询编排、响应构建、Trace、配置
├── ingestion/       # Chunk、Transform、Embedding、Storage 与 Pipeline
├── libs/            # LLM/Embedding/Loader/Reranker/Splitter/VectorStore 抽象
├── mcp_server/      # MCP 协议处理、Server 与 Tools
└── observability/   # Dashboard、评估与结构化日志

scripts/             # ingest、query、evaluate、Dashboard 启动入口
config/              # Provider、检索、重排、评估与摄取配置
tests/               # Unit、Integration、E2E 测试与固定样例

Подробные интерфейсы, потоки данных и ограничения модулей см. в DEV_SPEC.md.

Согласованность данных и хранилищ

Один приём координирует несколько серверных хранилищ:

Проверка целостности файлов использует SHA256 для пропуска файлов, которые уже были успешно обработаны и не изменились. Chunk ID стабильно генерируется на основе источника, местоположения и содержимого, повторный приём использует идемпотентный Upsert. DocumentManager отвечает за координированное удаление в Chroma, BM25, истории приёма и индексе изображений и возвращает информацию о частичных сбоях.

MCP Tools

В настоящее время Server предоставляет четыре Tools. Первые три универсальных Tool сохранены без изменений, четвёртый — это адаптационный слой для бизнеса по обучению за рубежом:

MCP использует Stdio Transport. stdout зарезервирован для JSON-RPC, журналы выполнения записываются в stderr, чтобы не нарушать кадры протокола.

search_admissions_knowledge по умолчанию запрашивает admissions_knowledge и всегда ограничивает business_domain=study_abroad_admissions. Он поддерживает точную фильтрацию по стране, вузу, программе, уровню степени, сезону поступления, раунду подачи и типу источника; по умолчанию исключает материалы, у которых valid_until раньше бизнес-даты запроса. Материалы с отсутствующим или неразрешимым сроком действия помечаются как needs_review и не молча считаются действующими правилами. Бизнес-Tool — это только адаптационный слой для параметров и ответов, в основе по-прежнему выполняются Dense + BM25, RRF, Cross-Encoder/LLM Rerank, цитирование и мультимодальный возврат.

Dashboard

Dashboard сохраняет структуру из шести страниц:

1. Overview: конфигурация компонентов, активы данных, статус работы, а также статистика действующих, требующих проверки и просроченных материалов по обучению за рубежом.

2. Data Browser: документы, Chunk, Metadata и связанные изображения; поддержка комбинированной фильтрации по стране, вузу, программе, степени, сезону поступления, раунду подачи, типу источника и статусу актуальности.

3. Ingestion Manager: запуск приёма, просмотр прогресса и координированное удаление документов.

4. Ingestion Traces: этапы приёма, методы обработки, время выполнения и исключения.

5. Query Traces: Dense/Sparse поиск, слияние, переранжирование и окончательные результаты.

6. Evaluation Panel: выполнение оценки и просмотр метрик и исторических результатов.

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

1. Подготовка окружения

Требуется Python 3.10–3.12.

git clone https://github.com/xiaoxinbuxingyeyuan/MODULAR-RAG-MCP-SERVER.git
cd MODULAR-RAG-MCP-SERVER
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS / Linux:

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

В pyproject.toml зафиксированы версии прямых зависимостей, проверенные для текущего проекта. При обновлении MCP, Ragas, LangChain или компонентов хранилища следует обновлять их отдельно и повторно выполнять офлайн- и онлайн-регрессию.

2. Настройка Provider

Отредактируйте config/settings.yaml, чтобы настроить LLM, Embedding, Vision LLM, VectorStore, Reranker и бэкенд оценки. API-ключи должны внедряться через безопасную конфигурацию и не должны попадать в репозиторий.

Если локально нет сервиса моделей, можно отключить необязательные LLM-улучшения и Rerank для проверки базовой цепочки, не зависящей от внешних сервисов.

3. Приём документов

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/simple.pdf \
  --collection admissions_knowledge

Приём каталога:

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/ \
  --collection admissions_knowledge

Приём с использованием бизнес-манифеста для обучения за рубежом:

python scripts/ingest.py \
  --path examples/documents/synthetic/ \
  --collection admissions_knowledge \
  --manifest examples/admissions_manifest.example.jsonl

Манифест использует UTF-8 JSONL, каждая строка соответствует одному PDF. Относительный document_path разрешается относительно каталога, в котором находится манифест; обязательные поля: document_path, title, country и source_type. Необязательные поля включают institution, program, degree_level, intake, application_round, published_at, valid_until, language, tags и access_scope. Полный пример см. в examples/admissions_manifest.example.jsonl.

После передачи манифеста каждый PDF, подлежащий приёму, должен иметь уникальное совпадение. Неизвестные поля, повторяющиеся пути, недопустимые перечисления и инвертированные даты приводят к сбою до записи в хранилище. Метаданные манифеста распространяются от Document к Chunk и записям Chroma; заголовки и теги на уровне Chunk, созданные LLM, не переопределяют document_title и business_tags.

Инкрементальное определение одновременно сравнивает SHA256 PDF и SHA256 нормализованных бизнес-метаданных: если оба не изменились, приём пропускается; изменение только манифеста автоматически повторно принимает документ и перезаписывает метаданные, соответствующие стабильному Chunk ID. При изменении содержимого PDF система сначала записывает новую версию, затем очищает Chunk Chroma, изображения и старые записи приёма по старому doc_hash; BM25 заменяет postings по префиксу стабильного пути источника. Старая история приёма в SQLite автоматически получает поле metadata_hash без ручной миграции. --force по-прежнему можно использовать для явного пересоздания, но он больше не является обязательным условием для применения обновлений манифеста.

Репозиторий предоставляет три полностью вымышленных бизнес-примера без личной информации, охватывающих действующие материалы, отсутствие срока действия и просроченные материалы; руководство по курсу включает блок-схему для проверки мультимодальной цепочки. Для повторной генерации примеров PDF выполните:

python examples/generate_synthetic_admissions_pdfs.py

4. Запросы из командной строки

python scripts/query.py \
  --query "申请材料需要包含哪些证明？" \
  --collection admissions_knowledge \
  --verbose

5. Запуск Dashboard

python scripts/start_dashboard.py

Адрес по умолчанию: http://localhost:8501.

6. Запуск MCP Server

python -m src.mcp_server.server

Форматы конфигурации разных MCP Client немного отличаются, основная конфигурация процесса выглядит так:

{
  "command": "<project>/.venv/Scripts/python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project>"
}

В macOS / Linux замените путь к Python на <project>/.venv/bin/python.

7. Выполнение оценки

python scripts/evaluate.py \
  --test-set examples/admissions_golden_test_set.json \
  --collection admissions_knowledge

Если нет внешней среды поиска, можно выполнить:

python scripts/evaluate.py --no-search

Обеспечение качества

Проект использует трёхуровневую структуру тестирования:

• Unit: контракты данных, алгоритмы, Factory, Tool Handler и адаптеры хранилищ.

• Integration: комбинированное поведение приёма, гибридного поиска, MCP, Provider и Trace.

• E2E: приём через CLI, MCP Client, smoke-тесты Dashboard и регрессия Recall.

python -m pytest tests/unit
python -m pytest tests/integration
python -m pytest tests/e2e
python -m pytest

Приведённые выше команды по умолчанию пропускают все тесты, помеченные как online, и не вызывают реальные Provider. Для реальных сервисов Azure, OpenAI или Ollama явно выполните в среде с соответствующими учётными данными и доступными сервисами:

python -m pytest --run-online -m online

Шлюз, совместимый с OpenAI, можно внедрить через OPENAI_API_KEY, OPENAI_BASE_URL и OPENAI_MODEL без изменения конфигурации репозитория или отправки учётных данных. Тесты Provider, которые не настроены, должны оставаться пропущенными.

Чтобы проверить только правильную классификацию онлайн-тестов без их запуска, выполните python -m pytest --collect-only -m online. Офлайн- и онлайн-результаты следует записывать отдельно; --run-online только снимает ограничение пропуска и не заменяет конфигурацию Provider.

Слой оценки продолжает поддерживать Custom Evaluator и Ragas. Бизнес-набор Golden Test Set дополнительно записывает комбинированную фильтрацию, бизнес-дату, политику истечения, ожидаемые источники и эталонные ответы; офлайн-приёмка бизнеса проверяет эти поля и поведение по актуальности бизнес-адаптера MCP. Общие интерфейсы оценки и исходный Golden Test Set не изменены.

Безопасность и эксплуатационные ограничения

• По умолчанию используется локальный Stdio и локальное хранилище, сетевые порты не открываются.

• API-ключи и личная информация студентов не сохраняются в журналах, Trace, тестовых фиксированных данных или истории Git.

• Перед попаданием бизнес-материалов в базу знаний необходимо подтвердить авторизацию и выполнить деидентификацию конфиденциальных данных.

• Результаты поиска должны сохранять ссылки на источники; при отсутствии надёжных источников следует возвращать пустой результат или подсказку о ручной проверке.

• Требования вузов имеют ограниченный срок действия; бизнес-Tool по умолчанию исключает материалы, у которых истёк valid_until, и явно указывает на отсутствие срока действия, но консультанты всё равно должны сверяться с официальными источниками.

• Текущая архитектура — это однопользовательский локальный сервис, не предоставляющий аутентификацию, изоляцию прав или гарантии многопользовательности.

Текущее состояние и план развития

Существующая ветка main уже имеет полный каркас универсального RAG, MCP, Dashboard, Trace и оценки. Доработка для обучения за рубежом ведётся инкрементально и не может удалять или упрощать существующие технические возможности.

Реализация любого этапа должна сохранять полный конвейер приёма PDF, Dense + BM25, RRF, Rerank, мультимодальность, согласованность множественных хранилищ, инкрементальное обновление и удаление, исходные три MCP Tools, шестистраничный Dashboard, двухканальные Trace, Custom + Ragas, трёхуровневое тестирование и все подключаемые интерфейсы.