Skip to content
Back to search

ru-marketplace-mcp

ru-marketplace-mcp для Claude Code: 12 маркетплейсов РФ и Китая и недвижимость Циан как MCP-серверы и 14 навыков без ключей API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vladimir-human--ru-marketplace-mcp/badge.svg)](/listings/vladimir-human--ru-marketplace-mcp)

HTML

<a href="/listings/vladimir-human--ru-marketplace-mcp"><img src="/api/listings/vladimir-human--ru-marketplace-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
  3. "name": "ru-marketplace-mcp",
  4. "owner": {"name": "Vladimir-Human", "url": "https://github.com/Vladimir-Human"},
  5. "description": "ru-marketplace-mcp для Claude Code: 12 маркетплейсов РФ и Китая и недвижимость Циан как MCP-серверы и 14 навыков без ключей API.",
  6. "plugins": [
  7. {
  8. "name": "ru-marketplace-mcp",
  9. "source": "./",
  10. "description": "Двенадцать площадок РФ и Китая (Wildberries, Ozon, Яндекс Маркет, Авито, Циан, AliExpress, Taobao, Детский мир, Мегамаркет, Lamoda, DNS, Ситилинк) как MCP-серверы и 14 навыков. Сравнение цен без ключей API.",
  11. "version": "2.11.0",
  12. "license": "MIT",
  13. "keywords": ["mcp", "wildberries", "ozon", "yandex-market", "avito", "cian", "aliexpress", "taobao", "price-comparison", "russia"]
  14. }
  15. ]
  16. }
