Инструменты-утилиты

Инструменты-утилиты предоставляют вспомогательную функциональность: получение токенов аутентификации, информации о рантайме и работу с большими ответами API, которые не помещаются в строку.

auth

Назначение

Получение токена аутентификации, заголовков или query-параметров для конкретной спецификации. Это даёт LLM доступ к учётным данным, которые можно использовать вне swag2mcp (например, для генерации curl-команды).

Когда использовать

Только когда пользователь явно запрашивает сырой токен или учётные данные
При генерации curl-команды или фрагмента кода, требующего аутентификацию
Когда пользователь хочет увидеть, какой метод аутентификации настроен

Когда НЕ использовать

Не вызывайте auth перед inspect или invoke — invoke автоматически получает и применяет аутентификацию
Не вызывайте auth просто для проверки, настроена ли аутентификация — используйте info

Как работает

Ищет конфигурацию аутентификации спецификации и выполняет поток аутентификации (обмен токена, выполнение скрипта и т.д.) для получения текущих учётных данных.

Параметры

Параметр	Тип	Обязательный	Описание
`specId`	string	Да	32-символьный MD5-хеш спецификации

Ответ

json

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "X-API-Key": "my-api-key"
  },
  "queryParams": {
    "api_key": "my-api-key"
  }
}

Поле	Тип	Описание
`token`	string	Сырое значение токена (bearer-токен, API-ключ и т.д.)
`headers`	object	HTTP-заголовки для включения в запросы
`queryParams`	object	Query-параметры для включения в запросы

Нюансы

Отключён по умолчанию в продакшене: Флаг --disable-llm-auth (по умолчанию: true) полностью удаляет инструмент auth из списка MCP-инструментов. LLM не может видеть или запрашивать токены. Установите --disable-llm-auth=false для включения при отладке или для короткоживущих токенов.
invoke обрабатывает аутентификацию автоматически: Не нужно вызывать auth перед invoke. Сервис invoke автоматически получает и применяет правильную аутентификацию.
Поддерживает 9 методов аутентификации: none, basic, bearer, digest, hmac, oauth2-cc (client credentials), oauth2-pwd (password), api-key, script.
Возвращает auth_error, если метод аутентификации не сработал (например, недоступна конечная точка OAuth2-токена, ошибка выполнения скрипта).

info

Назначение

Возвращает комплексную сводку рантайма swag2mcp: версию, путь рабочей области, активные спецификации, настройки HTTP-клиента, конфигурацию MCP-транспорта, методы аутентификации и статус режима моков.

Когда использовать

Когда пользователь спрашивает о конфигурации системы
Когда нужно проверить настройки рантайма (таймаут, лимит размера ответа, транспорт)
Когда нужно узнать, какие методы аутентификации доступны
При устранении проблем с конфигурацией

Как работает

Возвращает предварительно вычисленный снимок состояния рантайма. Параметры не требуются.

Параметры

Нет.

Ответ

json

{
  "version": "v1.2.0",
  "workspace": "~/.swag2mcp",
  "uptime": "2h 15m",
  "specs": {
    "total": 4,
    "active": 3,
    "disabled": 1,
    "collections": 6,
    "endpoints": 42
  },
  "http_client": {
    "timeout": "30s",
    "max_response_size": "1 MB",
    "follow_redirects": true,
    "max_redirects": 10,
    "randomize": false,
    "proxy": null,
    "headers": {},
    "cookies": []
  },
  "mcp": {
    "transport": "stdio",
    "addr": ":8080",
    "path": "/mcp",
    "auth_enabled": false
  },
  "auth": {
    "methods": ["bearer", "api-key"]
  },
  "mock": {
    "enabled": false
  }
}

Поле	Тип	Описание
`version`	string	Версия swag2mcp
`workspace`	string	Путь к директории рабочей области
`uptime`	string	Время работы сервера (человекочитаемое)
`specs`	object	Сводка спецификаций: всего, активно, отключено, коллекций, эндпоинтов
`http_client`	object	Конфигурация HTTP-клиента
`http_client.max_response_size`	string	Максимальный размер ответа в человекочитаемом формате (например, "1 MB")
`mcp`	object	Конфигурация MCP-сервера
`auth`	object	Доступные методы аутентификации
`mock`	object	Статус мок-сервера

Нюансы

max_response_size отображается в человекочитаемом формате (например, "1 KB", "2 MB")
uptime вычисляется из времени запуска сервера
Данные — это снимок, сделанный при загрузке; он отражает состояние на момент запуска MCP-сервера

response_outline

Назначение

Получение высокоуровневой структурной сводки большого JSON-файла ответа, который был сохранён на диск инструментом invoke. Возвращает форму данных — ключи, типы, длины массивов и подсказки для навигации — без возврата фактических значений.

Когда использовать

