Horoshop MCP Server

Хорошоп MCP: неофіційний MCP-сервер для магазинів на Хорошопі

Українська · Русский · English

Хорошоп MCP (horoshop-mcp): безкоштовний MCP-сервер з відкритим кодом, який підключає ШІ-агентів Claude, Cursor, Codex, Hermes Agent та інших до інтернет-магазину на платформі Хорошоп. Сервер працює на вашому комп'ютері, обслуговує кілька магазинів одночасно і дає агенту 118 інструментів для каталогу, замовлень, SEO, редиректів, фідів маркетплейсів, дизайну та налаштувань магазину.

Неофіційний проєкт. Хорошоп MCP не є продуктом компанії Хорошоп, не пов'язаний з нею і нею не підтримується. Інструменти адмінки працюють через внутрішні недокументовані запити, які Хорошоп може змінити без попередження. Нові сценарії спершу перевіряйте на тестовому магазині і лише потім запускайте на робочому.

• 118 інструментів на трьох рівнях: публічний API Хорошопу, адмінка та кошик вітрини.
• Багато магазинів, один сервер. Кожен інструмент приймає аргумент store, тож агенція може працювати з магазинами всіх клієнтів через одне підключення.
• Безпечно за замовчуванням. 57 з 71 інструмента запису лише показують план змін, доки ви не передасте dryRun:false; ризиковані масові операції вимагають явного підтвердження; кожен запис перевіряється повторним читанням результату.
• Локально. Сервер працює на вашому комп'ютері через stdio. Доступи лежать у файлі, який контролюєте ви.

Зміст

• Швидкий старт
• Можливості
• Готові сценарії
• Налаштування
• Захист від помилкових змін
• Обмеження платформи
• Безпека
• Як це працює
• Часті запитання
• Розробка
• Автор і контакти
• Ліцензія

Сторінка проєкту: igorshutko.github.io/horoshop-mcp

Документація: інструкція з встановлення для 22 клієнтів · довідник інструментів з усіма параметрами (англійською) · внутрішній устрій та особливості платформи (англійською).

Швидкий старт

1. Що потрібно. Node.js 18 або новіший і Git.

2. Доступи. Створіть в адмінці магазину окремого адміністратора (у російському інтерфейсі розділ «Настройки → Админы», кнопка «Добавить») і збережіть його логін і пароль. Та сама пара працює і для API, і для інструментів адмінки. Детальніше: як отримати доступи Хорошопу.

3. stores.json. Збережіть файл у місці, куди не мають доступу сторонні:

{
  "myshop": { "baseUrl": "https://myshop.com.ua", "login": "api-user", "password": "REPLACE_ME" }
}

4. Підключіть ШІ-клієнт. Клонувати репозиторій не потрібно.

Claude Desktop, найпростіший шлях: завантажте horoshop-mcp.mcpb зі сторінки релізу і відкрийте файл. Claude Desktop поставить сервер сам і спитає, де лежить ваш stores.json. Термінал не потрібен.

Решта клієнтів запускають сервер через npx.

Claude Code:

claude mcp add horoshop -s user -e HOROSHOP_STORES_FILE=/abs/path/to/stores.json -- npx -y github:IgorShutko/horoshop-mcp

Codex:

codex mcp add horoshop --env HOROSHOP_STORES_FILE=/abs/path/to/stores.json -- npx -y github:IgorShutko/horoshop-mcp

