Инструменты выполнения

Инструменты выполнения — ядро swag2mcp: search находит эндпоинты, когда нет ID, inspect раскрывает полный контракт OpenAPI, а invoke выполняет фактический API-вызов. Всегда используйте их в этом порядке: search → inspect → invoke.

search

Назначение

Единственный инструмент для поиска эндпоинтов, когда нет ID эндпоинта. Выполняет полнотекстовый поиск по всем эндпоинтам во всех спецификациях с использованием поискового движка bluge.

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

Когда неизвестен ID эндпоинта
Когда нужно найти эндпоинты по ключевым словам, методу, тегу или пути
Когда нужно обнаружить, какие эндпоинты существуют для конкретной функции

Как работает

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

Параметры

Параметр	Тип	Обязательный	Описание
`query`	string	Да	Поисковый запрос (поддерживает структурированный синтаксис)
`limit`	int	Да	Максимальное количество результатов (1-50)

Синтаксис запросов

Пример	Описание
`pet`	Простой текстовый поиск по всем полям
`method:GET`	Фильтр по HTTP-методу
`tag:pet`	Фильтр по имени тега
`path:"/api/v1/users"`	Точный поиск по пути
`+method:POST +tag:pet`	Должны совпадать оба условия
`-method:DELETE`	Исключить DELETE-методы
`create~`	Нечёткий поиск (устойчив к опечаткам)
`path:/api/v1/*`	Поиск по пути с подстановочным знаком
`/pattern/`	Регулярное выражение
`term^3`	Повышение релевантности термина

Поисковые поля: method (ключевое слово), tag (ключевое слово), path (текст), summary (текст), _all (поле текста по умолчанию).

Не поддерживается: круглые скобки для группировки, явные операторы AND/OR, группировка полей.

Ответ

json

{
  "endpoints": [
    {
      "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
      "tagId": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
      "tagName": "forecast",
      "collectionId": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
      "collectionTitle": "Weather Forecast",
      "specId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "specDomain": "meteo",
      "method": "GET",
      "path": "/v1/forecast",
      "summary": "Get weather forecast for a location"
    }
  ]
}

Каждый результат включает полную родословную (спецификация → коллекция → тег), чтобы LLM мог навигировать к связанным эндпоинтам.

Нюансы

limit должен быть от 1 до 50 (иначе возвращает validation_failed)
query обязателен (возвращает validation_failed, если пустой)
Результаты возвращаются в порядке релевантности (лучшее совпадение первым)
Используйте фильтры полей (method:GET, tag:pet) для сужения результатов
Для точного совпадения пути используйте кавычки: path:"/v1/forecast"

inspect

Назначение

Получение полного объекта OpenAPI-операции для эндпоинта: все параметры, схема тела запроса, схемы ответов, базовый URL и полный URL. Этот инструмент нужно вызывать перед invoke для понимания контракта эндпоинта.

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

Всегда перед invoke — нужен полный контракт для корректного вызова
Когда нужно объяснить пользователю технические детали API
Когда нужно узнать обязательные параметры, структуру тела запроса или формат ответа

Как работает

Ищет эндпоинт в индексе и возвращает полный объект OpenAPI-операции со всеми разрешёнными схемами.

Параметры

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

Ответ

json

{
  "id": "f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "tagId": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
  "collectionId": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
  "specId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "specDomain": "meteo",
  "method": "POST",
  "path": "/pet",
  "baseUrl": "https://meteo.swagger.io/v2",
  "fullUrl": "https://meteo.swagger.io/v2/pet",
  "operation": {
    "id": "addPet",
    "tags": ["pet"],
    "summary": "Add a new pet",
    "description": "Add a new pet to the store",
    "deprecated": false,
    "parameters": [
      {
        "name": "petId",
        "in": "path",
        "description": "ID of the pet",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64"
        }
      }
    ],
    "requestBody": {
      "description": "Pet object to add",
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "status": { "type": "string", "enum": ["available", "pending", "sold"] }
            },
            "required": ["name"]
          }
        }
      }
    },
    "responses": {
      "200": {
        "description": "Successful operation",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Pet"
            }
          }
        }
      },
      "405": {
        "description": "Invalid input"
      }
    }
  }
}

Поле	Тип	Описание
`baseUrl`	string	Базовый URL API (из конфига)
`fullUrl`	string	Полный URL эндпоинта (base + path)
`operation.parameters[]`	array	Параметры с именем, расположением (path/query/header/cookie), описанием, флагом обязательности и схемой
`operation.requestBody`	object	Тело запроса с типом контента и схемой
`operation.responses`	map	Коды ответов с описаниями и схемами
`operation.deprecated`	bool	Является ли эндпоинт устаревшим

Нюансы

