Moysklad Mcp Install

---
name: moysklad-mcp-install
description: "Установить MCP-сервер МойСклад (moysklad-mcp) для не-технического пользователя в режиме zero-terminal: человек говорит «поставь МойСклад MCP» — агент берёт код, запускает install.py под нужного клиента (Claude Desktop / Claude Code / Codex / OpenCode), помогает получить и сохранить токен в локальный кабинет, проверяет установку. Используй, когда пользователь хочет подключить свой аккаунт МойСклад к ИИ. Триггеры: «установи мойсклад mcp», «подключи МойСклад», «настрой учёт МойСклад», «добавь кабинет мойсклад», «install moysklad mcp», «настрой мойсклад к claude»."
---

# Установка moysklad-mcp под не-технического пользователя

Цель: пользователь сказал «поставь МойСклад MCP» — и через несколько минут в его ИИ-клиенте появились инструменты для работы с учётом (остатки, товары, заказы, документы, отчёты, запись документов), без ручного редактирования JSON и без `pip install`. Зависимости ставит сам `serve.py` при первом запуске (локальный venv).

**Репозиторий:** https://github.com/ilyautov/moysklad-mcp-ru — клонируй или используй подключённую папку проекта (см. Шаг 1).

Что внутри: один MCP-сервер `ms` (МойСклад JSON API 1.2). Токен хранится локально в `~/.moysklad-mcp/cabinets.json` (chmod 600, отдельный стор МойСклад, не конфликтует с WB/Ozon), НЕ в конфиге клиента и НЕ в репозитории.

---

## Шаг 0 — ОПРЕДЕЛИ СРЕДУ (критично, не пропускай)

От среды зависит, что ты можешь сделать сам, а что — только провести пользователя за руку. Будь честен про границу: НЕ обещай того, что среда физически не может.

### Ты в Claude Code (или другом локальном CLI, где bash = реальная машина)

bash выполняется НА машине пользователя — можешь сделать ВСЁ сам: взять код, запустить `python3 install.py --client claude-code`, помочь сохранить токен, проверить `serve.py ms --selfcheck`.
Проверка: `pwd && uname -a && whoami`. Домашняя папка на его ОС (не контейнер) → ты локально, иди по шагам 1→4 сам.

### Ты в Cowork (bash = изолированная Linux-песочница)

КРИТИЧНО. Твой bash — отдельный Linux-контейнер. Он НЕ видит конфиг Claude Desktop, НЕ может прописать хостовый MCP, НЕ может запустить `serve.py` на машине пользователя, и набирать в его терминал запрещено. Признак: `uname -a` показывает Linux-контейнер, домашняя папка вида `/home/...` или `/sessions/...`.

В Cowork ты НЕ ставишь MCP сам. Варианты (по предпочтению):
1. **Через Claude Code**, если он есть — подготовь команды Шагов 1-4 и попроси выполнить там.
2. **Двойной клик + computer-use.** Файлы проекта уже в подключённой папке. Через computer-use (если есть доступ): открой папку в Finder/Проводнике, двойной клик `install.command` (macOS) / `install.bat` (Windows) / `bash install.sh` (Linux). Установщик откроется в терминале пользователя и сам спросит токен.
3. **Проведи по шагам словами** — короткий чеклист по одному шагу, без простыни.

Не пиши «сейчас установлю» и не делай вид, что сервер появился. Скажи прямо: «Я в песочнице и не могу прописать MCP на твою машину напрямую — давай через двойной клик / Claude Code».

---

## Шаг 1 — Получить код на машину

Локальная папка: подключённая папка проекта (частый случай — она уже есть), либо `~/moysklad-mcp`. Проверь, что внутри есть `install.py` и `serve.py`.

Проверка Python (нужен 3.10+): `python3 --version` (Windows: `py -3 --version`). Нет Python — см. Troubleshooting, сначала поставь.

---

## Шаг 2 — Запустить установку под нужного клиента

`install.py` ничего не ломает: находит конфиг под ОС, дописывает запись сервера БЕЗ секрета, бэкапит старый конфиг. Повторный запуск безопасен. Он также копирует приложение в стабильную папку `~/.moysklad-mcp/app`, чтобы MCP не сломался, если исходную папку перенесут.

Спроси клиента. Команды (из папки проекта):

