Refract

Сокращает до 98% токенов, которые ваши AI-агенты тратят на использование инструментов MCP — без потерь.

Что именно меняется

Меньше отправленных токенов = ниже счета за API и быстрее ответы. И ничего не теряется. Каждая проверка подтверждает, что инструменты остаются на 100% работоспособными после сжатия.

Воспроизведите эти числа самостоятельно — каждый входной файл статический фикстур в репозитории, токены подсчитаны с помощью tiktoken cl100k_base:

python benchmarks/run_benchmark.py            # the table above
python benchmarks/run_benchmark.py --json     # machine-readable
python benchmarks/run_benchmark.py --fixture path/to/your_schemas.json

Related MCP server: Bifrost-MCP Gateway

Установка

Одной строкой (macOS / Linux) — устанавливает пакет и настраивает Claude Desktop:

curl -sSL https://raw.githubusercontent.com/LoudiliMed/Refract/main/install-refract.sh | sh

Передача скрипта из интернета в оболочку требует беглого просмотра: посмотреть install-refract.sh на GitHub. Он никогда не использует sudo.

Или напрямую через pip:

pip install refract-mcp

Дополнительные возможности:

pip install refract-mcp[semantic]   # semantic tool routing with embeddings
pip install refract-mcp[multilang]  # JavaScript, TypeScript, JSX, TSX support

Два режима

Режим 1 — Прокси MCP

Располагается между вашим агентом и любым MCP-сервером. Сжимает схемы инструментов на лету, чтобы агент не загружал полный каталог при каждом запросе.

Локальный подпроцесс (stdio):

refract-proxy --target "npx @modelcontextprotocol/server-filesystem /tmp" --verbose

Удалённый HTTP/SSE-сервер:

# --url implies SSE transport (explicit, recommended for remote endpoints)
refract-proxy --url https://my-mcp-server.com/sse

# or with --transport flag (auto-detection can be overridden)
refract-proxy --target https://my-mcp-server.com/sse --transport sse

Флаги прокси:

Добавление в Claude Desktop:

{
  "mcpServers": {
    "my-server-via-refract": {
      "command": "/path/to/refract-proxy",
      "args": [
        "--target",
        "npx @modelcontextprotocol/server-filesystem /path/to/folder",
        "--verbose"
      ]
    }
  }
}

Для удалённого MCP-сервера (SSE):

{
  "mcpServers": {
    "remote-via-refract": {
      "command": "/path/to/refract-proxy",
      "args": ["--url", "https://my-mcp-server.com/sse"]
    }
  }
}

refract-wrap-all — обёртка для всех серверов сразу

Вместо того чтобы редактировать записи по одной (или запускать refract-install для каждого сервера), refract-wrap-all переписывает все stdio-серверы в claude_desktop_config.json так, чтобы они проходили через refract-proxy одной командой:

# Preview what would change — writes nothing
refract-wrap-all --dry-run

# Wrap every stdio server not already going through refract
refract-wrap-all

# Restore the original commands
refract-wrap-all --unwrap

Пример: эта запись

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {"MY_VAR": "1"}
    }
  }
}

превращается в

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/refract-proxy",
      "args": ["--stdio-cmd", "npx @modelcontextprotocol/server-filesystem /tmp"],
      "env": {"MY_VAR": "1"}
    }
  }
}

Гарантии:

• Резервная копия конфигурации создаётся перед каждой записью (claude_desktop_config.json.bak, затем .bak2, .bak3… — существующая резервная копия никогда не перезаписывается).

• Поля env, cwd и любые другие поля сервера сохраняются.

• Серверы, уже проходящие через refract-proxy или refract-server, пропускаются (already wrapped).

• Удалённые SSE/HTTP-серверы (записи с url) пропускаются — обёртываются только stdio-серверы.

• --unwrap — точная обратимая операция: wrap затем unwrap восстанавливает исходную команду, аргументы и поля.

Транспорты, поддерживаемые refract-proxy

Оба sse и http требуют HTTP(S) URL в --target.

# Connect to a remote MCP server via Streamable HTTP (recommended)
refract-proxy --target "https://my-mcp-server.com/mcp" --transport http

# Connect via SSE (legacy)
refract-proxy --target "https://my-mcp-server.com/sse" --transport sse

# Local subprocess (auto-detected, --transport stdio optional)
refract-proxy --target "npx @modelcontextprotocol/server-filesystem /tmp"

