@hubex/mcp 0.2.0

package/.env.example

@@ -0,0 +1,54 @@
+# --- HubEx MCP configuration ---
+
+# Target environment: dev | stg | prod
+# prod ходит на https://api.hubex.ru/fsm (без префикса), dev/stg — на https://{env}-api.hubex.ru/fsm
+# Этой же переменной выбирается кэш swagger-схем: prod читает swagger/prod/ и
+# generated/index.prod.json, dev и stg — swagger/dev/ и generated/index.dev.json.
+HUBEX_ENV=dev
+
+# Required header for every request. For the dev tenant this is 5.
+HUBEX_APPLICATION_ID=5
+
+# Optional: pin the tenant explicitly. If omitted, it is read from the JWT (TenantID claim).
+# HUBEX_TENANT_ID=5
+
+# Auth mode: token | login | service
+HUBEX_AUTH_MODE=token
+
+# --- mode "token" ---
+# Ничего настраивать не нужно: сервер сам попросит access-токен при первом
+# обращении (поле ввода в клиенте, либо инструмент hubex_set_token).
+
+# --- mode "login" ---
+# HUBEX_AUTH_MODE=login
+# HUBEX_USERNAME=poweruser@hubex.ru
+# HUBEX_PASSWORD=your-password
+
+# --- mode "service" ---
+# Долгоживущий интеграционный токен. HUBEX_TENANT_ID в этом режиме не нужен:
+# токен сам определяет члена тенанта.
+# HUBEX_AUTH_MODE=service
+# HUBEX_SERVICE_TOKEN=ВАШ_ИНТЕГРАЦИОННЫЙ_ТОКЕН
+
+# Какие HTTP-методы вообще доступны серверу.
+# По умолчанию все: GET,POST,PUT,PATCH,DELETE,HEAD
+# Запрещённые методы не регистрируются: их search_*/request_* не видны агенту.
+# HUBEX_METHODS=GET,POST,PUT
+
+# Эквивалент HUBEX_METHODS=GET,HEAD. При конфликте побеждает более узкое.
+# HUBEX_READONLY=true
+
+# Ограничить область поиска и исполнения списком сервисов.
+# По умолчанию доступны все 22.
+# HUBEX_SERVICES=WORK,ES,ADM
+
+# Значения, подставляемые в тело write-запросов, если поле не задано.
+# HUBEX_DEFAULT_REQUEST_METHOD_ID=4
+# HUBEX_DEFAULT_TASK_TYPE_ID=1
+# HUBEX_DEFAULT_COMPANY_ID=123
+
+# Маскировать персональные данные (ФИО, телефоны, email, адреса, логины,
+# токены, координаты) в ответах перед отдачей в контекст модели.
+# По умолчанию включено. Выключается только явно — маска необратима,
+# и агент не сможет использовать увиденное значение в следующем запросе.
+# HUBEX_MASK_PII=false

package/CONNECTING.md