| Клиент | Команда | Что делает |
|---|---|---|
| **Claude Desktop** (по умолчанию) | `python3 install.py --client claude-desktop` | Пишет `claude_desktop_config.json`, бэкапит старый |
| **Claude Code** (CLI) | `python3 install.py --client claude-code` | ПЕЧАТАЕТ `claude mcp add moysklad -- … ms` — её надо выполнить |
| **Codex** (CLI) | `python3 install.py --client codex` | ПЕЧАТАЕТ `codex mcp add …` — выполнить |
| **OpenCode** | `python3 install.py --client opencode` | Пишет `~/.config/opencode/opencode.json` |

Для `claude-code`/`codex` install.py НЕ пишет конфиг сам — печатает команду, её нужно реально выполнить. Только посмотреть блок: `python3 install.py --print`.

После установки (Claude Desktop / OpenCode) — **перезапусти клиент**. Первый запуск `serve.py` сам создаст venv и поставит зависимости (несколько секунд, вывод в stderr).

---

## Шаг 3 — Токен (где взять и как сохранить)

Токен НИКОГДА не кладётся в репозиторий и в конфиг клиента — он идёт в `~/.moysklad-mcp/cabinets.json` (chmod 600).

**Где взять:** МойСклад → Настройки → Пользователи → Токены доступа → создать Bearer-токен.

**Как сохранить:**
- Интерактивно: `python3 install.py` (спросит токен, Enter = пропустить).
- Флагом (не эхай реальное значение в чат): `python3 install.py --token <TOKEN>` (несколько аккаунтов — `--cabinet account2`).
- Из чата, когда сервер подключён: `ms_add_cabinet(credentials={"token":"…"})`, переключение `ms_use_cabinet`, список `ms_list_cabinets`.

**Запись документов (опционально).** По умолчанию запись ВЫКЛючена. Чтобы агент мог создавать/проводить/удалять документы (приёмки, отгрузки, заказы, счета, возвраты), нужно выставить `MOYSKLAD_ALLOW_WRITE=1` в окружении сервера — и направлять ТОЛЬКО на ТЕСТОВЫЙ кабинет, не на боевой учёт. Без флага все тулы записи безопасно отказывают.

**Безопасность:** не печатай токен обратно в чат даже частично; засветился — перевыпусти в МойСклад (старый отзови).

---

## Шаг 4 — Проверка

Селфчек (токен не нужен): `python3 serve.py ms --selfcheck` → «OK: ms ready, N tools».
Из чата после рестарта: `ms_check_auth` (покажет активный кабинет, чего не хватает; секрет не эхает) → затем `ms_ping` (HTTP 200) → первый боевой вызов `ms_get_products` или `ms_get_stock`. Вернулись реальные данные — установка прошла.

---

## Troubleshooting

**`command not found: python3`:** поставить Python 3.10+ с https://python.org. Windows — отметить «Add python.exe to PATH», открыть новый терминал. Двойной клик `install.bat`/`install.command` подскажет, если Python не найден.

**Кривой/пустой кабинет затеняет env:** активный кабинет в `cabinets.json` приоритетнее переменных окружения. Необъяснимый 401 / «token malformed» — проверь стор: если активный кабинет пустой/dummy, пересохрани реальный токен (`install.py` или `ms_add_cabinet`), либо удали кривой (`ms_remove_cabinet`) и переключись (`ms_use_cabinet`).

**Тулы не появились:** перезапусти клиент (конфиг читается при старте). Для Claude Code/Codex проверь, что реально ВЫПОЛНИЛ напечатанные `* mcp add` команды. Первый запуск ставит venv — если упал, запусти `python3 serve.py ms --selfcheck` вручную и прочитай stderr.

**Запись возвращает «forbidden / запись выключена»:** это норма — выстави `MOYSKLAD_ALLOW_WRITE=1` в окружении сервера и направляй только на тестовый кабинет. Для проведения/удаления тул дополнительно требует подтверждающие флаги.

---

## Памятка (anti-overpromise)

- **Claude Code / локальный CLI** → делаешь всё сам, до проверки включительно.
- **Cowork** → НЕ ставишь MCP сам. Двойной клик (computer-use) ИЛИ Claude Code ИЛИ пошаговый чеклист. Честно проговори границу песочницы.