st-mcp-mp-docs (0.2.1)
Installation
pip install --index-url About this package
Локальный MCP-сервер гибридного поиска (BM25+dense) по документации API маркетплейсов
MCP Marketplaces Docs
MCP-сервер гибридного поиска (BM25 + dense-эмбеддинги) по документации API и бизнес-справке маркетплейсов (Ozon, Yandex Market, Wildberries). Индексирует корпус docs/ из скрапера и отдаёт агенту opencode инструменты ранжированного поиска с фильтрами по метаданным и навигацией по секциям.
🚀 Возможности
- Гибридный поиск BM25+dense (
intfloat/multilingual-e5-base, GPU) через Reciprocal Rank Fusion — включаетсяMP_HYBRID(по умолчаниюtrue) - Фильтрация по метаданным frontmatter в одном вызове:
marketplace,type,archived - Возврат сниппетов секций вместо целых файлов — экономия контекста агента
- Чанкинг по заголовкам H2 с объединением мелких секций
- Идемпотентная индексация: перестройка только при изменении
docs/,knowledge/или схемы индекса - E2E-проверка инструментов и замер recall@k из коробки
- Слой знаний
knowledge/: операционная правда (memory/) и живой навигатор-глоссарий (guide/), мостящий разрыв между вопросом продавца и словами документации
📚 Слои корпуса
Корпус состоит из двух корней (MP_DOCS_PATH + MP_KNOWLEDGE_PATH), индексируемых вместе:
| Слой | type |
Кто пишет | Перезапись | Вес в поиске |
|---|---|---|---|---|
docs/api/, docs/seller/ |
api, seller |
скрапер marketplaces.docs.scraper |
перезаписывается при каждом скрапинге | по умолчанию |
knowledge/memory/ |
memory |
человек (сверка данных с ЛК/API) | никогда | высокий |
knowledge/guide/ |
guide |
человек (накапливаемый опыт) | никогда | высокий |
knowledge/memory/*.md и knowledge/guide/*.md — правятся руками, не генерируются format.py.
Правило потребления описано в AGENTS.md: сначала get_guide(marketplace), потом search.
🛠️ Технологический стек
| Технология | Версия | Назначение |
|---|---|---|
| Python | 3.13 | Язык разработки |
| mcp[cli] | 1.28.1 | MCP SDK, транспорт stdio |
| rank-bm25 | 0.2.2 | BM25-ранжирование |
| sentence-transformers | 5.6.0 | Dense-эмбеддинги (multilingual-e5-base) |
| torch | 2.13.0 | GPU-инференс модели эмбеддингов |
| numpy | 2.5.1 | Хранение и косинус эмбеддингов |
| pyyaml | 6.0.3 | Парсинг frontmatter |
| python-dotenv | 1.2.2 | Загрузка переменных окружения |
🖥️ Требования к GPU
Построение индекса (make index) требует CUDA-доступный GPU в этой версии — dense-эмбеддинги
считаются всегда, без CPU-fallback. Поиск в рантайме (search) тоже требует GPU при MP_HYBRID=true
(значение по умолчанию); MP_HYBRID=false отключает dense-ветку и работает чисто на BM25 без
обращения к GPU.
Модель intfloat/multilingual-e5-base (~280 МБ) кэшируется при первом запуске в
~/.cache/huggingface/ — это отдельный кэш от MP_CACHE_DIR (тот хранит только
bm25.pkl/chunks.jsonl/embeddings.npy/manifest.json). Первая установка скачивает torch+CUDA
(~2.5+ ГБ) и саму модель.
📁 Структура проекта
marketplaces.mcp.docs/
├── src/st_mcp_mp_docs/
│ ├── main.py # Точка входа: запуск сервера по stdio
│ ├── server.py # FastMCP и регистрация инструментов
│ ├── tools.py # Реализация инструментов поверх BM25+dense
│ ├── indexer.py # Построение индекса: frontmatter, чанкинг, embeddings, кэш
│ ├── embedder.py # Dense-эмбеддинги через sentence-transformers (e5-base, GPU)
│ ├── hybrid.py # Reciprocal Rank Fusion: слияние BM25 и dense
│ ├── tokenizer.py # Токенизация camelCase/snake_case, стоп-слова
│ ├── format.py # Сниппеты и форма результатов
│ └── config.py # Пути и параметры из окружения
├── scripts/
│ ├── check.py # E2E-прогон через MCP-клиент
│ └── eval.py # Замер recall@k и MRR
├── tests/
│ └── eval_queries.jsonl # Набор поисковых запросов
├── knowledge/
│ ├── memory/ # Операционная правда об API (человеческий слой)
│ └── guide/ # Глоссарий и навигация по разделам (человеческий слой)
├── cache/ # BM25-индекс и метаданные (gitignored)
├── Makefile
├── pyproject.toml
├── AGENTS.md
└── README.md
🚀 Установка и запуск
Предварительные требования
- Python 3.13+
- uv
- NVIDIA GPU + CUDA-совместимый драйвер (построение индекса и поиск при
MP_HYBRID=true, дефолт) - Каталог
docs/скрапераmarketplaces.docs.scraper
Установка
make help # Справка по командам
make install # Создание окружения и установка зависимостей
make index # Построение BM25-индекса из docs/ + knowledge/
Запуск
make serve # Запуск MCP-сервера (stdio)
Регистрация в opencode — секция mcp в opencode.json:
{
"mcp": {
"mp-docs": {
"type": "local",
"command": [
"uvx",
"--from",
"st-mcp-mp-docs",
"--index",
"https://forgejo.emptyvessel.ru/api/packages/st/pypi/simple",
"st-mcp-mp-docs",
],
"environment": {
"MP_DOCS_PATH": "/path/to/marketplaces.docs/docs",
"MP_KNOWLEDGE_PATH": "/path/to/marketplaces.mcp.docs/knowledge",
},
"enabled": true,
},
},
}
🔧 Разработка
make index # Построение BM25-индекса из docs/ + knowledge/
make serve # Запуск MCP-сервера (stdio)
make eval # Замер recall@k на eval-наборе
make e2e # Прогон инструментов через MCP-клиент
make lint # Проверка линтером
make fix # Автоисправление и проверка типов
make format # Форматирование кода
make clean # Очистка кэша
make purge # Полная очистка окружения, индекса и кэшей
make build # Сборка wheel и sdist
make publish # Публикация в forgejo registry
👥 Команда разработки
- Станислав (@stanislavbajkov2)
📄 Лицензия
Проект разработан для коммерческого использования. Права защищены.
© 2026 ДонНовоТех Передовые программные и аппаратные решения для транспорта
📍 Адрес: ул. М.Горького 205, Ростов-на-Дону, 344000, Россия
📞 Телефон: +7-904-500-6087
📧 Email: leojohn@yandex.ru
🌐 Сайт: donnovotech.ru
🏢 ИНН: 6163227601