Режим 2 — MCP-сервер

Предоставляет вашу кодовую базу как MCP-сервер. Ваш агент может проиндексировать репозиторий, получить сжатый контекст файла, развернуть конкретные функции, проанализировать влияние, обнаружить критические изменения и нанести на карту риски безопасности.

refract-server --root /path/to/your/repo

Добавление в Claude Desktop:

{
  "mcpServers": {
    "refract-code": {
      "command": "/path/to/refract-server",
      "args": ["--root", "/path/to/your/repo"]
    }
  }
}

Как это работает (без жаргона)

Представьте библиотеку с 50 книгами.

Без Refract: ваш агент получает подробное описание всех 50 книг на каждый вопрос, даже если ответу нужна только одна.

С Refract: агент сначала получает список названий (индекс). Как только он понимает, какая книга нужна, он получает только содержимое этой книги.

Технически:

Индекс (всегда отправляется): только названия инструментов и краткое описание каждого.

Детали (отправляются только при необходимости): полное описание используемого инструмента, всё необходимое для его правильного использования, ничего лишнего.

Проверка: после каждого сжатия Refract автоматически проверяет, что ничего важного не удалено. Если есть сомнения, отправляется полная версия — без риска.

В этом процессе не задействована ни одна AI-модель. Он полностью автоматический, быстрый и детерминированный.

Инструменты прокси MCP

Инструменты MCP-сервера

Проверка здоровья репозитория

refract-status --root /path/to/repo
refract-status --root /path/to/repo --json

Показывает: файлы по языкам, исходные и сжатые токены, функции/классы в индексе, опасные вызовы по категориям, языки без поддержки tree-sitter.

blast_radius

Попросите Claude показать, какие функции сломаются, если вы измените целевую функцию.

Пример результата:

{
  "target": "authenticate",
  "direct_callers": ["login_user"],
  "all_impacted": ["login_user", "verify_session", "admin_access"],
  "impacted_count": 3,
  "risk_level": "MEDIUM"
}

Уровни риска: LOW (от 0 до 2 затронутых), MEDIUM (от 3 до 5), HIGH (6 и более).

semantic_diff

Обнаруживает критические изменения API, сравнивая интерфейсы функций, а не их тела. Используйте как шлюз CI.

Пример результата:

{
  "breaking": ["authenticate"],
  "body_only": ["logout"],
  "added": ["new_function"],
  "removed": [],
  "unchanged": ["hash_password"],
  "is_breaking": true
}

Если is_breaking равно true, PR изменяет публичный API и требует проверки.

security_surface

Наносит на карту каждую функцию, вызывающую опасные примитивы, во всём репозитории.

HIGH риск: subprocess, os.system, eval, exec, pickle, ctypes

MEDIUM риск: open (режим записи), socket, requests, httpx, urllib

Пример результата:

{
  "high_risk": [
    {
      "file": "src/llm_client.py",
      "function": "run_command",
      "calls": ["subprocess.run"]
    }
  ],
  "summary": {
    "high_risk_count": 1,
    "medium_risk_count": 3,
    "total_functions_scanned": 87,
    "clean_files": 8
  }
}

Поддерживаемые языки

Python (через модуль ast), JavaScript, TypeScript, JSX, TSX (через tree-sitter, опционально: pip install refract-mcp[multilang]).

Язык определяется автоматически по расширению файла. Элегантный откат, если tree-sitter не установлен.

Встроенное кэширование Anthropic

Refract интегрируется с кэшированием подсказок Anthropic. as_anthropic_tools() автоматически помечает сжатый каталог как кэшируемый, что ещё больше снижает затраты на повторные запросы.

Пример за 30 дней, 100 запросов в день, 5 000 токенов схем:

Устранение неполадок

"Failed to spawn process: No such file or directory" в Claude Desktop

Claude Desktop не может найти refract-proxy в своём PATH. Найдите абсолютный путь и используйте его напрямую:

which refract-proxy

Затем используйте полный путь в claude_desktop_config.json:

{
  "mcpServers": {
    "my-tool-via-refract": {
      "command": "/full/path/to/refract-proxy",
      "args": [
        "--target",
        "npx @modelcontextprotocol/server-filesystem /path/to/folder"
      ]
    }
  }
}

Работает с

Claude Desktop, Cursor, любым клиентом, соответствующим стандарту MCP, любым существующим MCP-сервером.

Лицензия

MIT — свободное использование, включая коммерческое.