mcp-compressor

Обертка для MCP-сервера, предназначенная для сокращения количества токенов, потребляемых инструментами MCP.

• Репозиторий Github: https://github.com/atlassian-labs/mcp-compressor/

• Документация: https://atlassian-labs.github.io/mcp-compressor/

• Документация TypeScript (GH Pages): https://atlassian-labs.github.io/mcp-compressor/typescript/

• Код пакета TypeScript: https://github.com/atlassian-labs/mcp-compressor/blob/main/typescript/

• Блог: https://www.atlassian.com/blog/developer/mcp-compression-preventing-tool-bloat-in-ai-agents/

📋 Что нового

06.04.2026 — Реализация на TypeScript

Добавлена аналогичная реализация на TypeScript с соответствующими концепциями сжатия, поддержкой OAuth, API для выполнения внутри процесса и режимом CLI на TypeScript.

06.04.2026 — JSON-строки конфигурации MCP для одного сервера

COMMAND_OR_URL теперь может быть одной JSON-строкой конфигурации MCP. На данный момент mcpServers должен содержать ровно один сервер, и его ключ становится значением по умолчанию для --server-name, если оно не передано явно.

24.03.2026 — Режим CLI

--cli-mode — Преобразует любой обернутый MCP-сервер в локальный CLI. Генерирует исполняемый shell-скрипт (Unix) или .cmd-файл (Windows), чтобы агенты и пользователи могли взаимодействовать с бэкендом через привычные соглашения командной строки, а не через структурированные вызовы инструментов.

24.03.2026 — Вывод TOON

--toonify — Автоматически преобразует JSON-ответы от обернутых бэкенд-инструментов в формат TOON, компактную альтернативу JSON, читаемую как людьми, так и LLM.

Обзор

MCP Compressor — это прокси-сервер, который оборачивает существующие серверы Model Context Protocol (MCP) и сжимает описания их инструментов для значительного сокращения потребления токенов. Вместо того чтобы предоставлять языковым моделям все инструменты с полными схемами напрямую, он предлагает двухуровневый интерфейс:

1. get_tool_schema(tool_name) — Получение полной схемы для конкретного инструмента при необходимости

2. invoke_tool(tool_name, tool_input) — Выполнение инструмента с предоставленными аргументами

Такой подход радикально сокращает количество токенов, отправляемых в начальном контексте, сохраняя при этом полную функциональность.

Зачем?

MCP-серверы стремительно набирают популярность, но описания их инструментов потребляют значительное количество токенов в каждом запросе к LLM. Например:

• Официальный MCP-сервер GitHub предоставляет 94 инструмента, потребляющих 17 600 токенов

• Официальный MCP-сервер Atlassian потребляет ~10 000 токенов

При 30 000+ токенов только на описания инструментов затраты могут достигать 1-10 центов за запрос в зависимости от кэширования промптов. MCP Compressor решает эту проблему, заменяя десятки инструментов всего двумя инструментами-обертками, достигая 70-97% сокращения токенов при сохранении полной функциональности. Это позволяет:

• Добавлять множество MCP-серверов, не переполняя контекстные окна

• Значительно экономить на ценообразовании API, основанном на токенах

• Обеспечивать поддержку сотен или тысяч инструментов на нескольких серверах для вашего агента

Возможности

• Реализации на Python и TypeScript: Зрелая реализация на Python плюс аналогичный пакет TypeScript для потребителей Node.js

• Сокращение токенов: Сжатие описаний инструментов до 99% в зависимости от уровня сжатия и количества инструментов

• Несколько уровней сжатия: Выбор между low, medium, high или max

• Универсальная совместимость: Работает с любым MCP-сервером (stdio, HTTP, SSE)

• Преобразование вывода в TOON: Опциональное преобразование результатов JSON-инструментов бэкенда в TOON с помощью --toonify

• Режим CLI: Преобразование любого MCP-сервера в локальный CLI с помощью --cli-mode — генерирует shell-скрипт, позволяющий вам (или AI-агенту) взаимодействовать с бэкендом через привычный синтаксис командной строки

