# ru-docs-mcp

«Context7 по-русски»: MCP-сервер, который отдаёт ИИ-агенту актуальную документацию российских
сервисов, а вместе с ней **грабли** - проверенные ловушки интеграции со ссылкой на первоисточник.

Агенты чаще всего ошибаются именно здесь: российских SDK мало в обучающих данных, поэтому модель
выдумывает поля, путает копейки с рублями и забывает проверить подпись вебхука.

| Платежи | Чеки 54-ФЗ | Мессенджеры | CRM | Данные, SMS, ИИ | 1С |
|---|---|---|---|---|---|
| ЮKassa, ЮMoney, CloudPayments, Robokassa, PayKeeper, Яндекс Пэй, платежи в Telegram, Т-Банк (только грабли) | OrangeData, АТОЛ Онлайн (см. ниже) | МАКС, VK API, Яндекс Мессенджер | Битрикс24, amoCRM | DaData, SMS.ru, GigaChat | БСП 3.2 (программный интерфейс общих модулей) |

## Установка

Нужен [uv](https://docs.astral.sh/uv/). Сервер работает у вас локально, внешний сервер не нужен.

```sh
claude mcp add ru-docs -s user -- uvx --from git+https://github.com/Nezeronxer/ru-docs-mcp ru-docs
```

При первом запуске сервер сам соберёт индекс в `~/.local/share/ru-docs/` (несколько минут, ~100 МБ)
и дальше раз в неделю обновляет его в фоне. Пока индекс собирается, инструменты так и отвечают.
Собрать вручную: `uvx --from git+https://github.com/Nezeronxer/ru-docs-mcp ru-docs-ingest`.

Другие клиенты (Cursor, Codex, Claude Desktop) - тот же stdio-запуск:
`uvx --from git+https://github.com/Nezeronxer/ru-docs-mcp ru-docs`.

## Инструменты

- `resolve_library(query)` - id библиотеки по названию, по-русски или по-английски: «тинькофф», «бот макс», «бсп».
- `get_docs(library_id, topic, tokens=5000)` - фрагменты документации по теме, первым блоком грабли.
- `get_gotchas(library_id, topic?)` - только грабли.

Поиск понимает словоформы (SQLite FTS5 + стемминг Snowball): «вебхук возврата» находит
«уведомления о возвратах», `PaymentId` находится по «payment id».

## Как добавить источник или граблю

- Библиотека - блок `[[library]]` в `src/ru_docs/sources.toml`. Загрузчики: `openapi`, `html`
  (`urls` / `sitemap` / `crawl`), `pdf`, `github` (`md`, `bsl`, `vk`).
- Грабля - раздел `## Заголовок` в `src/ru_docs/gotchas/<id>.md` со строками `Источник: URL` и
  `Проверено: дата`. Только то, что сверено с документацией или проверено на живой интеграции.
- Проверка: `uv run pytest`, пересборка: `uv run ru-docs-ingest <id>` или `--gotchas-only`.

## Почему у Т-Банка только грабли

developer.tbank.ru подписан корнем Минцифры (Russian Trusted Root CA). Доверять такому корню значит
разрешить подмену трафика к любому сайту, поэтому ru-docs его не подключает и проверку TLS не
отключает. Полная документация - в Context7 (`/websites/developer_tbank_ru_eacq`) или в браузере.

## Почему АТОЛ Онлайн может не собраться

С октября 2026 сайт АТОЛ (online.atol.ru -> atol.online) отвечает на любой адрес страницей
антибот-проверки вместо PDF с API. ru-docs такую проверку не обходит: сборка пропускает АТОЛ
и подхватит его, когда файл снова станет доступен. Уже собранный индекс при ошибке не затирается.

## Чего нет и почему

- СДЭК - api-docs.cdek.ru не открывается из-за рубежа (а MCP часто работает через VPN).
- Почта России (API Отправки) - спецификация рисуется JavaScript, текста в HTML нет.
- Wildberries, Ozon - документация закрыта антиботом.
- YandexGPT (AI Studio) - сайт отдаёт капчу, а репозиторий yandex-cloud/docs весит 1,2 ГБ.
- МойСклад - одностраничное приложение без текста в HTML.

## Источники и права

Индекс собирается на вашей машине из публичных страниц, ru-docs ничего не раздаёт со своего сервера.
Выдаются короткие фрагменты со ссылкой на оригинал. Не индексируются: Prodamus (robots.txt
запрещает), its.1c.ru (подписка ИТС), справка платформы 1С (лицензия 1С).
Открытые лицензии: схема МАКС - Apache-2.0, схема VK API - MIT, БСП - CC-BY-4.0 (© 1С).

Правообладателю: если источник нужно убрать - откройте issue, он будет удалён из `sources.toml`.

## Лицензия

MIT - для кода. Документация принадлежит правообладателям.