Metadata-Version: 2.4
Name: st-mcp-mp-docs
Version: 0.1.0
Summary: Локальный MCP-сервер BM25-поиска по документации API маркетплейсов
Requires-Python: >=3.13
Requires-Dist: mcp[cli]==1.28.1
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: pyyaml==6.0.3
Requires-Dist: rank-bm25==0.2.2
Provides-Extra: dev
Requires-Dist: ruff==0.15.17; extra == 'dev'
Requires-Dist: ty==0.0.49; extra == 'dev'
Description-Content-Type: text/markdown

# MCP Marketplaces Docs

[![Python 3.13](https://img.shields.io/badge/Python-3.13-3776AB?style=flat&logo=python)](https://python.org/)
[![MCP](https://img.shields.io/badge/mcp%5Bcli%5D-1.28.1-000000?style=flat)](https://github.com/modelcontextprotocol/python-sdk)
[![rank-bm25](https://img.shields.io/badge/rank--bm25-0.2.2-3776AB?style=flat)](https://github.com/dorianbrown/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`

### Установка

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

### Запуск

```bash
make serve      # Запуск MCP-сервера (stdio)
```

Регистрация в opencode — секция `mcp` в `opencode.json`:

```jsonc
{
  "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,
    },
  },
}
```

## 🔧 Разработка

```bash
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
```

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

- **Станислав** ([@stanislavbajkov2](mailto:stanislavbajkov2@gmail.com))

## 📄 Лицензия

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

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

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