Команды CLI

Обзор

CLI swag2mcp — это единая точка входа для всех операций: от инициализации рабочей области и управления спецификациями API до запуска MCP-сервера для интеграции с LLM. Он предоставляет 13 команд, охватывающих полный жизненный цикл работы со спецификациями OpenAPI/Swagger/Postman.

Что решает CLI

• Жизненный цикл рабочей области — создание (init), просмотр (info, ls), очистка (clean), обновление (update) и удаление (delete) рабочих областей и их содержимого
• Управление спецификациями и коллекциями — добавление (add), просмотр (ls) и удаление (delete) спецификаций API и их коллекций
• Режимы запуска — запуск MCP-сервера для доступа LLM к инструментам (mcp) или запуск интерактивного TUI-обозревателя (run)
• Диагностика — проверка конфигурации (validate), показ версии (version), отображение информации о runtime (info)
• Резервное копирование и восстановление — полный цикл рабочей области через ZIP (export, import)

Ключевые нюансы

• Разрешение пути — команды, принимающие [path], ожидают директорию рабочей области (не путь к файлу). Порядок разрешения: явный [path] → текущая директория (./) → ~/.swag2mcp/. CLI автоматически добавляет swag2mcp.yaml. Всегда передавайте явный путь при запуске в качестве сервиса или в конфиге IDE, чтобы избежать загрузки не той рабочей области.
• Спецификация vs Коллекция — спецификация представляет логический API-сервис (например, "Open-Meteo API"), а коллекция — это один файл OpenAPI/Swagger/Postman. Спецификация может иметь несколько коллекций.
• --version поддерживается как флаг (swag2mcp --version), так и подкоманда (swag2mcp version).
• add spec / add collection принимают YAML-ввод через --yaml (строка или - для stdin). Передача через файл или heredoc позволяет избежать проблем с экранированием специальных символов в оболочке.
• delete требует TTY (интерактивный терминал). Нет флага --force или --yes — всегда запрашивает выбор и подтверждение.
• mcp — основная команда для интеграции с LLM. Поддерживает три транспорта: stdio (по умолчанию), sse и streamable-http. Флаг --disable-llm-auth (по умолчанию: true) удаляет инструмент auth из списка MCP-инструментов, предотвращая просмотр или запрос токенов LLM. Аутентификация всё равно работает — токены получаются через стандартный механизм конфига, а не через LLM. Этот режим рекомендуется для продакшена (LLM никогда не имеет доступа к учётным данным). Для отладки или при использовании короткоживущих токенов установите --disable-llm-auth=false, чтобы LLM могла запрашивать свежие токены через инструмент auth.
• validate проверяет синтаксис YAML, структуру конфига, существование файлов спецификаций, доступность URL, формат спецификаций (OpenAPI/Swagger/Postman), настройки аутентификации и корректность HTTP-клиента. Он не тестирует эндпоинты аутентификации или доступность API-эндпоинтов.
• export / import обеспечивают полный цикл рабочей области — файл конфига, файлы спецификаций, кэш и скрипты аутентификации включаются в ZIP-архив.
• clean удаляет директории cache/ и responses/, но сохраняет specs/ и auth_scripts/. Старые ответы (>48 ч) также автоматически очищаются при запуске mcp.

Команды

Команда	Описание
init	Инициализация директории рабочей области с конфигом по умолчанию
add	Добавление спецификации или коллекции в конфиг
delete	Интерактивное удаление спецификации или коллекции
ls	Список всех спецификаций и их коллекций
run	Запуск интерактивного TUI-обозревателя API
validate	Проверка конфигурации и файлов спецификаций
clean	Очистка кэшированных спецификаций и ответов на вызовы
update	Повторная проверка, перекэширование и переиндексация всех спецификаций
mcp	Запуск MCP-сервера для доступа LLM к инструментам
version	Вывод версии swag2mcp
info	Показ подробной информации о конфигурации и runtime
import	Импорт файлов спецификаций или восстановление рабочей области из ZIP
export	Экспорт рабочей области в портативный ZIP-архив

Глобальные флаги

Флаг	Описание
--version	Показать версию (то же, что подкоманда version)
--help	Показать справку для любой команды