@@ -0,0 +1,260 @@
+# Подключение HubEx MCP
+
+Инструкции по подключению сервера к разным клиентам: **Claude Code**, **Claude Desktop**,
+**Codex CLI** и **Cursor**.
+
+## 0. Как получить сервер
+
+Пакет называется `@hubex/mcp` и публикуется в публичный npmjs. Во всех конфигах ниже
+используется команда `hubex-mcp` — она появляется в `PATH` после глобальной установки
+(имя команды осталось прежним, скоуп на него не влияет).
+
+### Вариант А — из npm (обычный путь)
+
+```bash
+npm install -g @hubex/mcp
+```
+
+Проверка: `which hubex-mcp`. Обновление — `npm update -g @hubex/mcp`,
+удаление — `npm rm -g @hubex/mcp`.
+
+Без установки — `npx -y @hubex/mcp`; тогда в конфигах вместо `"command": "hubex-mcp"`
+пишут `"command": "npx"` и `"args": ["-y", "@hubex/mcp"]`.
+
+Патч-часть версии — дата сборки схем по UTC (`0.2.20260827`), так что по версии
+установленного пакета сразу видно, насколько свежий в нём кэш swagger.
+
+> Первый релиз выпускается вручную, и до него этот вариант вернёт 404 —
+> пользуйтесь вариантом Б.
+
+### Вариант Б — готовый пакет (для тех, кому его передали)
+
+Автор присылает файл `hubex-mcp-<версия>.tgz` (имя файла без скоупа — npm склеивает
+`@hubex/mcp` в `hubex-mcp`). Установка:
+
+```bash
+npm install -g ./hubex-mcp-0.2.0.tgz
+```
+
+Дальше всё как в варианте А: в `PATH` появляется команда `hubex-mcp`, абсолютные пути
+к `dist/index.js` не нужны. Обновление — переустановить новый `.tgz` той же командой.
+
+### Вариант В — собрать пакет для раздачи (автор)
+
+```bash
+cd /path/to/hubexMCP
+npm install
+npm pack
+```
+
+`npm pack` сам запускает сборку (`prepack` → `npm run build`) и кладёт рядом
+`hubex-mcp-<версия>.tgz` — самодостаточный архив: скомпилированный `dist/`, индекс
+эндпоинтов `generated/index.{dev,prod}.json`, кэш `swagger/{dev,prod}/` и гайды
+`docs/guides/`.
+Получателю нужен только Node.js ≥ 20 — ни исходников, ни репозитория.
+
+Перед раздачей поднимите `version` в `package.json`: она видна клиенту в `serverInfo`
+и по ней получатель понимает, что у него за сборка.
+
+> `npm publish` уедет в публичный npmjs (`publishConfig.access: "public"`), а внутрь
+> тарбола попадает кэш внутренних swagger-схем обоих контуров — учитывайте это перед
+> публикацией.
+
+### Вариант Г — из исходников (разработка сервера)
+
+```bash
+cd /path/to/hubexMCP
+npm install
+npm run build
+```
+
+Точка входа: `<путь-до-репозитория>/dist/index.js` — её указывают вместо команды
+`hubex-mcp` в конфигах ниже (`"command": "node"`, `"args": ["<путь>/dist/index.js"]`).
+Пересобирайте после каждого `git pull`.
+
+### Переменные окружения
+
+| Переменная | Обязательна | Значение |
+|---|---|---|
+| `HUBEX_ENV` | да | `dev`, `stg` или `prod` |
+| `HUBEX_APPLICATION_ID` | да | `5` (для dev-тенанта) |
+| `HUBEX_AUTH_MODE` | да | `token`, `login` или `service` |
+| `HUBEX_USERNAME` / `HUBEX_PASSWORD` | для `login` | логин/пароль (токен обновляется сам) |
+| `HUBEX_SERVICE_TOKEN` | для `service` | долгоживущий интеграционный токен (обновляется сам) |
+| `HUBEX_TENANT_ID` | нет | tenant явно; иначе берётся из JWT |
+| `HUBEX_METHODS` | нет | список доступных HTTP-методов через запятую (по умолчанию — все шесть) |
+| `HUBEX_READONLY` | нет | `true` — эквивалент `HUBEX_METHODS=GET,HEAD` |
+| `HUBEX_SERVICES` | нет | ограничить поиск и исполнение списком сервисов (по умолчанию — все 22) |
+| `HUBEX_DEFAULT_REQUEST_METHOD_ID` | нет | значение по умолчанию для тела write-запросов |
+| `HUBEX_DEFAULT_TASK_TYPE_ID` | нет | значение по умолчанию для тела write-запросов |
+| `HUBEX_DEFAULT_COMPANY_ID` | нет | значение по умолчанию для тела write-запросов |
+
+> Режим `token` переменных не требует: при первом обращении сервер попросит
+> access-токен. Клиенты с поддержкой elicitation (Claude Code, Claude Desktop)
+> покажут поле ввода; остальным нужно вызвать инструмент `hubex_set_token` и
+> передать токен в него. По токену запрашивается refresh, дальше сессия
+> продлевается сама; после перезапуска сервера токен спрашивается заново.
+
+> Сервисный токен выпускается один раз администратором:
+> `POST /fsm/AUTHZ/ServiceTokens` с Bearer и полномочием `ServiceTokenAdd`, тело — массив id
+> членов тенанта. Отзыв — `DELETE /fsm/AUTHZ/ServiceTokens` с полномочием `ServiceTokenRemove`.
+
+---
+
+## 1. Claude Code (CLI)
+
+Команда `claude mcp add` со scope `user` — сервер станет доступен во **всех** ваших проектах:
+
+```bash
+claude mcp add hubex --scope user \
+  --env HUBEX_ENV=dev \
+  --env HUBEX_APPLICATION_ID=5 \
+  --env HUBEX_AUTH_MODE=login \
+  --env HUBEX_USERNAME=poweruser@hubex.ru \
+  --env HUBEX_PASSWORD=<пароль> \
+  -- hubex-mcp
+```
+
+С сервисным токеном (`--env HUBEX_AUTH_MODE=service --env HUBEX_SERVICE_TOKEN=<токен>` вместо
+`HUBEX_AUTH_MODE=login` + `HUBEX_USERNAME`/`HUBEX_PASSWORD`) — удобно для CI и общих окружений,
+где заводить учётку не хочется.
+
+Без `--scope user` конфиг попадёт в scope `local` — только для текущего каталога.
+
+Проверка: `claude mcp list` → `hubex: ✓ connected`. Список инструментов — командой `/mcp`
+внутри сессии (после перезапуска).
+
+Чтобы расшарить конфиг команде через git, используйте scope `project` (создаёт `.mcp.json`
+в корне репозитория — **без секретов**, подставляйте токен/пароль из окружения):
+
+```bash
+claude mcp add hubex --scope project -- hubex-mcp
+```
+
+Удалить: `claude mcp remove hubex`.
+
+---
+
+## 2. Claude Desktop
+
+Файл конфигурации:
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS).
+
+```json
+{
+  "mcpServers": {
+    "hubex": {
+      "command": "hubex-mcp",
+      "env": {
+        "HUBEX_ENV": "dev",
+        "HUBEX_APPLICATION_ID": "5",
+        "HUBEX_AUTH_MODE": "login",
+        "HUBEX_USERNAME": "...",
+        "HUBEX_PASSWORD": "...",
+        "HUBEX_METHODS": "GET,HEAD,POST,PUT",
+        "HUBEX_SERVICES": "WORK,ES,ADM",
+        "HUBEX_DEFAULT_REQUEST_METHOD_ID": "4"
+      }
+    }
+  }
+}
+```
+
+Этот пример разрешает всё, кроме удаления; чтобы вернуть `DELETE`, добавь его в
+`HUBEX_METHODS` — тогда появятся `hubex_search_delete_endpoints` и `hubex_request_delete`.
+
+Для сервисного токена замени `HUBEX_AUTH_MODE`/`HUBEX_USERNAME`/`HUBEX_PASSWORD` на:
+
+```json
+"HUBEX_AUTH_MODE": "service",
+"HUBEX_SERVICE_TOKEN": "<токен>"
+```
+
+После правки **полностью перезапустите** Claude Desktop. Инструменты появятся в меню 🔌.
+
+---
+
+## 3. Codex CLI
+
+Codex хранит конфиг MCP в `~/.codex/config.toml` (формат TOML, секция `mcp_servers`):
+
+```toml
+[mcp_servers.hubex]
+command = "hubex-mcp"
+args = []
+
+[mcp_servers.hubex.env]
+HUBEX_ENV = "dev"
+HUBEX_APPLICATION_ID = "5"
+HUBEX_AUTH_MODE = "login"
+HUBEX_USERNAME = "poweruser@hubex.ru"
+HUBEX_PASSWORD = "<пароль>"
+```
+
+Либо через CLI (если версия поддерживает):
+
+```bash
+codex mcp add hubex \
+  --env HUBEX_ENV=dev --env HUBEX_APPLICATION_ID=5 \
+  --env HUBEX_AUTH_MODE=login \
+  --env HUBEX_USERNAME=poweruser@hubex.ru --env HUBEX_PASSWORD=<пароль> \
+  -- hubex-mcp
+```
+
+Для сервисного токена замени `HUBEX_AUTH_MODE = "login"` + `HUBEX_USERNAME`/`HUBEX_PASSWORD`
+(или `--env HUBEX_AUTH_MODE=login ...`) на `HUBEX_AUTH_MODE = "service"` +
+`HUBEX_SERVICE_TOKEN = "<токен>"`.
+
+Проверка: `codex mcp list`.
+
+---
+
+## 4. Cursor
+
+Cursor читает MCP из JSON:
+
+- глобально — `~/.cursor/mcp.json`;
+- для проекта — `.cursor/mcp.json` в корне репозитория.
+
+```json
+{
+  "mcpServers": {
+    "hubex": {
+      "command": "hubex-mcp",
+      "env": {
+        "HUBEX_ENV": "dev",
+        "HUBEX_APPLICATION_ID": "5",
+        "HUBEX_AUTH_MODE": "login",
+        "HUBEX_USERNAME": "poweruser@hubex.ru",
+        "HUBEX_PASSWORD": "<пароль>"
+      }
+    }
+  }
+}
+```
+
+Для сервисного токена замени `HUBEX_AUTH_MODE`/`HUBEX_USERNAME`/`HUBEX_PASSWORD` на:
+
+```json
+"HUBEX_AUTH_MODE": "service",
+"HUBEX_SERVICE_TOKEN": "<токен>"
+```
+
+Затем: **Cursor → Settings → MCP** и включите сервер `hubex` (кнопка обновить/enable).
+Зелёный индикатор = подключено.
+
+---
+
+## Проверка после подключения
+
+Вызовите инструмент `hubex_whoami` — он вернёт окружение, tenant и срок действия токена.
+Если видите `tokenExpired: true` или ошибки 401 — обновите токен или используйте режим
+`login`/`service` (сервер сам получает и обновляет токен, см. раздел «Переменные окружения»).
+
+## Безопасность
+
+- Не коммитьте реальные токены/пароли. Файлы `.mcp.json` / `.cursor/mcp.json` с секретами
+  добавляйте в `.gitignore` или храните значения в переменных окружения.
+- Окружение выбирается через `HUBEX_ENV` (`dev` / `stg` / `prod`); на проде базовый URL без префикса —
+  `https://api.hubex.ru/fsm`. Для прода стоит держать `HUBEX_READONLY=true`, если запись не нужна.
+- Для полностью безопасного режима задайте `HUBEX_READONLY=true`.

