Станислав Байков
Repositories
6
 Projects Packages
5
 Public activity Starred repositories

st-mcp-mp-docs (0.1.0)

Published 2026-07-15 12:53:02 +03:00 by st

Installation

pip install --index-url  st-mcp-mp-docs

About this package

Локальный MCP-сервер BM25-поиска по документации API маркетплейсов

MCP Marketplaces Docs

Python 3.13 MCP rank-bm25

MCP-сервер BM25-поиска по документации API и бизнес-справке маркетплейсов (Ozon, Yandex Market, Wildberries). Индексирует корпус docs/ из скрапера и отдаёт агенту opencode инструменты ранжированного поиска с фильтрами по метаданным и навигацией по секциям.

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

  • BM25-поиск по файлам документации без embeddings и внешних сервисов
  • Фильтрация по метаданным frontmatter в одном вызове: marketplace, type, archived
  • Возврат сниппетов секций вместо целых файлов — экономия контекста агента
  • Чанкинг по заголовкам H2 с объединением мелких секций
  • Идемпотентная индексация: перестройка только при изменении docs/
  • E2E-проверка инструментов и замер recall@k из коробки

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

Технология Версия Назначение
Python 3.13 Язык разработки
mcp[cli] 1.28.1 MCP SDK, транспорт stdio
rank-bm25 0.2.2 BM25-ранжирование
pyyaml 6.0.3 Парсинг frontmatter
python-dotenv 1.2.2 Загрузка переменных окружения

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

marketplaces.mcp.docs/
├── src/st_mcp_mp_docs/
│   ├── main.py              # Точка входа: запуск сервера по stdio
│   ├── server.py            # FastMCP и регистрация инструментов
│   ├── tools.py             # Реализация инструментов поверх BM25
│   ├── indexer.py           # Построение индекса: frontmatter, чанкинг, кэш
│   ├── tokenizer.py         # Токенизация camelCase/snake_case, стоп-слова
│   ├── format.py            # Сниппеты и форма результатов
│   └── config.py            # Пути и параметры из окружения
├── scripts/
│   ├── check.py             # E2E-прогон через MCP-клиент
│   └── eval.py              # Замер recall@k и MRR
├── tests/
│   └── eval_queries.jsonl   # Набор из 20 поисковых запросов
├── cache/                   # BM25-индекс и метаданные (gitignored)
├── Makefile
├── pyproject.toml
└── README.md

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

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

  • Python 3.13+
  • uv
  • Каталог docs/ скрапера marketplaces.docs.scraper

Установка

make help       # Справка по командам
make install    # Создание окружения и установка зависимостей
make index      # Построение BM25-индекса из docs/

Запуск

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",
      },
      "enabled": true,
    },
  },
}

🔧 Разработка

make index      # Построение BM25-индекса из docs/
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

👥 Команда разработки

📄 Лицензия

Проект разработан для коммерческого использования. Права защищены.

© 2026 ДонНовоТех Передовые программные и аппаратные решения для транспорта

📍 Адрес: ул. М.Горького 205, Ростов-на-Дону, 344000, Россия
📞 Телефон: +7-904-500-6087
📧 Email: leojohn@yandex.ru
🌐 Сайт: donnovotech.ru
🏢 ИНН: 6163227601

Requirements

Requires Python: >=3.13
Details
PyPI
2026-07-15 12:53:02 +03:00
6
27 KiB
Assets (2)
st_mcp_mp_docs-0.1.0-py3-none-any.whl 14 KiB
st_mcp_mp_docs-0.1.0.tar.gz 14 KiB
Versions (6) View all
0.5.0 2026-07-15
0.4.0 2026-07-15
0.3.0 2026-07-15
0.2.1 2026-07-15
0.2.0 2026-07-15