Cursor (~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf, LM Studio, Kiro і більшість інших клієнтів:

{
  "mcpServers": {
    "horoshop": {
      "command": "npx",
      "args": ["-y", "github:IgorShutko/horoshop-mcp"],
      "env": { "HOROSHOP_STORES_FILE": "/abs/path/to/stores.json" }
    }
  }
}

Щоб закріпити конкретну версію, додайте тег до адреси: github:IgorShutko/horoshop-mcp#v0.2.0.

У Windows використовуйте "command": "cmd", "args": ["/c", "npx", "-y", "github:IgorShutko/horoshop-mcp"]. Перший запуск завантажує і збирає пакет, це займає близько 20 секунд. У VS Code, Zed, Hermes Agent, Gemini CLI, OpenCode, Goose та інших клієнтів свій формат налаштувань: дивіться інструкцію з встановлення, там також описано встановлення через клонування і тайм-аути клієнтів.

5. Спробуйте. Попросіть агента:

• «Покажи мої магазини на Хорошопі та перевір, чи працює авторизація.»
• «Покажи 10 найновіших замовлень у myshop зі статусом і сумою.»
• «Яких товарів у myshop немає в наявності? Покажи артикул, назву і ціну.»
• «Задай SEO-заголовок і опис категорії /shoes/ українською та російською. Лише план змін.»
• «Створи 301-редиректи з цього списку старих URL. Спершу покажи план змін.»

Можливості

Кожен інструмент, його рівень доступу та всі параметри: довідник інструментів (англійською). Агентам зручніший docs/tools.json: той самий перелік без тексту, по одному компактному запису на інструмент.

Готові сценарії

Щоб не доводилось формулювати задачу словами, сервер віддає сім готових сценаріїв. Клієнт показує їх власним списком: у Claude Desktop це меню «+» у полі вводу, у Claude Code команда /mcp. Ви обираєте сценарій, заповнюєте одне-два поля, і агент іде за описаним порядком дій.

Сценарії описані в src/prompts.ts і навмисно називають агенту конкретні інструменти та порядок кроків: модель не вгадує, як влаштований Хорошоп, а йде перевіреним шляхом.

Налаштування

Сервер бере всі параметри зі змінних середовища.

Формат файлу з магазинами:

{
  "myshop": { "baseUrl": "https://myshop.com.ua", "login": "api-user", "password": "REPLACE_ME" },
  "othershop": { "baseUrl": "othershop.ua", "login": "api-user", "password": "REPLACE_ME" }
}

Ключ задає назву, яку потім передають як store. baseUrl може бути просто доменом, зі слешем у кінці або з /api. Якщо конфігурації немає, сервер усе одно запускається і показує інструменти, а виклики пояснюють, чого бракує. Файл з помилкою зупиняє сервер зі зрозумілим повідомленням.

Захист від помилкових змін

• Спершу план. 57 з 71 інструмента запису за замовчуванням працюють з dryRun і повертають план: що зміниться, з якого значення і на яке. Нічого не записується, доки ви не повторите виклик з dryRun:false.
• Підтвердження для незворотних і масових дій. Видалення або скасування замовлень, видалення довідників, зміна аліасу фіду (це публічна адреса фіду) та запуск імпорту прайсу вимагають явного confirm. horoshop_admin_products_price_set не приймає нульову чи від'ємну ціну, для понад 50 товарів вимагає точну кількість товарів, для змін понад 50% окреме підтвердження, і повертає готові параметри для відкату.
• Перевірка читанням. Інструменти запису перечитують результат, часто іншим каналом (наприклад, запис через адмінку перевіряється через публічний API), бо Хорошоп інколи відповідає OK, нічого не зберігши.
• Захист шаблонів. Тексти вітрини часто містять змінні на кшталт {DISCOUNT_PERCENT} чи {site}. Інструменти запису не замінять їх звичайним текстом без allowPlaceholderLoss:true.
• Обмеження розміру. Інструменти читання вимірюють відповідь і не повертають понад 100 KB, а підказують, як звузити запит. Один виклик не засмітить розмову.
• Секрети приховані. horoshop_admin_design_get не віддає розділ оплати і маскує значення, схожі на ключі; horoshop_list_stores ніколи не повертає доступи.
• Анотації інструментів. Кожен інструмент позначений як читання, запис або руйнівний запис, тож клієнти, які це підтримують, можуть автоматично дозволяти читання і питати дозволу перед записом.

Обмеження платформи

Ці обмеження йдуть від платформи, а не від сервера, і виміряні на реальних магазинах:

• У публічному API є імпорт, але немає видалення. Товари та покупців через /api/ можна створювати й оновлювати, але не видаляти; категорії там доступні лише для читання. Видалення і редагування категорій закривають інструменти адмінки.
• Експорт каталогу віддає не більше 500 товарів за виклик, незалежно від limit. Гортайте через offset і limit (100 на сторінку працює добре).
• Товари в замовленні змінити не можна ні через API, ні через адмінку. Одержувача, адресу, оплату й коментар менеджера змінити можна.
• Окреме фото з галереї видалити не можна. Хорошоп не має такого маршруту.
• Записи через віджети адмінки інколи губляться. Під час сплесків навантаження частина запитів потрапляє на вітрину замість адмінки, і нічого не зберігається. Ідемпотентні записи (оновлення, видалення) повторюються до п'яти разів, а пропуски потрапляють у звіт; створення не повторюється ніколи, щоб не з'явилися дублікати.
• Відкриття замовлення в адмінці піднімає його на верх списку замовлень (платформа оновлює дату рядка). Дані замовлення не змінюються; інструменти відкривають редактор якомога рідше.
• Дашборд аналітики показує фіксований період. Для довільних дат збирайте дані через horoshop_orders_get.
• Деякі розділи існують, лише якщо в магазині підключено модуль, наприклад редактор власного CSS. Тоді horoshop_admin_css_get повертає available:false замість порожнього результату.

Повний список з подробицями: docs/INTERNALS.md (англійською).

Безпека

• Тримайте доступи у файлі магазинів або в змінних середовища, ніколи не вставляйте їх у запити до агента чи в аргументи інструментів. stores*.json, резервні копії та файли .env додані до gitignore.
• Створіть для сервера окремого адміністратора з найвужчою роллю, якої достатньо для роботи. Щоб закрити доступ, видаліть цього користувача.
• Сервер звертається лише до налаштованих магазинів, до сервісу завантаження зображень Хорошопу, на який вказує адмінка під час імпорту фото, і до адрес зображень, які ви самі просите завантажити. Телеметрії немає.
• API-токени та сесії адмінки зберігаються лише в пам'яті.
• Повідомляючи про помилку, не вставляйте в issue реальні дані магазину, замовлень чи доступи.
• Модель безпеки, перелік того, що маскується у відповідях, і куди писати про вразливість: SECURITY.md.

Як це працює

Сервер поєднує три канали до магазину:

flowchart TD
  AI["ШІ-клієнт<br/>Claude · Cursor · Codex · Gemini CLI"] -->|"MCP, stdio"| S["horoshop-mcp<br/>118 інструментів"]
  S --> G{"Це запис?"}
  G -->|"читання"| CH["Три канали до магазину"]
  G -->|"запис: спершу план,<br/>виконання лише з dryRun:false"| CH
  CH --> P["Публічний API<br/>каталог, замовлення, покупці"]
  CH --> A["Адмінка<br/>SEO, фіди, дизайн, налаштування"]
  CH --> V["Вітрина<br/>кошик і оформлення"]
  P --> ST["Ваш магазин на Хорошопі<br/>аргумент store обирає, який саме"]
  A --> ST
  V --> ST

1. Публічний API (/api/<function>/): авторизація токеном, який кешується для кожного магазину й оновлюється непомітно. Використовується для каталогу, замовлень, покупців, довідкових даних, B2B і вебхуків.
2. Адмінка: сесія через /core-api/admin/security/login, далі класичні екрани адмінки. Адмінка влаштована одноманітно і розрізняє розділи за параметром handler (тип сутності): списки, форми редагування, збереження. Реєстр цих типів дає невеликому універсальному ядру доступ майже до кожного розділу, а для частих задач є окремі інструменти. Запис читає всю форму, змінює лише потрібні поля і відправляє решту без змін, тож поля, яких ви не торкалися, зберігаються.
3. Вітрина: власний віджет кошика магазину (/_widget/ajax_cart/) для питань, на які API не відповідає. Наприклад, чи зможе покупець дійти до оформлення замовлення з певним способом доставки.

Архітектура, структура проєкту та особливості платформи: docs/INTERNALS.md (англійською).

Часті запитання

Що таке Хорошоп MCP?

Хорошоп MCP реалізує протокол Model Context Protocol для інтернет-магазинів на Хорошопі. Підключений до нього ШІ-агент читає та змінює магазин через 118 інструментів: товари, замовлення, покупців, категорії, SEO-тексти, 301-редиректи, фіди маркетплейсів, дизайн і налаштування. Сервер з відкритим кодом працює локально й може обслуговувати кілька магазинів одночасно.

Чи є Хорошоп MCP офіційним продуктом Хорошопу?

Ні. Хорошоп MCP розробляється незалежно і не пов'язаний з компанією Хорошоп. Сервер використовує публічний API Хорошопу, а все, чого в API немає, робить тими самими запитами, які надсилає інтерфейс адмінки. Ці внутрішні запити можуть змінитися будь-коли, тому нові сценарії перевіряйте на окремому тестовому магазині.

Які ШІ-асистенти працюють з Хорошоп MCP?

Будь-який MCP-клієнт, який уміє запускати локальний stdio-сервер. В інструкції з встановлення є покрокове налаштування для 22 клієнтів, серед них Claude Code, Claude Desktop, Cursor, OpenAI Codex, Hermes Agent, VS Code з GitHub Copilot, Windsurf, Gemini CLI, Zed і Cline.

Що потрібно, щоб підключити магазин на Хорошопі?

Node.js 18 або новіший, Git, а також логін і пароль адміністратора вашого магазину на Хорошопі. Запишіть доступи в stores.json, додайте сервер у ШІ-клієнт однією командою і зачекайте близько 20 секунд, поки перший запуск збере пакет.

Чи безпечно давати ШІ-агенту доступ до магазину?

Сервер спроєктований саме для цього. 57 з 71 інструмента запису лише показують план, доки ви не передасте dryRun:false, незворотні дії вимагають явного confirm, а кожен запис перевіряється читанням результату. Доступи зберігаються в локальному файлі, телеметрії немає. Дайте серверу окремого адміністратора з найвужчою роллю, якої достатньо.

Чи можна керувати кількома магазинами з одного сервера?

Так. Опишіть усі магазини в одному файлі stores.json, а кожен виклик обирає магазин аргументом store. Так агенція працює з магазинами всіх клієнтів через одне підключення.

Скільки коштує Хорошоп MCP?

Хорошоп MCP безкоштовний і поширюється за ліцензією MIT. Платите лише за свій тариф Хорошопу і за ШІ-клієнт, яким користуєтеся.

Розробка

git clone https://github.com/IgorShutko/horoshop-mcp.git
cd horoshop-mcp
npm install          # installs dependencies and builds dist/
npm run watch        # recompile on change
npm run inspect      # build and open the MCP Inspector
npm run docs:tools   # regenerate docs/TOOLS.md from the running server

MCP-клієнти запускають сервер один раз, тому після перезбирання перезапустіть клієнт. horoshop_check_auth і horoshop_list_stores повертають stale:true, якщо збірка на диску новіша за запущений процес.

У evaluation/horoshop_eval.xml зібрано запитання лише на читання, щоб перевірити, чи справляється модель з реальними задачами через сервер. Відповіді залежать від підключеного магазину, тож заповнюйте їх на власному тестовому магазині.

npm test піднімає зібраний сервер і перевіряє те, на що спирається кожен клієнт: усі 118 інструментів на місці, канал stdout чистий, кожен інструмент маршрутизується в магазин. Ті самі команди ганяє CI на Node 18 і 22.

Issues і pull requests вітаються: CONTRIBUTING.md - правила, AGENTS.md - те саме для ШІ-агентів, які правлять цей код, CHANGELOG.md - що змінилось між версіями. Не публікуйте реальні дані магазинів в issues, логах і тестових файлах.

Автор і контакти

Хорошоп MCP створює та підтримує Ігор Шутко, агенція Target+.

• Telegram: @shutko_igor
• Telegram-канал: @shutko_ads

Помилки та побажання: GitHub Issues.

Ліцензія

MIT.