• Отсутствие потери функциональности: Все инструменты остаются полностью доступными через интерфейс обертки

• Простая интеграция: Готовое решение для замены существующих MCP-серверов

Python против TypeScript

Используйте реализацию на Python, если вам нужен наиболее зрелый набор функций сегодня. Используйте реализацию на TypeScript, если вам нужно использование, нативное для Node.js, встраивание внутри процесса или более тесная интеграция с экосистемой TypeScript.

Установка

Установите с помощью pip или uv:

pip install mcp-compressor
# or
uv pip install mcp-compressor

Быстрый старт

Базовое использование

Оберните любой MCP-сервер, предоставив его команду или URL:

# Wrap a stdio MCP server
uvx mcp-compressor uvx mcp-server-fetch

# Wrap a remote HTTP MCP server
uvx mcp-compressor https://example.com/server/mcp

# Wrap a remote SSE MCP server
uvx mcp-compressor https://example.com/server/sse

См. uvx mcp-compressor --help для получения подробной документации по доступным аргументам.

Уровни сжатия

Управляйте степенью сжатия с помощью флага --compression-level или -c:

# Low
mcp-compressor uvx mcp-server-fetch -c low

# Medium (default)
mcp-compressor uvx mcp-server-fetch -c medium

# High
mcp-compressor uvx mcp-server-fetch -c high

# Max
mcp-compressor uvx mcp-server-fetch -c max

Режим CLI

Если вы хотите, чтобы обернутый бэкенд вел себя как локальный инструмент командной строки, начните отсюда:

mcp-compressor --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp

Затем используйте сгенерированный CLI-скрипт:

atlassian --help

Вместо того чтобы предоставлять обернутый бэкенд как множество инструментов MCP, --cli-mode превращает бэкенд в локальный CLI с одним инструментом справки для обнаружения. Это особенно полезно, когда вы хотите, чтобы агент работал через интерфейс в стиле оболочки, или когда бэкенд-сервер уже имеет больше смысла как команды и флаги, чем как прямые вызовы инструментов MCP.

flowchart LR
    Client["MCP Client / Agent"] -->|discovers| HelpTool["<server_name>_help"]
    HelpTool -->|explains commands| GeneratedCLI["Generated local CLI script\n(e.g. atlassian)"]
    User["User or Agent"] -->|runs CLI subcommands| GeneratedCLI
    GeneratedCLI --> Bridge["Local HTTP bridge\n127.0.0.1:<port>"]
    Bridge --> Compressor["mcp-compressor\n--cli-mode"]
    Compressor --> Backend["Wrapped MCP server"]
    Backend --> Compressor
    Compressor --> Bridge
    Bridge --> GeneratedCLI

Почему режим CLI важен

• Один инструмент вместо многих: клиент MCP видит один инструмент <server_name>_help вместо набора инструментов обертки

• Естественный UX оболочки: бэкенд-инструменты становятся подкомандами CLI с флагами, производными от JSON-схемы

• Хорошо работает для агентов: агенты могут изучить справку, а затем многократно вызывать локальную команду, не неся в контексте всю поверхность инструментов MCP

• OAuth по-прежнему работает: если обернутый бэкенд требует OAuth, режим CLI выполняет этот поток подключения перед генерацией локального CLI

• TOON по умолчанию: --toonify автоматически включается в режиме CLI для компактного, читаемого вывода

Быстрый старт режима CLI

# Wrap a remote MCP server as a local CLI
uvx mcp-compressor --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp

# Or pass a single MCP config JSON string
uvx mcp-compressor --cli-mode '{"mcpServers": {"atlassian": {"url": "https://mcp.atlassian.com/v1/mcp"}}}'

Когда запускается режим CLI, он:

1. Подключается к обернутому бэкенд-серверу, включая OAuth, если требуется

2. Запускает локальный HTTP-мост на 127.0.0.1:<port>