package/README.md

@@ -0,0 +1,266 @@
+# HubEx MCP
+
+MCP-сервер для управления **тестовыми данными** в HubEx (создание, редактирование, удаление
+заявок, объектов, компаний, пользователей) прямо из Claude.
+
+Окружение задаётся в `HUBEX_ENV`: `dev`, `stg` или `prod`. На проде базовый URL — без префикса
+(`https://api.hubex.ru/fsm`); ограничить его чтением можно через `HUBEX_READONLY=true`.
+
+## Что внутри
+
+- **13 инструментов** (список — в разделе [«Инструменты»](#инструменты)): поиск и исполнение
+  работают через тонкий индекс, а не через по-эндпоинтную генерацию, поэтому их число не растёт
+  вместе с количеством эндпоинтов HubEx (~1100 в 22 сервисах).
+- Единый HTTP-клиент с авторизацией (Bearer + `X-Application-ID`) и понятными сообщениями об ошибках.
+- Два режима авторизации: готовый токен или логин/пароль (Basic → JWT через сервис AUTHN, авто-refresh).
+- Три независимых рубежа ограничения доступа: список HTTP-методов на сервере, тумблеры инструментов
+  в MCP-клиенте, проверка метода на исполнении.
+
+## Установка
+
+```bash
+npm install
+npm run build
+```
+
+## Инструменты
+
+13 инструментов, число не зависит от количества эндпоинтов HubEx (~1100 в 22 сервисах).
+
+| Инструмент | Назначение |
+|---|---|
+| `hubex_whoami` | окружение, tenant, срок действия токена |
+| `hubex_get_guide` | гайд по процессу, топики сгруппированы по областям: база — `start`, `dictionaries`; заявки — `taskcreate`, `taskedit`, `taskchecklists`; объекты и контрагенты — `assets`, `companies`, `users`, `materials`; настройка тенанта — `lifecycle`, `tasktypes`, `roles`, `notifications`, `sla`, `attributes`, `checklisttemplates` |
+| `hubex_list_scopes` | карта сервисов; с `service` — ресурсы внутри |
+| `hubex_search_read_endpoints` | поиск GET-эндпоинтов |
+| `hubex_search_write_endpoints` | поиск POST/PUT/PATCH-эндпоинтов |
+| `hubex_search_delete_endpoints` | поиск DELETE-эндпоинтов |
+| `hubex_search_head_endpoints` | поиск HEAD-эндпоинтов |
+| `hubex_describe_endpoint` | полная схема параметров и тела (до 5 идентификаторов за вызов) |
+| `hubex_request_read` | выполнить GET |
+| `hubex_request_write` | выполнить POST/PUT/PATCH |
+| `hubex_request_delete` | выполнить DELETE (принимает `body`: часть эндпоинтов удаляет пачкой по списку) |
+| `hubex_request_head` | выполнить HEAD |
+| `hubex_create_test_task` | создать тестовую заявку с дефолтами и префиксом `[MCP-TEST]` |
+
+### Как этим пользоваться
+
+Типичный путь модели:
+
+1. `hubex_get_guide` с нужным топиком — понять порядок вызовов.
+2. `hubex_list_scopes` — увидеть сервисы; с `service=WORK` — ресурсы внутри.
+3. `hubex_search_read_endpoints` со `scope`/`tag`/`query` — найти эндпоинт.
+4. `hubex_describe_endpoint` — получить схему только для того, что будет вызвано.
+5. `hubex_request_*` — выполнить.
+
+Ступени необязательны: зная идентификатор из гайда, можно идти сразу к шагу 4.
+
+### Ограничение доступных методов
+
+Три независимых рубежа:
+
+1. `HUBEX_METHODS` на сервере — запрещённые группы не регистрируются и не видны агенту.
+2. Тумблеры инструментов в MCP-клиенте — можно выключить пару `search_delete` + `request_delete`.
+3. Проверка на исполнении — `request_*` принимает только `endpointId` и отклоняет чужой метод.
+
+Поэтому поиск и исполнение разделены по методам симметрично: выключения только
+поискового инструмента было бы недостаточно.
+
+## Миграция с 0.1.x
+
+Это ломающее изменение: все инструменты v1 вида `hubex_work_tasks_list`, `hubex_es_assets_get`
+и подобные (по одному на каждый сгенерированный эндпоинт) больше не существуют. Взамен —
+лестница `hubex_list_scopes → hubex_search_*_endpoints → hubex_describe_endpoint → hubex_request_*`,
+описанная выше. `hubex_whoami` и `hubex_create_test_task` не изменились. Если в сохранённых
+промптах или конфигурации использовались v1-имена инструментов — замените их на новую лестницу.
+
+## Конфигурация
+
+Переменные окружения (см. `.env.example`):
+
+| Переменная | Обязательна | Описание |
+|---|---|---|
+| `HUBEX_ENV` | да | `dev`, `stg` или `prod` |
+| `HUBEX_APPLICATION_ID` | да | заголовок `X-Application-ID` (для dev-тенанта — `5`) |
+| `HUBEX_AUTH_MODE` | да | `token`, `login` или `service` |
+| `HUBEX_USERNAME` / `HUBEX_PASSWORD` | для `login` | учётные данные |
+| `HUBEX_SERVICE_TOKEN` | для `service` | долгоживущий интеграционный токен |
+| `HUBEX_TENANT_ID` | нет | tenant явно; иначе берётся из JWT (`TenantID`) |
+| `HUBEX_METHODS` | нет | список доступных HTTP-методов через запятую (по умолчанию — все шесть) |
+| `HUBEX_READONLY` | нет | `true` — эквивалент `HUBEX_METHODS=GET,HEAD` |
+| `HUBEX_MASK_PII` | нет | по умолчанию `true` — маскирует ПДн (ФИО, телефоны, email и т.п.) в ответах; `false` отключает маскирование |
+| `HUBEX_SERVICES` | нет | ограничить поиск и исполнение списком сервисов (по умолчанию — все 22) |
+| `HUBEX_DEFAULT_REQUEST_METHOD_ID` | нет | значение по умолчанию для тела write-запросов |
+| `HUBEX_DEFAULT_TASK_TYPE_ID` | нет | значение по умолчанию для тела write-запросов |
+| `HUBEX_DEFAULT_COMPANY_ID` | нет | значение по умолчанию для тела write-запросов |
+
+Режим `token` переменных не требует: при первом обращении сервер сам попросит
+access-токен (через MCP elicitation, а если клиент этого не умеет — через
+инструмент `hubex_set_token`). По введённому токену запрашивается refresh, и
+дальше сессия продлевается сама. Токены хранятся только в памяти процесса — после
+перезапуска сервер спросит токен заново.
+
+## Подключение
+
+Полное руководство для **Claude Code, Claude Desktop, Codex CLI и Cursor** — в [CONNECTING.md](CONNECTING.md).
+
+Кратко. Соберите пакет (`npm pack`) и установите его — появится команда `hubex-mcp`:
+
+```bash
+npm install -g ./hubex-mcp-0.2.0.tgz
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "hubex": {
+      "command": "hubex-mcp",
+      "env": {
+        "HUBEX_ENV": "dev",
+        "HUBEX_APPLICATION_ID": "5",
+        "HUBEX_AUTH_MODE": "token"
+      }
+    }
+  }
+}
+```
+
+Для Claude Code (во всех проектах): `claude mcp add hubex --scope user -- hubex-mcp`
+(переменные окружения задайте через `--env` или в `.env` окружении процесса).
+
+## Разработка
+
+```bash
+npm run generate          # перегенерировать оба индекса из swagger/{dev,prod}/*.json
+npm run refresh-swagger   # скачать swagger обоих контуров заново и перегенерировать индексы
+npm run check-swagger     # CI: обновить swagger и упасть, если индекс разошёлся
+npm run release-swagger   # обновить схемы и, при изменениях, выпустить релиз в npm
+npm run typecheck         # проверка типов (src, scripts и test)
+npm test                  # unit-тесты (vitest)
+npm run check-guides      # сверить источники гайдов с первоисточниками
+npm run dev               # запуск из исходников (tsx)
+```
+
+`npm run check-guides -- /path/to/HubEx.Wiki [/path/to/HubEx.Frontend.AdminApp]`
+сверяет `sources` во фронтматтере каждого гайда с первоисточником: страницы вики
+(`admin/...`) — по полю `content_hash` самой страницы, файлы AdminApp
+(`adminapp/...`) — по sha256 содержимого. Без второго пути источники AdminApp
+пропускаются. Ненулевой код возврата означает, что первоисточник изменился и
+гайд пора перечитать.
+
+### Контуры swagger: dev и prod
+
+Схемы хранятся раздельно, по каталогу на контур, и индекс собирается для каждого:
+
+| Контур | Кэш схем       | Индекс                      | Источник                                                     |
+| ------ | -------------- | --------------------------- | ------------------------------------------------------------ |
+| `dev`  | `swagger/dev/`  | `generated/index.dev.json`  | `https://dev-api.hubex.ru/fsm/{SERVICE}/swagger/{версия}/swagger.json` |
+| `prod` | `swagger/prod/` | `generated/index.prod.json` | `https://api.hubex.ru/fsm/{SERVICE}/swagger/{версия}/swagger.json` (то же, что раздаёт [doc.hubex.ru](https://doc.hubex.ru/#/)) |
+
+Контур выбирается на старте сервера по `HUBEX_ENV`: `prod` читает prod-каталог,
+`dev` и `stg` — dev-каталог (отдельного стенда документации у stg нет). Поиск,
+`hubex_describe_endpoint` и валидация тел запросов работают по схемам выбранного
+контура, так что на проде агент не увидит эндпоинтов, которых там ещё нет.
+
+`npm run generate` всегда пересобирает оба индекса — оба каталога должны быть на месте.
+
+Список сервисов берётся со страницы документации контура — `doc.hubex.ru` для prod
+и `dev-doc.hubex.ru` для dev. Каталог `swagger/` источником быть не может: по нему
+не узнать о сервисе, которого там ещё нет. Со страницы берутся только ссылки на
+хост своего контура — dev-страница перечисляет заодно и stg.
+
+`npm run refresh-swagger` без аргументов обновляет оба контура. Ограничения:
+
+```bash
+npm run refresh-swagger -- --catalog=prod            # только prod
+npm run refresh-swagger -- --catalog=dev WORK ES ADM # отдельные сервисы одного контура
+```
+
+Список сервисов допустим только вместе с `--catalog`, а индекс после загрузки всё
+равно строится по всему каталогу контура. Версия схем — `v1.0.0.0`, меняется через
+`HUBEX_SWAGGER_VERSION`.
+
+### Проверка расхождений в пайплайне
+
+`npm run check-swagger` обновляет схемы и сравнивает результат с тем, что лежит в
+репозитории. Сравнение идёт в два слоя, потому что индекс хранит только сигнатуры:
+
+- **файлы схем** — по sha256: какой `swagger/<контур>/*.json` появился, пропал или
+  изменился. Этот слой ловит правки внутри схем тел запросов и ответов — новое
+  поле, изменившийся тип, — которых в индексе нет вовсе;
+- **индекс** — какие эндпоинты появились, пропали и у каких изменилась сигнатура
+  (`summary`, `tags`, path/query-параметры, наличие и обязательность тела). Порядок
+  тегов и параметров сравнивается как множество, поэтому перестановка внутри
+  swagger расхождением не считается.
+
+Если файл изменился, а сигнатуры нет, отчёт говорит об этом прямо — значит правка
+внутри тела или ответа.
+
+Коды возврата разводят дрейф и поломку — пайплайну есть на что реагировать:
+
+| Код | Значение                                                   |
+| --- | ---------------------------------------------------------- |
+| `0` | расхождений нет, индексы в репозитории актуальны            |
+| `1` | схемы разошлись: появились, пропали или изменились эндпоинты |
+| `2` | проверку выполнить не удалось: сеть, HTTP != 200, битый JSON |
+
+Если страница документации недоступна, `refresh-swagger` предупреждает и берёт
+список сервисов из каталога, а `check-swagger` завершается кодом `2`: запасной
+список вернул бы слепое пятно на новый сервис, ради которого проверка и нужна.
+
+Как и `refresh-swagger`, принимает `--catalog=dev|prod|all` (по умолчанию оба).
+Схемы и индексы после запуска остаются **обновлёнными**, поэтому в пайплайне
+`git diff` можно опубликовать артефактом, а локально — сразу закоммитить.
+Загрузка атомарна: при обрыве сети рабочий каталог остаётся нетронутым, и код `2`
+не будет спутан с реальным расхождением.
+
+### Ежедневная сборка
+
+Вся логика лежит в `scripts/release-swagger.ts` и запускается одной командой —
+`npm run release-swagger`. Пайплайн `azure-pipelines-swagger.yml` только вызывает
+её по расписанию, поэтому тот же сценарий целиком прогоняется локально:
+
+```bash
+npm run release-swagger -- --dry-run   # без коммита, push и публикации
+```
+
+Скрипт обновляет схемы обоих контуров и, если что-то изменилось, прогоняет
+typecheck, тесты и сборку, поднимает версию, коммитит, пушит и публикует пакет.
+Работает **только в ветке `swagger-daily`**, `main` не трогает.
+
+Релиз выпускается только из чистого рабочего дерева: свои пути (`swagger/`,
+`generated/`, `package.json`) скрипт коммитит целиком, и чужая незакоммиченная
+правка в них уехала бы в автоматический коммит.
+
+CI-триггера у пайплайна нет, только расписание: ручные слияния `main` →
+`swagger-daily` ничего не запускают, публикация происходит исключительно после
+автоматического обновления схем. Синхронизация ветки с `main` делается руками.
+
+Версия релиза — `0.2.YYYYMMDD`. Если при повторном дрейфе за сутки такая версия
+уже в реестре, схемы коммитятся, а публикация пропускается: следующая уедет назавтра.
+
+Перед первым запуском нужно:
+
+1. создать ветку `swagger-daily` из `main` — файл пайплайна должен быть в ней;
+2. дать Build Service право **Contribute** на репозиторий, иначе push не пройдёт;
+3. убедиться, что на `swagger-daily` нет branch policies;
+4. завести секретную переменную `NPM_TOKEN` с токеном публикации npm.
+
+### Как добавить сервис
+
+1. Передайте новый сервис команде `npm run refresh-swagger -- --catalog=<dev|prod> <SERVICE>`
+   либо положите его swagger в `swagger/<dev|prod>/<SERVICE>.json`.
+2. `npm run generate` — индексы перестраиваются по всем файлам обоих каталогов
+   автоматически (при использовании `refresh-swagger` этот шаг уже выполнен),
+   курировать список эндпоинтов не нужно.
+3. `npm run build`.
+
+## Безопасность
+
+- На проде используется отдельный кэш схем `swagger/prod/`: эндпоинты, которых на
+  проде ещё нет, агенту не видны.
+- Все мутационные инструменты помечены «(изменяет данные)» в описании.
+- `HUBEX_READONLY=true` полностью отключает изменение данных.
+- Тестовые заявки из `hubex_create_test_task` помечаются префиксом `[MCP-TEST]`.