Сразу после того, как invoke вернул fileRef (ответ слишком большой для встраивания в строку)
Это обязательный первый шаг в рабочем процессе с большими ответами

Как работает

Читает сохранённый файл ответа и анализирует его структуру: тип верхнего уровня, ключи, длины массивов, глубину вложенности и подсказки для сжатия.

Параметры

Параметр	Тип	Обязательный	Описание
`path`	string	Да	Абсолютный путь из `fileRef.path`
`maxDepth`	int	Нет	Максимальная глубина рекурсии (по умолчанию: 3)
`maxArrayItems`	int	Нет	Сколько элементов массива проверять (по умолчанию: 5)

Ответ

json

{
  "outline": {
    "type": "object",
    "size": 1572864,
    "lineCount": 12500,
    "depth": 3,
    "structure": {
      "type": "object",
      "keys": ["data", "meta", "error"],
      "data": {
        "type": "array",
        "length": 500,
        "items": {
          "type": "object",
          "keys": ["id", "name", "status", "createdAt"]
        }
      }
    },
    "schemaHint": "object with 3 keys: data (array[500]), meta (object), error (null)",
    "keys": ["data", "meta", "error"],
    "itemCount": 500,
    "itemType": "object",
    "compressionHints": [
      "response_compress(path, 'first_of_array', 'data')",
      "response_compress(path, 'sample_array', 'data', arrayHead=3, arrayTail=2)",
      "response_compress(path, 'keys_only', 'data')",
      "response_compress(path, 'select_keys', 'data', selectKeys=[id, name])"
    ],
    "navigationHints": {
      "topLevelPaths": [
        {"path": "data", "type": "array"},
        {"path": "meta", "type": "object"},
        {"path": "error", "type": "null"}
      ],
      "arrayPaths": [
        {"path": "data", "length": 500, "itemType": "object"}
      ]
    }
  }
}

Поле	Тип	Описание
`type`	string	Тип верхнего уровня: "object" или "array"
`size`	int	Размер файла в байтах
`lineCount`	int	Количество строк в файле
`depth`	int	Максимальная проверенная глубина вложенности
`structure`	object	Рекурсивная структура с ключами, типами, длинами массивов
`schemaHint`	string	Однострочная сводка формы верхнего уровня
`keys`	array	Ключи верхнего уровня (для объектов)
`itemCount`	int	Длина массива (для массивов)
`compressionHints`	array	Предлагаемые вызовы `response_compress` с параметрами
`navigationHints`	object	Пути верхнего уровня и массивы с длинами

Нюансы

Возвращает validation_failed, если путь некорректен или не находится внутри директории responses
Возвращает not_found, если файл не существует
Возвращает validation_failed, если файл не является валидным JSON
Поле compressionHints предоставляет готовые к использованию предложения для вызовов response_compress

response_compress

Назначение

Уменьшение JSON-значения внутри сохранённого файла ответа, чтобы оно поместилось в лимит размера ответа и могло быть возвращено LLM в строке. Несколько режимов сжатия позволяют выбрать правильный баланс между размером и информацией.

Когда использовать

После response_outline для понимания структуры
Когда нужно получить данные из большого ответа в строке
Когда response_slice слишком узок и нужен более широкий обзор

Как работает

Читает сохранённый файл ответа, переходит к указанному JSON-пути, применяет режим сжатия и возвращает сжатый результат. Если результат всё ещё превышает лимит размера, он сохраняется в новый файл.

Параметры

Параметр	Тип	Обязательный	Описание
`path`	string	Да	Абсолютный путь из `fileRef.path`
`jsonPath`	string	Нет	Путь к значению для сжатия (например, `data` или `data.0`)
`mode`	string	Да	Режим сжатия (см. таблицу ниже)
`arrayHead`	int	Нет	Начальные элементы для сохранения в режиме `sample_array` (по умолчанию: 3)
`arrayTail`	int	Нет	Конечные элементы для сохранения в режиме `sample_array` (по умолчанию: 2)
`stringLen`	int	Нет	Максимальная длина строки в режиме `truncate_strings` (по умолчанию: 80)
`selectKeys`	array	Нет	Ключи для сохранения в режиме `select_keys`

Режимы сжатия

Режим	Описание	Лучше всего для
`first_of_array`	Сохранить только первый элемент массива	Когда все элементы имеют одинаковую структуру
`sample_array`	Сохранить начало и конец массива	Когда нужно увидеть диапазон значений
`truncate_strings`	Укоротить каждую строку до `stringLen` символов	Когда строки очень длинные, но структура важна
`keys_only`	Заменить значения объектов на имена их типов	Когда нужна только структура
`select_keys`	Сохранить только указанные ключи в каждом объекте	Когда нужны конкретные поля из многих объектов

Ответ

json

