zaytsv-bot-graph-mcp 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "zaytsv",
+  "owner": { "name": "zaytsv", "url": "https://zaytsv.ru" },
+  "description": "Плагины zaytsv для Claude Code.",
+  "plugins": [
+    {
+      "name": "zaytsv-bot-graph",
+      "source": "./",
+      "description": "Сборка и публикация воронок Telegram-ботов (zaytsv /bots) из описания через MCP + скилл."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "zaytsv-bot-graph",
+  "displayName": "Zaytsv Bot Graph",
+  "version": "0.1.0",
+  "description": "MCP-сервер + скилл для сборки и публикации воронок Telegram-ботов в сервисе zaytsv /bots: из текстового описания → валидный граф → заливка и публикация по API.",
+  "author": { "name": "zaytsv", "url": "https://zaytsv.ru" },
+  "homepage": "https://zaytsv.ru/bots",
+  "repository": "https://github.com/skiddgoddamn/zaytsv-bot-graph-mcp",
+  "license": "MIT",
+  "keywords": ["mcp", "telegram", "bot", "funnel", "zaytsv", "no-code", "claude-code"],
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "bot-graph": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/src/index.mjs"],
+      "env": {
+        "ZAYTSV_BASE_URL": "https://zaytsv.ru",
+        "ZAYTSV_MCP_TOKEN": "${ZAYTSV_MCP_TOKEN}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zaytsv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# zaytsv-bot-graph-mcp
+
+[![CI](https://github.com/skiddgoddamn/zaytsv-bot-graph-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/skiddgoddamn/zaytsv-bot-graph-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/zaytsv-bot-graph-mcp.svg)](https://www.npmjs.com/package/zaytsv-bot-graph-mcp)
+[![node](https://img.shields.io/node/v/zaytsv-bot-graph-mcp.svg)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+MCP-сервер (+ скилл для Claude Code) для **сборки и публикации воронок Telegram-ботов** в сервисе [zaytsv `/bots`](https://zaytsv.ru/bots): из текстового описания → валидный граф сценария → заливка и публикация через API.
+
+- 🤖 **8 инструментов**: `list_bots`, `list_graphs`, `get_graph`, `create_graph`, `update_graph`, `dry_run`, `publish_graph`, `import_funnel`.
+- 🧠 **Скилл `build-bot-funnel`**: учит агента собирать корректный граф (типы узлов, ветки, кнопки, задержки) и проверять его перед публикацией.
+- 📦 **Без зависимостей** — чистый Node ≥18, ставится и запускается сразу.
+
+---
+
+## Установка
+
+### Вариант A — как плагин Claude Code (рекомендуется)
+
+```text
+/plugin marketplace add skiddgoddamn/zaytsv-bot-graph-mcp
+/plugin install zaytsv-bot-graph@zaytsv
+```
+
+Подтянутся и MCP-сервер `bot-graph`, и скилл `build-bot-funnel`. Проверить: `/mcp` и `/plugin`.
+
+### Вариант B — как обычный MCP-сервер (Claude Code / Cursor / Windsurf / любой MCP-клиент)
+
+Через `npx` без установки. Пример конфига (`.mcp.json` / настройки клиента):
+
+```json
+{
+  "mcpServers": {
+    "bot-graph": {
+      "command": "npx",
+      "args": ["-y", "zaytsv-bot-graph-mcp"],
+      "env": {
+        "ZAYTSV_BASE_URL": "https://zaytsv.ru",
+        "ZAYTSV_MCP_TOKEN": "zmcp_ваш_токен"
+      }
+    }
+  }
+}
+```
+
+См. также [`examples/.mcp.json`](examples/.mcp.json).
+
+---
+
+## Авторизация — персональный токен
+
+Токен даёт **полный доступ** к управлению твоими ботами (как вход в аккаунт).
+
+1. Залогинься на https://zaytsv.ru → открой **`/bots/mcp-tokens`**.
+2. Создай токен → скопируй секрет `zmcp_...` (показывается один раз).
+3. Передай его серверу через `ZAYTSV_MCP_TOKEN`:
+   - как `env` в `.mcp.json` (Вариант B), **или**
+   - переменной окружения (Вариант A, плагин): PowerShell `setx ZAYTSV_MCP_TOKEN "zmcp_..."`, bash `export ZAYTSV_MCP_TOKEN="zmcp_..."`.
+
+Отозвать токен можно там же — доступ блокируется мгновенно.
+
+> Дев-окружение: `ZAYTSV_BASE_URL=http://localhost:8066`.
+> Fallback без токена: `ZAYTSV_SESSION_COOKIE` = значение куки `SESSION` из браузера.
+
+---
+
+## Использование
+
+Опиши воронку словами — агент соберёт граф и (через MCP) опубликует:
+
+> «Собери бота: `/start` → приветствие с кнопкой подписки на канал → вопрос с 3 кнопками (бизнес / эксперт / просто смотрю) → для каждой свою цепочку из 2 сообщений с задержкой 1 день → финал с регистрацией на вебинар. Залей в бота и опубликуй.»
+
+Под капотом скилл соберёт `nodes/edges`, прогонит локальную проверку и вызовет `import_funnel` → создаст граф, зальёт узлы, прогонит `dry-run /start`, опубликует. При ошибках публикации — разберёт по `code`/`nodeId`, починит, повторит.
+
+### Инструменты
+
+| Tool | Назначение |
+|---|---|
+| `list_bots` | список ботов |
+| `list_graphs(botId)` | графы (сценарии) бота |
+| `get_graph(graphId)` | получить граф |
+| `create_graph(botId, name)` | создать пустой граф (DRAFT) |
+| `update_graph(graphId, graph\|nodes,edges)` | залить узлы/рёбра (PUT) |
+| `dry_run(graphId, kind, value)` | прогон без публикации |
+| `publish_graph(graphId)` | публикация (вернёт `errors[]` при провале) |
+| `import_funnel(botId, name, graph)` | всё за раз: create → update → dry-run → publish |
+
+---
+
+## Формат графа и проверка
+
+Граф — контейнер `zaytsv-bot-graph` (`nodes[]` + `edges[]`). Полная схема узлов/хэндлов и правила валидатора — в скилле:
+- [`skills/build-bot-funnel/reference/schema.md`](skills/build-bot-funnel/reference/schema.md)
+- [`skills/build-bot-funnel/reference/validation.md`](skills/build-bot-funnel/reference/validation.md)
+
+Локальная проверка графа перед заливкой:
+
+```bash
+node skills/build-bot-funnel/validate.mjs path/to/import.json
+```
+
+---
+
+## Разработка
+
+```bash
+git clone https://github.com/skiddgoddamn/zaytsv-bot-graph-mcp
+cd zaytsv-bot-graph-mcp
+ZAYTSV_MCP_TOKEN=zmcp_... node src/index.mjs   # стартует stdio MCP-сервер
+```
+
+Зависимостей нет — это голый JSON-RPC по stdio (протокол MCP `2024-11-05`).
+
+## Безопасность
+
+Токен = доступ к аккаунту по API. Не коммить его; держи в `env`. В конфигах храни ссылку `${ZAYTSV_MCP_TOKEN}`, не само значение.
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "zaytsv-bot-graph-mcp",
+  "version": "0.1.0",
+  "description": "MCP server to build and publish Telegram bot funnels in the zaytsv /bots service. Zero dependencies.",
+  "type": "module",
+  "bin": { "zaytsv-bot-graph-mcp": "src/index.mjs" },
+  "main": "src/index.mjs",
+  "files": ["src", "skills", ".mcp.json", ".claude-plugin", "README.md", "LICENSE"],
+  "scripts": {
+    "start": "node src/index.mjs",
+    "check": "node --check src/index.mjs",
+    "test": "node scripts/smoke.mjs",
+    "validate": "node skills/build-bot-funnel/validate.mjs"
+  },
+  "engines": { "node": ">=18" },
+  "keywords": ["mcp", "telegram", "bot", "funnel", "zaytsv", "claude-code", "model-context-protocol"],
+  "repository": { "type": "git", "url": "https://github.com/skiddgoddamn/zaytsv-bot-graph-mcp.git" },
+  "homepage": "https://zaytsv.ru/bots",
+  "license": "MIT"
+}

package/skills/build-bot-funnel/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: build-bot-funnel
+description: Собрать воронку (сценарий) Telegram-бота для сервиса /bots из текстового описания — сгенерировать валидный граф формата zaytsv-bot-graph, проверить его и (через MCP bot-graph) залить в бота, прогнать dry-run и опубликовать. Использовать, когда пользователь описывает воронку/прогрев/сценарий бота словами и просит «собрать», «сделать граф», «залить в бота», «опубликовать сценарий».
+---
+
+# Сборка воронки бота (zaytsv /bots)
+
+Превращает **текстовое описание воронки** в валидный граф `zaytsv-bot-graph` и (опционально) публикует его через MCP-сервер `bot-graph`.
+
+## Когда применять
+Пользователь описывает сценарий бота словами: приветствие → подписка → вопрос с кнопками → ветки → задержки → вебинар и т.п. Либо просит залить/опубликовать готовую воронку.
+
+## Рабочий процесс (делай по шагам)
+
+1. **Уточни вход.** Если описание неполное, спроси кратко: точка(и) входа (команда `/start` и т.п.), тексты сообщений, кнопки и куда они ведут, развилки/условия, задержки, финал. Не выдумывай маркетинговые тексты — проси у пользователя или помечай `[ВСТАВЬ ТЕКСТ]` только если он сам разрешил.
+
+2. **Спланируй граф.** Нарисуй в голове дерево: триггеры → сообщения → ветки. Каждой кнопке-выбору — свой выходной хэндл (`btn_0`, `btn_1`…). Подробности типов узлов и хэндлов: [reference/schema.md](reference/schema.md).
+
+3. **Сгенерируй JSON** формата `zaytsv-bot-graph` (см. схему). Требования к корректности (иначе не опубликуется) — в [reference/validation.md](reference/validation.md). Главное:
+   - У каждого `SEND_MESSAGE` непустой `config.text` (и продублируй в `cards[0].text`).
+   - id узлов и рёбер — валидные UUID, уникальные.
+   - Есть хотя бы один корневой `TRIGGER_*`; все нелистовые узлы достижимы от триггера; синхронных циклов нет (цикл только через `ASK_QUESTION`/`DELAY`/`SCHEDULE`).
+   - Кнопки-выборы разведены по хэндлам `btn_N`; условия — `yes`/`no`; вопрос — `valid`/`invalid`.
+
+4. **Проверь локально** перед заливкой:
+   ```bash
+   node "<путь к скиллу>/validate.mjs" <путь к import.json>
+   ```
+   Скрипт ловит пустые сообщения, висячие рёбра, дубли id, недостижимые узлы, превышение 4096, кривые DELAY. Исправь всё, что он покажет.
+
+5. **Залей и опубликуй через MCP `bot-graph`** (если он подключён и пользователь просит публикацию):
+   - `list_bots` → выбрать `botId` (или `create_graph` в существующем боте).
+   - `create_graph(botId, name)` → получить `graphId`.
+   - `update_graph(graphId, nodes, edges, canvasMeta)` → залить узлы/рёбра.
+   - `dry_run(graphId, kind:"command", value:"start")` → прогнать стартовую ветку, проверить `runStatus`.
+   - `publish_graph(graphId)` → если вернулись `errors[]`, разобрать по `code`/`nodeId`, починить узлы, обновить, опубликовать снова.
+   Если MCP не подключён — отдай готовый `import.json` и подскажи: /bots → граф → **Импорт**.
+
+6. **Отчитайся**: сколько узлов/веток, какие тексты помечены на проверку, ссылка/ id графа.
+
+## Важные ограничения
+- **Источник = текст** (этот режим). Если просят распознать с приватной Miro-доски — самый надёжный путь: CSV-экспорт из Miro; либо запуск залогиненного Chrome пользователя и съёмка экрана (headless WebGL-холст Miro не отдаёт). Это отдельный сценарий, не основной для этого скилла.
+- **Авторизация MCP** — персональный токен `ZAYTSV_MCP_TOKEN` (создаётся в вебе на `/bots/mcp-tokens`, формат `zmcp_…`, полный доступ). Fallback — session-cookie. См. README MCP-сервера.
+- Бэкенд читает плоские поля `config.text`/`config.photoUrl`; редактор берёт текст из первой карточки `type:"text"`. Поэтому **всегда заполняй и `text`, и `cards`**.
+
+## Файлы скилла
+- [reference/schema.md](reference/schema.md) — формат графа, типы узлов, конфиги, хэндлы.
+- [reference/validation.md](reference/validation.md) — правила валидатора бэкенда (коды ошибок) и `cardsToLegacy`.
+- `validate.mjs` — оффлайн-проверка графа перед заливкой.

package/skills/build-bot-funnel/reference/schema.md

@@ -0,0 +1,81 @@
+# Формат графа `zaytsv-bot-graph`
+
+## Контейнер импорта
+```json
+{
+  "format": "zaytsv-bot-graph",
+  "version": 1,
+  "name": "Название воронки",
+  "nodes": [ /* TgNode[] */ ],
+  "edges": [ /* TgEdge[] */ ],
+  "canvasMeta": {}
+}
+```
+При заливке через MCP в `update_graph` передаются только `nodes`, `edges`, `canvasMeta`, `name`.
+
+## Узел (TgNode)
+```json
+{ "id": "<uuid>", "type": "<NodeType>", "config": { ... }, "position": { "x": 0, "y": 0 } }
+```
+- `id` — валидный UUID (8-4-4-4-12), уникальный.
+- `position` — раскладка на холсте (слева направо: шаг x ≈ 420; ветки разносим по y).
+
+## Ребро (TgEdge) — «стрелка»
+```json
+{ "id": "<uuid|строка>", "sourceNodeId": "<uuid>", "sourceHandle": "next", "targetNodeId": "<uuid>" }
+```
+`sourceHandle` — какой выход узла используется (см. ниже).
+
+## Типы узлов (NodeType) и их config
+
+### Триггеры (точки входа, корневые)
+- `TRIGGER_COMMAND` — `{ "isRoot": true, "command": "start" }` (команда без `/`). Первый — с `isRoot:true`.
+- `TRIGGER_CALLBACK` — `{ "matchMode": "EQUALS"|"STARTS_WITH", "value": "<callback_data>" }`
+- `TRIGGER_TEXT` — `{ "matchMode": "ANY"|"EQUALS"|"CONTAINS"|"REGEX", "value": "..." }`
+- `BROADCAST_FILTER` — режим рассылки (если есть — единственный триггер).
+
+### Сообщения
+- `SEND_MESSAGE` —
+  ```json
+  { "_title": "Заголовок узла", "parseMode": "PLAIN"|"HTML"|"MARKDOWN",
+    "text": "Текст сообщения",
+    "cards": [ { "id": "c1", "type": "text", "text": "Текст сообщения" } ],
+    "buttons": [ [ { "text": "Кнопка", "kind": "CALLBACK"|"URL", "value": "data|url" } ] ] }
+  ```
+  ВСЕГДА заполняй и `text`, и `cards[0].text` одинаково. `buttons` — массив рядов (каждый ряд — массив кнопок).
+- `SEND_PHOTO` — `{ "photoUrl": "https://...", "text": "подпись (необязательно)" }`
+
+### Логика / ветвление
+- `CONDITION` — выходы `yes` / `no`. `{ "match":"ALL"|"ANY", "conditions":[ { "kind":"...", "op":"...", "key":"...", "value":"..." } ] }`
+- `BRANCH` — `{ "cases":[ {"id":"c1","label":"...","expression":"var.x=='a'"} ], "hasDefault": false, "abTest": false }`. Выходы: `case_<id>` (+ `default`).
+- `ASK_QUESTION` — вопрос со сбором ответа. `{ "promptText":"...","saveTo":"name","validator":"ANY"|"PHONE"|"EMAIL"|"REGEX","regex":"...","retryText":"...","maxAttempts":3 }`. Выходы `valid` / `invalid`.
+- `END` — `{}` (конец ветки).
+
+### Тайминги
+- `DELAY` — пауза:
+  - фиксированная: `{ "kind":"FIXED", "durationSec": 86400 }`
+  - до даты/времени: `{ "kind":"UNTIL", "isoDate":"2026-06-25", "time":"18:00" }`
+- `SCHEDULE` — `{ "isoDate":"2026-06-25", "time":"18:00", "timezone":"Europe/Moscow" }`. Выходы `scheduled` / `past`.
+
+### Состояние / действия
+- `SET_VARIABLE`, `ADD_TAG`, `REMOVE_TAG`, `FORMULA` (`{ "expression":"...", "saveTo":"name" }`)
+- `ACTIONS` — пакет действий: `{ "actions":[ { "kind":"add_tag","tag":"lead" }, { "kind":"notify","text":"..." }, { "kind":"set_field","key":"phone","value":"{{var.phone}}" }, { "kind":"external_request","url":"...","method":"POST","body":"..." } ] }`
+
+### Внешнее / прочее
+- `CALL_WEBHOOK` — `{ "url":"https://...", "method":"POST", "bodyTemplate":"{...}", "timeoutMs":5000 }`. Выходы `ok` / `error`.
+- `AI_REPLY`, `PAYMENT_LINK`.
+
+## Выходные хэндлы (`sourceHandle`) — шпаргалка
+| Узел | Хэндлы |
+|---|---|
+| обычный поток | `next` |
+| кнопки сообщения (`buttons`) | `btn_0`, `btn_1`, … (по индексу кнопки) |
+| `CONDITION` | `yes`, `no` |
+| `BRANCH` | `case_<id>`, `default` |
+| `ASK_QUESTION` | `valid`, `invalid` |
+| `CALL_WEBHOOK` | `ok`, `error` |
+| `SCHEDULE` | `scheduled`, `past` |
+| `DELAY` | `next` |
+
+## Подстановки в тексте
+`{{from.first_name}}`, `{{from.username}}`, `{{var.<имя>}}`, либо `{Имя}` как плейсхолдер. Имена переменных/меток: `[a-z_][a-z0-9_]{0,63}` (var) и `[a-z0-9_-]{1,64}` (tag).

package/skills/build-bot-funnel/reference/validation.md

@@ -0,0 +1,47 @@
+# Правила валидатора (GraphValidator) — чтобы граф публиковался
+
+Источник истины: `zaytsvBackend/.../service/bot/GraphValidator.java`. При `publish` бэкенд возвращает `errors: [{ nodeId, code, message }]`. Ниже — что проверяется и как не нарваться.
+
+## Коды ошибок и условия
+
+### `SEND_NO_TEXT` — «Пустое сообщение — добавьте текст или картинку»
+`SEND_MESSAGE` считается пустым, если **`config.text` пустой/из пробелов И `config.photoUrl` пустой**.
+- Бэкенд читает плоское `config.text` (НЕ `cards`).
+- Но редактор при сохранении пересобирает `text` из карточек через `cardsToLegacy`: берёт **первую карточку `type:"text"` с непустым `text`** (или `image.url`→`photoUrl`).
+- ⇒ ВСЕГДА заполняй и `config.text`, и `cards[0]` (тип `text`, непустой `text`). Тогда оба пути дают непустой текст.
+- Кнопок недостаточно: сообщение только с `buttons` — пустое.
+- Пробелы/таб/перенос строки = пусто (`.isBlank()`).
+
+### Длина текста
+- `text` ≤ 4096; если есть `photoUrl` (подпись) — ≤ 1024.
+- При `parseMode:"HTML"` — текст должен быть безопасным HTML (без неразрешённых тегов). Если не уверен — `PLAIN`.
+
+### Триггеры и достижимость
+- Нужен **хотя бы один корневой `TRIGGER_*`** без входящих рёбер.
+- Если есть `BROADCAST_FILTER` — он должен быть единственным триггером.
+- **Все нелистовые узлы достижимы** от какого-либо триггера. Недостижимый узел = ошибка.
+
+### Циклы
+- **Синхронных циклов нет.** Цикл допустим только если проходит через `ASK_QUESTION`, `DELAY` или `SCHEDULE` (узлы, которые «ждут»).
+
+### Per-node конфиг
+- `TRIGGER_COMMAND`: `command` обязателен.
+- `TRIGGER_CALLBACK`: `value` обязателен; `matchMode` ∈ {EQUALS, STARTS_WITH}.
+- `TRIGGER_TEXT`: `matchMode` ∈ {ANY,EQUALS,CONTAINS,REGEX}; для не-ANY нужен `value`.
+- `ASK_QUESTION`: `promptText` обязателен; `saveTo` ∈ `[a-z_][a-z0-9_]{0,63}`.
+- `BRANCH`: ≥1 case; выражения валидны (или `abTest:true`).
+- `CALL_WEBHOOK`: `url` обязателен, http(s)://.
+- `DELAY`: `FIXED` с `durationSec>0`, либо `UNTIL` с `isoDate`+`time`.
+- Метки: `[a-z0-9_-]{1,64}`. Переменные: `[a-z_][a-z0-9_]{0,63}`.
+
+## Рёбра
+- `sourceNodeId` и `targetNodeId` должны указывать на существующие узлы (нет «висячих»).
+- `sourceHandle` должен соответствовать типу узла-источника (см. schema.md).
+- id узлов и рёбер — уникальны; id узлов — валидные UUID (Jackson десериализует `UUID`).
+
+## Жизненный цикл
+- Статусы графа: `DRAFT` / `PUBLISHED`. Публикация заменяет активную опубликованную версию.
+- Перед публикацией полезно прогнать `dry_run` (kind `command`/`callback`/`text`) — поймать рантайм-проблемы стартовой ветки.
+
+## Локальная проверка
+`node validate.mjs <import.json>` повторяет ключевые проверки (пустые сообщения с учётом `cardsToLegacy`, висячие рёбра, дубли id, достижимость от триггеров, длину текста, базовый конфиг DELAY/триггеров). Гонять перед каждой заливкой.

package/skills/build-bot-funnel/validate.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Оффлайн-валидатор графа zaytsv-bot-graph. Без зависимостей.
+// Использование:  node validate.mjs <path/to/import.json>
+// Повторяет ключевые правила GraphValidator + cardsToLegacy редактора.
+
+import { readFileSync } from "node:fs";
+
+const path = process.argv[2];
+if (!path) { console.error("Usage: node validate.mjs <import.json>"); process.exit(2); }
+
+let g;
+try { g = JSON.parse(readFileSync(path, "utf8")); }
+catch (e) { console.error("❌ Не удалось прочитать/распарсить JSON:", e.message); process.exit(2); }
+
+const nodes = Array.isArray(g.nodes) ? g.nodes : [];
+const edges = Array.isArray(g.edges) ? g.edges : [];
+const errors = [];
+const warns = [];
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VAR_RE = /^[a-z_][a-z0-9_]{0,63}$/;
+
+// cardsToLegacy: текст = первая text-карточка с непустым text (или image.url -> photoUrl)
+function cardsToLegacy(cards) {
+  cards = Array.isArray(cards) ? cards : [];
+  const firstImage = cards.find((c) => c && c.type === "image" && c.url);
+  const firstText = cards.find((c) => c && c.type === "text" && c.text);
+  const firstMedia = cards.find((c) => c && ["image", "video", "audio", "file"].includes(c.type) && c.text);
+  let text, photoUrl;
+  if (firstImage) { photoUrl = firstImage.url; text = firstImage.text || (firstText && firstText.text) || ""; }
+  else if (firstText) { text = firstText.text; }
+  else if (firstMedia) { text = firstMedia.text; }
+  if (!text && !photoUrl) text = "";
+  return { text: text || "", photoUrl: photoUrl || "" };
+}
+const blank = (s) => !s || !String(s).trim();
+
+// --- id / структура ---
+const ids = new Set();
+for (const n of nodes) {
+  if (!n || !n.id) { errors.push(`Узел без id: ${JSON.stringify(n).slice(0, 80)}`); continue; }
+  if (ids.has(n.id)) errors.push(`Дубль id узла: ${n.id}`);
+  ids.add(n.id);
+  if (!UUID_RE.test(n.id)) warns.push(`id узла не UUID (бэкенд десериализует UUID): ${n.id} «${n.config?._title || n.type}»`);
+}
+const edgeIds = new Set();
+for (const e of edges) {
+  if (e.id && edgeIds.has(e.id)) errors.push(`Дубль id ребра: ${e.id}`);
+  if (e.id) edgeIds.add(e.id);
+  if (!ids.has(e.sourceNodeId)) errors.push(`Висячее ребро ${e.id}: нет sourceNodeId ${e.sourceNodeId}`);
+  if (!ids.has(e.targetNodeId)) errors.push(`Висячее ребро ${e.id}: нет targetNodeId ${e.targetNodeId}`);
+}
+
+// --- per-node ---
+const triggers = nodes.filter((n) => String(n.type).startsWith("TRIGGER") || n.type === "BROADCAST_FILTER");
+if (triggers.length === 0) errors.push("Нет ни одного триггера (TRIGGER_*) — graph не опубликуется.");
+const broadcast = nodes.filter((n) => n.type === "BROADCAST_FILTER");
+if (broadcast.length && triggers.length > broadcast.length) errors.push("BROADCAST_FILTER должен быть единственным триггером.");
+
+for (const n of nodes) {
+  const c = n.config || {};
+  const who = `«${c._title || n.id}» (${n.type})`;
+  switch (n.type) {
+    case "SEND_MESSAGE": {
+      const flat = !blank(c.text) || !blank(c.photoUrl);
+      const lg = Array.isArray(c.cards) && c.cards.length ? cardsToLegacy(c.cards) : { text: c.text || "", photoUrl: c.photoUrl || "" };
+      if (!flat) errors.push(`SEND_NO_TEXT: ${who} — пустой config.text/photoUrl.`);
+      else if (blank(lg.text) && blank(lg.photoUrl)) errors.push(`SEND_NO_TEXT: ${who} — после cardsToLegacy текст пуст (нет text-карточки с содержимым).`);
+      const t = String(c.text || "");
+      const lim = !blank(c.photoUrl) ? 1024 : 4096;
+      if (t.length > lim) errors.push(`Текст ${who} = ${t.length} > ${lim}.`);
+      break;
+    }
+    case "SEND_PHOTO":
+      if (blank(c.photoUrl)) errors.push(`${who}: нужен photoUrl.`);
+      break;
+    case "TRIGGER_COMMAND":
+      if (blank(c.command)) errors.push(`${who}: нужен command.`);
+      break;
+    case "TRIGGER_CALLBACK":
+      if (blank(c.value)) errors.push(`${who}: нужен value.`);
+      if (c.matchMode && !["EQUALS", "STARTS_WITH"].includes(c.matchMode)) errors.push(`${who}: matchMode ∈ {EQUALS,STARTS_WITH}.`);
+      break;
+    case "TRIGGER_TEXT":
+      if (c.matchMode && c.matchMode !== "ANY" && blank(c.value)) errors.push(`${who}: для matchMode≠ANY нужен value.`);
+      break;
+    case "ASK_QUESTION":
+      if (blank(c.promptText)) errors.push(`${who}: нужен promptText.`);
+      if (c.saveTo && !VAR_RE.test(c.saveTo)) errors.push(`${who}: saveTo «${c.saveTo}» не матчит [a-z_][a-z0-9_]{0,63}.`);
+      break;
+    case "CALL_WEBHOOK":
+      if (blank(c.url) || !/^https?:\/\//.test(c.url)) errors.push(`${who}: url обязателен и http(s)://.`);
+      break;
+    case "DELAY":
+      if (c.kind === "FIXED") { if (!(Number(c.durationSec) > 0)) errors.push(`${who}: FIXED требует durationSec>0.`); }
+      else if (c.kind === "UNTIL") { if (blank(c.isoDate) || blank(c.time)) errors.push(`${who}: UNTIL требует isoDate и time.`); }
+      else errors.push(`${who}: kind ∈ {FIXED,UNTIL}.`);
+      break;
+    case "BRANCH":
+      if (!Array.isArray(c.cases) || c.cases.length === 0) errors.push(`${who}: нужен хотя бы один case.`);
+      break;
+  }
+}
+
+// --- достижимость от триггеров ---
+const adj = {};
+for (const e of edges) (adj[e.sourceNodeId] = adj[e.sourceNodeId] || []).push(e.targetNodeId);
+const reach = new Set();
+const stack = triggers.map((t) => t.id);
+while (stack.length) { const x = stack.pop(); if (reach.has(x)) continue; reach.add(x); (adj[x] || []).forEach((y) => stack.push(y)); }
+for (const n of nodes) {
+  if (String(n.type).startsWith("TRIGGER") || n.type === "BROADCAST_FILTER") continue;
+  if (!reach.has(n.id)) errors.push(`Недостижимый узел от триггера: «${n.config?._title || n.id}» (${n.type}).`);
+}
+
+// --- синхронные циклы (цикл без DELAY/ASK_QUESTION/SCHEDULE = ошибка) ---
+const waitTypes = new Set(["ASK_QUESTION", "DELAY", "SCHEDULE"]);
+const typeById = Object.fromEntries(nodes.map((n) => [n.id, n.type]));
+const color = {}; // 0=white,1=gray,2=black
+function dfs(u, pathHasWaitAtEdgeInto) {
+  color[u] = 1;
+  for (const v of adj[u] || []) {
+    if (color[v] === 1) {
+      // нашли цикл u->...->v; ок только если в цикле есть wait-узел
+      // упрощённо: если ни u, ни v не wait — предупредим как потенциальный синхронный цикл
+      if (!waitTypes.has(typeById[u]) && !waitTypes.has(typeById[v]))
+        warns.push(`Возможный синхронный цикл рядом с ${v} — убедись, что в петле есть DELAY/ASK_QUESTION/SCHEDULE.`);
+    } else if (color[v] !== 2) {
+      dfs(v);
+    }
+  }
+  color[u] = 2;
+}
+for (const n of nodes) if (!color[n.id]) dfs(n.id);
+
+// --- отчёт ---
+const byType = {};
+nodes.forEach((n) => (byType[n.type] = (byType[n.type] || 0) + 1));
+console.log(`Граф: ${nodes.length} узлов, ${edges.length} рёбер, ${triggers.length} триггеров`);
+console.log(`Типы: ${JSON.stringify(byType)}`);
+if (warns.length) { console.log(`\n⚠️  Предупреждения (${warns.length}):`); warns.forEach((w) => console.log("  • " + w)); }
+if (errors.length) {
+  console.log(`\n❌ Ошибки (${errors.length}) — публикация не пройдёт:`);
+  errors.forEach((e) => console.log("  • " + e));
+  process.exit(1);
+}
+console.log("\n✅ Валидация пройдена — граф готов к заливке/публикации.");

package/src/index.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * zaytsv-bot-graph-mcp — MCP-сервер для сборки и публикации графов Telegram-ботов
+ * через API сервиса zaytsv /bots. Без внешних зависимостей (голый JSON-RPC по stdio),
+ * поэтому работает сразу, без npm install — в Claude Code, Cursor, Windsurf и т.п.
+ *
+ * Авторизация: персональный токен (PAT) Bearer; fallback — session-cookie.
+ *
+ * ENV:
+ *   ZAYTSV_MCP_TOKEN       персональный токен "zmcp_..." (создаётся в вебе: /bots/mcp-tokens)
+ *   ZAYTSV_BASE_URL        база API. По умолчанию https://zaytsv.ru (дев: http://localhost:8066)
+ *   ZAYTSV_SESSION_COOKIE  (fallback) значение куки SESSION из браузера
+ *   ZAYTSV_COOKIE          (fallback) полная строка Cookie
+ */
+
+import { createInterface } from "node:readline";
+
+const VERSION = "0.1.0";
+const BASE = (process.env.ZAYTSV_BASE_URL || "https://zaytsv.ru").replace(/\/+$/, "");
+const TOKEN = (process.env.ZAYTSV_MCP_TOKEN || "").trim();
+const COOKIE =
+  process.env.ZAYTSV_COOKIE ||
+  (process.env.ZAYTSV_SESSION_COOKIE ? `SESSION=${process.env.ZAYTSV_SESSION_COOKIE}` : "");
+
+function authHeaders() {
+  const h = { "Content-Type": "application/json" };
+  if (TOKEN) h.Authorization = `Bearer ${TOKEN}`;
+  else if (COOKIE) h.Cookie = COOKIE;
+  return h;
+}
+
+async function api(path, { method = "GET", body } = {}) {
+  if (!TOKEN && !COOKIE) {
+    throw new Error("Не задана авторизация: установи ZAYTSV_MCP_TOKEN (рекомендуется) или ZAYTSV_SESSION_COOKIE в env.");
+  }
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: authHeaders(),
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = text; }
+  if (!res.ok) {
+    const msg = typeof data === "string" ? data : JSON.stringify(data);
+    throw new Error(`${method} ${path} → HTTP ${res.status}. ${(msg || "").slice(0, 600)}`);
+  }
+  return data;
+}
+
+const okResult = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
+const errResult = (e) => ({ isError: true, content: [{ type: "text", text: "❌ " + (e?.message || String(e)) }] });
+
+function extractGraph(g) {
+  if (!g || typeof g !== "object") throw new Error("graph должен быть объектом (контейнер zaytsv-bot-graph или {nodes,edges}).");
+  const nodes = g.nodes ?? g.graph?.nodes;
+  const edges = g.edges ?? g.graph?.edges;
+  if (!Array.isArray(nodes) || !Array.isArray(edges)) throw new Error("В graph нет массивов nodes[] и edges[].");
+  return { name: g.name, nodes, edges, canvasMeta: g.canvasMeta ?? {} };
+}
+
+const TOOLS = [
+  { name: "list_bots", description: "Список ботов пользователя (id, имя, статус).", inputSchema: { type: "object", properties: {} } },
+  { name: "list_graphs", description: "Список графов (сценариев) бота.", inputSchema: { type: "object", properties: { botId: { type: "string" } }, required: ["botId"] } },
+  { name: "get_graph", description: "Получить граф целиком по graphId.", inputSchema: { type: "object", properties: { graphId: { type: "string" } }, required: ["graphId"] } },
+  { name: "create_graph", description: "Создать пустой граф (DRAFT) в боте. Возвращает граф с id.", inputSchema: { type: "object", properties: { botId: { type: "string" }, name: { type: "string" } }, required: ["botId", "name"] } },
+  { name: "update_graph", description: "Залить узлы/рёбра в граф (PUT). Принимает graph-контейнер или nodes/edges.", inputSchema: { type: "object", properties: { graphId: { type: "string" }, graph: { type: "object" }, nodes: { type: "array" }, edges: { type: "array" }, canvasMeta: { type: "object" }, name: { type: "string" } }, required: ["graphId"] } },
+  { name: "dry_run", description: "Прогнать сценарий без публикации. kind: command|callback|text.", inputSchema: { type: "object", properties: { graphId: { type: "string" }, kind: { type: "string", enum: ["command", "callback", "text"] }, value: { type: "string" }, fromUsername: { type: "string" }, presetVariables: { type: "object" }, presetTags: { type: "array", items: { type: "string" } } }, required: ["graphId", "kind", "value"] } },
+  { name: "publish_graph", description: "Опубликовать граф. Вернёт publishedGraphId или errors[] (code, nodeId, message).", inputSchema: { type: "object", properties: { graphId: { type: "string" } }, required: ["graphId"] } },
+  { name: "import_funnel", description: "Всё за раз: создать граф, залить узлы/рёбра, (опц.) dry-run /start, опубликовать.", inputSchema: { type: "object", properties: { botId: { type: "string" }, name: { type: "string" }, graph: { type: "object" }, dryRun: { type: "boolean" }, publish: { type: "boolean" } }, required: ["botId", "graph"] } },
+];
+
+async function handleCall(params) {
+  const a = (params && params.arguments) || {};
+  switch (params && params.name) {
+    case "list_bots": return okResult(await api("/api/tg/bots"));
+    case "list_graphs": return okResult(await api(`/api/tg/bots/${a.botId}/graphs`));
+    case "get_graph": return okResult(await api(`/api/tg/graphs/${a.graphId}`));
+    case "create_graph": return okResult(await api(`/api/tg/bots/${a.botId}/graphs`, { method: "POST", body: { name: a.name } }));
+    case "update_graph": {
+      const src = a.graph ? extractGraph(a.graph) : { nodes: a.nodes, edges: a.edges, canvasMeta: a.canvasMeta ?? {}, name: a.name };
+      if (!Array.isArray(src.nodes) || !Array.isArray(src.edges)) throw new Error("Нужны nodes[] и edges[] (в graph или отдельно).");
+      const payload = { nodes: src.nodes, edges: src.edges, canvasMeta: src.canvasMeta ?? {} };
+      if (a.name ?? src.name) payload.name = a.name ?? src.name;
+      return okResult(await api(`/api/tg/graphs/${a.graphId}`, { method: "PUT", body: payload }));
+    }
+    case "dry_run":
+      return okResult(await api(`/api/tg/graphs/${a.graphId}/dry-run`, { method: "POST", body: { kind: a.kind, value: a.value, fromUsername: a.fromUsername, presetVariables: a.presetVariables, presetTags: a.presetTags } }));
+    case "publish_graph":
+      return okResult(await api(`/api/tg/graphs/${a.graphId}/publish`, { method: "POST" }));
+    case "import_funnel": {
+      const src = extractGraph(a.graph);
+      const steps = [];
+      const created = await api(`/api/tg/bots/${a.botId}/graphs`, { method: "POST", body: { name: a.name || src.name || "Воронка" } });
+      const graphId = created.id;
+      steps.push(`создан граф ${graphId}`);
+      await api(`/api/tg/graphs/${graphId}`, { method: "PUT", body: { nodes: src.nodes, edges: src.edges, canvasMeta: src.canvasMeta ?? {}, name: a.name || src.name } });
+      steps.push(`залито узлов: ${src.nodes.length}, рёбер: ${src.edges.length}`);
+      if (a.dryRun !== false) {
+        const dr = await api(`/api/tg/graphs/${graphId}/dry-run`, { method: "POST", body: { kind: "command", value: "start" } });
+        steps.push(`dry-run /start: runStatus=${dr.runStatus}`);
+      }
+      if (a.publish !== false) {
+        const pub = await api(`/api/tg/graphs/${graphId}/publish`, { method: "POST" });
+        if (pub.errors && pub.errors.length) {
+          steps.push(`❌ публикация не прошла, ошибок: ${pub.errors.length}`);
+          return okResult({ graphId, steps, publishErrors: pub.errors });
+        }
+        steps.push(`✅ опубликовано: publishedGraphId=${pub.publishedGraphId}`);
+        return okResult({ graphId, publishedGraphId: pub.publishedGraphId, steps });
+      }
+      return okResult({ graphId, steps });
+    }
+    default:
+      throw new Error(`Неизвестный инструмент: ${params && params.name}`);
+  }
+}
+
+// ---- JSON-RPC stdio (MCP) ----
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", async (line) => {
+  line = line.trim();
+  if (!line) return;
+  let req;
+  try { req = JSON.parse(line); } catch { return; }
+  const { id, method, params } = req;
+  try {
+    if (method === "initialize") {
+      send({ jsonrpc: "2.0", id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "zaytsv-bot-graph", version: VERSION } } });
+    } else if (method === "tools/list") {
+      send({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+    } else if (method === "tools/call") {
+      let result;
+      try { result = await handleCall(params); } catch (e) { result = errResult(e); }
+      send({ jsonrpc: "2.0", id, result });
+    } else if (method === "ping") {
+      send({ jsonrpc: "2.0", id, result: {} });
+    } else if (id !== undefined && id !== null) {
+      // неизвестный метод с id — корректный JSON-RPC error; нотификации игнорируем
+      send({ jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } });
+    }
+  } catch (e) {
+    if (id !== undefined && id !== null) send({ jsonrpc: "2.0", id, error: { code: -32603, message: String(e?.message || e) } });
+  }
+});
+
+process.stderr.write(`[zaytsv-bot-graph] MCP ${VERSION}. BASE=${BASE}. Авторизация: ${TOKEN ? "токен (Bearer)" : COOKIE ? "cookie" : "НЕ задана"}.\n`);