README.md · README · 555 lines
  1. # ru-marketplace-mcp — MCP-серверы для маркетплейсов России и Китая
  2. <!-- mcp-name: io.github.Vladimir-Human/ru-marketplace-mcp -->
  3. **Русский** · [English](README.en.md) · [Установка для ИИ-агентов](llms-install.md) · [llms.txt](llms.txt)
  4. [![CI](https://github.com/Vladimir-Human/ru-marketplace-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Vladimir-Human/ru-marketplace-mcp/actions/workflows/ci.yml)
  5. [![PyPI](https://img.shields.io/pypi/v/ru-marketplace-mcp.svg)](https://pypi.org/project/ru-marketplace-mcp/)
  6. [![npm](https://img.shields.io/npm/v/ru-marketplace-mcp-dsh.svg?label=npm%20%28dsh%29)](https://www.npmjs.com/package/ru-marketplace-mcp-dsh)
  7. [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
  8. [![MCP](https://img.shields.io/badge/MCP-stdio%20%7C%20http-orange.svg)](https://modelcontextprotocol.io)
  9. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  10. Живые цены, остатки, рейтинги, отзывы и реквизиты продавцов с 12 площадок РФ и
  11. Китая: **Wildberries**, **Ozon**, **Яндекс Маркет**, **Авито**, **AliExpress**,
  12. **Taobao**, **DNS**, **Ситилинк**, **Мегамаркет**, **Lamoda**, **Детский мир** и
  13. недвижимость с **Циана**.
  14. `compare_prices` сравнивает цены по всем товарным площадкам одним вызовом,
  15. отсеивает флешки и чехлы по цене смартфона (`cheapest_comparable`) и не выдаёт
  16. скидку по WB Кошельку, Яндекс Пэй или купону за обычную цену. Только чтение, без
  17. ключей API и кабинета продавца: открытые площадки отвечают по HTTP, закрытые
  18. анти-ботом — через ваш отдельный Chrome (для Taobao и Мегамаркета в нём нужен
  19. обычный покупательский вход).
  20. <p align="center">
  21. <img src="docs/assets/demo-compare.svg" width="560"
  22. alt="compare_prices(&quot;iphone 16 128gb&quot;): флешка 1 531 ₽ и цена по WB Кошельку 56 833 ₽ не побеждают; лидер comparable — Apple iPhone 16 за 64 990 ₽ на AliExpress">
  23. </p>
  24. <sub>Реальный разбор из раздела <a href="#настоящий-ответ">«Настоящий ответ»</a> (`c1-iphone16-128gb.json`).</sub>
  25. ## Быстрый старт
  26. Нужны **Python 3.12+** и [uv](https://docs.astral.sh/uv/). Клонировать репозиторий
  27. не нужно: одна команда скачает пакет с PyPI, найдёт установленные MCP-клиенты и
  28. настроит подключение (`--dry-run` только покажет план):
  29. ```bash
  30. uvx ru-marketplace-mcp setup
  31. ```
  32. Или установка в один клик:
  33. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=marketplace&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22ru-marketplace-mcp%22%2C%22compare-mcp%22%5D%7D)
  34. [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000?logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=marketplace&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJydS1tYXJrZXRwbGFjZS1tY3AiLCJjb21wYXJlLW1jcCJdfQ==)
  35. Для **Claude Desktop** без терминала — бандл `ru-marketplace-mcp-compare-<версия>.mcpb` в [GitHub Releases](https://github.com/Vladimir-Human/ru-marketplace-mcp/releases) (проверено на Windows, на macOS не проверялось).
  36. ### Какой профиль выбрать
  37. Описания подключённых инструментов уходят модели в каждом запросе, поэтому
  38. `setup` и `install` по умолчанию ставят компактный профиль `compare`:
  39. | Профиль | Объём | Когда выбирать |
  40. | --- | --- | --- |
  41. | **`compare`** *(по умолч.)*<br>`compare-mcp` | 4 · ≈1.7k | Сравнить цены по площадкам и проверить карточку лидера |
  42. | **`decision`**<br>`decision-mcp` | 5 · ≈2.0k | Всё из `compare` плюс осмотр шортлиста с отзывами |
  43. | **`full`**<br>`marketplace-mcp` | 39 · ≈13.1k | Прямой поиск, отзывы, продавцы, категории и Циан |
  44. | Одна площадка<br>`--per-source` | 2–8 · мин. | Нужен только один маркетплейс |
  45. > **Безопасность и границы:** не включайте эти серверы в одну сессию агента с инструментами, которые читают личные данные и могут отправить их наружу без вашего подтверждения, и держите отдельный профиль Chrome без почты и банка ([SECURITY.md](SECURITY.md)).
  46. [Первый успешный запрос](docs/QUICKSTART.md) · [Справочник инструментов](docs/TOOLS.md) ·
  47. [Архитектура](docs/ARCHITECTURE.md) · [Про анти-бот](docs/ANTI_BOT.md)
  48. ---
  49. ## Поддерживаемые площадки (12 источников)
  50. | Площадка | Доступ | Что умеет |
  51. | --- | --- | --- |
  52. | **Wildberries** (8) | HTTP (403 → Chrome) | Поиск, карты, отзывы, Q&A, seller ID, каталог |
  53. | **Яндекс Маркет** (2) | прямой HTTP | Цены и отзывы, оценки по звёздам |
  54. | **Детский мир** (3) | прямой HTTP | Детские товары, остатки, каталог |
  55. | **Ozon** (3) | Chrome / HTTP | Поиск, карты, отзывы |
  56. | **Авито** (3) | Chrome + паузы | Лоты, карты, рейтинг продавца |
  57. | **Taobao** (2) | Chrome + вход | Поиск, карты, цены в юанях |
  58. | **Мегамаркет** (2) | Chrome + вход | Поиск и карты через API |
  59. | **Lamoda** (2) | HTTP → Chrome | Поиск, карты, размеры |
  60. | **DNS** (2) | Chrome (Qrator) | Поиск и карты техники |
  61. | **Ситилинк** (2) | Chrome (Qrator) | Поиск и карты техники |
  62. | **AliExpress** (2) | Chrome (x5sec) | Поиск и карты в рублях |
  63. | **Циан** (2) | Chrome (WAF IP) | Жильё: продажа, аренда, сутки |
  64. | **Сравнение** (4) | по площадкам | «Где дешевле?», сверка, снимок |
  65. Без браузера работают Wildberries, Яндекс Маркет и Детский мир (если API
  66. Wildberries отвечает 403, поиск и карточки сами перечитываются через ваш Chrome).
  67. Карточки Lamoda сначала идут по HTTP GraphQL и обращаются к Chrome (CDP) только
  68. при отказе. Остальным нужен ваш Chrome с CDP, а Taobao и Мегамаркету — ещё и вход
  69. в аккаунт площадки: без него Taobao упирается в страницу входа, а Мегамаркет
  70. возвращает пустую выдачу. Авито режет датацентровые адреса и отвечает с обычного
  71. (не облачного) подключения при спокойном темпе запросов. К браузерным источникам
  72. коннекторы ходят с паузой: очередь без передышки роняет сессию (так на проверках
  73. отваливались DNS и Taobao). Точное состояние из вашей среды покажет
  74. `marketplace-mcp doctor`.
  75. Аналитика MPStats переехала на официальный MCP-сервер MPStats (`https://mcp.mpstats.io/mcp?token=<ваш токен MPStats>`) и в текущий состав `ru-marketplace-mcp` не входит.
  76. Всего 37 инструментов в 13 серверах на общем рантайме `mcp-core`, плюс
  77. промежуточный `decision-mcp` (5 инструментов) и объединённый `marketplace-mcp`,
  78. который монтирует всё под одной записью в конфиге клиента и добавляет два своих
  79. инструмента — `marketplace_sources` (какие коннекторы поднялись, а какие
  80. пропущены и почему) и `marketplace_health` (жив ли Chrome, какие хосты остывают,
  81. какую страницу открыть человеку) — итого 39 инструментов.
  82. ### Настоящий ответ
  83. `compare_prices(query="iphone 16 128gb")`. Ответы площадок записаны в Chrome на машине владельца 17 ноября 2026 года в 01:29 UTC (аудит, цикл 1, запись [c1-iphone16-128gb.json](packages/compare-connector/tests/benchmark/recordings/c1-iphone16-128gb.json)) и пропущены через код `2.11.0` (коммит `f39a786f`). Ниже оставлены ключевые поля и по одному предупреждению каждого типа; полный ответ ещё содержит `source_outcomes` и все 25 предложений в `offers`.
  84. ```json
  85. {
  86. "query": "iphone 16 128gb",
  87. "sources_queried": [
  88. "aliexpress", "citilink", "dns",
  89. "taobao", "wildberries", "yandex_market"
  90. ],
  91. "sources_ok": [
  92. "aliexpress", "dns", "taobao", "wildberries", "yandex_market"
  93. ],
  94. "complete": false,
  95. "total_offers": 25,
  96. "cheapest": {
  97. "source": "aliexpress",
  98. "product_id": "1005009110731940",
  99. "title": "MOVESPEED флешка USB Type C 64/128/256/512 ГБ",
  100. "price_rub": 1531.0,
  101. "currency": "rub",
  102. "rating": 4.8,
  103. "url": "https://aliexpress.ru/item/1005009110731940.html"
  104. },
  105. "cheapest_comparable": {
  106. "source": "aliexpress",
  107. "product_id": "1005008110020734",
  108. "title": "Смартфон Apple iPhone 16, 8/128ГБ",
  109. "price_rub": 64990.0,
  110. "currency": "rub",
  111. "rating": 5.0,
  112. "url": "https://aliexpress.ru/item/1005008110020734.html"
  113. },
  114. "price_spread_rub": 93459.0,
  115. "warnings": [
  116. "partial: 1 of 6 marketplaces did not answer (citilink) ...",
  117. "conditional_price: wildberries/1415238452: 56833 RUB requires WB Wallet; not ranked",
  118. "info:conditional_price_available: yandex_market/103530694148: 72825 RUB with Yandex Pay",
  119. "price_outlier: the cheapest offer is 1531.0 ₽ against a median of 70299.0 ₽ across 17 offers ...",
  120. "comparable_price: the raw cheapest listing is an accessory, a different condition, variant or model; cheapest_comparable is the safer like-for-like candidate",
  121. "foreign_currency: 5 offer(s) are priced in cny, not roubles ... excluded from the ranking"
  122. ],
  123. "server_version": "2.11.0"
  124. }
  125. ```
  126. <details>
  127. <summary>Полный список <code>warnings</code> из этой записи (15 строк)</summary>
  128. ```json
  129. [
  130. "partial: 1 of 6 marketplaces did not answer (citilink) — prices below cover only aliexpress, dns, taobao, wildberries, yandex_market",
  131. "source_warning:aliexpress: 2 tile(s) advertise a coupon price; price_rub carries the regular price and the coupon value is not part of the response — treat 'cheapest' ranking with care",
  132. "source_warning:wildberries: dom_fallback: WB API refused this address (HTTP 403); read through the scraping Chrome, in the WB region set in that browser rather than dest",
  133. "source_warning:wildberries: wb_dom_search: price_rub is the WB Wallet price on search tiles (the regular card price is equal or a few % higher and shows only on the product page — verify leaders with wb_card)",
  134. "conditional_price: wildberries/1415238452: 56833 RUB requires WB Wallet; not ranked",
  135. "conditional_price: wildberries/580725150: 76922 RUB requires WB Wallet; not ranked",
  136. "conditional_price: wildberries/580725161: 76922 RUB requires WB Wallet; not ranked",
  137. "info:conditional_price_available: yandex_market/103572173063: 71800 RUB with Yandex Pay",
  138. "info:conditional_price_available: yandex_market/103530694148: 72825 RUB with Yandex Pay",
  139. "info:conditional_price_available: yandex_market/4775394349: 68107 RUB with Yandex Pay",
  140. "info:conditional_price_available: yandex_market/5302780524: 66699 RUB with Yandex Pay",
  141. "info:conditional_price_available: yandex_market/4775394347: 69323 RUB with Yandex Pay",
  142. "price_outlier: the cheapest offer is 1531.0 ₽ against a median of 70299.0 ₽ across 17 offers — check it is the same product and configuration",
  143. "comparable_price: the raw cheapest listing is an accessory, a different condition, variant or model; cheapest_comparable is the safer like-for-like candidate",
  144. "foreign_currency: 5 offer(s) are priced in cny, not roubles — their price is in price_native and they are excluded from the ranking and from cheapest"
  145. ]
  146. ```
  147. </details>
  148. Самым дешёвым формально оказалась флешка: в её названии есть «128». Поэтому ответ отдельно называет `cheapest_comparable`, то есть сам телефон, и предупреждает о выбросе цены. Цена Wildberries, которая действует только с WB Кошельком, показана, но в сравнении не участвует. Ситилинк в этом вызове ответил отказом, и ответ говорит, что он неполный.
  149. ## Подключение к MCP-клиенту
  150. Самый короткий путь — `uvx ru-marketplace-mcp setup` (или `uv run marketplace-mcp setup`
  151. из клона репозитория): команда находит установленные клиенты (**Claude Desktop**,
  152. **Cursor**, **Claude Code**, **VS Code**, **Windsurf**, **Antigravity**,
  153. **Gemini CLI**, **Codex CLI**), прописывает профиль `compare`, запускает
  154. отдельный Chrome для парсинга, проверяет источники через `doctor` и предлагает
  155. `unblock`, если площадка просит вход или капчу (`--dry-run` только показывает
  156. шаги и файлы; `--no-browser` и `--no-doctor` пропускают браузер и сетевые вызовы).
  157. Настроить один конкретный клиент (поддерживаются все **9 целей**):
  158. ```console
  159. uvx ru-marketplace-mcp install <client> --write --profile compare
  160. ```
  161. | Клиент (`<client>`) | Что обновляет `--write` |
  162. | --- | --- |
  163. | **Claude Desktop**<br>`claude` | `mcpServers.marketplace` в конфиге Claude Desktop + `.bak`; есть и `.mcpb` в [Releases](https://github.com/Vladimir-Human/ru-marketplace-mcp/releases) |
  164. | **Cursor**<br>`cursor` | `mcpServers.marketplace` в `~/.cursor/mcp.json` + `.bak` |
  165. | **VS Code**<br>`vscode` | **`servers.marketplace`** (`"type": "stdio"`) в `Code/User/mcp.json` + `.bak` |
  166. | **Windsurf**<br>`windsurf` | `mcpServers.marketplace` в конфиге Windsurf + `.bak` |
  167. | **Antigravity**<br>`antigravity` | `mcpServers.marketplace` в конфиге Antigravity + `.bak` |
  168. | **Gemini CLI**<br>`gemini` | `mcpServers.marketplace` в `~/.gemini/settings.json` + `.bak` |
  169. | **Claude Code**<br>`claude-code` | Печатает `claude mcp add marketplace --scope user -- ...` |
  170. | **Codex CLI**<br>`codex` | Печатает `codex mcp add marketplace -- ...` |
  171. | **DeepSeek Harness**<br>`dsh` | Печатает `cordis.patch.yml` (плагин — в спойлере и [dsh/README.md](dsh/README.md)) |
  172. <sub>Пути конфигов: **Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json` (Win), `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `~/.config/Claude/claude_desktop_config.json` (Linux); **Windsurf** — `~/.codeium/windsurf/mcp_config.json`; **Antigravity** — `~/.gemini/config/mcp_config.json`. Перед записью создаётся копия `.bak-&lt;метка&gt;`.</sub>
  173. По умолчанию ставится профиль `compare` (`compare-mcp`). `--profile decision`
  174. переключает запись на `decision-mcp`, `--profile full` — на полный
  175. `marketplace-mcp` (при перезаписи существующей записи добавьте `--force`;
  176. `--write --dry-run` показывает дифф без записи; `--per-source` печатает или
  177. пишет отдельные серверы по площадкам и с `--profile` не сочетается). Неизвестное
  178. имя клиента команда отклоняет с кодом возврата `2`.
  179. Управление браузером и разблокировкой:
  180. - `marketplace-mcp browser start` — запустить отдельный Chrome для парсинга (по умолчанию окно видно, `--hidden` — за экраном);
  181. - `marketplace-mcp browser status` — доступен ли CDP, версия Chrome, вкладки и положение окна;
  182. - `marketplace-mcp browser show` — вывести окно на экран (на Windows автозапуск паркует его за экраном);
  183. - `marketplace-mcp unblock <source>` — открыть страницу входа или проверки в новой вкладке, подождать, пока вы пройдёте её сами, и перепроверить только этот источник (капчу за человека команды не решают).
  184. <details>
  185. <summary><b>Ручная настройка JSON и выбор площадок (<code>MARKETPLACE_SOURCES</code>)</b></summary>
  186. Для клиентов с `mcpServers` (Claude Desktop, Cursor, Windsurf, Antigravity, Gemini CLI, Cline, OpenCode) без клона репозитория:
  187. ```json
  188. {
  189. "mcpServers": {
  190. "marketplace": {
  191. "command": "uvx",
  192. "args": ["--from", "ru-marketplace-mcp", "compare-mcp"]
  193. }
  194. }
  195. }
  196. ```
  197. Для **VS Code** (`Code/User/mcp.json` использует корневой ключ `"servers"` и `"type": "stdio"`):
  198. ```json
  199. {
  200. "servers": {
  201. "marketplace": {
  202. "type": "stdio",
  203. "command": "uvx",
  204. "args": ["--from", "ru-marketplace-mcp", "compare-mcp"]
  205. }
  206. }
  207. }
  208. ```
  209. Из локального клона (пути с прямыми слешами `/` или двойными обратными `\\`):
  210. ```json
  211. {
  212. "mcpServers": {
  213. "marketplace": {
  214. "command": "uv",
  215. "args": ["run", "--directory", "C:/путь/к/ru-marketplace-mcp", "compare-mcp"]
  216. }
  217. }
  218. }
  219. ```
  220. Полный список из 15 консольных точек входа: `wb-mcp`, `ozon-mcp`, `yandex-mcp`,
  221. `detmir-mcp`, `avito-mcp`, `taobao-mcp`, `megamarket-mcp`, `lamoda-mcp`,
  222. `dns-mcp`, `citilink-mcp`, `aliexpress-mcp`, `cian-mcp`, `compare-mcp`,
  223. `decision-mcp`, `marketplace-mcp`. Все серверы общаются по JSON-RPC через stdin
  224. и stdout, а диагностику пишут в stderr.
  225. ### Только нужные площадки в полном режиме: `MARKETPLACE_SOURCES`
  226. Объединённый `marketplace-mcp` монтирует все источники сразу. Переменная
  227. `MARKETPLACE_SOURCES` оставляет только перечисленные и экономит контекст:
  228. ```json
  229. {
  230. "mcpServers": {
  231. "marketplace": {
  232. "command": "uv",
  233. "args": ["run", "--directory", "C:/путь/к/ru-marketplace-mcp", "marketplace-mcp"],
  234. "env": {
  235. "MARKETPLACE_SOURCES": "wildberries,ozon,yandex_market,avito,aliexpress,dns,compare"
  236. }
  237. }
  238. }
  239. }
  240. ```
  241. Имена канонические (`wildberries`, `ozon`, `yandex_market`, `detsky_mir`,
  242. `avito`, `taobao`, `megamarket`, `lamoda`, `dns`, `citilink`, `aliexpress`,
  243. `cian`, `compare`); короткие псевдонимы `wb`, `ym`/`yandex`, `detmir`, `ali`
  244. тоже принимаются. Опечатка в имени остановит старт сервера со списком допустимых
  245. площадок. Отключённые источники видны в `marketplace_sources` в поле `skipped`.
  246. `compare_prices` опрашивает только выбранные товарные источники с текстовым
  247. поиском (Детский мир и Циан туда не входят); явный `sources` для отключённой
  248. площадки вернёт `bad_request`.
  249. </details>
  250. <details>
  251. <summary><b>Claude Code</b> — плагин с 14 навыками или <code>claude mcp add</code></summary>
  252. Установка плагина (14 навыков + MCP) одной командой:
  253. ```text
  254. /plugin install ru-marketplace-mcp --marketplace Vladimir-Human/ru-marketplace-mcp
  255. ```
  256. Или подключение компактного профиля `compare-mcp` через CLI:
  257. ```bash
  258. claude mcp add marketplace --scope user -- uvx --from ru-marketplace-mcp compare-mcp
  259. ```
  260. </details>
  261. <details>
  262. <summary><b>DeepSeek Harness (dsh)</b> — плагин-бандл</summary>
  263. В dsh это не запись `mcpServers`, а слой профиля. Бандл лежит в подкаталоге
  264. [`dsh/`](dsh/README.md) и ставится штатным менеджером плагинов (`pnpm` нужен на PATH):
  265. ```console
  266. dsh plugin --profile web add ru-marketplace-mcp-dsh
  267. # или напрямую из GitHub:
  268. dsh plugin --profile web add github:Vladimir-Human/ru-marketplace-mcp#path:/dsh
  269. ```
  270. Сразу после установки появляются 14 навыков и **ни одного** MCP-инструмента: все три
  271. строки MCP выключены, пока не задана переменная `RU_MARKETPLACE_MCP_DIR` с путём к
  272. клону.
  273. <!-- tools-cost:start -->
  274. Так сделано потому, что смонтированный сервер платится в каждом запросе:
  275. рекомендуемый режим сравнения цен стоит ≈1.7k токенов, режим с инспекцией
  276. карточки — ≈2.0k, полный набор — ≈13.1k (оценка по `tools/list`;
  277. подробности в [docs/TOOLS.md](docs/TOOLS.md)).
  278. <!-- tools-cost:end -->
  279. Включение и полный режим описаны в [dsh/README.md](dsh/README.md).
  280. </details>
  281. После подключения перезапустите клиент и проверьте доступность источников
  282. командой `marketplace-mcp doctor` (подробнее в [docs/QUICKSTART.md](docs/QUICKSTART.md)):
  283. код `0` — выбранные проверки здоровы, `1` — дрейф парсера, `2` — площадка
  284. закрыта анти-ботом, ждёт Chrome/входа или лимита бюджета (`budget_refused`), `3` —
  285. не записался `--status-file`, `4` — сбой самой проверки или неверные аргументы.
  286. Тревогу поднимают коды `1` и `4`, а при `2` следуйте подсказке `next:` в выводе.
  287. ## Инструменты
  288. Сгенерированный справочник по инструментам с параметрами и ценой контекста:
  289. [docs/TOOLS.md](docs/TOOLS.md).
  290. Канарейки `*_selfcheck` в этом перечне не значатся намеренно: они не публикуются
  291. по MCP, потому что диагностика оператора стоила бы модели ~7,5 тыс. токенов в
  292. каждом запросе. Запускает их `marketplace-mcp doctor` — все разом, из командной
  293. строки.
  294. Подробно по каждой площадке, с таблицами инструментов и примерами, — в
  295. [docs/TOOLS.ru.md](docs/TOOLS.ru.md):
  296. - [Wildberries — `wb_*`](docs/TOOLS.ru.md#wildberries--wb_)
  297. - [Яндекс Маркет — `yandex_*`](docs/TOOLS.ru.md#яндекс-маркет--yandex_)
  298. - [Детский мир — `detmir_*`](docs/TOOLS.ru.md#детский-мир--detmir_)
  299. - [Ozon — `ozon_*`](docs/TOOLS.ru.md#ozon--ozon_)
  300. - [Авито — `avito_*`](docs/TOOLS.ru.md#авито--avito_)
  301. - [Taobao — `taobao_*`](docs/TOOLS.ru.md#taobao--taobao_)
  302. - [Мегамаркет, Lamoda, DNS, Ситилинк](docs/TOOLS.ru.md#мегамаркет-lamoda-dns-ситилинк)
  303. - [AliExpress — `aliexpress_*`](docs/TOOLS.ru.md#aliexpress--aliexpress_)
  304. - [Циан — `cian_*`](docs/TOOLS.ru.md#циан--cian_)
  305. - [Сравнение цен — `compare_*`](docs/TOOLS.ru.md#сравнение-цен--compare_)
  306. ## Навыки для агента
  307. У каждого коннектора — свой навык в `skills/`: четырнадцать штук, по одному
  308. на источник плюс общий `marketplace`. Навык это не пересказ README: он объясняет агенту, когда за этот
  309. источник вообще браться, чего у источника нет, и каким его ответам нельзя верить
  310. без второго взгляда.
  311. | Навык | Сервер |
  312. | ----------------------------- | ----------------- |
  313. | `skills/wb-connector` | `wb-mcp` |
  314. | `skills/ozon-connector` | `ozon-mcp` |
  315. | `skills/yandex-connector` | `yandex-mcp` |
  316. | `skills/detmir-connector` | `detmir-mcp` |
  317. | `skills/avito-connector` | `avito-mcp` |
  318. | `skills/taobao-connector` | `taobao-mcp` |
  319. | `skills/megamarket-connector` | `megamarket-mcp` |
  320. | `skills/lamoda-connector` | `lamoda-mcp` |
  321. | `skills/dns-connector` | `dns-mcp` |
  322. | `skills/citilink-connector` | `citilink-mcp` |
  323. | `skills/aliexpress-connector` | `aliexpress-mcp` |
  324. | `skills/cian-connector` | `cian-mcp` |
  325. | `skills/compare-prices` | `compare-mcp` |
  326. | `skills/marketplace` | `marketplace-mcp` |
  327. `mcp-core` — общий рантайм под остальными серверами. Своего навыка у него нет.
  328. Соответствие проверяется тестом
  329. ([test_skills_parity.py](packages/marketplace-connector/tests/test_skills_parity.py)): новый коннектор
  330. без навыка роняет прогон, как и навык, который называет несуществующий
  331. инструмент или забыл существующий. До этого теста навык DNS почти год советовал
  332. формат ссылки `/product/<24-hex>/` — тот самый шаблон, который чинили как баг.
  333. Скиллы едут в Docker-образ (`/app/skills/`), но в колёсах их нет: `skills/`
  334. лежит в корне репозитория. При установке release-wheel или пакета
  335. `ru-marketplace-mcp` с PyPI возьмите навыки из репозитория отдельно.
  336. ## Настройка
  337. Все параметры задаются переменными окружения с префиксом коннектора. Все
  338. необязательные.
  339. При проверке в браузере `CHROME_CHALLENGE_HANDOFF_S=120` придерживает открытую
  340. вкладку: когда вы пройдёте проверку, повтор того же запроса от того же клиента
  341. (в той же MCP-сессии или к тому же stdio-процессу сервера) дочитает эту вкладку
  342. без новой навигации. Поддержка и ограничения описаны в
  343. [настройке Chrome](docs/CDP_SETUP.md#optional-challenge-handoff).
  344. | Префикс | Основные параметры |
  345. | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
  346. | `WB_` | `TIMEOUT`, `MIN_GAP`, `DEFAULT_DEST`, `NET_RETRIES`, `MAX_BODY_BYTES`, `CACHE_TTL`, `PROXY`, `TRANSPORT`, `DOM_FALLBACK` |
  347. | `YANDEX_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL`, `PROXY` |
  348. | `DETMIR_` | `REGION` (`RU-MOW`, `RU-SPE` и другие), `CACHE_TTL`, `PROXY` |
  349. | `OZON_` | `TIMEOUT`, `MIN_GAP`, `IMPERSONATE`, `CACHE_TTL`, `PROXY`, `CHROME_COMPAT` |
  350. | `AVITO_` | `TIMEOUT`, `MIN_GAP`, `IMPERSONATE`, `CACHE_TTL`, `PROXY`, `LOCATION_ID` |
  351. | `TAOBAO_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL` |
  352. | `ALI_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL` |
  353. | `MEGAMARKET_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL`, `USE_PROFILE_ADDRESS` (0/1, по умолчанию 0 — приватный список адресов профиля не читается; 1 = адрес по умолчанию из залогиненного профиля, цены «как видит оператор») |
  354. | `LAMODA_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL`, `PROXY` |
  355. | `DNS_` / `CITILINK_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL` |
  356. | `CIAN_` | `TIMEOUT`, `MIN_GAP`, `CACHE_TTL`, `MAX_BODY_BYTES`, `REGION` |
  357. | `CHROME_` | `CDP_HOST`, `CDP_PORT`, `SCRAPING_PROFILE`, `BINARY`, `HEADLESS`, `STEALTH`, `NAV_TIMEOUT_MS`, `CHALLENGE_HANDOFF_S` |
  358. | `COMPARE_` | `SOURCE_TIMEOUT` |
  359. | `MCP_` | `TRANSPORT` (`stdio` по умолчанию, либо `http`), `HTTP_HOST`, `HTTP_PORT` |
  360. `CHROME_CDP_HOST` указывает, куда дозвониться CDP-клиенту (по умолчанию
  361. `127.0.0.1`). Из контейнера ставьте `chrome` (сайдкар) или `host.docker.internal`
  362. — это открывает tier-2 источники (Ozon, Авито, Taobao, Мегамаркет, Lamoda,
  363. DNS, Ситилинк, AliExpress, Циан) в Docker без host networking. Подробности в
  364. [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
  365. `*_CACHE_TTL=0` выключает кэш. `*_PROXY` перекрывает стандартные `HTTPS_PROXY` и
  366. `ALL_PROXY` — свой префикс есть у шести коннекторов: `WB_`, `YANDEX_`, `DETMIR_`,
  367. `OZON_`, `AVITO_` и `LAMODA_`. У Taobao своего нет намеренно: поиск там
  368. подписан и ходит через собственный клиент. У Мегамаркета, DNS и Ситилинка тоже нет:
  369. их трафик идёт через ваш Chrome, а его egress — дело настроек браузера. Кэшируются
  370. только удачные ответы: запомнить сбой значило бы растянуть секундную помеху на весь
  371. TTL.
  372. У Ozon прокси применяется к первому уровню. Второй идёт через ваш собственный Chrome,
  373. и его трафик — дело настроек этого браузера.
  374. ## Разработка
  375. ```bash
  376. git clone https://github.com/Vladimir-Human/ru-marketplace-mcp.git
  377. cd ru-marketplace-mcp
  378. uv sync --all-packages
  379. uv run pytest -q -m "not live and not cdp" # офлайн-тесты, сеть не нужна (то, что гоняет CI)
  380. uv run pytest -q -m "not live and not cdp" --cov --cov-fail-under=80 # покрытие, порог 80% в CI
  381. uv run ruff check . && uv run ruff format --check .
  382. uv run mypy # что проверять — в [tool.mypy] files
  383. uv run mypy --platform win32 # ловит ошибки, видимые только на Windows
  384. uv run python scripts/check_no_print.py # запись в stdout ломает JSON-RPC
  385. uv run python scripts/check_versions.py # единая версия во всех отслеживаемых файлах
  386. ```
  387. Публикация на PyPI (для владельца): [DEPLOYMENT.md — PyPI](docs/DEPLOYMENT.md#pypi-maintainer). Справочник по устройству добавления коннектора — [docs/ADDING_A_SOURCE.md](docs/ADDING_A_SOURCE.md).
  388. Проверка живого эндпоинта:
  389. ```bash
  390. uv run python -c "
  391. import asyncio
  392. from wb_connector.server import wb_selfcheck
  393. print(asyncio.run(wb_selfcheck()).status) # ждём success
  394. "
  395. ```
  396. Часть тестов прогоняет **настоящий JS-экстрактор коннектора** по снятой разметке
  397. и проверяет результат против цен, которые в тот момент были на странице. Для
  398. этого нужен Node с jsdom:
  399. ```bash
  400. npm install jsdom # либо NODE_PATH на уже установленный
  401. uv run pytest -q packages/dns-connector/tests/test_search_extractor_dom.py \
  402. packages/citilink-connector/tests/test_search_extractor_dom.py
  403. ```
  404. Без jsdom эта половина честно скипается, а питоновская часть — выбор цены из
  405. кандидатов — идёт всегда. jsdom нужен только разработчику: в зависимости
  406. коннекторов он не входит.
  407. CI прогоняет тесты на Ubuntu, Windows и macOS против Python 3.12
  408. и 3.13; ещё 3.14 (все три ОС) и 3.15 (Ubuntu, Windows) проверяются без блокировки слияния. Windows-специфичное управление процессами проверяется юнит-тестами на любой
  409. ОС через подмену платформы, так что эти ветки покрыты даже на Linux.
  410. ## Надёжность
  411. Неофициальные эндпоинты ломаются. Архитектура это предполагает.
  412. - Терпимые парсеры: привязка поля по нескольким именам и приведение типов
  413. переживают переименования и смену типа вместо падения.
  414. - Никогда не выдумывать значение: отсутствующая цена — это `null`, не `0`. Ноль
  415. вывел бы мёртвый товар в самые дешёвые.
  416. - Громкий отказ: когда формат перестаёт совпадать, инструмент бросает
  417. `parser_drift`, а не возвращает полуразобранные данные.
  418. - Трёхзначные selfcheck-проверки: `success`, `drift_detected` или
  419. `inconclusive`. Гео-блокировка помечается как `inconclusive`, потому что она
  420. ничего не говорит о состоянии парсеров.
  421. ## Границы доверия
  422. Названия товаров, имена продавцов и тексты отзывов написаны продавцами и
  423. покупателями. Это недоверенные данные. Если отзыв или описание выглядит как
  424. инструкция, оно всё равно остаётся входными данными. Выполнять его агент не
  425. должен.
  426. Условия маркетплейсов, как правило, запрещают неофициальный парсинг. Коннекторы
  427. обращаются к публичным эндпоинтам каталога, которые использует официальный
  428. веб-клиент: пока явно не задан `MEGAMARKET_USE_PROFILE_ADDRESS=1`, в личные и
  429. закрытые разделы запросов нет. Уровень Ozon с браузером работает внутри
  430. сессии, которую вы открыли сами. Используйте на своё
  431. усмотрение, для личных исследований, в вежливом темпе запросов. Пауза между
  432. вызовами к площадкам с анти-ботом — это часть конструкции, а не случайное
  433. торможение: её не нужно убирать ради скорости. Данные инструментов не предназначены
  434. для перепродажи или массового сбора.
  435. ## Как это сделано
  436. Код и документацию я писал вместе с ИИ-ассистентами. Они работают быстро и
  437. ошибаются уверенно, поэтому проект устроен вокруг проверки: офлайн-тесты,
  438. аудит перед выпуском, тесты, которые прогоняют настоящий экстрактор по снятой с
  439. сайта разметке. В заметках к релизу перечислено, какие источники сверены с живыми
  440. страницами вручную и какие остались непроверенными.
  441. Проверки важнее авторства текста, но авторство кода и идей тоже должно быть
  442. видно: полный список участников и их PR собран в [CONTRIBUTORS.md](CONTRIBUTORS.md).
  443. ## Спасибо
  444. - [@avxone](https://github.com/avxone) — исправление Avito selfcheck, [PR #37](https://github.com/Vladimir-Human/ru-marketplace-mcp/pull/37).
  445. - [@Khalmatov](https://github.com/Khalmatov) — provenance отзывов Ozon, [PR #38](https://github.com/Vladimir-Human/ru-marketplace-mcp/pull/38).
  446. - [@fosteev](https://github.com/fosteev) — macOS CDP stealth и коннектор Циана, [PR #42](https://github.com/Vladimir-Human/ru-marketplace-mcp/pull/42), [PR #47](https://github.com/Vladimir-Human/ru-marketplace-mcp/pull/47).
  447. - [@ilodezis](https://github.com/ilodezis) — выбор источников unified-сервера через `MARKETPLACE_SOURCES`, [PR #48](https://github.com/Vladimir-Human/ru-marketplace-mcp/pull/48).
  448. - [@HeckfyCU](https://github.com/HeckfyCU) — замеры навигации AliExpress в [issue #190](https://github.com/Vladimir-Human/ru-marketplace-mcp/issues/190): по его замерам найден и исправлен предел ожидания страницы.
  449. - [@XaruStar](https://github.com/XaruStar) — разбор живого ответа Ozon `webListReviews` со строковым `itemId`, [issue #214](https://github.com/Vladimir-Human/ru-marketplace-mcp/issues/214): по нему исправлен учёт `own_reviews` и проверка `item_id` в `ozon_selfcheck`.
  450. ## Лицензия
  451. MIT, файл [LICENSE](LICENSE).
scripts/routing_eval.py · Bundled script · 90 lines
  1. """Deterministic DSH routing contract evaluation.
  2. This is a model-facing acceptance fixture: route selection must send explicit
  3. cross-market price requests to ``compare-prices`` and full-mount/setup requests
  4. to ``marketplace`` while leaving single-source requests to that source skill.
  5. It intentionally tests both positive and negative examples and emits JSON for CI.
  6. """
  7. from __future__ import annotations
  8. import argparse
  9. import json
  10. from dataclasses import dataclass
  11. from pathlib import Path
  12. @dataclass(frozen=True)
  13. class Case:
  14. query: str
  15. expected: str
  16. should_not: tuple[str, ...] = ()
  17. CASES = (
  18. Case("где дешевле купить iphone 15", "compare-prices", ("marketplace", "wb-connector")),
  19. Case("сравни цены на стиральную машину", "compare-prices", ("marketplace",)),
  20. Case("сколько стоит на вайлдберриз", "wb-connector", ("compare-prices",)),
  21. Case("отзывы на озоне", "ozon-connector", ("compare-prices",)),
  22. Case("покажи все источники и настрой marketplace", "marketplace", ("compare-prices",)),
  23. Case("marketplace_sources", "marketplace", ("compare-prices",)),
  24. )
  25. def route(query: str) -> str:
  26. q = query.casefold()
  27. if any(
  28. token in q for token in ("где дешевле", "сравни цены", "сравнить цены", "самую низкую цену", "compare prices")
  29. ):
  30. return "compare-prices"
  31. if any(token in q for token in ("marketplace_sources", "все источники", "настрой marketplace", "full marketplace")):
  32. return "marketplace"
  33. for source, tokens in {
  34. "wb-connector": ("вайбeрриз", "wildberries", "на wb", "на вайлдберриз"),
  35. "ozon-connector": ("озон", "ozon"),
  36. "yandex-connector": ("яндекс маркет", "на яндекс"),
  37. }.items():
  38. if any(token in q for token in tokens):
  39. return source
  40. return "marketplace"
  41. def evaluate(cases: tuple[Case, ...] = CASES) -> dict[str, object]:
  42. rows = []
  43. for case in cases:
  44. actual = route(case.query)
  45. passed = actual == case.expected and actual not in case.should_not
  46. rows.append(
  47. {
  48. "query": case.query,
  49. "expected": case.expected,
  50. "actual": actual,
  51. "passed": passed,
  52. "forbidden": list(case.should_not),
  53. }
  54. )
  55. passed = sum(1 for row in rows if row["passed"])
  56. return {
  57. "version": 1,
  58. "total": len(rows),
  59. "passed": passed,
  60. "accuracy": passed / len(rows) if rows else 1.0,
  61. "ok": passed == len(rows),
  62. "cases": rows,
  63. }
  64. def main() -> int:
  65. parser = argparse.ArgumentParser(description=__doc__)
  66. parser.add_argument("--json-out", type=Path)
  67. args = parser.parse_args()
  68. report = evaluate()
  69. print(json.dumps(report, ensure_ascii=False, indent=2))
  70. if args.json_out:
  71. args.json_out.parent.mkdir(parents=True, exist_ok=True)
  72. args.json_out.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
  73. return 0 if report["ok"] else 1
  74. if __name__ == "__main__":
  75. raise SystemExit(main())
scripts/test_build_changelog.py · Bundled script · 410 lines
  1. """R-CHANGELOG-FRAGMENTS: temporary-tree folding, in-memory PR/Markdown and CI checks.
  2. The Markdown below is deliberately hand-written release input, not captured marketplace
  3. content. No transport, clock, filesystem or subprocess is faked or monkeypatched.
  4. """
  5. from __future__ import annotations
  6. import re
  7. import shutil
  8. import subprocess
  9. import sys
  10. from pathlib import Path
  11. import pytest
  12. sys.path.insert(0, str(Path(__file__).resolve().parent))
  13. import build_changelog as builder
  14. OLD_RELEASE = "## [2.9.3] - 2026-11-15\n\n### Fixed\n- Старое.\n- Old.\n"
  15. HEADER = "# Changelog\n\nРусский первый, английский ниже.\n\n## [Unreleased]\n\n"
  16. ENTRY = "### Fixed\n- Исправлено (#12).\n- Fixed (#12).\n"
  17. RELEASE_ARGS = ["--version", "3.0.0", "--date", "2026-11-16"]
  18. def _tree(tmp_path: Path, hand: str = "") -> Path:
  19. (tmp_path / "CHANGELOG.md").write_text(HEADER + hand + OLD_RELEASE, encoding="utf-8", newline="\n")
  20. (tmp_path / "changes").mkdir()
  21. (tmp_path / "changes" / ".gitkeep").write_bytes(b"")
  22. return tmp_path
  23. def _fragment(root: Path, name: str = "12.md", text: str = ENTRY) -> Path:
  24. path = root / "changes" / name
  25. path.write_text(text, encoding="utf-8", newline="\n")
  26. return path
  27. def _snapshot(root: Path) -> dict[str, bytes]:
  28. return {path.relative_to(root).as_posix(): path.read_bytes() for path in root.rglob("*") if path.is_file()}
  29. # START_BLOCK_RELEASE_TESTS
  30. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.dry-run", "R-CHANGELOG-FRAGMENTS.fold")
  31. def test_two_fragments_fold_in_section_and_numeric_pr_order(tmp_path: Path) -> None:
  32. root = _tree(tmp_path)
  33. _fragment(
  34. root, "100.md", "### Fixed\n- Сто (#100).\n- Hundred (#100).\n\n### Added\n- Новое (#100).\n- New (#100).\n"
  35. )
  36. _fragment(
  37. root,
  38. "12.md",
  39. "### Fixed\n- Двенадцать (#12).\n- Twelve (#12).\n\n### Security\n- Защита (#12).\n- Security (#12).\n",
  40. )
  41. assert builder.main(RELEASE_ARGS, root=root) == 0
  42. expected = (
  43. "## [3.0.0] - 2026-11-16\n\n"
  44. "### Added\n- Новое (#100).\n- New (#100).\n\n"
  45. "### Fixed\n- Двенадцать (#12).\n- Twelve (#12).\n\n- Сто (#100).\n- Hundred (#100).\n\n"
  46. "### Security\n- Защита (#12).\n- Security (#12).\n\n"
  47. )
  48. assert (root / "CHANGELOG.md").read_text(encoding="utf-8") == HEADER + expected + OLD_RELEASE
  49. assert list((root / "changes").iterdir()) == [root / "changes" / ".gitkeep"]
  50. assert b"\r" not in (root / "CHANGELOG.md").read_bytes()
  51. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.fold")
  52. def test_hand_text_is_preserved_before_fragment_entries(tmp_path: Path) -> None:
  53. hand = "Заметка вручную.\nManual note.\n\n### Fixed\n- Ручное.\n- Manual.\n\n"
  54. root = _tree(tmp_path, hand)
  55. _fragment(root)
  56. assert builder.main(RELEASE_ARGS, root=root) == 0
  57. text = (root / "CHANGELOG.md").read_text(encoding="utf-8")
  58. assert text.startswith(HEADER + "## [3.0.0] - 2026-11-16\n\n" + hand + "- Исправлено (#12).\n- Fixed (#12).\n\n")
  59. assert text.count("### Fixed") == 2 # one new section, one untouched old release
  60. assert text.endswith(OLD_RELEASE)
  61. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.fold")
  62. def test_all_keep_a_changelog_sections_use_the_standard_order(tmp_path: Path) -> None:
  63. root = _tree(tmp_path)
  64. sections = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
  65. _fragment(
  66. root, text="\n".join(f"### {section}\n- RU {section}.\n- EN {section}.\n" for section in reversed(sections))
  67. )
  68. assert builder.main(RELEASE_ARGS, root=root) == 0
  69. text = (root / "CHANGELOG.md").read_text(encoding="utf-8").split(OLD_RELEASE)[0]
  70. positions = [text.index(f"### {section}") for section in sections]
  71. assert positions == sorted(positions)
  72. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.dry-run")
  73. def test_dry_run_prints_the_same_section_and_touches_nothing(
  74. tmp_path: Path, capsys: pytest.CaptureFixture[str]
  75. ) -> None:
  76. root = _tree(tmp_path, "Ручной текст.\nHand text.\n\n")
  77. _fragment(root)
  78. before = _snapshot(root)
  79. assert builder.main([*RELEASE_ARGS, "--dry-run"], root=root) == 0
  80. section = capsys.readouterr().out
  81. assert section.startswith("## [3.0.0] - 2026-11-16\n\nРучной текст.\nHand text.\n\n### Fixed\n")
  82. assert ENTRY in section
  83. assert _snapshot(root) == before
  84. assert builder.main(RELEASE_ARGS, root=root) == 0
  85. assert (root / "CHANGELOG.md").read_text(encoding="utf-8") == HEADER + section + "\n" + OLD_RELEASE
  86. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  87. @pytest.mark.parametrize(
  88. ("text", "line"),
  89. [
  90. ("### Unknown\n- Entry.\n", 1),
  91. ("### Added\nOnly prose.\n", 1),
  92. ("### Added\n- Entry.\n## [3.0.0]\n", 3),
  93. ("### Added\n- Entry.\n\n### Fixed\n", 4),
  94. ("", 1),
  95. ("- No section.\n", 1),
  96. ],
  97. )
  98. def test_bad_fragment_names_the_file_and_line_without_writing(
  99. tmp_path: Path, capsys: pytest.CaptureFixture[str], text: str, line: int
  100. ) -> None:
  101. root = _tree(tmp_path)
  102. _fragment(root, "1.md") # a valid earlier fragment must not be consumed on failure
  103. _fragment(root, "12.md", text)
  104. before = _snapshot(root)
  105. assert builder.main(RELEASE_ARGS, root=root) == 1
  106. assert f"changes/12.md:{line}:" in capsys.readouterr().err
  107. assert _snapshot(root) == before
  108. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.fold", "R-CHANGELOG-FRAGMENTS.validation")
  109. def test_odd_bullet_counts_and_continuations_are_kept(tmp_path: Path) -> None:
  110. root = _tree(tmp_path)
  111. fragment = "### Changed\n- Нечётная заметка (#12).\n continuation with `code`.\n - nested detail\n"
  112. _fragment(root, text=fragment)
  113. assert builder.main(RELEASE_ARGS, root=root) == 0
  114. assert fragment in (root / "CHANGELOG.md").read_text(encoding="utf-8")
  115. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  116. @pytest.mark.parametrize("dry_run", [False, True])
  117. def test_an_existing_version_is_refused_without_writing(
  118. tmp_path: Path, capsys: pytest.CaptureFixture[str], dry_run: bool
  119. ) -> None:
  120. root = _tree(tmp_path)
  121. _fragment(root)
  122. before = _snapshot(root)
  123. args = ["--version", "2.9.3", *(["--dry-run"] if dry_run else [])]
  124. assert builder.main(args, root=root) == 1
  125. assert "2.9.3" in capsys.readouterr().err
  126. assert _snapshot(root) == before
  127. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.dry-run")
  128. def test_no_fragments_builds_an_empty_section(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
  129. root = _tree(tmp_path)
  130. assert builder.main([*RELEASE_ARGS, "--dry-run"], root=root) == 0
  131. assert capsys.readouterr().out == "## [3.0.0] - 2026-11-16\n"
  132. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  133. @pytest.mark.parametrize("name", ["oops.md", "0.md"])
  134. def test_non_pr_fragment_names_are_refused(tmp_path: Path, capsys: pytest.CaptureFixture[str], name: str) -> None:
  135. root = _tree(tmp_path)
  136. _fragment(root, name)
  137. before = _snapshot(root)
  138. assert builder.main(RELEASE_ARGS, root=root) == 1
  139. assert name in capsys.readouterr().err
  140. assert _snapshot(root) == before
  141. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  142. @pytest.mark.parametrize("args", [["--version", "1.2"], ["--version", "1.2.3", "--date", "2026-02-30"]])
  143. def test_bad_release_arguments_are_refused(tmp_path: Path, args: list[str]) -> None:
  144. root = _tree(tmp_path)
  145. before = _snapshot(root)
  146. assert builder.main(args, root=root) == 1
  147. assert _snapshot(root) == before
  148. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  149. def test_missing_unreleased_heading_is_refused(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
  150. root = _tree(tmp_path)
  151. (root / "CHANGELOG.md").write_text("# Changelog\n\n" + OLD_RELEASE, encoding="utf-8", newline="\n")
  152. before = _snapshot(root)
  153. assert builder.main(RELEASE_ARGS, root=root) == 1
  154. assert "Unreleased" in capsys.readouterr().err
  155. assert _snapshot(root) == before
  156. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.fold")
  157. @pytest.mark.parametrize("fence", ["```", "~~~~"])
  158. def test_fenced_manual_headings_stay_inside_their_example(fence: str) -> None:
  159. """R-CHANGELOG-FRAGMENTS.fold: Markdown examples must not split or reorder hand text."""
  160. hand = f"### Fixed\n- Ручное.\n- Manual.\n\n{fence}markdown\n## Migration details\n### Added\n- Example only.\n{fence}\n\n"
  161. fragment = "### Added\n- Новое.\n- New.\n"
  162. section, updated = builder.build_release(
  163. HEADER + hand + OLD_RELEASE, [("changes/12.md", fragment)], "3.0.0", "2026-11-16"
  164. )
  165. expected = "## [3.0.0] - 2026-11-16\n\n" + fragment + "\n" + hand.rstrip("\n") + "\n"
  166. assert section == expected
  167. assert updated == HEADER + expected + "\n" + OLD_RELEASE
  168. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  169. @pytest.mark.parametrize("fence", ["```", "~~~~"])
  170. def test_fenced_fragment_examples_are_not_headings_or_top_level_bullets(fence: str) -> None:
  171. """R-CHANGELOG-FRAGMENTS.validation: literal code is neither a section nor a bullet."""
  172. example = f"{fence}markdown\n# comment\n## Example\n### Added\n- Example only.\n{fence}\n"
  173. text = "### Changed\n- Изменено.\n- Changed.\n\n" + example
  174. assert builder.parse_fragment(text, "changes/12.md") == {"Changed": text.split("\n", 1)[1].rstrip("\n")}
  175. with pytest.raises(ValueError, match=r"changes/12\.md:1:.*bullet"):
  176. builder.parse_fragment(f"### Changed\n{fence}\n- Example only.\n{fence}\n", "changes/12.md")
  177. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.pr", "R-CHANGELOG-FRAGMENTS.validation")
  178. @pytest.mark.parametrize("mode", ["release", "pr"])
  179. def test_invalid_utf8_fragment_reports_its_name_and_line(
  180. tmp_path: Path, capsys: pytest.CaptureFixture[str], mode: str
  181. ) -> None:
  182. """R-CHANGELOG-FRAGMENTS.validation: decoding errors retain actionable diagnostics."""
  183. root = _tree(tmp_path)
  184. (root / "changes" / "12.md").write_bytes(b"### Fixed\n- \xff\n")
  185. changed = root / "changed-paths"
  186. changed.write_bytes(b"packages/demo/file\0changes/12.md\0")
  187. before = _snapshot(root)
  188. args = (
  189. RELEASE_ARGS
  190. if mode == "release"
  191. else [
  192. "--check-pr",
  193. "--pr-number",
  194. "12",
  195. "--changed-files",
  196. str(changed),
  197. "--labels",
  198. "[]",
  199. "--author",
  200. "contributor",
  201. ]
  202. )
  203. assert builder.main(args, root=root) == 1
  204. error = capsys.readouterr().err
  205. assert "changes/12.md:2:" in error
  206. if mode == "pr":
  207. assert "no-changelog" in error and len(error.splitlines()) == 1
  208. assert _snapshot(root) == before
  209. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.validation")
  210. @pytest.mark.parametrize("indent", ["", " ", " ", " "])
  211. @pytest.mark.parametrize("marker", ["-", "+", "*"])
  212. def test_top_level_bullet_indentation_uses_markdown_rules(indent: str, marker: str) -> None:
  213. """R-CHANGELOG-FRAGMENTS.validation: up to three spaces is still a top-level list."""
  214. body = f"{indent}{marker} RU.\n{indent}{marker} EN."
  215. assert builder.parse_fragment("### Fixed\n" + body + "\n", "changes/12.md") == {"Fixed": body}
  216. with pytest.raises(ValueError, match=r"changes/12\.md:1:.*bullet"):
  217. builder.parse_fragment(f"### Fixed\n {marker} Only indented code.\n", "changes/12.md")
  218. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.fold", "R-CHANGELOG-FRAGMENTS.validation")
  219. @pytest.mark.parametrize("fence", ["```", "~~~~"])
  220. def test_fences_in_list_items_keep_their_literal_headings(fence: str) -> None:
  221. """R-CHANGELOG-FRAGMENTS.fold/validation: a list-item example is not a new section."""
  222. body = f"- RU.\n- EN.\n- {fence}markdown\n ### Added\n - example\n {fence}"
  223. assert builder.parse_fragment("### Changed\n" + body + "\n", "changes/12.md") == {"Changed": body}
  224. section, _ = builder.build_release(
  225. HEADER + "### Changed\n" + body + "\n\n" + OLD_RELEASE, [], "3.0.0", "2026-11-16"
  226. )
  227. assert section == "## [3.0.0] - 2026-11-16\n\n### Changed\n" + body + "\n"
  228. # END_BLOCK_RELEASE_TESTS
  229. # START_BLOCK_PR_TESTS
  230. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.pr")
  231. @pytest.mark.parametrize(
  232. ("paths", "labels", "author", "fragment", "passes"),
  233. [
  234. (["docs/guide.md", "packages-other/file"], [], "contributor", None, True),
  235. (["packages/demo/file"], [], "dependabot[bot]", None, True),
  236. (["packages/demo/file"], ["no-changelog"], "contributor", None, True),
  237. (["packages/demo/file", "changes/12.md"], [], "contributor", ENTRY, True),
  238. (["packages/demo/file"], [], "contributor", None, False),
  239. (["packages/demo/file", "changes/13.md"], [], "contributor", ENTRY, False),
  240. (["packages/demo/file", "changes/12.md"], [], "contributor", "### Wrong\n- Entry.\n", False),
  241. (["packages/demo/file", "changes/12.md"], [], "contributor", None, False),
  242. (["packages/demo/file"], ["No-changelog"], "dependabot", None, False),
  243. ],
  244. )
  245. def test_pure_pr_decision_branches(
  246. paths: list[str], labels: list[str], author: str, fragment: str | None, passes: bool
  247. ) -> None:
  248. problem = builder.check_pr(12, paths, labels, author, fragment)
  249. assert (problem is None) == passes
  250. if not passes:
  251. assert problem is not None
  252. assert "changes/12.md" in problem and "no-changelog" in problem
  253. assert "\n" not in problem
  254. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.pr")
  255. @pytest.mark.parametrize(
  256. ("paths", "labels", "author", "fragment", "expected"),
  257. [
  258. (["docs/guide.md"], "[]", "contributor", None, 0),
  259. (["packages/demo/file"], "[]", "dependabot[bot]", None, 0),
  260. (["packages/demo/file"], '["no-changelog"]', "contributor", None, 0),
  261. (["packages/demo/file", "changes/12.md"], "[]", "contributor", ENTRY, 0),
  262. (["packages/demo/file"], "[]", "contributor", None, 1),
  263. (["packages/demo/file", "changes/13.md"], "[]", "contributor", ENTRY, 1),
  264. (["packages/demo/file", "changes/12.md"], "[]", "contributor", "### Fixed\nNo bullet.\n", 1),
  265. ],
  266. )
  267. def test_check_pr_cli_inputs(
  268. tmp_path: Path,
  269. capsys: pytest.CaptureFixture[str],
  270. paths: list[str],
  271. labels: str,
  272. author: str,
  273. fragment: str | None,
  274. expected: int,
  275. ) -> None:
  276. root = _tree(tmp_path)
  277. if fragment is not None:
  278. _fragment(root, "13.md" if "changes/13.md" in paths else "12.md", fragment)
  279. changed = root / "changed-paths"
  280. # git diff -z keeps spaces, Unicode and even newlines inside a path intact.
  281. changed.write_bytes(("\0".join([*paths, "docs/имя с\nпереносом.md"]) + "\0").encode("utf-8"))
  282. before = _snapshot(root)
  283. code = builder.main(
  284. ["--check-pr", "--pr-number", "12", "--changed-files", str(changed), "--labels", labels, "--author", author],
  285. root=root,
  286. )
  287. assert code == expected
  288. output = capsys.readouterr()
  289. if expected:
  290. assert "changes/12.md" in output.err and "no-changelog" in output.err
  291. assert len(output.err.splitlines()) == 1
  292. assert _snapshot(root) == before
  293. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.dry-run")
  294. def test_real_cli_uses_its_copied_tree(tmp_path: Path) -> None:
  295. root = _tree(tmp_path)
  296. _fragment(root)
  297. scripts = root / "scripts"
  298. scripts.mkdir()
  299. script = scripts / "build_changelog.py"
  300. shutil.copyfile(builder.__file__, script)
  301. before = _snapshot(root)
  302. result = subprocess.run(
  303. [sys.executable, str(script), *RELEASE_ARGS, "--dry-run"],
  304. cwd=root,
  305. capture_output=True,
  306. text=True,
  307. encoding="utf-8",
  308. )
  309. assert result.returncode == 0, result.stdout + result.stderr
  310. assert ENTRY in result.stdout
  311. assert _snapshot(root) == before
  312. # END_BLOCK_PR_TESTS
  313. # START_BLOCK_WORKFLOW_TESTS
  314. def _assert_ci_fragment_step(text: str) -> None:
  315. trigger = re.search(r"^ pull_request:\n(.*?)(?=^ \S)", text, re.M | re.S)
  316. assert trigger is not None
  317. assert "types: [opened, synchronize, reopened, labeled, unlabeled]" in trigger.group(1)
  318. lint = re.search(r"^ lint:\n(.*?)(?=^ \S)", text, re.M | re.S)
  319. assert lint is not None
  320. body = lint.group(1)
  321. assert "fetch-depth: 0" in body
  322. step = body[body.rindex(" - name:") :]
  323. assert step.startswith(" - name: CHANGELOG fragment\n")
  324. assert "if: github.event_name == 'pull_request'" in step
  325. assert 'git diff --name-only --no-renames -z "$PR_BASE_SHA...$PR_HEAD_SHA"' in step
  326. assert "--check-pr" in step and "build_changelog.py" in step
  327. for source in ("number", "base.sha", "head.sha", "labels.*.name", "user.login"):
  328. assert f"github.event.pull_request.{source}" in step
  329. for option in ("--pr-number", "--changed-files", "--labels", "--author"):
  330. assert option in step
  331. @pytest.mark.req("R-CHANGELOG-FRAGMENTS.pr")
  332. def test_ci_fragment_step_and_label_events() -> None:
  333. """The workflow gathers git/PR inputs only and reruns the final lint step for labels."""
  334. workflow = Path(__file__).resolve().parent.parent / ".github" / "workflows" / "ci.yml"
  335. _assert_ci_fragment_step(workflow.read_text(encoding="utf-8"))
  336. # END_BLOCK_WORKFLOW_TESTS

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.