{
  "body": [
    { "id": 1, "name": "Rex", "status": "available" },
    { "id": 2, "name": "Max", "status": "pending" }
  ],
  "hint": "Compressed array from 500 to 2 items using first_of_array mode"
}

Поле	Тип	Описание
`body`	any	Сжатое JSON-значение (присутствует, когда в пределах лимита размера)
`fileRef`	object	Ссылка на файл (присутствует, когда всё ещё слишком большой)
`hint`	string	Объяснение того, что было сжато

Нюансы

Если сжатый результат всё ещё превышает max_response_size, он сохраняется в новый файл и возвращается FileReference
Значения по умолчанию: arrayHead=3, arrayTail=2, stringLen=80
Возвращает validation_failed для неверного пути, неверного JSONPath или не-JSON файла
Возвращает not_found, если файл не существует или JSONPath не совпадает

response_slice

Назначение

Извлечение конкретного фрагмента сохранённого JSON-файла ответа по логическому JSON-пути или по диапазону строк. В отличие от response_compress, возвращает сырые, неизменённые данные.

Когда использовать

Когда нужен конкретный элемент или значение из большого ответа
Когда response_compress не даёт достаточно деталей
Когда нужно перемещаться по ответу шаг за шагом

Как работает

Читает сохранённый файл ответа и извлекает фрагмент по JSON-пути (например, data.3.name) или по диапазону строк (например, 120-240). Возвращает подсказки для навигации по массивам и объектам.

Параметры

Параметр	Тип	Обязательный	Описание
`path`	string	Да	Абсолютный путь из `fileRef.path`
`jsonPath`	string	Нет	Логический путь к значению (например, `data.3.name`)
`line`	int	Нет	Номер строки (начиная с 1) для центрирования фрагмента
`range`	string	Нет	Диапазон строк в формате `start-end` (например, `120-240`)
`around`	int	Нет	Строк для включения вокруг `line` (по умолчанию: 20)

Ответ

json

{
  "slice": {
    "lines": [120, 130],
    "fragment": "{\n  \"id\": 1,\n  \"name\": \"Rex\"\n}",
    "value": {
      "id": 1,
      "name": "Rex"
    },
    "jsonPath": "data.0",
    "context": "object",
    "isComplete": true,
    "nextLine": 131,
    "prevLine": 119,
    "nextPath": "data.1",
    "prevPath": null
  }
}

Поле	Тип	Описание
`lines`	array	Диапазон строк [начало, конец] (начиная с 1)
`fragment`	string	Сырой JSON-текст (когда достаточно мал)
`value`	any	Извлечённое JSON-значение
`jsonPath`	string	Использованный JSON-путь
`context`	string	"object", "array" или "value"
`isComplete`	bool	True, когда значение является валидным JSON-фрагментом
`nextLine`	int	Предлагаемая следующая строка для построчной навигации
`prevLine`	int	Предлагаемая предыдущая строка
`nextPath`	string	Предлагаемый следующий JSON-путь для навигации по массиву
`prevPath`	string	Предлагаемый предыдущий JSON-путь

Нюансы

Предпочитайте jsonPath номерам строк — JSON-пути стабильны и описательны, номера строк меняются при перегенерации файла
Если извлечённый фрагмент превышает max_response_size, он сохраняется в новый файл и возвращается FileReference
По умолчанию around равен 20 строкам
Ответ включает nextPath/prevPath для навигации по массивам и nextLine/prevLine для построчной навигации
Возвращает validation_failed для неверного пути, неверного JSONPath, неверной строки/диапазона или не-JSON файла
Возвращает not_found, если файл не существует или JSONPath не совпадает

Инструменты-утилиты ​

auth ​

Назначение ​

Когда использовать ​

Когда НЕ использовать ​

Как работает ​

Параметры ​

Ответ ​

Нюансы ​

info ​

Назначение ​

Когда использовать ​

Как работает ​

Параметры ​

Ответ ​

Нюансы ​

response_outline ​

Назначение ​

Когда использовать ​

Как работает ​

Параметры ​

Ответ ​

Нюансы ​

response_compress ​

Назначение ​

Когда использовать ​

Как работает ​

Параметры ​

Режимы сжатия ​

Ответ ​

Нюансы ​

response_slice ​

Назначение ​

Когда использовать ​

Как работает ​

Параметры ​

Ответ ​

Нюансы ​

Инструменты-утилиты

auth

Назначение

Когда использовать

Когда НЕ использовать

Как работает

Параметры

Ответ

Нюансы

info

Назначение

Когда использовать

Как работает

Параметры

Ответ

Нюансы

response_outline

Назначение

Когда использовать

Как работает

Параметры

Ответ

Нюансы

response_compress

Назначение

Когда использовать

Как работает

Параметры

Режимы сжатия

Ответ

Нюансы

response_slice

Назначение

Когда использовать

Как работает

Параметры

Ответ

Нюансы