Возвращает not_found, если эндпоинт не существует
Это единственный инструмент, возвращающий полную OpenAPI-операцию — endpoint_by_id возвращает только сводку
Всегда вызывайте inspect перед invoke для понимания обязательных параметров и структуры тела
Объект operation включает ссылки $ref, которые разрешаются в полные определения схем

invoke

Назначение

Выполнение реального API-вызова к эндпоинту. Это единственный инструмент, который выполняет фактические HTTP-запросы. Аутентификация применяется автоматически — не нужно вызывать auth заранее.

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

Только после вызова inspect для понимания контракта эндпоинта
Только с явным подтверждением пользователя для деструктивных операций (POST, PUT, PATCH, DELETE)
Когда пользователь просит вызвать API и у вас есть все обязательные параметры

Как работает

Ищет эндпоинт в индексе
Подставляет path-параметры в URL
Добавляет query-параметры
Добавляет заголовки и cookies
Сериализует тело запроса в JSON
Автоматически получает и применяет аутентификацию (токен, заголовки, query-параметры)
Выполняет HTTP-запрос
Возвращает ответ или сохраняет его в файл, если слишком большой

Параметры

Параметр	Тип	Обязательный	Описание
`endpointId`	string	Да	32-символьный MD5-хеш эндпоинта
`parameters`	object	Нет	Path-, query- и header-параметры в виде пар ключ-значение
`requestBody`	object	Нет	Тело запроса для POST/PUT/PATCH-запросов
`headers`	object	Нет	Дополнительные HTTP-заголовки
`cookies`	object	Нет	Дополнительные HTTP-cookies

Ответ (встроенный)

json

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "id": 1,
    "name": "Rex",
    "status": "available"
  }
}

Ответ (ссылка на файл — когда тело превышает лимит размера)

json

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "fileRef": {
    "path": "/Users/user/.swag2mcp/responses/response_a1b2c3d4.json",
    "size": 1572864,
    "sizeHint": "1.5 MB",
    "maxSizeHint": "1 MB",
    "message": "Response exceeds the 1 MB limit and has been saved to disk.",
    "openCmd": "open /Users/user/.swag2mcp/responses/response_a1b2c3d4.json"
  }
}

Поле	Тип	Описание
`statusCode`	int	HTTP-код статуса ответа
`headers`	object	HTTP-заголовки ответа
`body`	any	Тело ответа (присутствует, когда в пределах лимита размера)
`fileRef`	object	Ссылка на файл (присутствует, когда тело превышает лимит размера)

Работа с большими ответами

Когда invoke возвращает fileRef, используйте инструменты для работы с ответами:

response_outline(path) — получение структурной сводки (ключи, типы, длины массивов)
response_compress(path, mode) — сжатие данных для встраивания в строку
response_slice(path, jsonPath) — извлечение конкретного фрагмента

Нюансы

Аутентификация автоматическая: Инструмент invoke автоматически получает и применяет аутентификацию из конфигурации спецификации. Не нужно вызывать auth заранее.
Ограничение частоты: Каждый эндпоинт имеет 10-секундную задержку. Второй вызов того же эндпоинта в течение 10 секунд молча блокируется (возвращает ошибку rate_limit).
Лимит размера ответа: По умолчанию 1 МБ (настраивается через max_response_size). Если ответ превышает этот лимит, он сохраняется в {workspace}/responses/ и возвращается FileReference вместо встроенного body.
Обработка параметров: Path-параметры подставляются в URL. Query-параметры добавляются. Параметры из запроса переопределяют значения по умолчанию из спецификации операции.
Тело запроса: Для POST/PUT/PATCH тело сериализуется в JSON. Content-Type устанавливается в application/json автоматически.
Обработка ошибок: HTTP-ошибки (не 2xx) возвращаются как invoke_error с кодом статуса и телом ответа в подсказке.
Деструктивные операции: Никогда не вызывайте POST/PUT/PATCH/DELETE без явного подтверждения пользователя.

Инструменты выполнения ​

search ​

Назначение ​

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

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

Параметры ​

Синтаксис запросов ​

Ответ ​

Нюансы ​

inspect ​

Назначение ​

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

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

Параметры ​

Ответ ​

Нюансы ​

invoke ​

Назначение ​

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

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

Параметры ​

Ответ (встроенный) ​

Ответ (ссылка на файл — когда тело превышает лимит размера) ​

Работа с большими ответами ​

Нюансы ​

Инструменты выполнения

search

Назначение

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

Как работает

Параметры

Синтаксис запросов

Ответ

Нюансы

inspect

Назначение

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

Как работает

Параметры

Ответ

Нюансы

invoke

Назначение

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

Как работает

Параметры

Ответ (встроенный)

Ответ (ссылка на файл — когда тело превышает лимит размера)

Работа с большими ответами

Нюансы