Надёжная работа с MCP

Основной MCP использует один реестр обработчиков в двух профилях. full публикует отдельные инструменты и discovery, compact — четыре инструмента: list_sections, search_actions, describe_actions, call_action. Универсальный вызов принимает ID разрешённого действия, а не HTTP-путь. Проверка исходной схемы и контекст транспорта сохраняются.

Последовательность работы агента

1. Найдите раздел через list_sections и действия через search_actions.
2. Прочитайте describe_actions для выбранных ID. Проверьте транспорт, параметры, эффект, разрушительность и способ наблюдать длительное действие.
3. Получите реальные ID проекта и объектов. Запрашивайте только нужные данные.
4. Выполните call_action с аргументами исходного действия.
5. Проверьте isError, бизнес-ошибку и _meta.botcraft, затем результат записи.

search_actions возвращает total и next_cursor; продолжайте с этим курсором, пока не получите нужные действия. Параметр limit не означает полноту каталога. В HTTP нет локальных load/save/export: эти действия доступны только stdio.

Что означает результат

Старые content-блоки сохранены. Общая структурированная оболочка содержит data и execution; данные разных действий неоднородны. Схема оболочки не заменяет точную бизнес-схему там, где та пока отсутствует. Дополнительные метаданные выполнения доступны в _meta.botcraft.

outcome	Значение и следующий шаг
read	Чтение. Не считать операцией записи.
prepared	Подготовлен JSON или план; живой проект не сохранён.
saved	Есть persistence.confirmed=true; изучите квитанцию и побочные эффекты.
pending	Работа ещё требует наблюдения через pollAction или статус операции.
partial	Выполнена только часть; изучите подтверждённые ID и ошибки.
unknown	Исход неоднозначен. Сначала прочитайте состояние, не повторяйте вслепую.
error	Ошибка. Не объявляйте задачу выполненной.
unverified	Обработчик не предоставил достаточного подтверждения записи.
file_result	Файловый результат; это не подтверждение записи живого проекта.

create_node готовит объект, add_node и update_node меняют переданный JSON. Для записи сценария в приложение используйте действия db_* либо update_project_db. save_project сохраняет локальный файл stdio-клиента.

Подтверждение хранения, live-доставка и применение ботом — разные результаты. Ошибка снимка версии, Redis или рассылки после COMMIT не превращает сохранение в откат. Проверяйте sideEffects и состояние работающего бота отдельно. Отправка WebSocket-сообщения не доказывает, что каждое окно его получило.

Конкурентное редактирование

Проект имеет серверную revision. Передавайте прочитанную ревизию как expected_revision в update_project_db (в HTTP — expectedRevision). Сценарные операции читают ревизию перед изменением и защищают итоговую запись. GET → изменение в памяти → PUT не является общей транзакцией.

При 409 перечитайте проект и согласуйте правки. Не подменяйте ревизию свежей, оставляя старый JSON: это снова создаст риск перезаписи чужих изменений. Входящие сохранённые снимки упорядочиваются по ревизии, а не времени доставки. Открытый локальный черновик откладывает внешний снимок; чужие сигналы сохранения и сброса не разрешают уничтожить этот черновик.

Изменение таблицы публикует событие её проекта. Контент _content дополнительно передаёт холсту актуальный сохранённый сценарий с ревизией. После разрыва связи интерфейс перечитывает данные; успешный COMMIT не зависит от доступности live.

Повторные запросы и внешние действия

Если схема требует UUID requestId или request_id, создайте его один раз для одного намерения и сохраняйте при повторе того же запроса. Не меняйте аргументы под тем же ID. Сервер проверяет доступ до получения записи о повторе.

Ledger хранит хеш запроса и безопасный результат. Выполненный запрос возвращает сохранённый результат; одинаковый ID с другими аргументами даёт конфликт. Незавершённый или неизвестный исход не запускается повторно автоматически. При частичном создании проекта используйте возвращённый ID для восстановления.

Транзакция БД не обеспечивает exactly-once отправку Telegram. Обрыв после внешнего эффекта, но до подтверждения требует проверки результата. Не создавайте новый ID лишь для обхода состояния unknown или pending.

Границы доступа

Действия используют существующую авторизацию HTTP API и ограничения проекта. Remote MCP не читает произвольные пути сервера. Файлы и медиа проверяются на принадлежность проекту; публичная ссылка не отменяет эту проверку. ENV возвращается с замаскированными значениями; управление собственными PAT, выдача прав, раскрытие секретов и глобальные storage-настройки не публикуются автоматически. Намеренные исключения должны быть отражены в матрице покрытия.

Отдельный OpenAPI→MCP адаптер является ограниченным альтернативным интерфейсом, а не полным зеркалом основного MCP. Его разрешённые маршруты перечислены в руководстве адаптера.

Генерация и проверки

node tools/generate-mcp-docs.mjs захватывает фактические регистрации SDK без исполнения действий. Он обновляет JSON-каталог, карточки docs/mcp/tools и встроенную справку lib/generated/mcp-docs. Структурные примеры проверяются исходной Zod-схемой; ID заменяют данными задачи. Отсутствие безопасного примера явно обозначается, секреты не подставляются.

Тесты SDK сравнивают full/compact и схемы действий. Тесты сохранения, доступа, конфликтов и обработчиков выполняются отдельно: регистрация не доказывает запись. Используемые изолированные SQL-модели и HTTP-заглушки не заменяют проверку конкуренции на настоящем PostgreSQL; отчёт должен сохранять это различие.

Включение и возврат к совместимому профилю

Изменения подготовлены локально; эта инструкция не означает выполненный деплой. Перед включением обновлённого сервера примените штатным процессом миграции 0037_project_revision.sql, 0038_analytics_budget_idempotency.sql и 0039_action_requests.sql, изучив их зависимости и сохранив резервную копию. Не запускайте изменяющие действия против схемы БД без требуемых миграций.

Задайте BOTCRAFT_MCP_PROFILE=compact в окружении соответствующего MCP-процесса и перезапустите его. Переподключите клиент и проверьте реальный tools/list: должны присутствовать только четыре discovery-инструмента. Подключение и авторизация остаются транспортными: смена профиля не выдаёт новых прав.

Для возврата задайте BOTCRAFT_MCP_PROFILE=full либо уберите переменную и перезапустите процесс. Отдельные инструменты вернутся вместе с discovery. Возврат профиля не требует удаления ревизий или ledger-таблиц. Не удаляйте ledger-записи ради повтора внешних действий: это снимает защиту от дублирования.