3. Генерирует исполняемый скрипт — в Unix он обычно записывается в ~/.local/bin/<name>, если доступен в PATH, в противном случае в текущую директорию; в Windows он записывает загрузчик .cmd в подходящую директорию в PATH

4. Предоставляет один инструмент MCP с именем <server_name>_help, чтобы клиент мог обнаружить сгенерированный CLI и его подкоманды

Пример использования после запуска:

# Top-level help — lists all subcommands
atlassian --help

# Per-tool help — shows flags derived from the backend tool schema
atlassian get-confluence-page --help

# Invoke a tool using ordinary CLI flags
atlassian get-confluence-page --cloud-id abc123 --page-id 456

# Escape hatch for complex inputs
atlassian create-jira-issue --json '{"cloudId":"abc","projectKey":"PROJ","summary":"Bug"}'

Имена подкоманд CLI — это преобразование snake_case → kebab-case имен бэкенд-инструментов (например, getConfluencePage → get-confluence-page). Сгенерированный скрипт работает только пока запущен mcp-compressor --cli-mode. Используйте --cli-port, если хотите закрепить локальный мост за определенным портом.

Дополнительные параметры

Серверы Stdio

# Set working directory
mcp-compressor uvx mcp-server-fetch --cwd /path/to/dir

# Pass environment variables (supports environment variable expansion)
mcp-compressor uvx mcp-server-fetch \
  -e API_KEY=${MY_API_KEY} \
  -e DEBUG=true

Удаленные серверы (HTTP/SSE)

# Add custom headers
mcp-compressor https://api.example.com/mcp \
  -H "Authorization=Bearer ${TOKEN}" \
  -H "X-Custom-Header=value"

# Set timeout (default: 10 seconds)
mcp-compressor https://api.example.com/mcp \
  --timeout 30

Пользовательские имена серверов

При запуске нескольких MCP-серверов через mcp-compressor вы можете добавить пользовательские префиксы к именам инструментов обертки, чтобы избежать конфликтов:

# Without server name - tools will be: get_tool_schema, invoke_tool
mcp-compressor uvx mcp-server-fetch

# With server name - tools will be: github_get_tool_schema, github_invoke_tool
mcp-compressor https://api.githubcopilot.com/mcp/ --server-name github

# Special characters are automatically sanitized
mcp-compressor uvx mcp-server-fetch --server-name "My Server!"
  # Results in: my_server__get_tool_schema, my_server__invoke_tool

Преобразование вывода в TOON

Используйте --toonify для автоматического преобразования результатов JSON-инструментов бэкенда в формат TOON.

# Convert JSON backend tool results to TOON
mcp-compressor https://api.example.com/mcp --toonify

Когда --toonify включен:

• Успешные результаты бэкенд-инструментов, возвращаемые через прямые вызовы инструментов, преобразуются в TOON, если они являются JSON-объектами или массивами

• Успешные результаты бэкенд-инструментов, возвращаемые через invoke_tool(...), также преобразуются в TOON

• Ответы обертки от get_tool_schema(...) и list_tools(...) никогда не преобразуются в TOON

• Руководящий или ошибочный текст, сгенерированный оберткой от invoke_tool(...), никогда не преобразуется в TOON

• Текст, не являющийся JSON, возвращается без изменений

Режим CLI

Режим CLI описан в специальном разделе Режим CLI выше. Краткая версия: используйте --cli-mode, дайте серверу имя и взаимодействуйте со сгенерированным локальным скриптом, пока запущен mcp-compressor.

mcp-compressor https://mcp.atlassian.com/v1/mcp --server-name atlassian --cli-mode --cli-port 8765

Логирование

# Set log level
mcp-compressor uvx mcp-server-fetch --log-level debug
mcp-compressor uvx mcp-server-fetch -l warning

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

MCP Compressor действует как прозрачный прокси между вашим LLM-клиентом и базовым MCP-сервером:

