HTTP-клиент

swag2mcp использует настраиваемый HTTP-клиент для всех вызовов API. Эти настройки определяются глобально и могут быть переопределены на уровне спецификации и коллекции.

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

http_client:
  timeout: 30s
  max_response_size: 1048576
  user_agent: "swag2mcp-global/1.0"
  follow_redirects: true
  max_redirects: 10
  random: false
  proxy:
    url: ""
    username: ""
    password: ""
    bypass: []
  headers:
    "Accept": "application/json"
  cookies:
    - name: "session"
      value: "abc123"
      domain: ".example.com"
      path: "/"

Таймаут

Управляет тем, как долго swag2mcp ждёт ответа от API, прежде чем отказаться от запроса.

• Тип: duration (Go-формат: 30s, 60s, 2m)
• По умолчанию: 30s
• Диапазон: от 1 секунды до 5 минут
• Эффект: Если API не отвечает в течение этого времени, запрос завершается ошибкой таймаута.
• Когда увеличивать: Медленные API, большие полезные нагрузки, ненадёжные сети.
• Когда уменьшать: Внутренние API, health checks, сценарии быстрого отказа.

http_client:
  timeout: 60s

Максимальный размер ответа

Ограничивает размер ответа, прежде чем swag2mcp сохранит его на диск вместо возврата LLM.

• Тип: int (байты)
• По умолчанию: 1048576 (1 МБ)
• Диапазон: от 256 до 10 485 760 байт (10 МБ)
• Эффект: Когда ответ превышает этот лимит, он сохраняется в {workspace}/responses/ как JSON-файл. LLM получает ссылку на файл и может исследовать его с помощью инструментов response_outline, response_compress и response_slice.
• Когда увеличивать: API, возвращающие большие наборы данных (отчёты, логи, аналитика).
• Когда уменьшать: Ограниченный контекст LLM или когда вы предпочитаете файловый доступ для всех ответов.

http_client:
  max_response_size: 4194304  # 4 МБ

User-Agent

Заголовок User-Agent, отправляемый с каждым запросом. Некоторые API требуют определённый user-agent или блокируют известные ботовые user-agent'ы.

• Тип: string
• По умолчанию: "swag2mcp-global/1.0"
• Эффект: Идентифицирует ваше приложение для сервера API.
• Когда изменять: API требует определённый user-agent, или вы хотите идентифицировать своё приложение для аналитики.

http_client:
  user_agent: "MyApp/1.0"

Следовать перенаправлениям

Управляет тем, будет ли swag2mcp автоматически следовать HTTP-перенаправлениям (коды статуса 3xx).

• Тип: bool
• По умолчанию: true
• Эффект: Если true, swag2mcp следует перенаправлениям до max_redirects раз. Если false, ответ с перенаправлением возвращается как есть.
• Когда отключать: API, которые перенаправляют по циклу, эндпоинты, чувствительные к безопасности, где вы хотите вручную проверять цели перенаправления.

http_client:
  follow_redirects: false

Максимум перенаправлений

Ограничивает количество перенаправлений, которым следует swag2mcp, прежде чем остановиться.

• Тип: int
• По умолчанию: 10
• Диапазон: от 0 до 50
• Эффект: Если API перенаправляет больше раз, чем этот лимит, запрос завершается ошибкой.
• Когда изменять: API с длинными цепочками перенаправлений или уменьшить для более быстрого отказа при циклах перенаправлений.

http_client:
  max_redirects: 5

Рандомизатор

Добавляет случайные браузероподобные заголовки к каждому запросу, чтобы избежать fingerprinting и блокировок.

• Тип: bool
• По умолчанию: false
• Эффект: Если true, swag2mcp генерирует случайные заголовки для каждого запроса: User-Agent (из пула реальных браузерных строк), Accept, Accept-Language, Accept-Encoding, Referer, Sec-Ch-Ua, Sec-Ch-Ua-Platform, Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest. Это переопределяет настройку user_agent.
• Когда включать: API, которые блокируют запросы на основе User-Agent или шаблонов заголовков, сценарии парсинга.

http_client:
  random: true

Прокси

Прокси-сервер выступает в роли посредника между swag2mcp и целевым API. Весь HTTP-трафик направляется через него.

