Действия приложения

Действия приложения — это выбранные методы backend плагина, которые Senler добавляет в MCP установленного проекта. Благодаря им AI может по просьбе пользователя работать с данными приложения или подготовить настройки его инструмента и шага. Пользователь не добавляет эти методы в агента или схему вручную: они появляются только в проектах, где плагин установлен и активен.

Это отдельная возможность плагина:

инструмент агента вызывается самим агентом во время диалога;
шаг приложения выполняется внутри процесса автоматизации;
действие приложения вызывается AI через MCP, когда он помогает работать с интерфейсом и настройками плагина.

Подготовьте backend и OpenAPI

Опубликуйте OpenAPI 3 в JSON на адресе, доступном серверам Senler. В production нужен публичный HTTPS URL. Senler не следует перенаправлениям, ждёт загрузку схемы до 5 секунд и принимает документ размером не более 5 МБ. Загруженная схема кэшируется примерно на 30 секунд, поэтому изменение может появиться в каталоге не мгновенно.

Размечаются операции 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, но хуже поймёт результат до вызова.

Выберите контекст и результат

Поле 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 сохранить их в нужном инструменте или узле схемы.

Как MCP находит и вызывает действие

Действия установленных приложений не раздувают постоянный список MCP-инструментов. AI работает через общий протокол:

вызывает search с коротким описанием задачи;
берёт точное method_name из результата;
вызывает describe_method, если компактного ответа поиска недостаточно для вложенных параметров, схемы ответа или метаданных app_action;
вызывает execute с тем же method_name и объектом parameters по полученной схеме.

Например, поиск «получить аккаунты Prodamus» может вернуть prodamus__list_accounts, а поиск «получить реферальные кампании» — reflink__list_campaigns. AI не должен угадывать эти имена.

Область проекта зависит от вида MCP:

Подключение	Как определяется проект	Нужен ли `project_id`
Senler.io Project MCP	Проект зашит в проектный OAuth-токен	Нет; его нельзя подменить параметром
User MCP внутри агента или диалога проекта	Senler передаёт подписанный контекст выполнения	Нет; AI не должен его запрашивать
Прямое личное подключение User MCP	Выбранный проект не зашит в само подключение	Да; известный `project_id` повторяется в `search`, `describe_method` и `execute`

В прямом User MCP project_id — служебный верхнеуровневый параметр MCP-инструмента. Он не входит в parameters действия и не передаётся backend плагина. Подробный сценарий для AI-клиента описан в статье «Senler.io как MCP-сервер».

Как авторизуется backend приложения

MCP-ключ или OAuth-токен авторизует AI-клиент только в Senler. Senler проверяет проект, текущие права, активную установку и наличие точного действия в OpenAPI. Исходный MCP-секрет, OAuth-токен или заголовок авторизации не передаются в backend плагина.

Вместо этого для каждого вызова создаётся короткая сессия между Senler и приложением:

Senler подписывает одноразовый launch_code с ID проекта, сроком действия и nonce с помощью Client Secret приложения;
отправляет его на /api/embedded/management-session того же origin, где размещён OpenAPI;
backend проверяет подпись, срок и повтор nonce, затем возвращает собственный короткоживущий management_token;
Senler вызывает отмеченный endpoint с Authorization: Bearer <management_token>.

Запрос создания сессии выглядит так:

POST /api/embedded/management-session
Content-Type: application/json

{"launch_code":"<одноразовый код Senler>"}

Backend приложения должен проверить launch_code с Client Secret и вернуть собственный короткоживущий токен:

{"management_token":"app-session-token"}

Тайм-аут одного действия — 15 секунд, перенаправления не выполняются. Определяйте проект и права только по проверенной management session, а не по параметрам, которые AI передал методу.

management_token действует только в backend самого приложения. Если backend после этого вызывает API Senler, ему нужен собственный API-ключ или OAuth access token приложения с нужными правами. Ни management_token, ни исходный MCP-токен для API Senler не подходят.

Используйте SDK для NestJS

Начиная с @aisenler/sdk-fetch v0.1.16, расширение можно добавить готовыми декораторами:

import { Get } from "@nestjs/common";
import { AppAction } from "@aisenler/sdk-fetch/app-actions/nest";

@Get("orders")
@AppAction({
  name: "list_orders",
  description: "Возвращает заказы текущего проекта.",
  readOnly: true,
  destructive: false,
  idempotent: true,
  response: { status: 200, type: OrdersResponseDto },
})
listOrders() {
  // Проект берётся из проверенной management session.
}

Для конфигураторов используйте AgentToolConfigurator и AutomationStepConfigurator: они сами задают нужный контекст и вид результата. Общие типы и framework-neutral сборщик метаданных экспортируются из @aisenler/sdk-fetch/app-actions.

После генерации OpenAPI проверьте локальный файл или URL:

npx senler-app validate-openapi ./openapi.json

Проверка находит неверные имена и контексты, дубликаты, неподдерживаемые параметры и тела, отсутствие схемы ответа, а также неправильные пути конфигурации и веток. Добавьте её в CI backend приложения.

Включите действия в приложении

У приложения типа «Плагин» откройте раздел «Встроенная страница» и найдите блок «Действия приложения».

Включите «Публиковать действия в MCP».
Введите стабильный префикс методов длиной от 2 до 32 символов: строчные латинские буквы, цифры и _, начиная с буквы. Например, при префиксе my_plugin действие list_orders получит имя my_plugin__list_orders.
Укажите URL JSON-схемы OpenAPI backend приложения.
Нажмите отдельную кнопку «Сохранить» этого блока.

Включите действия в приложении. Отмеченные элементы: 1. блок «Действия приложения»; 2. «Публиковать действия в MCP»; 3. стабильный префикс методов; 4. URL JSON-схемы OpenAPI; 5. кнопку «Сохранить» — 1. блок «Действия приложения» · 2. «Публиковать действия в MCP» · 3. стабильный префикс методов · 4. URL JSON-схемы OpenAPI · 5. кнопку «Сохранить»

Префикс должен оставаться постоянным после публикации: полное имя метода использует AI и сохранённые сценарии. У двух активных установленных приложений одного проекта не должно быть одинакового полного имени действия.

Проверьте в тестовом проекте

Установите и активируйте плагин в тестовом проекте, подключите Senler Project MCP или User MCP с правом использования приложений и дайте AI задачу, для которой подходит безопасное действие с read_only: true. Проверьте, что:

метод появился под именем <namespace>__<name>;
AI видит ожидаемые параметры и описание результата;
backend создаёт management session только для действительного launch_code;
действие получает Bearer-токен приложения и возвращает ответ за 15 секунд;
изменяющие и необратимые операции правильно отмечены флагами безопасности.

Не помещайте Client Secret, management token и закрытые данные в OpenAPI, описание действия или его параметры.

Если действие не появилось

убедитесь, что плагин установлен и его установка активна в выбранном проекте;
проверьте переключатель публикации и сохранение блока;
откройте URL OpenAPI с сервера, а не только из браузера разработчика;
запустите senler-app validate-openapi и убедитесь, что операция использует поддерживаемый HTTP-метод и точное расширение x-senler-app-action версии 1;
подождите до 30 секунд после изменения схемы;
проверьте уникальность полного имени <namespace>__<name> среди установленных приложений;
для ошибки создания management session проверьте путь /api/embedded/management-session, подпись и срок launch_code, а также поле management_token в ответе;
для ошибки выполнения проверьте endpoint, Bearer-токен, ответ backend и лимит 15 секунд.