moysklad-mcp-ru 0.1.0

MCP server for the MoySklad JSON API 1.2 (schema-driven, safety-gated, document writes).

moysklad-mcp-ru: AI-доступ к МойСклад для Claude Code, Cursor, Codex и Cowork

🇬🇧 English version

Ведёте учёт в МойСклад — дайте ИИ прямой доступ к вашему аккаунту. Один MCP-сервер над JSON API 1.2 МойСклад: остатки, товары, заказы, контрагенты, отчёты (прибыль, обороты, деньги) и запись документов (приёмки, отгрузки, заказы, счета, возвраты) — напрямую по API, без браузера. Числа приходят из реального API, а не выдумываются моделью. Два гейта на запись не дают случайно создать или провести документ в боевом учёте. Авто-пагинация, мультикабинет, поиск по-русски. Для Claude Code, Cursor, Codex, Cowork и Claude Desktop.

⚠️ alpha. Помогает с операционкой учёта, но это инструмент, а не замена бухгалтера. Курированное ядро и срез записи выверены боем на тестовом кабинете; импортированные из доки методы — карта для разведки (пути надёжны, тела write-запросов сверяйте по доке или зовите через ms_call_raw). Подробности — в разделе «Оговорки».

Зачем это нужно

Учёт живёт в МойСклад, а ИИ-ассистент обычно бесполезен: либо ходит через браузер и спотыкается, либо выдумывает цифры, которые звучат уверенно. moysklad-mcp-ru даёт агенту прямой доступ к JSON API 1.2 вашего аккаунта:

• Числа из реального API, а не из головы модели. Остатки, заказы, прибыль, обороты — это ответ МойСклад, с источником и полями.
• Запись за двумя гейтами. Создание документа делает ЧЕРНОВИК; проведение (двигает учёт) — отдельный destructive-шаг с подтверждением. Запись вообще выключена, пока её явно не включить и не направить на тестовый кабинет.
• Без браузера. Прямые HTTPS-вызовы по токену кабинета.

Скажите агенту обычными словами: «покажи остатки», «что пора дозаказать», «создай приёмку на 10 Рога от поставщика» — он подберёт метод или сценарий.

Что внутри

Не «один тул на эндпоинт», а 8 generic мета-тулов над каталогом — полное покрытие API при маленькой поверхности.

ваш ИИ-агент
      │
      ▼
 8 мета-тулов  ──►  каталог (endpoints.yaml)  ──►  общий core
 search / describe /                                клиент · safety · ошибки
 call / call_raw /                                  пагинация · реестр
 fetch_all / map / ...                                    │
 + типизированные тулы (ms_get_stock, ms_create_document, …)  ▼
                                              МойСклад JSON API 1.2 (HTTPS)

Мета-тулы (ms_search_methods, ms_describe_method, ms_call_method, ms_call_raw, ms_fetch_all, ms_map, + тулы кабинетов).

Типизированные read-тулы: ms_get_stock, ms_get_products, ms_get_orders, ms_get_profit, ms_get_money, ms_get_turnover, ms_get_counterparties, ms_get_stores, ms_get_documents (7 типов), ms_ping. Копейки автоматически переводятся в рубли.

Тулы записи (за двумя гейтами):

Тул	Уровень	Назначение
ms_build_document	read	Preview ЛЮБОГО типа: резолв ссылок + точное тело, БЕЗ записи.
ms_create_document	write	Создать ЛЮБОЙ ролевой тип ЧЕРНОВИКОМ (applicable:false).
ms_build_purchaseorder / ms_create_purchaseorder	read / write	Типизированный заказ поставщику (для совместимости).
ms_post_document	destructive	Провести документ (applicable:true) — двигает учёт.
ms_delete_document	destructive	Удалить документ (уборка).

7 ролевых типов: purchaseorder, supply, demand, invoicein, invoiceout, salesreturn, purchasereturn.

Каталог — schema-driven из официальной доки МойСклад: 892 метода (курированное ядро выверено живьём; остальное импортировано из доки). ms_call_raw достаёт всё, чего ещё нет в каталоге.

Что можно спросить

покажи остатки и что пора дозаказать
вытащи прибыль по товарам за прошлый месяц
кто из контрагентов должен нам денег
создай черновик приёмки: 10 «Рога» от «ООО Поставщик» по 250 ₽   (на тестовом кабинете)
проведи эту приёмку и покажи, как изменился остаток

Не уверены, с чего начать — скажите «что ты умеешь по моему кабинету» или вызовите ms_map.

Safety model

Токен кабинета двигает остатки и деньги. Каждый метод классифицирован:

• read → выполняется сразу;
• write (создать черновик) → требует confirm_write=true И включённой записи MOYSKLAD_ALLOW_WRITE=1;
• destructive (провести / удалить) → ещё и i_understand_this_modifies_data=true.

