mcp

Назначение

Запустить MCP-сервер (Model Context Protocol) — основной режим для интеграции с LLM. Это то, что вы запускаете, чтобы дать AI-агенту (Claude, Cursor, OpenCode и др.) доступ к вашим API через 16 MCP-инструментов.

Когда использовать

• Вы хотите подключить LLM-агента к вашим API
• Вы настраиваете IDE (VS Code, Cursor, JetBrains) или десктопное приложение (Claude Desktop)
• Вам нужно предоставить доступ к вашим API через протокол MCP
• Вы тестируете MCP-сервер перед интеграцией

Синтаксис

swag2mcp mcp [path] [flags]

Аргументы

Аргумент	Позиция	Обязательно	Описание
path	1	Нет	Директория рабочей области. Если не указан, разрешается по правилам разрешения пути.

Флаги

Флаг	Сокращение	Тип	По умолчанию	Описание
--transport		string	"stdio"	MCP-транспорт: stdio, sse, streamable-http
--http-addr		string	":8080"	Адрес HTTP-сервера (для sse и streamable-http)
--http-path		string	"/mcp"	HTTP-путь для MCP-обработчика
--auth-token		string	""	Bearer-токен для аутентификации HTTP-транспорта
--logfile	-f	string	""	Путь к файлу лога. Если не указан, логи пишутся в stderr.
--disable-llm-auth		bool	true	Удалить инструмент auth из списка MCP-инструментов
--dump-dir		string	""	Директория для сохранения HTTP-запросов (отладка)
--tags	-t	string	""	Фильтр спецификаций по тегам (через запятую)

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

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

Используется, когда MCP-сервер запускается как подпроцесс LLM-клиентом (IDE, Claude Desktop и т.д.). Сервер общается через стандартный ввод/вывод.

swag2mcp mcp

SSE транспорт

Server-Sent Events транспорт для HTTP-взаимодействия. Требует последовательности рукопожатия MCP.

swag2mcp mcp --transport sse --http-addr :8080

Streamable HTTP транспорт

Современный HTTP-транспорт с поддержкой потоковых ответов.

swag2mcp mcp --transport streamable-http --http-addr 0.0.0.0:8080

С аутентификацией

Защитите HTTP-эндпоинт с помощью bearer-токена:

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

С фильтрацией по тегам

Загружать только спецификации с определёнными тегами:

swag2mcp mcp --tags=public

С включённым инструментом auth (режим отладки)

Разрешить LLM запрашивать свежие токены через инструмент auth:

swag2mcp mcp --disable-llm-auth=false

С директорией для дампов запросов

Сохранять все HTTP-запросы для отладки:

swag2mcp mcp --dump-dir ./dumps

MCP HTTP-транспорт — протокол рукопожатия

При использовании sse или streamable-http протокол MCP требует определённого рукопожатия. Вызовы инструментов будут завершаться ошибкой до инициализации:

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

Health check

Работает без инициализации:

curl http://localhost:8080/health
# → {"status":"ok","version":"v1.2.0"}

Примеры конфигурации IDE

VS Code (.vscode/settings.json или глобальные настройки)

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

Cursor / Windsurf (~/.cursor/mcp.json или проект .cursor/mcp.json)

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

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS)

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

JetBrains IDE (Настройки → Инструменты → MCP)

• Имя: swag2mcp
• Команда: swag2mcp
• Аргументы: mcp /абсолютный/путь/до/.swag2mcp

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

Вывод

При успешном запуске сервер выводит:

MCP server listening on http://127.0.0.1:8080/mcp

Нюансы

• Нет автоинициализации: Если файл конфигурации не существует, mcp возвращает ошибку: "configuration not found at <path>". Сначала выполните init.
• --disable-llm-auth (по умолчанию: true): Когда включён, инструмент auth полностью удаляется из списка MCP-инструментов. LLM не может видеть или запрашивать токены. Аутентификация всё равно работает — токены получаются через стандартный механизм конфига, а не через LLM. Этот режим рекомендуется для продакшена. Для отладки или при использовании короткоживущих токенов установите --disable-llm-auth=false, чтобы LLM могла запрашивать свежие токены через инструмент auth.
• Резервный YAML-конфиг: Если флаг CLI не установлен явно, значение берётся из раздела mcp в swag2mcp.yaml (если он присутствует). Это позволяет настроить сервер в файле конфигурации вместо передачи флагов каждый раз.
• Очистка ответов: При запуске ответы старше 48 часов автоматически удаляются из директории responses/.
• Предупреждение о разрешении пути: Когда [path] не указан, mcp сначала ищет swag2mcp.yaml в текущей директории, затем переключается на ~/.swag2mcp/. Если вы запускаете команду из неправильной директории, может загрузиться не та рабочая область. Всегда указывайте [path] явно при запуске в качестве сервиса или в конфиге IDE.