Рецепты

Что решает рецепт

В каталоге по одному рецепту на сервис: GitHub, Stripe, Cloudflare, AWS и больше сотни других. Рецепт говорит, куда подставить ключ, к каким хостам он допущен и читает вызов, меняет или удаляет.

Подключение пользуется рецептом, из которого создано. Иначе Sallyport выбирает рецепт с подходящим хостом, и побеждает самый точный хост. Хост, которого нет ни в одном рецепте, тоже работает, класс ему даёт метод.

Как читать каталог

GET /v1/recipes отдаёт каталог, фильтры: q (название, ключ или поставщик), vendor и host. GET /v1/recipes/{key} отдаёт один рецепт. Оба маршрута работают с ключом консоли, см. REST API.

{
  "data": {
    "key": "github",
    "name": "GitHub API",
    "vendor": "GitHub",
    "hosts": ["api.github.com"],
    "connection_hosts": ["api.github.com"],
    "connection_domains": [],
    "channel": "http",
    "adapter": "bearer",
    "adapters": ["bearer", "oauth2-ac"],
    "credential_fields": [
      { "name": "value", "label": "Personal access token or installation token", "secret": true, "required": true, "sent_as": [] }
    ],
    "methods": [
      {
        "adapter": "bearer",
        "fields": [
          { "name": "value", "label": "Personal access token or installation token", "secret": true, "required": true, "sent_as": [] }
        ],
        "provider": "",
        "sallyport_app": false,
        "redirect_uri": ""
      },
      {
        "adapter": "oauth2-ac",
        "fields": [],
        "provider": "GitHub",
        "sallyport_app": false,
        "redirect_uri": "https://mcp.sallyport.cloud/callback/upstream"
      }
    ],
    "notes": null,
    "docs_url": "https://docs.github.com/en/rest",
    "create_url": "https://github.com/settings/personal-access-tokens/new",
    "revoke_url": "https://github.com/settings/tokens",
    "scopes_recommended": [],
    "default_profile": "direct",
    "oauth": true,
    "version": 2
  },
  "request_id": "5d0c2f7e8a1b4c6d9e0f1a2b3c4d5e6f"
}

Правила классов и место подстановки ключа остаются внутри Sallyport и в этот ответ не входят.

Как определяется класс вызова

Каждый вызов относится к read, write или destructive. Дальше решает правило агента для этого класса на подключении: выполнить, спросить человека или отказать.

• Нижнюю границу задаёт метод: GET, HEAD и OPTIONS читают, POST, PUT и PATCH меняют, DELETE и любой другой метод считаются необратимыми.
• Правила рецепта проверяются по порядку, срабатывает первое подходящее. Правило только повышает класс, и повышает одно: GET, которым поставщик что-то меняет, становится изменением. Ни одно правило рецепта не делает вызов необратимым.
• Сегмент пути, который начинается с webhook, hooks, build, trigger, send, invoke, execute, exec или run, делает вызов как минимум изменением. Правило рецепта, совпавшее по пути, это отменяет.
• Рецепт может перечислить точные операции чтения, которые идут через POST, например DescribeInstances в AWS или запрос GraphQL. Чтением они считаются, только если весь запрос читается однозначно.
• Запросы GraphQL, JSON-RPC и пакетные запросы получают самый высокий класс из своих частей.
• Подмена метода через _method и X-HTTP-Method-Override убирается до определения класса и до отправки.

Инструменты MCP-сервера получают класс по своим readOnlyHint и destructiveHint, инструмент без обеих пометок считается изменением. SSH-команды считаются изменением, кроме короткого списка точных чтений, а команды вроде rm или dd необратимы. Подробнее на странице SSH-команды. Операции с файлами на SSH-хосте получают класс по тому, что делают. list, stat и read считаются чтением, write, mkdir и rename изменением, delete и rmdir необратимы. Подробнее на странице Файлы по SFTP.

Проверка ключа

Некоторые рецепты, в том числе GitHub, называют одно безопасное чтение, которое доказывает, что ключ работает: у GitHub это GET /user. Sallyport выполняет его при сохранении ключа, при замене и по кнопке «Проверить снова».

Если сервис отверг ключ, это видно на странице ключа вместе с сообщением поставщика. Ответ, который ничего не доказывает, например нехватка прав, ничего не меняет.