Когда может понадобиться прокси:

• Корпоративная сеть — весь исходящий трафик должен проходить через корпоративный прокси
• Географические ограничения — некоторые API ограничены по региону, прокси в нужном регионе обходит это
• Статический IP — API, требующие белый список IP
• Анонимность — скрыть исходный IP от целевого API

URL прокси

• Тип: string
• По умолчанию: "" (без прокси)
• Поддерживаемые схемы: http, https, socks5, socks5h
• Поддерживает $(VAR): ✅ разрешается во время выполнения

Схема	Описание	Сценарий использования
http	HTTP-прокси для HTTP-трафика	Корпоративные прокси, базовое проксирование
https	HTTPS-прокси (CONNECT-туннель)	Безопасные корпоративные прокси
socks5	SOCKS5-прокси (DNS разрешается локально)	Общего назначения, любой протокол
socks5h	SOCKS5-прокси (DNS разрешается на прокси)	Когда у прокси лучшее DNS-разрешение

Аутентификация прокси

Если прокси требует аутентификации, укажите username и password:

• Поддерживает $(VAR): ✅ разрешается во время выполнения для всех трёх полей (url, username, password)

http_client:
  proxy:
    url: "http://proxy.example.com:8080"
    username: "proxyuser"
    password: "$(PROXY_PASSWORD)"

Исключения прокси

Список доменов, которые не должны проходить через прокси. Полезно для внутренних сервисов, localhost или API, доступных только напрямую.

http_client:
  proxy:
    url: "http://proxy.example.com:8080"
    bypass:
      - "localhost"
      - "127.0.0.1"
      - "*.internal.company.com"
      - "api.local"

Исключения поддерживают шаблоны с подстановочными знаками (*.example.com соответствует любому поддомену).

Заголовки

Пользовательские HTTP-заголовки, добавляемые к каждому запросу. Заголовки объединяются по уровням каскада:

Глобальные заголовки → Заголовки спецификации (объединяются) → Заголовки коллекции (объединяются)

Заголовки коллекции переопределяют заголовки спецификации, которые переопределяют глобальные заголовки для одного и того же ключа.

http_client:
  headers:
    "Accept": "application/json"
    "Accept-Language": "en-US"

Значения заголовков поддерживают разрешение $(ENV_VAR).

Куки

Куки, отправляемые с каждым запросом. Куки объединяются по уровням каскада (нижний уровень переопределяет глобальный для того же имени куки).

http_client:
  cookies:
    - name: "session"
      value: "abc123"
      domain: ".example.com"
      path: "/"
      secure: false
      http_only: false

Поля куки

Поле	Обязательно	Описание
name	Да	Имя куки
value	Да	Значение куки (поддерживает разрешение $(ENV_VAR))
domain	Нет	Область действия домена (например, .example.com)
path	Нет	Область действия пути (например, /)
secure	Нет	Отправлять только через HTTPS
http_only	Нет	Недоступно через JavaScript

Пользовательские заголовки на уровне спецификации

specs:
  - domain: jokes
    llm_title: Dad Joke API
    base_url: https://icanhazdadjoke.com
    http_client:
      headers:
        "Accept": "application/json"
    collections:
      - llm_title: Jokes
        location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/dadjoke.yaml

Куки на уровне спецификации

specs:
  - domain: example
    llm_title: Example API
    base_url: https://api.example.com
    http_client:
      cookies:
        - name: "session"
          value: "abc123"
        - name: "csrf"
          value: "$(CSRF_TOKEN)"
    collections:
      - llm_title: Default
        location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/dadjoke.yaml

Каскад

Настройки HTTP-клиента каскадируются от глобального уровня к спецификации и коллекции. Все настройки могут быть переопределены на каждом уровне:

Global (http_client)
    ↓ переопределяет (все настройки)
Spec (specs[].http_client)
    ↓ переопределяет (все настройки)
Collection (specs[].collections[].http_client)

Все настройки HTTP-клиента (таймаут, прокси, user-agent, перенаправления, размер ответа, рандомизатор, заголовки, куки) могут быть переопределены на уровнях спецификации и коллекции.

Подробнее: Каскад конфигурации.