flowchart TB
    subgraph github["GitHub MCP"]
        g1["create_pr"]
        g2["get_me"]
        g3["list_repos"]
        g4["get_issue"]
        g5["..."]
        g6["(+87 more tools)"]
    end

    subgraph proxy["MCP Compressor"]
        t1["get_tool_schema"]
        t2["invoke_tool"]
    end

    subgraph client["MCP Client"]
    end

    g1 <--> proxy
    g2 <--> proxy
    g3 <--> proxy
    g4 <--> proxy
    g6 <--> proxy
    t1 <--> client
    t2 <--> client

Вместо того чтобы видеть все инструменты с полными схемами (которые часто составляют тысячи токенов), LLM видит только:

Available tools:
<tool>search_web(query, max_results): Search the web for information</tool>
<tool>get_weather(location, units): Get current weather for a location</tool>
<tool>send_email(to, subject, body): Send an email message</tool>

Когда LLM нужно использовать инструмент, она сначала вызывает get_tool_schema(tool_name) для получения полной схемы, а затем invoke_tool(tool_name, tool_input) для его выполнения.

Если --toonify включен, успешные результаты бэкенд-инструментов преобразуются из JSON в TOON перед возвратом клиенту. Сами ответы помощника обертки не переформатируются.

В режиме CLI (--cli-mode) компрессор предоставляет один инструмент <server_name>_help вместо обычных оберток. Все фактическое взаимодействие с инструментами происходит через сгенерированный shell-скрипт через локальный HTTP-мост.

sequenceDiagram
    participant Client as MCP Client
    participant Compressor as MCP Compressor
    participant Server as GitHub MCP<br/>(91 tools)

    Client->>Compressor: list_tools()
    Compressor->>Server: list_tools()
    Server-->>Compressor: create_pr, get_me, list_repos, ...
    Compressor-->>Client: get_tool_schema, invoke_tool

    Client->>Compressor: get_tool_schema("create_pr")
    Compressor-->>Client: create_pr description & schema

    Client->>Compressor: invoke_tool("create_pr", {...})
    Compressor->>Server: create_pr({...})
    Server-->>Compressor: result
    Compressor-->>Client: result

Подробности уровней сжатия

Лучший выбор уровня сжатия будет зависеть от ряда факторов, включая:

1. Количество инструментов на MCP-сервере — чем больше инструментов, тем больше сжатия.

2. Как часто ожидается использование инструментов — если инструменты со сжатого сервера используются редко, сжимайте их сильнее, чтобы не тратить токены впустую.

3. Насколько необычны или сложны инструменты — более простые инструменты можно сжимать сильнее с небольшими потерями. Рассмотрим простой инструмент bash с одним входным аргументом command. Любая современная LLM точно поймет, как его использовать, увидев только имя инструмента и имя аргумента, поэтому, если внутри инструмента нет неожиданной внутренней логики, можно использовать агрессивное сжатие с небольшими минусами.

Конфигурация с помощью JSON-файла MCP

Вы также можете передать одну JSON-строку конфигурации MCP напрямую в качестве COMMAND_OR_URL в CLI. Это особенно полезно для удаленных серверов, когда вы хотите, чтобы сама конфигурация содержала URL, заголовки, транспорт или детали команды stdio.

На данный момент прямой ввод JSON-строки поддерживает ровно одну запись сервера в mcpServers.

Чтобы настроить mcp-compressor в JSON-файле конфигурации MCP, используйте следующий шаблон:

{
  "mcpServers": {
    "compressed-github": {
      "command": "mcp-compressor",
      "args": [
        "https://api.githubcopilot.com/mcp/",
        "--header",
        "Authorization=Bearer ${GH_PAT}",
        "--server-name",
        "github"
      ],
    },
    "compressed-fetch": {
      "command": "mcp-compressor",
      "args": [
        "uvx",
        "mcp-server-fetch",
        "--server-name",
        "fetch"
      ],
    }
  }
}

Эта конфигурация создаст инструменты с именами github_get_tool_schema, github_invoke_tool, fetch_get_tool_schema и fetch_invoke_tool, предотвращая конфликты имен при совместном использовании нескольких сжатых серверов.