Командная строка и MCP

Исполняемый файл gately содержит две подкоманды: gately ctl вызывает управляющий API запущенного экземпляра из терминала, а gately mcp предоставляет те же интерфейсы AI-клиентам в виде инструментов MCP. Обе обращаются к экземпляру по HTTP с API-токеном; список интерфейсов берётся из /api/openapi.json экземпляра, права определяются токеном.

Кроме того, gately reset-password и gately reset-totp работают напрямую с локальным каталогом конфигурации, без API, и восстанавливают доступ администратора, если пароль забыт или аутентификатор утерян; см. Сброс пароля и двухфакторной аутентификации.

Параметры подключения

Параметры подключения определяются в следующем порядке, более поздние переопределяют более ранние:

1. Адрес по умолчанию http://127.0.0.1:16680
2. Файл конфигурации ctl.json
3. Переменные окружения GATELY_URL, GATELY_TOKEN
4. Параметры командной строки -url, -token

Файл конфигурации находится в пользовательском каталоге конфигурации системы: gately/ctl.json (в Linux ~/.config/gately/ctl.json, в macOS ~/Library/Application Support/gately/ctl.json). Пример содержимого:

{
  "url": "http://127.0.0.1:16680",
  "token": "gtl_xxxx",
  "insecure": false
}

Этот файл создаёт команда gately ctl login.

gately ctl

Подкоманды

Команда	Описание
gately ctl ls [ключевое слово]	Список интерфейсов, доступных токену: метод, путь и описание; можно фильтровать по ключевому слову
gately ctl get <путь>	Отправляет GET-запрос
gately ctl post <путь> [JSON или @файл]	Отправляет POST-запрос
gately ctl put <путь> [JSON или @файл]	Отправляет PUT-запрос
gately ctl delete <путь> [JSON или @файл]	Отправляет DELETE-запрос
gately ctl login <адрес> <токен>	Проверяет подключение и сохраняет его в файл конфигурации

Путь должен начинаться с /api/. Тело запроса может быть литералом JSON, @имя_файла (чтение из файла) или - (чтение из стандартного ввода); содержимое должно быть корректным JSON. Метод patch тоже доступен, а ls можно писать как list.

Параметры подключения

Параметры указываются перед подкомандой:

Параметр	Описание
-url <адрес>	Адрес управления, начинается с http или https
-token <токен>	API-токен
-insecure	Пропускает проверку HTTPS-сертификата; для экземпляров в локальной сети с самоподписанным сертификатом
-raw	Выводит ответ как есть, по умолчанию JSON форматируется

При успехе код возврата 0. Если интерфейс вернул не 2xx, выводится 错误: HTTP 状态码: 说明 и команда завершается с кодом 1; ошибки аргументов завершаются с кодом 2.

Примеры

# Сохранить параметры подключения (сначала проверяется токен запросом к /api/session)
gately ctl login http://192.168.1.2:16680 gtl_xxxx

# Показать интерфейсы, доступные токену, отфильтровав строки с ddns
gately ctl ls ddns

# Получить состояние системы
gately ctl get /api/status

# Разбудить устройство
gately ctl post /api/wol/devices/abc123/wake

# Отключить одно задание DDNS
gately ctl put /api/ddns/tasks/abc/enable '{"enable":false}'

# Взять тело запроса из файла
gately ctl post /api/ddns/tasks @task.json

# Временно задать переменные окружения
GATELY_URL=https://gw.example.com GATELY_TOKEN=gtl_xxxx gately ctl get /api/status

Подсказка

ls показывает интерфейсы, доступные токену; интерфейсы только для сессии входа (учётная запись, управление токенами, восстановление из резервной копии и т. п.) в списке не появляются. Разрешены ли операции записи, зависит от прав токена; при нехватке прав возвращается 403.

gately mcp

gately mcp предоставляет сервис MCP через стандартный ввод и вывод (JSON-RPC, одно сообщение на строку); AI-клиент запускает его как дочерний процесс.

Параметры

Параметр	Описание
--url <адрес>	Адрес управления
--token <токен>	API-токен
--write	Дополнительно открывает инструменты записи
--insecure	Пропускает проверку HTTPS-сертификата

Источники параметров подключения те же, что у gately ctl (файл конфигурации, GATELY_URL, GATELY_TOKEN, параметры).

Правила генерации инструментов

• После запуска сервиса, при первом запросе клиентом списка инструментов, читается документ OpenAPI экземпляра, и для каждого интерфейса, доступного токену, создаётся один инструмент.
• Имя инструмента составляется из метода и пути, например get_ddns_tasks, put_ddns_tasks_key_enable; максимальная длина 64 символа, при совпадении имён добавляется номер.
• Параметры пути становятся обязательными строковыми параметрами; у GET-инструментов есть необязательный параметр query (например, since=10); у интерфейсов с телом запроса есть параметр body, его структура берётся из OpenAPI.
• Описание инструмента содержит краткое описание интерфейса, метод с путём и необходимые права; инструменты помечаются readOnlyHint, а DELETE-инструменты — destructiveHint.
• Ответ длиннее 200000 символов обрезается.

По умолчанию только чтение

Без --write открываются только инструменты GET и HEAD. Чтобы разрешить AI менять конфигурацию, добавьте --write. Даже при включённой записи действуют права самого токена, поэтому надёжнее создать для MCP отдельный токен и выдать ему только нужные права.

Внимание

--write позволяет AI-клиенту вызывать все интерфейсы записи в пределах прав токена, включая удаление. Сначала проверьте сценарий с токеном только для чтения, затем при необходимости выдайте права на запись.

Настройка клиента

Для клиентов, использующих формат конфигурации mcpServers (Claude Desktop, Cursor и др.):

{
  "mcpServers": {
    "gately": {
      "command": "gately",
      "args": ["mcp"],
      "env": {
        "GATELY_URL": "http://127.0.0.1:16680",
        "GATELY_TOKEN": "gtl_xxxx"
      }
    }
  }
}

Чтобы включить запись, измените args на ["mcp", "--write"]. В command можно указать абсолютный путь к gately.

В Claude Code сервер добавляется из командной строки:

claude mcp add gately -e GATELY_URL=http://127.0.0.1:16680 -e GATELY_TOKEN=gtl_xxxx -- gately mcp