FAQ

Общие вопросы

Что такое swag2mcp и какую проблему он решает?

swag2mcp объединяет спецификации OpenAPI/Swagger/Postman с LLM-агентами через протокол MCP. Вместо того чтобы писать собственный код для подключения каждого API к AI-агенту, вы настраиваете его один раз в YAML-файле, и LLM получает 19 инструментов для обнаружения, изучения и вызова ваших API.

Чем он отличается от других инструментов для связи API с LLM?

Не требует программирования — настройте API в YAML, код интеграции не нужен
19 MCP-инструментов — полный набор от обнаружения до вызова и обработки больших ответов
9 методов аутентификации — работает с любой схемой авторизации API
Полнотекстовый поиск — поиск на движке bluge по всем эндпоинтам
TUI-обозреватель — интерактивный терминальный интерфейс для просмотра и тестирования
Mock-сервер — тестирование без реальных вызовов API

Какие форматы спецификаций поддерживаются?

OpenAPI 3.x, Swagger 2.0 и Postman Collections v2.1.

В чём разница между спецификацией и коллекцией?

Спецификация представляет логический API-сервис (например, "Open-Meteo Weather APIs"). Коллекция — это один файл OpenAPI/Swagger/Postman. Спецификация может содержать несколько коллекций — например, когда у API есть отдельные файлы спецификаций для разных сервисов (прогноз погоды, качество воздуха, морские данные).

Какие MCP-транспорты поддерживаются?

Три транспорта: stdio (по умолчанию, для локальных LLM-клиентов), sse (Server-Sent Events для удалённых клиентов) и streamable-http (современная HTTP-трансляция).

Могу ли я использовать swag2mcp с любой LLM?

Да, с любым LLM-клиентом, поддерживающим протокол MCP: Claude Desktop, VS Code, Cursor, Windsurf, JetBrains IDE, OpenCode и другие.

Установка

Как установить swag2mcp?

bash

# Вариант 1: Скачать с GitHub Releases
# Перейдите на https://github.com/mmadfox/swag2mcp/releases/latest
# Скачайте архив для вашей ОС и архитектуры

# Вариант 2: Установить через Go
go install github.com/mmadfox/swag2mcp/cmd/swag2mcp@latest

Нужен ли мне установленный Go?

Нет. Готовые бинарные файлы доступны для Linux (amd64, arm64), macOS (amd64, arm64) и Windows (amd64) на странице GitHub Releases.

Как установить mock-сервер?

Mock-сервер — это отдельный бинарный файл:

bash

go install github.com/mmadfox/swag2mcp/cmd/swag2mcp-mock@latest

Или скачайте swag2mcp-mock_<version>_<os>_<arch>.tar.gz с GitHub Releases.

Начало работы

Как быстро начать?

bash

# 1. Инициализируйте рабочую область
mkdir -p .swag2mcp && swag2mcp init ./.swag2mcp

# 2. Запустите MCP-сервер (после init уже включены публичные примеры спецификаций)
swag2mcp mcp

После init рабочая область уже содержит несколько публичных примеров спецификаций (icanhazdadjoke, Open-Meteo, Binance, PokéAPI). Вы можете сразу запустить MCP-сервер — добавлять спецификации вручную не нужно.

Если вы хотите добавить свой API:

bash

swag2mcp add spec --yaml - <<EOF
domain: dadjoke
llm_title: icanhazdadjoke API
base_url: https://icanhazdadjoke.com
collections:
  - llm_title: Jokes
    location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/dadjoke.yaml
EOF

Как подключить swag2mcp к моей IDE?

VS Code (.vscode/settings.json):

json

{
  "mcp": {
    "servers": {
      "swag2mcp": {
        "command": "swag2mcp",
        "args": ["mcp", "/абсолютный/путь/до/.swag2mcp"]
      }
    }
  }
}

Cursor (~/.cursor/mcp.json):

json

