crank/docs/ui.md

Веб-интерфейс

Веб-интерфейс нужен для настройки инструментов, агентов и доступа к MCP.

Операции

Операция описывает один REST endpoint как MCP-инструмент.

В операции задаются:

• имя инструмента;
• описание для AI-агента;
• входная схема;
• REST endpoint;
• правила преобразования входных параметров в REST-запрос;
• правила преобразования REST-ответа в результат инструмента;
• тестовый пример;
• статус публикации.

Черновик можно редактировать и тестировать. MCP-клиенты видят только опубликованные операции, которые привязаны к опубликованному агенту.

Создание операции

В мастере операции основной сценарий такой:

1. Выбрать REST.
2. Выбрать upstream или добавить новый Base URL.
3. Указать HTTP-метод и путь endpoint-а.
4. Описать инструмент и его входную/выходную схему.
5. Загрузить или вставить JSON-пример запроса и ответа.
6. Связать поля инструмента с Path, Query, Header и Body.
7. Выбрать поля ответа API, которые вернет MCP-инструмент.
8. Запустить тест.
9. Сохранить и опубликовать операцию.

Для обычной работы достаточно визуального конструктора связей. YAML/JSONPath открыт в блоке Дополнительно для сложных случаев: вложенные поля, ручная правка, перенос готовой конфигурации.

Если пример ответа содержит массив, визуальное дерево показывает поля первого элемента как items[0].name. Это удобно, когда агенту нужно одно конкретное поле. Если агенту нужен весь список, используйте блок Дополнительно и верните массив целиком.

Импорт OpenAPI

Кнопка Импорт OpenAPI создает черновики операций из OpenAPI/Swagger. После импорта откройте черновик в мастере и проверьте:

• описание инструмента;
• входные поля;
• связи Path / Query / Header / Body;
• пример тестового запроса;
• поля ответа, которые попадут в результат инструмента.

Агенты

Агент - это отдельный MCP endpoint с выбранным набором инструментов.

Рекомендуемый подход:

• группировать инструменты под конкретную задачу;
• не давать одному агенту слишком много инструментов;
• делать названия и описания инструментов однозначными;
• публиковать агента только после проверки операций.

API ключи

API-ключ выдается на конкретного агента. Ключ позволяет MCP-клиенту:

• открыть MCP-сессию;
• получить список инструментов агента;
• вызвать опубликованный инструмент.

Полное значение ключа показывается только при создании.

Секреты

Секреты используются для авторизации на конечных REST API.

После сохранения значение шифруется и больше не отображается. Секрет можно ротировать или удалить, если он не используется профилем авторизации.

Логи и использование

Раздел Логи показывает вызовы операций, ошибки маппинга, ошибки REST API и успешные ответы.

Раздел Использование показывает количество вызовов, ошибки и задержки по операциям.