Рабочая область

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

Структура

~/.swag2mcp/                          # Корень рабочей области (по умолчанию)
├── swag2mcp.yaml                     # Файл конфигурации
├── cache/                            # Кэшированные удалённые файлы спецификаций
│   ├── a1b2c3d4e5f6...spec          # Содержимое кэшированной спецификации
│   └── a1b2c3d4e5f6...meta          # Метаданные кэша (JSON)
├── specs/                            # Локальные файлы спецификаций
│   └── my-api.yaml
├── responses/                        # Сохранённые ответы API (большие ответы)
│   ├── meteo-get-forecast-abc123.json
│   └── response-fragment-def456.json
└── auth_scripts/                     # Скрипты аутентификации
    ├── meteo.sh                      # Unix shell-скрипт
    └── meteo.bat                     # Windows batch-скрипт

Путь по умолчанию

• Linux/macOS: ~/.swag2mcp/
• Windows: %USERPROFILE%\.swag2mcp\

Пользовательский путь

swag2mcp mcp /путь/до/workspace
swag2mcp mcp ./my-workspace

Директории

cache/

Хранит скачанные удалённые файлы спецификаций. Каждый файл кэшируется с SHA-256 хешем его URL в качестве имени файла:

• {hash}.spec — содержимое кэшированного файла спецификации
• {hash}.meta — JSON-метаданные (исходный URL, время кэширования, TTL)

Каждый кэшированный файл имеет случайный TTL от 1 часа до 48 часов. Кэш автоматически проверяется при каждом запуске — если существует валидная (непросроченная) запись, она используется повторно без загрузки.

Команды:

• swag2mcp update — очищает кэш и перезагружает все спецификации
• swag2mcp clean — очищает кэш и ответы

specs/

Хранит локальные файлы спецификаций, на которые коллекции ссылаются через location: specs/{name}. Файлы здесь используются напрямую без кэширования.

Эта директория заполняется:

• swag2mcp import <source> <name> — скачивает удалённую спецификацию и сохраняет её сюда
• swag2mcp export — копирует спецификации сюда в экспортный ZIP
• Вручную — вы можете скопировать файлы спецификаций сюда самостоятельно

responses/

Хранит ответы API, превышающие лимит max_response_size (по умолчанию 1 МБ). Когда LLM вызывает эндпоинт и ответ слишком велик, swag2mcp сохраняет его сюда и возвращает ссылку на файл.

Соглашение об именовании: {domain}-{method}-{path_with_underscores}-{6симв_hex}.json

Старые ответы автоматически очищаются через 48 часов при запуске MCP-сервера.

auth_scripts/

Хранит скрипты аутентификации для типа script. Каждый скрипт назван по домену спецификации.

Соглашение об именовании

Платформа	Имя файла	Пример
Unix (Linux, macOS)	{domain}.sh	meteo.sh
Windows	{domain}.bat	meteo.bat

Домен не должен содержать символы / или \.

Как работают скрипты

1. swag2mcp запускает скрипт с таймаутом 30 секунд
2. Скрипт должен вывести валидный JSON в stdout
3. swag2mcp разбирает JSON и использует токен для API-запросов

Ожидаемый формат вывода

{
  "token": "ваш-токен-здесь",
  "expires_in": 3600
}

Поле	Тип	Обязательно	Описание
token	string	✅	Токен аутентификации
access_token	string	❌	Альтернатива token (проверяется в первую очередь)
token_type	string	❌	Тип токена (например, "Bearer")
expires_in	number	❌	Время жизни токена в секундах (по умолчанию: 3600)

Выполнение

Платформа	Команда
Unix	sh {domain}.sh
Windows	cmd /c {domain}.bat

Кэширование токена

Токен кэшируется в памяти до истечения срока действия. При каждом вызове API swag2mcp сначала проверяет кэш — скрипт выполняется только когда кэшированный токен истёк.

Создание заглушки

Когда вы настраиваете auth: { type: script, config: { domain: "jokes" } }, swag2mcp автоматически создаёт скрипт-заглушку:

Unix (auth_scripts/jokes.sh):

#!/bin/sh
echo '{"token": "ваш-токен-здесь", "expires_in": 3600}'

Windows (auth_scripts/jokes.bat):

@echo off
echo {"token": "ваш-токен-здесь", "expires_in": 3600}

Замените токен-заполнитель на вашу реальную логику аутентификации.

Очистка осиротевших скриптов

Когда вы удаляете спецификацию, её скрипт аутентификации становится осиротевшим. swag2mcp автоматически удаляет осиротевшие скрипты при:

• swag2mcp update
• swag2mcp clean

Команды

update

swag2mcp update [path]

Проверяет конфиг, очищает кэш и ответы, затем перезагружает все файлы спецификаций. Также проверяет наличие скриптов аутентификации и удаляет осиротевшие скрипты.

Используйте эту команду после:

• Добавления или удаления коллекций
• Изменения location коллекций
• Редактирования файлов спецификаций, требующих перекэширования

clean

swag2mcp clean [path]

Удаляет всё содержимое cache/ и responses/, а также осиротевшие скрипты аутентификации. НЕ перекэширует спецификации — для этого используйте update.

validate

swag2mcp validate [path]

Проверяет конфиг, включая все location коллекций. Подробнее: CLI: validate.

Экспорт и импорт

# Экспорт рабочей области в ZIP (имя по умолчанию: swag2mcp-backup-{date}.zip)
swag2mcp export

# Экспорт по конкретному пути
swag2mcp export /путь/до/workspace /путь/до/backup.zip

# Экспорт только определённых спецификаций
swag2mcp export --spec meteo

# Восстановление из резервной копии
swag2mcp import --from-zip /путь/до/backup.zip
swag2mcp import /путь/до/workspace /путь/до/backup.zip

Экспорт включает: swag2mcp.yaml, specs/, auth_scripts/. Кэш и ответы исключены (это локальные данные).

.gitignore

Если ваша рабочая область находится внутри Git-репозитория, добавьте эти записи в .gitignore:

# swag2mcp — только локальные данные
.swag2mcp/cache/
.swag2mcp/responses/

Директории cache/ и responses/ содержат локальные данные, специфичные для машины, которые не следует коммитить. Всё остальное (swag2mcp.yaml, specs/, auth_scripts/) должно быть в репозитории, чтобы конфигурация была общей для всей команды.