Управление размером ответов

Обзор

Ответы API могут быть очень большими — иногда слишком большими, чтобы поместиться в контекстном окне LLM. swag2mcp автоматически управляет размерами ответов, сохраняя слишком большие ответы на диск и предоставляя инструменты для их исследования.

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

1. Вы вызываете invoke — swag2mcp выполняет API-запрос
2. Если ответ маленький (в пределах лимита) — он возвращается LLM напрямую
3. Если ответ слишком большой (превышает лимит) — он сохраняется в {workspace}/responses/ как JSON-файл. LLM получает ссылку на файл вместо полного ответа

Пример: маленький ответ (напрямую)

{
  "statusCode": 200,
  "body": {
    "id": 1,
    "name": "Rex",
    "status": "available"
  }
}

Пример: большой ответ (ссылка на файл)

{
  "statusCode": 200,
  "fileRef": {
    "path": "/Users/user/.swag2mcp/responses/response_a1b2c3d4.json",
    "size": 1572864,
    "sizeHint": "1.5 MB",
    "maxSizeHint": "1 MB",
    "message": "Ответ превышает лимит 1 МБ и был сохранён на диск.",
    "openCmd": "open /Users/user/.swag2mcp/responses/response_a1b2c3d4.json"
  }
}

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

http_client:
  max_response_size: 1048576  # 1 МБ в байтах

max_response_size

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

Работа с большими ответами

Когда invoke возвращает fileRef, используйте эти три инструмента для исследования данных:

1. response_outline — понять структуру

Получить структурную сводку ответа: ключи, типы, длины массивов и подсказки по навигации.

→ response_outline(path: "/path/to/file.json")
← {
    "type": "object",
    "size": 1572864,
    "keys": ["data", "meta"],
    "itemCount": 500,
    "compressionHints": [
      "response_compress(path, 'first_of_array', 'data')",
      "response_compress(path, 'sample_array', 'data', arrayHead=3, arrayTail=2)"
    ]
  }

2. response_compress — получить уменьшенную версию

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

Режим	Описание	Для чего подходит
first_of_array	Оставить только первый элемент массива	Когда все элементы имеют одинаковую структуру
sample_array	Оставить начало (3) и конец (2) массива	Когда нужно увидеть диапазон значений
truncate_strings	Укоротить каждую строку до N символов	Когда строки очень длинные
keys_only	Заменить значения на имена типов	Когда нужна только структура
select_keys	Оставить только указанные ключи	Когда нужны конкретные поля

→ response_compress(path: "/path/to/file.json", mode: "first_of_array", jsonPath: "data")
← {
    "body": [{ "id": 1, "name": "Rex" }],
    "hint": "Массив сжат с 500 до 1 элемента с использованием режима first_of_array"
  }

3. response_slice — извлечь конкретный фрагмент

Получить конкретный элемент или значение по JSON-пути или диапазону строк.

→ response_slice(path: "/path/to/file.json", jsonPath: "data.0")
← {
    "slice": {
      "value": { "id": 1, "name": "Rex" },
      "jsonPath": "data.0",
      "nextPath": "data.1",
      "prevPath": null
    }
  }

Полный рабочий процесс

1. invoke(endpoint) → fileRef (ответ 1.5 МБ)
2. response_outline(path) → структура: { data: Array(500) }
3. response_compress(path, mode: "first_of_array", jsonPath: "data") → первый элемент
4. response_slice(path, jsonPath: "data.0") → полные детали первого элемента
5. response_slice(path, jsonPath: "data.1") → второй элемент

Автоматическая очистка

При запуске MCP-сервера (swag2mcp mcp) файлы ответов старше 48 часов автоматически удаляются. Вы также можете очистить их вручную:

swag2mcp clean

Важные замечания

• Лимит в байтах — 1048576 = 1 МБ, 2097152 = 2 МБ и т.д.
• Ссылки на файлы включают команду открытия — на macOS это open, на Linux — xdg-open
• Файлы ответов именуются со случайными суффиксами — нет конфликтов между параллельными вызовами
• Директория responses создаётся автоматически — ручная настройка не требуется