swag2mcp

Русский

English
Deutsch
Français
Español
中文
日本語
한국어

Русский

English
Deutsch
Français
Español
中文
日本語
한국어

Appearance

Решение проблем ​

Проблемы установки ​

swag2mcp: command not found ​

Бинарный файл не находится в PATH.

bash
# Проверьте, установлен ли Go
go version

# Узнайте, куда Go устанавливает бинарные файлы
go env GOPATH
# Обычно ~/go или ~/go/bin

# Добавьте в PATH (добавьте это в ~/.zshrc или ~/.bashrc)
export PATH=$PATH:$(go env GOPATH)/bin

# Или используйте полный путь
~/go/bin/swag2mcp --version

Если вы скачали бинарный файл с GitHub Releases, убедитесь, что он находится в директории, которая есть в PATH:

bash
# Переместите в /usr/local/bin (macOS/Linux)
sudo mv swag2mcp /usr/local/bin/

Permission denied ​

У бинарного файла нет прав на выполнение.

bash
# Для go install (исправить владельца)
sudo chown -R $(whoami) $(go env GOPATH)

# Для скачанного бинарного файла
chmod +x /путь/до/swag2mcp

Слишком старая версия Go ​

swag2mcp требует Go 1.26+.

bash
go version
# Если версия < 1.26, обновите Go:
# https://go.dev/dl/

Mock-сервер не найден ​

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

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

Проблемы конфигурации ​

Файл конфигурации не найден ​

swag2mcp не может найти swag2mcp.yaml.

bash
# Создайте новый конфиг
swag2mcp init

# Или укажите путь явно
swag2mcp mcp /путь/до/workspace
swag2mcp ls /путь/до/workspace

Частая причина: Вы запустили swag2mcp mcp из случайной директории, и он искал ~/.swag2mcp/ вместо рабочей области вашего проекта. Всегда передавайте путь явно.

Загружена не та рабочая область ​

swag2mcp загрузил другую рабочую область, чем ожидалось.

Порядок разрешения: Явный [path] → текущая директория (./) → ~/.swag2mcp/. Если вы запускаете swag2mcp mcp без пути из директории, в которой нет swag2mcp.yaml, он переключается на ~/.swag2mcp/.

Решение: Всегда передавайте путь к рабочей области: swag2mcp mcp /путь/до/вашей/workspace

Ошибка парсинга YAML ​

Файл конфигурации содержит неверный синтаксис YAML.

bash
# Проверьте конфиг
swag2mcp validate

# Частые ошибки:
# - Табуляция вместо пробелов (YAML требует пробелы)
# - Отсутствие отступов для вложенных полей
# - Неэкранированные строки со спецсимволами (: # & {)

Совет: Используйте YAML-линтер или редактор с поддержкой YAML для выявления синтаксических ошибок.

Ошибка валидации: "no specifications defined" ​

Файл конфигурации существует, но в нём нет спецификаций.

bash
# Добавьте спецификацию
swag2mcp add spec

# Или отредактируйте swag2mcp.yaml и добавьте хотя бы одну спецификацию

Ошибка валидации: "duplicate domain" ​

Две спецификации имеют одинаковое значение domain. Домены должны быть уникальными.

bash
# Список текущих спецификаций
swag2mcp ls

# Проверьте наличие дублирующихся доменов в swag2mcp.yaml

Ошибка валидации: "invalid spec location" ​

URL или путь к файлу location недоступен или не является файлом спецификации.

bash
# Проверьте, доступен ли URL
curl -I https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/dadjoke.yaml

# Проверьте, существует ли локальный файл
ls -la ./specs/my-api.yaml

# Убедитесь, что файл является валидным OpenAPI/Swagger/Postman
# (а не просто JSON или HTML-страницей)

