Refract

Reduziert bis zu 98 % der Tokens, die Ihre KI-Agenten bei der Nutzung von MCP-Tools verbrauchen – ohne dabei etwas zu verlieren.

Was sich tatsächlich ändert

Weniger gesendete Tokens = niedrigere API-Kosten, schnellere Antworten. Und nichts geht verloren. Jede Überprüfung bestätigt, dass die Tools nach der Komprimierung zu 100 % nutzbar bleiben.

Reproduzieren Sie diese Zahlen selbst – jede Eingabe ist eine statische Testdatei im Repository, Tokens gezählt mit 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

Installation

Einzeiler (macOS / Linux) – installiert das Paket und konfiguriert Claude Desktop:

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

Das Weiterleiten eines Skripts aus dem Internet an Ihre Shell verdient einen kurzen Blick: install-refract.sh auf GitHub ansehen. Es verwendet niemals sudo.

Oder direkt mit pip:

pip install refract-mcp

Optionale Zusätze:

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

Zwei Modi

Modus 1 – MCP-Proxy

Sitzt zwischen Ihrem Agenten und einem beliebigen MCP-Server. Komprimiert Tool-Schemata on the fly, sodass Ihr Agent nicht bei jeder Anfrage den gesamten Katalog laden muss.

Lokaler Unterprozess (stdio):

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

Remote-HTTP/SSE-Server:

# --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

Proxy-Flags:

Zu Claude Desktop hinzufügen:

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

Für einen entfernten MCP-Server (SSE):

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

refract-wrap-all – alle Server auf einmal umschließen

Anstatt Einträge einzeln zu bearbeiten (oder refract-install pro Server auszuführen), überschreibt refract-wrap-all alle stdio-Server in claude_desktop_config.json, um sie in einem einzigen Befehl durch refract-proxy zu leiten:

# 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

Beispiel: Dieser Eintrag

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

wird zu

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

Garantien:

• Vor jedem Schreibvorgang wird ein Backup der Konfiguration erstellt (claude_desktop_config.json.bak, dann .bak2, .bak3 … – ein vorhandenes Backup wird niemals überschrieben).

• env, cwd und alle anderen Serverfelder bleiben erhalten.

• Server, die bereits über refract-proxy oder refract-server laufen, werden übersprungen (bereits umschlossen).

• Remote-SSE/HTTP-Server (url-Einträge) werden übersprungen – nur stdio-Server werden umschlossen.

• --unwrap ist eine exakte Rundreise: Umschließen und dann Entschließen stellt jeden ursprünglichen Befehl, jedes Argument und jedes Feld wieder her.

Von refract-proxy unterstützte Transporte

Sowohl sse als auch http erfordern eine HTTP(S)-URL in --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"

Modus 2 – MCP-Server

Macht Ihre Codebasis als MCP-Server zugänglich. Ihr Agent kann ein Repository indizieren, komprimierten Dateikontext abrufen, bestimmte Funktionen erweitern, Auswirkungen analysieren, Breaking Changes erkennen und Sicherheitsrisiken kartieren.

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

Zu Claude Desktop hinzufügen:

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

Wie es funktioniert, ohne Fachjargon

Stellen Sie sich eine Bibliothek mit 50 Büchern vor.

Ohne Refract: Ihr Agent erhält bei jeder Frage eine detaillierte Zusammenfassung aller 50 Bücher, selbst wenn die Antwort nur eines davon benötigt.

Mit Refract: Ihr Agent erhält zunächst eine Liste der Titel (das Inhaltsverzeichnis). Sobald er weiß, welches Buch er braucht, erhält er nur den Inhalt dieses Buches.

Technisch gesehen:

Das Inhaltsverzeichnis (immer gesendet): nur Tool-Namen und eine kurze Beschreibung von jedem.

Das Detail (nur bei Bedarf gesendet): die vollständige Beschreibung des tatsächlich verwendeten Tools, alles, was für die korrekte Verwendung erforderlich ist, nicht mehr.

Die Überprüfung: Nach jeder Komprimierung prüft Refract automatisch, ob nichts Wichtiges entfernt wurde. Bei Zweifeln wird die Vollversion gesendet, anstatt ein Risiko einzugehen.

An diesem Prozess ist kein KI-Modell beteiligt. Er ist vollautomatisch, schnell und deterministisch.

MCP-Proxy-Tools

MCP-Server-Tools

Repository-Integritätsprüfung

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

Zeigt: Dateien pro Sprache, rohe vs. komprimierte Tokens, indizierte Funktionen/Klassen, gefährliche Aufrufe nach Kategorie, Sprachen ohne tree-sitter-Unterstützung.

blast_radius

Fragen Sie Claude, welche Funktionen brechen, wenn Sie eine Zielfunktion ändern.

Beispielergebnis:

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

Risikostufen: NIEDRIG (0 bis 2 betroffen), MITTEL (3 bis 5), HOCH (6 oder mehr).

semantic_diff

Erkennt Breaking Changes in der API durch den Vergleich von Funktionsschnittstellen, nicht von Rümpfen. Verwenden Sie es als CI-Gate.

Beispielergebnis:

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

Wenn is_breaking wahr ist, ändert der PR die öffentliche API und muss überprüft werden.

security_surface

Kartiert jede Funktion, die gefährliche Primitive in Ihrem Repository aufruft.

HOCHES Risiko: subprocess, os.system, eval, exec, pickle, ctypes

MITTLERES Risiko: open (Schreibmodus), socket, requests, httpx, urllib

Beispielergebnis:

{
  "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
  }
}

Unterstützte Sprachen

Python (über das ast-Modul), JavaScript, TypeScript, JSX, TSX (über tree-sitter, optional mit pip install refract-mcp[multilang]).

Die Sprache wird automatisch anhand der Dateierweiterung erkannt. Graceful Fallback, wenn tree-sitter nicht installiert ist.

Integriertes Anthropic-Caching

Refract integriert sich in das Anthropic-Prompt-Caching. as_anthropic_tools() markiert den komprimierten Katalog automatisch als cacheable, was die Kosten bei wiederholten Anfragen weiter senkt.

Beispiel über 30 Tage, 100 Anfragen pro Tag, 5.000 Tokens an Schemata:

Fehlerbehebung

"Fehler beim Erzeugen des Prozesses: Datei oder Verzeichnis nicht gefunden" in Claude Desktop

Claude Desktop kann refract-proxy nicht in seinem PATH finden. Ermitteln Sie den absoluten Pfad und verwenden Sie ihn direkt:

which refract-proxy

Verwenden Sie dann den vollständigen Pfad in claude_desktop_config.json:

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

Funktioniert mit

Claude Desktop, Cursor, jedem Client, der dem MCP-Standard folgt, jedem vorhandenen MCP-Server.

Lizenz

MIT – kostenlos nutzbar, auch kommerziell.