Два независимых слоя: (1) процессный guard (MOYSKLAD_ALLOW_WRITE, по умолчанию ВЫКЛ, опц. пин к кабинету MOYSKLAD_WRITE_CABINETS) — защита от направления на боевой кабинет; (2) per-call гейт. Guard покрывает и сырые ms_call_method/ ms_call_raw, не только типизированные тулы. 0 мутаций, помеченных как read — проверяется тестом (test_safety_catalog) в CI. Создание всегда делает ЧЕРНОВИК; проведение — отдельный шаг.

Установка

Подробный гайд — в QUICKSTART.md. Три пути, один результат:

1. Проще всего — попроси своего ИИ (без терминала). Открой Claude / Cowork и скажи: «установи МойСклад MCP» — агент проведёт по встроенному install-skill/.
2. Скачать и кликнуть. Возьми release-zip, распакуй, двойной клик install.command (macOS) / install.bat (Windows), вставь токен.
3. Технический. python3 install.py --client <твой-клиент> (claude-desktop / claude-code / codex / opencode).
4. Для разработчиков. Пакет на PyPI — запуск без установки: uvx moysklad-mcp-ru. Для Claude Desktop — готовый .mcpb-бандл из релиза (двойной клик, токен вводится в окне настроек). Полный список каналов и как режется релиз — в docs/DISTRIBUTION.md.

Для путей 1–3 не нужно ни pip install, ни правки JSON: зависимости ставятся сами при первом запуске (локальный venv), от тебя — только токен.

Где взять токен: МойСклад → Настройки → Пользователи → Токены доступа. Токен хранится в ~/.moysklad-mcp/cabinets.json (локально, chmod 600, никогда в репо и не в чат). Поддержка мультикабинета — несколько аккаунтов с переключением из чата (ms_add_cabinet / ms_use_cabinet).

Проверка после установки: python3 serve.py ms --selfcheck → «OK: ms ready, N tools».

Деньги

Все суммы в API — в копейках. Read-тулы отдают рубли. На записи convert_money_to_kopecks переводит цены/суммы рубли→копейки (price позиции, sum, price-объекты). Сырые мета-тулы работают в копейках как есть.

Выверено боем

• Хост api.moysklad.ru/api/remap/1.2, списки в rows, offset+limit (макс 1000).
• Лимит: бакет 45/3с, окно 3000 мс, тяжёлый отчёт остатков весит 5 единиц.
• Жёстко: Accept: application/json;charset=utf-8 ровно (иначе 400 код 1062), Accept-Encoding: gzip (иначе 415).
• Запись (демо-кабинет): веер create→read-back→проведение→движение остатков→ удаление→откат на всех 6 ролевых типах + purchaseorder. Деньги ×100 верны, supply/salesreturn +, demand/purchasereturn −, счета не двигают, удаление откатывает, возвраты создаются standalone.

Оговорки (сверяйте с живой докой)

• Импортированные из доки методы: пути надёжны, тела write — нет. Считайте их картой разведки: подтверждайте по доке или зовите через ms_call_raw. Курированное ядро и срез записи — надёжны.
• Кабинет затеняет env: активный кабинет в cabinets.json приоритетнее переменных окружения. Необъяснимый 401 — первым делом проверьте стор.
• Запись только на тестовый кабинет. Не направляйте MOYSKLAD_ALLOW_WRITE=1 на боевой учёт, пока сами не проверите на тесте.

Структура

core/                 ← вендорный движок ilyautov/marketplaces-mcp-ru (MIT, не менялся)
moysklad_mcp/         ← специфика МойСклад: server.py, build.py, money.py, refs.py,
                        write_guard.py, endpoints.yaml(+curated), workflows.yaml, entities.yaml
tests/                ← 70 офлайн-тестов
scripts/              ← ingest_moysklad.py (парсер доки), package_release.py
serve.py              ← лаунчер (авто-venv): python3 serve.py ms [--selfcheck]
install.py + .command/.bat/.sh + install-skill/   ← установка под 4 клиента
.mcp.json + .claude-plugin/ .codex-plugin/ .cursor-plugin/   ← плагин-манифесты
docs/                 ← исследование, аудит, RUNBOOK-и, точки возобновления (dev-доки)

Лицензия

MIT. Вендорный core/ — под MIT Ильи Утова, см. NOTICE. Архитектура (schema-driven каталог, safety-гейт, единые ошибки, авто-пагинация) переиспользует сильнейшие идеи marketplaces-mcp-ru.

Нашли косяк — заводите issue. Это alpha и открытый код: ставьте, проверяйте на своих данных, экспериментируйте.