{
  "mcpServers": {
    "swag2mcp": {
      "command": "swag2mcp",
      "args": ["mcp", "/абсолютный/путь/до/.swag2mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

json

{
  "mcpServers": {
    "swag2mcp": {
      "command": "swag2mcp",
      "args": ["mcp", "/абсолютный/путь/до/.swag2mcp"]
    }
  }
}

Всегда используйте абсолютный путь к директории рабочей области.

Конфигурация

Где находится файл конфигурации?

По умолчанию: ~/.swag2mcp/swag2mcp.yaml. Вы также можете создать его в любой директории и передавать путь в команды.

Как добавить API?

bash

# Интерактивный режим
swag2mcp add spec

# С YAML (рекомендуется для скриптов)
swag2mcp add spec --yaml - <<EOF
domain: my-api
llm_title: My API
base_url: https://api.example.com/v1
collections:
  - llm_title: Main
    location: https://example.com/spec.yaml
EOF

Как добавить коллекцию к существующей спецификации?

bash

swag2mcp add collection --yaml - <<EOF
spec_domain: meteo
llm_title: Air Quality
location: https://example.com/air-quality.yaml
EOF

Как временно отключить спецификацию?

Установите disable: true в конфиге спецификации. Спецификация не будет загружена или проиндексирована.

Можно ли фильтровать, какие спецификации загружаются?

Да, используйте флаг --tags: swag2mcp mcp --tags=public. Будут загружены только спецификации с соответствующими тегами.

Как использовать переменные окружения для секретов?

Используйте синтаксис $(VAR_NAME) в полях аутентификации:

yaml

auth:
  type: bearer
  config:
    token: "$(MY_API_TOKEN)"

Установите переменную перед запуском: export MY_API_TOKEN="eyJhbGci..."

Аутентификация

Какие методы аутентификации поддерживаются?

Девять методов: none, basic, bearer, digest, hmac, oauth2-cc (client credentials), oauth2-pwd (password grant), api-key и script.

Как передать токен?

Через файл конфигурации или переменные окружения:

yaml

auth:
  type: bearer
  config:
    token: "$(MY_TOKEN)"

Нужно ли вызывать auth перед invoke?

Нет. Инструмент invoke автоматически применяет аутентификацию из конфига спецификации. MCP-инструмент auth нужен только если вы хотите показать токен пользователю (например, для команды curl).

Почему инструмент auth не отображается?

Инструмент auth отключён по умолчанию (--disable-llm-auth=true). Это мера безопасности для продакшена. Чтобы включить: swag2mcp mcp --disable-llm-auth=false.

Как обновляются токены OAuth2?

Токены OAuth2 Client Credentials и Password Grant автоматически обновляются при истечении срока действия. Bearer-токены статичны и должны обновляться вручную.

MCP-сервер

Как запустить MCP-сервер?

bash

# По умолчанию (stdio транспорт)
swag2mcp mcp

# С HTTP-транспортом
swag2mcp mcp --transport sse --http-addr :8080

Как изменить порт?

bash

swag2mcp mcp --transport sse --http-addr 0.0.0.0:9090

Как защитить MCP HTTP-эндпоинт?

Установите bearer-токен:

bash

swag2mcp mcp --transport sse --http-addr :8080 --auth-token "my-secret"

LLM-клиент должен включать Authorization: Bearer my-secret в каждый запрос.

Что такое MCP-рукопожатие для HTTP-транспорта?

Для SSE и Streamable HTTP транспортов протокол MCP требует трёхшаговое рукопожатие:

Шаг 1: POST /mcp → {"method":"initialize", ...}
Шаг 2: POST /mcp → {"method":"notifications/initialized"}
Шаг 3: POST /mcp → {"method":"tools/list", ...}  ← теперь работает

Вызовы инструментов будут завершаться ошибкой до инициализации.

Использование

Как искать эндпоинты?

Используйте MCP-инструмент search или TUI (swag2mcp run). Поиск поддерживает фильтры по полям (method:GET, tag:pets), нечёткий поиск, подстановочные знаки и логические операторы.

Как вызвать API?

LLM использует MCP-инструмент invoke. Всегда сначала изучайте эндпоинт, чтобы понять требуемые параметры:

inspect(endpointId: "...")  → понять контракт
invoke(endpointId: "...", parameters: {...})  → выполнить вызов

Что происходит, если ответ слишком большой?

Ответы, превышающие max_response_size (по умолчанию 1 МБ), сохраняются на диск. LLM получает ссылку на файл и может исследовать его с помощью инструментов response_outline, response_compress и response_slice.

Как работает ограничитель запросов?

У каждого эндпоинта есть период охлаждения 10 секунд. Если LLM вызывает один и тот же эндпоинт дважды в течение 10 секунд, второй вызов отклоняется с ошибкой rate_limit. Вы можете отключить или настроить это в конфиге.

Могу ли я тестировать без реальных вызовов API?

Да, используйте mock-сервер:

bash

swag2mcp-mock

Он генерирует фиктивные ответы на основе OpenAPI-схем.

Управление рабочей областью

Как сделать резервную копию конфигурации?

bash

swag2mcp export ~/backups/swag2mcp-2026-07-24.zip

Как перенести на другую машину?

bash

# На старой машине
swag2mcp export swag2mcp.zip

# Скопируйте ZIP, затем на новой машине
swag2mcp import --from-zip swag2mcp.zip

Как обновить файлы спецификаций?

bash

swag2mcp update

Это повторно проверяет конфиг, очищает кэш и заново скачивает все файлы спецификаций.

Как очистить дисковое пространство?

bash

swag2mcp clean

Удаляет кэшированные файлы спецификаций и сохранённые ответы API. Старые ответы (>48 ч) также автоматически очищаются при запуске MCP-сервера.

TUI

Что такое TUI и как им пользоваться?

TUI (Terminal User Interface) — это интерактивный обозреватель API. Запустите его командой swag2mcp run. У него три режима: Поиск (полнотекстовый), Обзор (древовидная навигация: Спецификация → Коллекция → Тег → Эндпоинт) и Auth (просмотр токенов).

Какие есть горячие клавиши?

Клавиша	Действие
`↑/↓`	Навигация
`Enter`	Выбор
`Esc`	Назад
`Tab`	Переключение режимов
`/`	Поиск
`N/P`	Следующая/предыдущая страница
`q`	Выход

Продвинутое

Могу ли я использовать прокси?

Да, настройте его в http_client.proxy:

yaml

http_client:
  proxy:
    url: "http://proxy.company.com:8080"
    username: "$(PROXY_USER)"
    password: "$(PROXY_PASS)"
    bypass:
      - "localhost"
      - "*.internal.com"

Могу ли я добавить свой метод аутентификации?

Да, реализуйте интерфейс Authenticator в internal/auth/ и зарегистрируйте его в парсере конфига. Подробнее в разделе Разработка.

Могу ли я добавить свой MCP-инструмент?

Да, добавьте метод в интерфейс Svc, реализуйте его в сервисном слое, добавьте обработчик и зарегистрируйте его. Подробнее в разделе Разработка.

В чём разница между `swag2mcp` и `swag2mcp-mock`?

swag2mcp — основной бинарный файл с командами CLI и MCP-сервером. swag2mcp-mock — отдельный бинарный файл, который запускает mock-серверы для тестирования без реальных вызовов API.

FAQ ​

Общие вопросы ​

Что такое swag2mcp и какую проблему он решает? ​

Чем он отличается от других инструментов для связи API с LLM? ​

Какие форматы спецификаций поддерживаются? ​

В чём разница между спецификацией и коллекцией? ​

Какие MCP-транспорты поддерживаются? ​

Могу ли я использовать swag2mcp с любой LLM? ​

Установка ​

Как установить swag2mcp? ​

Нужен ли мне установленный Go? ​

Как установить mock-сервер? ​

Начало работы ​

Как быстро начать? ​

Как подключить swag2mcp к моей IDE? ​

Конфигурация ​

Где находится файл конфигурации? ​

Как добавить API? ​

Как добавить коллекцию к существующей спецификации? ​

Как временно отключить спецификацию? ​

Можно ли фильтровать, какие спецификации загружаются? ​

Как использовать переменные окружения для секретов? ​

Аутентификация ​

Какие методы аутентификации поддерживаются? ​

Как передать токен? ​

Нужно ли вызывать auth перед invoke? ​

Почему инструмент auth не отображается? ​

Как обновляются токены OAuth2? ​

MCP-сервер ​

Как запустить MCP-сервер? ​

Как изменить порт? ​

Как защитить MCP HTTP-эндпоинт? ​

Что такое MCP-рукопожатие для HTTP-транспорта? ​

Использование ​

Как искать эндпоинты? ​

Как вызвать API? ​

Что происходит, если ответ слишком большой? ​

Как работает ограничитель запросов? ​

Могу ли я тестировать без реальных вызовов API? ​

Управление рабочей областью ​

Как сделать резервную копию конфигурации? ​

Как перенести на другую машину? ​

Как обновить файлы спецификаций? ​

Как очистить дисковое пространство? ​

TUI ​

Что такое TUI и как им пользоваться? ​

Какие есть горячие клавиши? ​

Продвинутое ​

Могу ли я использовать прокси? ​

Могу ли я добавить свой метод аутентификации? ​

Могу ли я добавить свой MCP-инструмент? ​

В чём разница между swag2mcp и swag2mcp-mock? ​

FAQ

Общие вопросы

Что такое swag2mcp и какую проблему он решает?

Чем он отличается от других инструментов для связи API с LLM?

Какие форматы спецификаций поддерживаются?

В чём разница между спецификацией и коллекцией?

Какие MCP-транспорты поддерживаются?

Могу ли я использовать swag2mcp с любой LLM?

Установка

Как установить swag2mcp?

Нужен ли мне установленный Go?

Как установить mock-сервер?

Начало работы

Как быстро начать?

Как подключить swag2mcp к моей IDE?

Конфигурация

Где находится файл конфигурации?

Как добавить API?

Как добавить коллекцию к существующей спецификации?

Как временно отключить спецификацию?

Можно ли фильтровать, какие спецификации загружаются?

Как использовать переменные окружения для секретов?

Аутентификация

Какие методы аутентификации поддерживаются?

Как передать токен?

Нужно ли вызывать auth перед invoke?

Почему инструмент auth не отображается?

Как обновляются токены OAuth2?

MCP-сервер

Как запустить MCP-сервер?

Как изменить порт?

Как защитить MCP HTTP-эндпоинт?

Что такое MCP-рукопожатие для HTTP-транспорта?

Использование

Как искать эндпоинты?

Как вызвать API?

Что происходит, если ответ слишком большой?

Как работает ограничитель запросов?

Могу ли я тестировать без реальных вызовов API?

Управление рабочей областью

Как сделать резервную копию конфигурации?

Как перенести на другую машину?

Как обновить файлы спецификаций?

Как очистить дисковое пространство?

TUI

Что такое TUI и как им пользоваться?

Какие есть горячие клавиши?

Продвинутое

Могу ли я использовать прокси?

Могу ли я добавить свой метод аутентификации?

Могу ли я добавить свой MCP-инструмент?

В чём разница между `swag2mcp` и `swag2mcp-mock`?