101 lines
7.7 KiB
Markdown
101 lines
7.7 KiB
Markdown
# Веб-интерфейс
|
||
|
||
Веб-интерфейс нужен для настройки инструментов, агентов и доступа к MCP.
|
||
|
||
## Операции
|
||
|
||
Операция описывает один REST endpoint как MCP-инструмент.
|
||
|
||
В операции задаются:
|
||
|
||
- имя инструмента;
|
||
- описание для AI-агента;
|
||
- входная схема;
|
||
- REST endpoint;
|
||
- правила преобразования входных параметров в REST-запрос;
|
||
- правила преобразования REST-ответа в результат инструмента;
|
||
- тестовый пример;
|
||
- статус публикации.
|
||
|
||
Черновик можно редактировать и тестировать. MCP-клиенты видят только опубликованные операции, которые привязаны к опубликованному агенту.
|
||
|
||
Опубликованная версия неизменяема. Следующее сохранение создаёт новую Draft revision и не меняет уже опубликованный Agent catalog. Каталог позволяет удалить только never-published Draft; для опубликованной Operation доступна archive с подтверждением. Archive запрещает новые изменения и привязки, но сохраняет существующие Agent snapshots и историю.
|
||
|
||
UI использует `ETag` для защиты от stale вкладок. При конфликте локальные поля не перезаписываются: интерфейс предлагает перезагрузить authoritative Draft. Test run показывает безопасные Request ID и Trace ID и позволяет копировать их отдельно от payload.
|
||
|
||
### Создание операции
|
||
|
||
В мастере операции основной сценарий такой:
|
||
|
||
1. Выбрать REST.
|
||
2. Выбрать upstream или добавить новый `Base URL`.
|
||
3. Указать HTTP-метод и путь endpoint-а.
|
||
4. Описать инструмент и его входную/выходную схему.
|
||
5. Загрузить или вставить JSON-пример запроса и ответа.
|
||
6. Связать поля инструмента с `Path`, `Query`, `Header` и `Body`.
|
||
7. Выбрать поля ответа API, которые вернет MCP-инструмент.
|
||
8. Запустить тест.
|
||
9. Сохранить и опубликовать операцию.
|
||
|
||
Для обычной работы достаточно визуального конструктора связей. YAML/JSONPath открыт в блоке **Дополнительно** для сложных случаев: вложенные поля, ручная правка, перенос готовой конфигурации.
|
||
|
||
Portable YAML export использует format v2 и не содержит внутренних ID, lifecycle timestamps, samples, wizard metadata или credentials. Импорт одинакового document является no-op; изменённый upsert добавляет следующую Draft revision и требует актуальный state token.
|
||
|
||
Если пример ответа содержит массив, визуальное дерево показывает поля первого элемента как `items[0].name`. Это удобно, когда агенту нужно одно конкретное поле. Если агенту нужен весь список, используйте блок **Дополнительно** и верните массив целиком.
|
||
|
||
### Импорт OpenAPI
|
||
|
||
Кнопка **Импорт OpenAPI** создает черновики операций из OpenAPI/Swagger. После импорта откройте черновик в мастере и проверьте:
|
||
|
||
- описание инструмента;
|
||
- входные поля;
|
||
- связи `Path / Query / Header / Body`;
|
||
- пример тестового запроса;
|
||
- поля ответа, которые попадут в результат инструмента.
|
||
|
||
## Агенты
|
||
|
||
Агент - это отдельный MCP endpoint с выбранным набором инструментов.
|
||
|
||
Рекомендуемый подход:
|
||
|
||
- группировать инструменты под конкретную задачу;
|
||
- не давать одному агенту слишком много инструментов;
|
||
- делать названия и описания инструментов однозначными;
|
||
- публиковать агента только после проверки операций.
|
||
|
||
В карточке агента явно выбирается способ доступа к каталогу:
|
||
|
||
- **Показывать сразу** — `tools/list` возвращает все привязанные инструменты. Это основной режим для небольшого каталога.
|
||
- **Подбирать по запросу** — `tools/list` возвращает только `search_tools` и `call_tool`. Модель сначала находит несколько подходящих инструментов, затем вызывает выбранный через прокси-инструмент.
|
||
|
||
В режиме подбора каталог можно разделить на именованные разделы. Название и описание раздела видит модель, а один инструмент можно включить в несколько разделов. Раздел ограничивает область поиска, но поиск без раздела всегда охватывает весь каталог.
|
||
|
||
Перед сохранением можно ввести пробную задачу и проверить результат подбора. Эта проверка использует тот же алгоритм, что и MCP-сервер.
|
||
|
||
## API ключи
|
||
|
||
API-ключ выдается на конкретного агента. В Community есть два режима ключей.
|
||
|
||
Ключ MCP-клиента позволяет:
|
||
|
||
- открыть MCP-сессию;
|
||
- получить список инструментов агента;
|
||
- вызвать опубликованный инструмент.
|
||
|
||
Ключ подтверждения используется только внешним интерфейсом, где человек подтверждает или отклоняет опасное действие. Такой ключ нельзя передавать MCP-клиенту или LLM.
|
||
|
||
Полное значение ключа показывается только при создании.
|
||
|
||
## Секреты
|
||
|
||
Секреты используются для авторизации на конечных REST API.
|
||
|
||
После сохранения значение шифруется и больше не отображается. Секрет можно ротировать или удалить, если он не используется профилем авторизации.
|
||
|
||
## Логи и использование
|
||
|
||
Раздел **Логи** показывает вызовы операций, ошибки маппинга, ошибки REST API и успешные ответы.
|
||
|
||
Раздел **Использование** показывает количество вызовов, ошибки и задержки по операциям.
|