MCP Инструменты

Обзор

swag2mcp предоставляет 19 MCP инструментов, которые дают LLM-агенту полный доступ к вашим API через протокол Model Context Protocol. Эти инструменты покрывают полный рабочий процесс: обнаружение доступных API, навигацию по иерархии спецификаций, поиск и проверку эндпоинтов, выполнение API-вызовов и работу с большими ответами.

Что решают инструменты

• Обнаружение — LLM может находить спецификации, коллекции и теги без предварительного знания ID
• Навигация — спуск от спецификации → коллекции → тега → эндпоинта по структурированной иерархии
• Поиск — полнотекстовый поиск по всем эндпоинтам, когда нет ID
• Проверка — получение полного объекта OpenAPI-операции перед вызовом
• Выполнение — выполнение реальных API-вызовов с автоматической аутентификацией
• Обработка больших ответов — обзор, сжатие и извлечение фрагментов ответов, которые не помещаются в строку

Только чтение vs Изменяемые

Тип	Количество	Инструменты
Только чтение	17	Все инструменты обнаружения, эндпоинтов, поиска, проверки, информации и ответов
Изменяемые	2	invoke (выполняет реальные HTTP-вызовы), auth (получает токены)

Инструменты только для чтения помечены флагами ReadOnlyHint=true и IdempotentHint=true в протоколе MCP, сообщая LLM, что их можно безопасно вызывать без побочных эффектов.

Обработка ошибок

Все инструменты возвращают ошибки в виде структурированных объектов LLMError с машиночитаемым кодом и человекочитаемым сообщением, объясняющим, что пошло не так и что делать дальше:

Код ошибки	Значение
validation_failed	Некорректный ввод (неверный формат ID, отсутствуют обязательные поля)
not_found	Сущность не найдена в индексе или рабочей области
rate_limit	Второй вызов invoke в течение 10 секунд на том же эндпоинте
invoke_error	Ошибка HTTP-вызова, ошибка загрузки
auth_error	Ошибка получения токена аутентификации
config_error	Ошибка загрузки или сохранения конфигурационного файла
parse_error	Ошибка парсинга файла спецификации

Категории

Категория	Инструменты	Описание
Обнаружение	spec_list, spec_by_id, collection_by_spec, collection_by_id, tag_by_spec, tag_by_collection, tag_by_id	Навигация по иерархии спецификаций: поиск спецификаций, коллекций и тегов
Эндпоинты	endpoint_by_spec, endpoint_by_collection, endpoint_by_tag, endpoint_by_id	Просмотр эндпоинтов на разных уровнях иерархии
Выполнение	search, inspect, invoke	Поиск, проверка полного контракта и вызов API
Утилиты	auth, info, response_outline, response_compress, response_slice	Токены аутентификации, информация о рантайме и обработка больших ответов
Навыки	Руководство по форматированию	Настройка отображения ответов инструментов

Полный список

Инструмент	Описание
spec_list	Список всех спецификаций API в рабочей области
spec_by_id	Детальная информация о спецификации с коллекциями
collection_by_spec	Список коллекций в спецификации
collection_by_id	Детали коллекции с тегами
tag_by_spec	Список всех тегов в спецификации
tag_by_collection	Список тегов в коллекции
tag_by_id	Детали тега (ID, название, количество методов)
endpoint_by_spec	Список всех эндпоинтов в спецификации
endpoint_by_collection	Список эндпоинтов в коллекции
endpoint_by_tag	Список эндпоинтов в теге
endpoint_by_id	Краткая сводка эндпоинта (метод, путь, описание)
search	Полнотекстовый поиск по всем эндпоинтам
inspect	Полные детали OpenAPI-операции (параметры, схемы)
invoke	Выполнение реального API-вызова
auth	Получение токена или заголовков аутентификации для спецификации
info	Информация о рантайме (версия, спецификации, конфиг)
response_outline	Структурная сводка большого файла ответа
response_compress	Сжатие большого ответа для встраивания в строку
response_slice	Извлечение фрагмента большого ответа

Иерархия навигации

spec_list
  └── spec_by_id(id)
        └── collection_by_spec(specId)
              └── collection_by_id(id)
                    └── tag_by_collection(collectionId)
                          └── tag_by_id(id)
                                └── endpoint_by_tag(tagId)
                                      └── endpoint_by_id(id)
                                            └── inspect(endpointId)
                                                  └── invoke(endpointId)

Когда у вас нет ID, используйте search для поиска эндпоинтов по запросу. Когда invoke возвращает fileRef (ответ слишком большой), используйте response_outline → response_compress или response_slice для изучения данных.