Частая причина: Поле location указывает на сам API-эндпоинт (например, https://api.example.com/v1/users), а не на URL файла спецификации. В location должен быть указан путь к файлу OpenAPI/Swagger/Postman.

Проблемы MCP-сервера ​

Порт уже занят ​

Другой процесс использует порт.

bash
# Найдите процесс
lsof -i :8080

# Завершите его
kill <PID>

# Или используйте другой порт
swag2mcp mcp --transport sse --http-addr :9090

Connection refused ​

MCP-сервер не запущен или недоступен.

bash
# Убедитесь, что сервер запущен
swag2mcp mcp --transport sse --http-addr 127.0.0.1:8080

# В другом терминале проверьте health-эндпоинт
curl http://127.0.0.1:8080/health

# Если используется нестандартный путь
curl http://127.0.0.1:8080/custom-path/health

MCP-инструменты не отображаются в LLM-клиенте ​

LLM-клиент не видит никаких инструментов.

bash
# Проверьте, загружены ли спецификации
swag2mcp ls

# Проверьте, что спецификации не отключены
swag2mcp validate

# Проверьте логи сервера
swag2mcp mcp --logfile /tmp/swag2mcp.log
cat /tmp/swag2mcp.log

# Убедитесь, что путь к рабочей области в конфиге IDE правильный
# (должен быть абсолютным)

Частые причины:

  • Неправильный путь к рабочей области в конфиге IDE
  • У всех спецификаций стоит disable: true
  • Спецификации отфильтрованы через --tags
  • Файл конфигурации не существует по указанному пути

Ошибка рукопожатия MCP (HTTP-транспорт) ​

Для SSE и Streamable HTTP транспортов протокол MCP требует инициализации перед вызовом инструментов.

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

Убедитесь, что ваш LLM-клиент выполняет рукопожатие перед вызовом инструментов.

Health check возвращает 404 ​

Путь к health-эндпоинту может отличаться от пути MCP.

bash
# Health-эндпоинт по умолчанию
curl http://127.0.0.1:8080/health

# Если вы изменили путь MCP, health всё равно находится по адресу /health
# (не зависит от --http-path)

Инструмент auth недоступен ​

MCP-инструмент auth не отображается.

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

bash
# Включите инструмент auth
swag2mcp mcp --disable-llm-auth=false

Проблемы аутентификации ​

401 Unauthorized ​

API отклонил запрос из-за отсутствия или неверных учётных данных.

bash
# Проверьте, настроена ли аутентификация
swag2mcp info

# Проверьте конфиг
swag2mcp validate

# Проверьте, установлены ли переменные окружения
echo $MY_TOKEN

# Убедитесь, что токен не истёк (bearer-токены статичны)

Частые причины:

  • Токен отсутствует или пуст
  • Переменная окружения не установлена
  • Срок действия токена истёк (bearer-токены не обновляются автоматически)
  • Выбран неверный тип аутентификации

403 Forbidden ​

API отклонил запрос из-за недостаточных прав.

  • У токена может не быть необходимых разрешений
  • API-ключ может не иметь доступа к этому ресурсу
  • Проверьте документацию API для получения информации о необходимых правах

OAuth2 token endpoint недоступен ​

swag2mcp не может подключиться к URL получения токена OAuth2.

bash
# Проверьте token_url в вашем конфиге
# Убедитесь, что URL правильный и доступен
curl -X POST https://auth.example.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=test" \
  -d "client_secret=test"

# Проверьте сетевое подключение
# Проверьте настройки прокси, если вы за корпоративным прокси

Digest-аутентификация не работает ​

swag2mcp не может выполнить рукопожатие Digest-аутентификации.

  • Сервер должен вернуть заголовок WWW-Authenticate: Digest ... с ответом 401
  • Запрос кэшируется на 5 минут — если сервер меняет nonce, дождитесь истечения кэша
  • Проверьте правильность имени пользователя и пароля

Несовпадение HMAC-подписи ​

API отклонил запрос с HMAC-подписью.

  • Убедитесь, что api_key и secret_key правильные
  • Проверьте, что API использует подпись HMAC-SHA256 в стиле Binance
  • Некоторые биржи используют другие методы подписи — HMAC-аутентификация предназначена специально для API, совместимых с Binance

Ошибка скриптовой аутентификации ​

Внешний скрипт аутентификации не сработал.

bash
# Проверьте, существует ли скрипт
ls -la ~/.swag2mcp/auth_scripts/my-domain.sh

# Запустите скрипт вручную для проверки
sh ~/.swag2mcp/auth_scripts/my-domain.sh

# Проверьте формат вывода скрипта (должен быть JSON: {"token": "...", "expires_in": 3600})
# Проверьте, что скрипт выполняется в течение 30 секунд
# Проверьте, что у скрипта есть права на выполнение
chmod +x ~/.swag2mcp/auth_scripts/my-domain.sh

Проблемы поиска ​

Нет результатов поиска ​

Поиск не вернул ни одного эндпоинта.

bash
# Проверьте, загружены ли спецификации
swag2mcp ls

# Проверьте, что спецификации не отключены
swag2mcp validate

# Попробуйте более простой запрос
# Попробуйте поиск по методу: method:GET
# Попробуйте поиск по тегу: tag:pets

# Индекс перестраивается при каждом запуске MCP-сервера
# Если вы только что добавили спецификацию, перезапустите сервер

Поиск возвращает нерелевантные результаты ​

Запрос слишком широкий или неоднозначный.

  • Используйте фильтры по полям для сужения: method:GET +tag:pets
  • Используйте точные фразы: "найти питомца по статусу"
  • Используйте параметр limit для получения более точных результатов

Проблемы вызова API ​

invoke возвращает ошибку ​

Вызов API не удался.

bash
# Проверьте сообщение об ошибке — оно содержит HTTP-статус код
# Ошибки 4xx: проверьте параметры, аутентификацию или права доступа
# Ошибки 5xx: проблема на стороне API-сервера

# Всегда изучайте эндпоинт перед вызовом
inspect(endpointId: "...")

# Проверьте, что все обязательные параметры предоставлены
# Проверьте типы параметров (строка, число, boolean)

Ошибка ограничения запросов ​

LLM вызвал один и тот же эндпоинт слишком быстро.

У каждого эндпоинта есть период охлаждения 10 секунд. Подождите перед повторным вызовом или отключите ограничитель:

yaml
disable_ratelimiter: true

Слишком большой ответ (возвращён fileRef) ​

Ответ превысил max_response_size.

Это нормально. Используйте инструменты для работы с ответами:

1. response_outline(path) → понять структуру
2. response_compress(path, mode: "first_of_array") → получить образец
3. response_slice(path, jsonPath: "data.0") → получить конкретные данные

Или увеличьте лимит:

yaml
http_client:
  max_response_size: 4194304  # 4 МБ

Медленные ответы API ​

API отвечает слишком долго.

yaml
http_client:
  timeout: 120s  # Увеличьте с 30s по умолчанию

Проблемы рабочей области ​

swag2mcp init не работает: "directory is not empty" ​

Целевая директория уже содержит файлы.

bash
# Используйте --force для перезаписи
swag2mcp init --force

# Или используйте другую директорию
swag2mcp init ./new-workspace

swag2mcp update не работает ​

Один или несколько файлов спецификаций не удалось загрузить.

bash
# Проверьте сообщение об ошибке — какой URL не сработал
# Убедитесь, что URL доступен
curl -I <неудачный-url>

# Проверьте сетевое подключение
# Проверьте настройки прокси

Экспорт не создаёт ZIP ​

Аргумент [output] должен быть путём к файлу, заканчивающимся на .zip, а не директорией.

bash
# Правильно
swag2mcp export /путь/до/workspace /путь/до/backup.zip

# Неправильно (ZIP не будет создан)
swag2mcp export /путь/до/workspace /какая-то/директория

Ошибка импорта: "not a valid swag2mcp backup" ​

ZIP-файл не был создан командой swag2mcp export.

Импортировать можно только ZIP-архивы, созданные swag2mcp export. Архив имеет определённую внутреннюю структуру (swag2mcp.yaml, specs/, auth_scripts/).

Проблемы TUI ​

TUI отображается некорректно ​

Терминал слишком мал или не поддерживает требуемые функции.

  • Минимальный размер терминала: 80×24 символа
  • TUI использует Bubbletea и работает в большинстве современных терминалов
  • Попробуйте изменить размер окна терминала
  • Попробуйте другой эмулятор терминала
  • Windows PowerShell 5.1: TUI может отображать поля ввода на новой строке. Используйте Windows Terminal или терминал VS Code — они корректно работают с raw mode.

TUI показывает "no specs found" ​

В рабочей области нет настроенных спецификаций.

bash
# Проверьте спецификации
swag2mcp ls

# Добавьте спецификацию
swag2mcp add spec

Проблемы Mock-сервера ​

Mock-сервер не запускается ​

bash
# Проверьте, что в конфиге указано mock_enabled: true
# Проверьте, что для каждой коллекции установлен base_mock_url
# Проверьте, что порты не заняты
lsof -i :9090

# Проверьте логи mock-сервера
swag2mcp-mock

Mock-сервер возвращает пустые ответы ​

В файле спецификации могут отсутствовать схемы ответов.

  • Mock-сервер генерирует данные на основе схем ответов
  • Если схема не найдена, возвращается {}
  • Проверьте, что ваша OpenAPI-спецификация содержит responses с определённой schema

Сетевые проблемы ​

Ошибка подключения через прокси ​

swag2mcp не может подключиться через настроенный прокси.

bash
# Проверьте формат URL прокси (должен содержать схему: http://, https://, socks5://)
# Проверьте учётные данные прокси
# Проверьте список bypass — целевой адрес может быть в списке исключений
# Протестируйте прокси с помощью curl
curl -x http://proxy.company.com:8080 https://api.example.com

Ошибки TLS/SSL ​

Не удалось проверить сертификат.

  • Если вы используете самоподписанный сертификат для MCP-сервера, клиент должен ему доверять
  • Для mock-сервера с --tls самоподписанный сертификат генерируется автоматически
  • Для вызовов API swag2mcp использует системное хранилище сертификатов

Другие проблемы ​

Высокое использование диска ​

Директории кэша и ответов могут со временем разрастаться.

bash
# Очистите всё
swag2mcp clean

# Старые ответы (>48 ч) автоматически очищаются при запуске MCP-сервера
# Файлы кэша истекают случайным образом в течение 1-48 часов

"command not found" после go install ​

Директория установки Go не находится в PATH.

bash
# Узнайте, куда Go устанавливает бинарные файлы
go env GOPATH
# Добавьте в PATH
export PATH=$PATH:$(go env GOPATH)/bin

LLM неправильно использует инструменты ​

LLM может потребоваться более точная инструкция или навык форматирования.

  • Используйте llm_instruction в конфиге спецификации, чтобы описать, что делает API
  • Рассмотрите возможность использования навыка swag2mcp-format для единообразного форматирования вывода
  • Качество ответов LLM зависит от модели и полученных инструкций

Как сообщить об ошибке? ​

Откройте issue на GitHub с указанием:

  • Версии swag2mcp (swag2mcp --version)
  • Вашей операционной системы и архитектуры
  • Точной команды, которую вы выполнили
  • Полного сообщения об ошибке
  • Вашего файла конфигурации (без секретов)