Reract

Reuce hasta el 98 % de los tokens que tus agentes de IA gastan al usar herramientas MCP — sin perder nada.

Lo que realmente cambia

Menos tokens envíados = facturas de API más bajas, respuestas más rápidas. Y no se pierde nada. Cada comprobación confirma que las herramientas siguen siendo 100% usables tras la compresión.

Reproduce estos números tú mismo — cada entrada es un fijo estático en el repo, tokens contados con tiktoken cl00k_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

Instalar

Un a linea (macOS / Linux) — instala el paquete y configura Claude Desktop:

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

Pasar un script de internet a tu shell merece un vistazo rápido primero: inspectar instalar-refract.sh en GitHub. Nunca usa sudo.

O directamente con pip:

pip install refract-mcp

Extras opcionales:

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

Dos modos

Modo 1 — Proxy MCP

Se interpone entre tu agente y cualquier servidor MCP. Comprie los esquemas de las herramientas sobre la marcha para que tu agente no cargue el catálogo completo en cada petición.

Subproceso local (stdio):

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

Servidor remoto 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

Flags del proxy:

Agrégalo a Claude Desktop:

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

Para un servidor MCP remoto (SSE):

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

refract-wrap-all — envuelve todos los servidores a la vez

En lugar de editar las entradas una por una (o ejecutar refract-install por servidor), refract-wrap-all reescribe todos los servidores stdio en claude_desktop_config.json para que pasen por refract-proxy en un solo comando:

# 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

Ejemplo: esta entrada

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

se convierte en

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

Garantías:

• Se hace una copia de seguridad de la configuración antes de cada escritura (claude_desktop_config.json.bak, luego .bak2, .bak3… — nunca se sobrescribe una copia existente).

• env, cwd y cualquier otro campo del servidor se conservan.

• Los servidores que ya pasan por refract-proxy o refract-server se saltan (already wrapped).

• Los servidores remotos SSE/HTTP (entradas url) se saltan — solo se envuelven servidores stdio.

• --unwrap es un viaje de ida y vuelta exacto: envolver y luego desenvolver restaura cada comando, argumentos y campos originales.

Transportes soportados por refract-proxy

Tanto sse como http requieren una URL HTTP(S) en --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"

Modo 2 — Servidor MCP

Expone tu base de código como un servidor MCP. Tu agente puede indexar un repositorio, obtener contexto comprimido de archivos, expandir funciones específicas, analizar impacto, detectar cambios disruptivos y mapear riesgos de seguridad.

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

Agrégalo a Claude Desktop:

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

Cómo funciona, sin tecnicismos

Imagina una biblioteca con 50 libros.

Sin Refract: tu agente recibe un resumen detallado de los 50 libros en cada pregunta, incluso si la respuesta solo necesita uno de ellos.

Con Refract: tu agente primero recibe una lista de títulos (el índice). Una vez que sabe qué libro necesita, solo recibe el contenido de ese libro.

Técnicamente:

El índice (siempre enviado): solo los nombres de las herramientas y una breve descripción de cada una.

El detalle (enviado solo cuando es necesario): la descripción completa de la herramienta realmente utilizada, todo lo necesario para usarla correctamente, nada más.

La verificación: después de cada compresión, Refract comprueba automáticamente que no se haya eliminado nada importante. Si hay alguna duda, envía la versión completa en lugar de arriesgarse.

Ningún modelo de IA está involucrado en este proceso. Es completamente automático, rápido y determinista.

Herramientas del proxy MCP

Herramientas del servidor MCP

Verificación de salud del repositorio

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

Muestra: archivos por lenguaje, tokens brutos vs comprimidos, funciones/clases indexadas, llamadas peligrosas por categoría, lenguajes sin soporte de tree-sitter.

blast_radius

Pide a Claude qué funciones se rompen si cambias una función objetivo.

Ejemplo de resultado:

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

Niveles de riesgo: BAJO (de 0 a 2 afectadas), MEDIO (de 3 a 5), ALTO (6 o más).

semantic_diff

Detecta cambios disruptivos en la API comparando interfaces de funciones, no cuerpos. Úsalo como puerta de CI.

Ejemplo de resultado:

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

Si is_breaking es true, el PR cambia la API pública y debe ser revisado.

security_surface

Mapa cada función que llama a primitivas peligrosas en todo tu repositorio.

RIESGO ALTO: subprocess, os.system, eval, exec, pickle, ctypes

RIESGO MEDIO: open (modo escritura), socket, requests, httpx, urllib

Ejemplo de resultado:

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

Lenguajes soportados

Python (mediante módulo ast), JavaScript, TypeScript, JSX, TSX (mediante tree-sitter, optativo con pip install refract-mcp[multilang]).

El lenguaje se detecta automáticamente de la extensión del archivo. Caída gaci si tree-sitter no est instalado.

Caché integradio de Anthropic

Refact se integra con el cché de prompts de Anthropic. as_anthropic_tols() marca automáticamente el catálogo comprimido como caable, reduciendo aú más ls costos en petiones repetidas.

Ejemplo en 30 días, 100 petiones al día, 5000 tokens de esquemas:

Solución de problemas

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

Claude Desktop no encuentra refract-proxy en su PATH. Encuentra la ruta absoluta y úsala directamente:

which refract-proxy

Luego usa la ruta completa en claude_desktop_config.json:

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

Funciona con

Claude Desktop, Cursor, cualquier cliente que siga el estándar MCP, cualquier servidor MCP existente.

Licencia

MIT — libre de usar, incluso comercialmente.