Концепции

Архитектура

swag2mcp выступает в роли моста между спецификациями API и LLM-агентами:

Основные понятия

Спецификация — логический контейнер, представляющий домен или сервис API (например, YouTube, Binance, Open-Meteo). Каждая спецификация имеет уникальный domain, base_url, опциональную auth и содержит одну или несколько коллекций. Вы также можете задать llm_instruction — короткую подсказку, которая внедряется в системный промпт swag2mcp и сообщает LLM, для чего предназначена эта спецификация и когда её использовать. Подробнее: Спецификации.

Коллекция — один файл OpenAPI/Swagger/Postman, описывающий конкретный API. Она указывает на location (URL или локальный путь к файлу). Одна спецификация может иметь несколько коллекций — например, спецификация "meteo" может содержать коллекции "Прогноз", "Качество воздуха" и "Морские данные", каждая из которых указывает на свой файл спецификации. Подробнее: Коллекции.

Тег — категория эндпоинтов внутри коллекции. Помогает LLM точнее находить нужные операции. Подробнее: Теги.

Эндпоинт — конкретный HTTP-метод + путь (например, GET /api/users). LLM может найти эндпоинт по описанию, изучить его параметры и схемы, а затем вызвать его. Подробнее: Эндпоинты.

Рабочая область — директория, в которой swag2mcp хранит конфиг, кэш спецификаций, сохранённые ответы и скрипты аутентификации. Подробнее: Рабочая область.

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

1. Добавьте спецификацию или коллекцию — определите её в YAML-конфиге (~/.swag2mcp/swag2mcp.yaml). Например:

   specs:
     - domain: jokes
       llm_title: Dad Joke API
       base_url: https://icanhazdadjoke.com
       collections:
         - llm_title: Jokes
           location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/dadjoke.yaml

2. swag2mcp парсит каждую коллекцию — создаёт теги и эндпоинты, индексирует их для поиска.

3. LLM находит нужный эндпоинт — через MCP-инструменты (search, endpoint_by_tag, inspect) LLM ищет подходящий эндпоинт по описанию, изучает его параметры и схему запроса.

4. LLM вызывает эндпоинт — через MCP-инструмент invoke LLM отправляет запрос. swag2mcp проверяет каждый входной параметр на соответствие OpenAPI-схеме эндпоинта (параметры пути, запроса, заголовки, тело запроса) перед выполнением вызова. Если что-то не соответствует схеме, LLM получает понятную ошибку с объяснением проблемы. После проверки swag2mcp выполняет реальный HTTP-вызов и возвращает результат.

5. Результат возвращается LLM — ответ API передаётся обратно агенту. Большие ответы сохраняются в рабочую область и могут быть исследованы с помощью трёх специальных MCP-инструментов: response_outline (просмотр структуры), response_compress (сжатие до репрезентативного образца) и response_slice (извлечение конкретных фрагментов).

swag2mcp — это мост между LLM и миром API. Вы добавляете спецификации API, а LLM — через протокол MCP — находит нужные эндпоинты, изучает их документацию и вызывает их. Всё, что вам нужно сделать — добавить спецификацию и запустить MCP-сервер.

Конфиг можно редактировать в любое время. YAML-файл конфигурации (~/.swag2mcp/swag2mcp.yaml) можно редактировать вручную — добавлять спецификации, менять аутентификацию, настраивать параметры. После каждого изменения перезапустите MCP-сервер (swag2mcp mcp), чтобы изменения вступили в силу.

Иерархия

Спецификация (domain, например "meteo")
  └── Коллекция 1 (файл спецификации, например forecast.yml)
        └── Тег 1 (категория)
              └── Эндпоинт (GET /api/forecast)
              └── Эндпоинт (POST /api/forecast)
        └── Тег 2
              └── Эндпоинт (GET /api/forecast/{id})
  └── Коллекция 2 (файл спецификации, например air-quality.yml)
        └── Тег 3
              └── Эндпоинт (GET /api/air-quality)