Описание действий
Подготовьте backend и OpenAPI
Опубликуйте OpenAPI 3 в JSON на публичном HTTPS-адресе backend приложения. Адреса localhost, частной сети и URL с логином или паролем для внешнего приложения не подходят. Senler не следует перенаправлениям, ждёт загрузку схемы до 5 секунд и принимает документ размером не более 5 МиБ. Загруженная схема кэшируется примерно на 30 секунд, поэтому изменение может появиться в каталоге не мгновенно.
Разместите схему и обработчики на одном origin: с одинаковыми протоколом, доменом и портом. Например, для схемы https://plugin.example.com/openapi.json путь /api/orders будет вызван как https://plugin.example.com/api/orders. Поле servers в OpenAPI этот адрес не переопределяет. Пути операций начинаются с /; полный URL или перенаправление на другой сервер не используются.
Размечаются операции GET, POST, PUT, PATCH и DELETE. Параметры пути и query описывайте обычными OpenAPI parameters, а тело — объектом application/json. project_id не добавляйте в параметры действия: Senler уже знает проект из проверенного контекста MCP.
Добавьте к каждой разрешённой операции расширение x-senler-app-action:
{
"paths": {
"/api/orders": {
"get": {
"summary": "Список заказов",
"x-senler-app-action": {
"version": 1,
"name": "list_orders",
"context": "app",
"description": "Возвращает заказы текущего проекта.",
"read_only": true,
"destructive": false,
"idempotent": true,
"result": { "kind": "data" }
},
"responses": {
"200": {
"description": "Заказы",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": { "type": "object" }
}
}
}
}
}
}
}
}
}
}
}name начинается с латинской буквы и содержит от 2 до 64 строчных латинских букв, цифр или _. Пишите description как инструкцию AI: что делает метод, когда его использовать и что возвращается. Флаги read_only, destructive и idempotent должны соответствовать реальному поведению, потому что MCP использует их при планировании безопасного вызова.
Опишите JSON-схему успешного ответа. Senler передаёт AI саму схему и компактный список её важных полей; без схемы AI сможет прочитать фактический JSON, но хуже поймёт результат до вызова.
Выберите контекст и результат
Для действий, доступных через MCP, поле context объясняет назначение метода:
| Контекст | Для чего используется | Результат |
|---|---|---|
app | Работа с данными и функциями общей страницы приложения | Обычные данные; используйте kind: data |
agent_tool | Подготовка настроек экземпляра инструмента агента | kind: agent_tool_configuration и путь configuration_path |
automation_step | Подготовка настроек шага и его веток | kind: automation_step_configuration, configuration_path и при необходимости branches_path |
Путь результата записывается через точки, например result.configuration. Для настройки шага ветки обычно находятся в result.branches. После вызова AI получает подсказку, откуда взять эти значения и каким методом Senler сохранить их в нужном инструменте или узле схемы.
Отчёты для воронок
Для источника данных воронки из плагина используется отдельный контекст funnel с результатом funnel_report. Такой метод только читает данные: укажите read_only: true и не отмечайте его как destructive. Он вызывается при получении отчёта подключённого источника. Формат запроса, ответа и связь записей с лидами описаны в контракте метода отчёта.
В каталоге действий установленных приложений для search, describe_method и execute сейчас доступны только три контекста из таблицы выше. Поэтому наличие метода funnel в OpenAPI не означает, что AI найдёт его как отдельное действие плагина через MCP.
В @senlerio/api версии 0.4.0 декораторы из @senlerio/api/app-actions/nest и команда senler-app validate-openapi также поддерживают только эти три контекста. Для отчёта воронки задайте x-senler-app-action непосредственно в OpenAPI. Ошибка этой версии CLI о неподдерживаемом funnel не означает, что Senler не принимает метод отчёта; его проверку нельзя считать покрытой этим CLI.
Следующий шаг
Реализуйте авторизацию backend, затем подключите OpenAPI в кабинете.