Smart AI Bridge

Smart AI Bridge v2.15.0

Orquestación multi-IA configurable para Claude Code. Añade cualquier proveedor compatible con OpenAI, enruta de forma inteligente y deja que múltiples IAs colaboren mediante el sistema de consejo.

Qué Hace

Smart AI Bridge es un servidor MCP que se sitúa entre Claude Code y tus backends de IA. Proporciona 17 herramientas para operaciones de archivos que ahorran tokens, flujos de trabajo multi-IA, comprobaciones de calidad de código y enrutamiento inteligente, todo configurado mediante un único archivo JSON.

• Funciona con cualquier proveedor compatible con OpenAI. Modelos locales (vLLM, LM Studio, Ollama), APIs en la nube, o una combinación de ambos. Los ajustes predefinidos incluidos cubren los proveedores más comunes, pero añadir el tuyo propio es solo una entrada de configuración.
• Enrutamiento inteligente selecciona el mejor backend para cada tarea mediante un sistema de 4 niveles: selección forzada, preferencias aprendidas, heurísticas basadas en reglas y respaldo basado en salud.
• Sistema de consejo consulta múltiples backends con el mismo prompt y devuelve todas las respuestas para que Claude las sintetice. Estrategias configurables (paralela, secuencial, debate, respaldo) por tema.
• Panel web para gestionar backends y configuración del consejo sin editar archivos JSON.

Cómo Funciona

La idea central: Claude nunca lee el archivo

La mayor parte del contexto de Claude en una tarea de codificación se gasta en el contenido de los archivos. Smart AI Bridge entrega ese trabajo a otro modelo y devuelve solo las conclusiones, de modo que el contexto costoso queda libre para el razonamiento.

sequenceDiagram
    accTitle: How Smart AI Bridge saves tokens
    accDescr: Claude Code calls analyze_file. Smart AI Bridge reads the file and sends its contents to a backend model. The backend returns a structured analysis, and only that analysis is returned to Claude. The file contents never enter Claude's context.
    participant C as Claude Code
    participant S as Smart AI Bridge
    participant F as Your files
    participant B as Backend<br/>(local or cloud)

    C->>S: analyze_file({ filePath, question })
    S->>F: read the file
    S->>B: file contents + question
    B-->>S: structured analysis
    S-->>C: { summary, findings[], confidence, tokens_saved }

    Note over C,S: The file contents never enter Claude's context.<br/>tokens_saved is measured from the real bytes,<br/>not estimated.

modify_file funciona de la misma manera pero devuelve un diff; explore devuelve evidencia file:line coincidente; batch_analyze lo hace a través de un glob. Cada una de estas reporta una cifra tokens_saved calculada a partir de los caracteres reales leídos frente a la respuesta real devuelta.

Elegir un backend: el enrutador de 4 niveles

Cada llamada que no nombra un backend pasa por la misma decisión, en orden. El primer nivel que produce un backend saludable gana.

flowchart TD
    accTitle: The four-tier backend routing decision
    accDescr: A tool call is routed in four ordered tiers. Tier 1 uses an explicitly named backend. Otherwise Tier 2 uses a learned preference above 0.7 confidence if that backend is healthy. Otherwise Tier 3 applies complexity and task-type rules. Otherwise Tier 4 takes the first healthy backend in the fallback chain.
    A[Tool call] --> B{"backend named<br/>and not 'auto'?"}
    B -- yes --> T1["<b>Tier 1 · Forced</b><br/>use it as given"]
    B -- no --> C{"learned preference<br/>above 0.7 confidence<br/><i>and</i> that backend healthy?"}
    C -- yes --> T2["<b>Tier 2 · Learned</b><br/>from past outcomes"]
    C -- no --> D{"a rule matches on<br/>complexity / task type?"}
    D -- yes --> T3["<b>Tier 3 · Rules</b><br/>heuristic match"]
    D -- no --> T4["<b>Tier 4 · Fallback</b><br/>first healthy backend<br/>in the chain"]

Una preferencia aprendida que es confiable pero apunta a un backend no saludable cae al Nivel 3 en lugar de usarse. Los fallos de salud abren un interruptor de circuito, de modo que un proveedor que está caído se omite en lugar de reintentarse hasta agotar el tiempo de espera.

Preguntar a varios modelos a la vez: el consejo

council envía un prompt a múltiples backends y devuelve cada respuesta para que Claude la sintetice. No vota ni elige un ganador: el desacuerdo entre modelos es la señal, por lo que se preserva en lugar de promediarse.

flowchart LR
    accTitle: Council strategies
    accDescr: One prompt is dispatched by a configurable strategy. Parallel queries all backends at once. Sequential runs them in order, each seeing the previous answer. Debate has models respond to each other. Fallback tries the next backend only if the previous failed. Every response is returned to Claude to synthesize.
    Q[One prompt] --> R{strategy}
    R -->|parallel| P[All backends at once]
    R -->|sequential| S[One after another,<br/>each sees the last]
    R -->|debate| D[Models respond<br/>to each other]
    R -->|fallback| F[Next only if<br/>the previous failed]
    P & S & D & F --> A[All responses returned<br/>to Claude to synthesize]

La estrategia es configurable por tema. Consulta docs/COUNCIL.md.

Inicio Rápido

No hay paquete npm: se instala clonando. Requiere Node.js >= 18.

1. Clonar e instalar

git clone https://github.com/Platano78/smart-ai-bridge.git
cd smart-ai-bridge
npm install

Confirma que la instalación es correcta antes de conectarla a cualquier cosa:

npm test          # expect: all tests pass, 0 failures

2. Configurar al menos un backend

El servidor se inicia y lista las 17 herramientas sin ninguna clave de API: solo necesitas un backend cuando realmente haces una llamada. Necesitas uno de:

• un servidor local compatible con OpenAI (llama.cpp, vLLM, LM Studio, Ollama): se auto-descubre en puertos comunes, sin necesidad de clave; o
• una clave de API en la nube de cualquier proveedor compatible.

# Set whichever apply -- one is enough
export NVIDIA_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"

Las definiciones de backend viven en src/config/backends.json; consulta CONFIGURATION.md para la referencia completa. Una clave faltante nunca es un error: la auditoría de preparación al inicio reporta dichos backends como cannot verify, no como rotos.

3. Registrar con tu cliente MCP

Usa una ruta absoluta a src/server.js. Las rutas relativas dependen de que el cliente respete cwd, lo cual no todos los clientes hacen.

Claude Code: copia .mcp.json.example a .mcp.json en tu proyecto, o añádelo a tu configuración MCP:

{
  "mcpServers": {
    "smart-ai-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/smart-ai-bridge/src/server.js"],
      "env": {
        "NVIDIA_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop: el mismo bloque, fusionado en claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cualquier otro cliente MCP: habla MCP sobre stdio. Ejecuta node /absolute/path/src/server.js y comunícate con JSON-RPC. Los diagnósticos van a stderr; stdout transporta solo tráfico de protocolo.

4. Reiniciar el cliente y verificar

Las 17 herramientas aparecen tras un reinicio. Verifica con una llamada que no necesite backend:

@get_analytics({})

Para comprobar un backend que realmente has configurado, nómbralo explícitamente: check_backend_health reporta local como crítico cuando no hay ningún modelo local en ejecución, lo cual es esperado en una configuración solo en la nube y no significa que la instalación haya fallado:

@check_backend_health({ "backend": "auto" })

Actualizar una instalación existente

cd /path/to/smart-ai-bridge
git pull origin main
npm install        # only needed when dependencies changed

Luego reinicia tu cliente MCP (en Claude Code, /mcp reconecta sin un reinicio completo).

Herramientas (17)

Operaciones de Archivos que Ahorran Tokens

Herramienta	Descripción
analyze_file	El backend lee y analiza archivos, devuelve hallazgos estructurados
modify_file	El backend aplica ediciones en lenguaje natural, devuelve diff
batch_analyze	Analiza múltiples archivos mediante patrones glob; grepFilter reduce por contenido primero, singlePass responde en una sola llamada
batch_modify	Aplica las mismas instrucciones en múltiples archivos
generate_file	Genera código a partir de una especificación en lenguaje natural
explore	Responde preguntas sobre el código usando búsqueda inteligente

Todas excepto generate_file devuelven un campo tokens_saved medido para esa llamada específica: los caracteres de contenido de archivo que el backend leyó en tu nombre, menos los caracteres de la respuesta entregada. Ambos lados se miden a partir de los datos reales en lugar de asumirse, de modo que la cifra refleja lo que realmente ocurrió en esa llamada — aunque la conversión de caracteres a tokens (~4 caracteres por token) es en sí aproximada, así que trata el resultado como un buen indicador más que como un recuento exacto de tokens. Varía enormemente con el tamaño del archivo y la longitud de la respuesta: un archivo pequeño puede no ahorrar nada. No publicamos un porcentaje general porque no hemos medido uno que pudiéramos defender.

Flujos de Trabajo Multi-IA

Herramienta	Descripción
ask	Enrutamiento inteligente con selección de backend automática o forzada
council	Consenso multi-IA entre backends configurables
dual_iterate	Bucle de generar, revisar, corregir entre dos backends
parallel_agents	Flujo de trabajo TDD con descomposición y puertas de calidad
spawn_subagent	Agentes de IA especializados (10 roles incluyendo TDD)

Calidad de Código

Herramienta	Descripción
review	Revisión de seguridad, rendimiento y calidad
refactor	Refactorización entre archivos con actualización de referencias

Infraestructura

Herramienta	Descripción
check_backend_health	Diagnósticos de salud para backends específicos
backup_restore	Gestión de copias de seguridad con marca de tiempo
write_files_atomic	Escrituras atómicas multi-archivo con copia de seguridad
get_analytics	Analíticas de uso y recomendaciones de optimización

Enrutamiento Inteligente

El enrutador selecciona backends usando un sistema de prioridad de 4 niveles:

1. Forzado: selección explícita de backend (model="my_backend")
2. Aprendizaje: preferencias aprendidas de resultados pasados (confianza >0.7)
3. Reglas: heurísticas de complejidad y tipo de tarea
4. Respaldo: respaldo basado en salud a través de la cadena de prioridad

Cuando un backend resuelto falla — uno que el enrutador eligió, porque pasaste backend: "auto" o dejaste que una regla de enrutamiento eligiera — la solicitud cae automáticamente al siguiente backend saludable en la cadena.

Un backend que nombraste explícitamente no tiene cascada. Recibe un intento, y si falla recibes un error que lo indica, distinguiendo "tu carril se intentó y falló" de "tu carril no pudo intentarse en absoluto". Esto es deliberado: las claves de API son tuyas, y reenrutar silenciosamente una solicitud que fijaste a un carril puede gastar tu crédito en carriles que nunca pediste. Pasa backend: "auto" cuando quieras la cadena.

Los interruptores de circuito protegen cada backend (5 fallos consecutivos activan un enfriamiento de 30 segundos).

Nombres de Backend

Hay dos capas de nombres de backend, y ambas son intencionales:

• Nombres amigables son los que pasas a las herramientas (p. ej. backend: "glm" o model="groq"). Son alias estables y neutrales respecto al proveedor.
• Nombres internos son los identificadores de registro/configuración usados en src/config/backends.json y analíticas.

Los ajustes predefinidos se mapean de la siguiente manera:

Nombre amigable	Nombre interno	Tipo de adaptador
local	local	local
deepseek	nvidia_deepseek	nvidia_deepseek
glm	nvidia_glm	nvidia_glm
gemini	gemini	gemini
groq	groq_llama	groq

Eliminados: nvidia_qwen / qwen3. El carril especialista en código de NVIDIA sirvió una vez a un modelo Qwen. NVIDIA lo ha retirado desde entonces, y su catálogo ahora no lista ningún modelo Qwen de ningún tipo — por lo que los nombres se eliminaron por completo en lugar de mantenerlos como alias apuntando a un carril con nombre diferente. nvidia_qwen y qwen3 ya no resuelven a nada.

Usa nvidia_glm (alias amigable: glm). Si tienes un force_backend: "nvidia_qwen" or a config carrying "type": "nvidia_qwen", change it to nvidia_glm guardado.

Esto no afecta a los modelos Qwen que ejecutas localmente. El puente aún los detecta en tu propio enrutador y aplica el manejo específico de Qwen (inferencia de capacidades, tokens FIM, supresión de razonamiento) — eso no tiene nada que ver con el carril retirado de NVIDIA.

El backend compatible con OpenAI se distribuye bajo el nombre interno openai_chatgpt (tipo de adaptador openai) y se alcanza mediante enrutamiento inteligente en lugar de un alias amigable. Para la herramienta ask, openai se acepta como alias de compatibilidad para el backend compatible con OpenAI configurado. Los backends personalizados que añades mediante configuración usan su campo name directamente como nombre interno.

Deriva de Backend y Retiro de Modelos

Los proveedores retiran modelos sin aviso, y el fallo es silencioso hasta que una solicitud falla. Dos cosas detectan eso:

Una auditoría de preparación al inicio. Comprueba el modelo de cada backend configurado contra el catálogo del proveedor e imprime hallazgos a stderr. Se ejecuta solo después de que el apretón de manos MCP se completa y nunca se espera, por lo que no puede retrasar ni abortar el inicio. Desactívala con SAB_DISABLE_READINESS_AUDIT=true.

Una sonda bajo demanda que envía a cada backend configurado una finalización real:

npm run audit:backends            # human-readable table
npm run audit:backends -- --json  # machine-readable

Una finalización real es la única comprobación confiable: los IDs de modelo aparecen en el listado /v1/models de un proveedor y aun así devuelven 404 para una cuenta determinada. Los backends se clasifican OK, RETIRED, TRANSIENT, ERROR, NO_MODEL o NO_KEY. Sale con código distinto de cero solo en RETIRED, ERROR o NO_MODEL, por lo que puede controlar CI.

Un backend sin clave de API nunca se reporta como roto. Tú proporcionas tus propias claves y la mayoría de las configuraciones usan un solo proveedor, por lo que una clave no establecida se reporta como cannot verify — <VAR> not set y no hace fallar la ejecución. El backend local se comprueba solo por alcanzabilidad, nunca contra el catálogo: su "model": "dynamic" configurado es un identificador, no un ID de catálogo.

Cuando un modelo ha sido retirado, el error resultante lo dice explícitamente — nombrando el backend, el modelo, el texto de fin de vida del proveedor y candidatos de reemplazo en vivo — en lugar de aparecer como un fallo HTTP genérico. El retiro es un error de configuración, por lo que abre el interruptor de circuito inmediatamente en lugar de reintentarse; la saturación (429/5xx) y los fallos de autenticación (401) deliberadamente no se tratan como retiro.

Fiabilidad de Respuesta (v2.4.0)

Todos los manejadores usan un pipeline de respuesta unificado (extractResponseText) que maneja correctamente todas las formas conocidas de respuesta de LLM — cadenas crudas, formatos de chat/finalización de OpenAI, reasoning_content de modelos de pensamiento, partes de contenido de arreglos y candidatos de Gemini. La salida repetitiva de modelos locales se colapsa automáticamente, y los hallazgos de análisis se deduplican y limitan.

Integridad de Escritura

fs.writeFile resolver no garantiza que los bytes en disco coincidan con lo solicitado: escrituras cortas o parciales, ENOSPC, codificación alterada o un escritor concurrente que sobrescribe el archivo entre la escritura y el retorno dejan contenido en disco que diverge del contenido previsto, mientras que la llamada de escritura en sí se resuelve limpiamente.

Cada ruta que escribe contenido que te importa lo lee de vuelta y lo compara antes de reportar éxito:

Ruta	Qué se verifica
modify_file auto-escritura	archivo modificado, más la copia de seguridad que realiza primero
generate_file auto-escritura	archivo generado y su archivo de pruebas generado
write_files_atomic write	cada archivo escrito, más cada copia de seguridad
write_files_atomic append	el archivo creció exactamente en la longitud añadida y termina exactamente con esos bytes
write_files_atomic reversión	cada archivo restaurado (la copia de seguridad solo se elimina una vez confirmada la restauración)
batch_modify	modificaciones (vía modify_file) y su reversión restaura
parallel_agents	cada archivo de código generado
backup_restore	la copia de seguridad, la instantánea previa a la restauración y la restauración en sí

Una discrepancia genera WRITE_VERIFY_MISMATCH — nombrando el archivo, la longitud esperada vs. la real y la primera línea divergente — en lugar de reportar success: true sobre un archivo corrupto.

Las rutas de recuperación reciben el mismo tratamiento deliberadamente: una copia de seguridad que falla silenciosamente es peor que no tener copia, porque una reversión posterior restauraría bytes corruptos sobre el original.

No verificado, por diseño: artefactos de ejecución internos y archivos de estado que son registros en lugar de entregables — parallel_agents' decomposed.json/results.json/quality-*.json/synthesis.json, el sidecar .meta.json de backup_restore, el almacén de patrones y los hilos de conversación.

Sistema de Consejo

El consejo consulta múltiples backends con el mismo prompt y devuelve todas las respuestas para que Claude las sintetice. Temas como coding, architecture y security se asignan cada uno a un conjunto de backends y una estrategia (paralela, secuencial, debate o respaldo).

Consulta docs/COUNCIL.md para la documentación completa.

Panel de Control

Un panel de control web opcional proporciona una interfaz para la gestión de backends (habilitar/deshabilitar, prioridades, comprobaciones de salud) y la configuración del consejo (estrategias, mapeo de temas).

Consulta docs/DASHBOARD.md para la configuración y la referencia de la API.

SmartCrusher (Compresión de Resultados de Herramientas)

Resultados de herramientas grandes — análisis de archivos largos, respuestas del consejo, salidas por lotes — pueden llenar rápidamente la ventana de contexto de Claude. SmartCrusher recorta arreglos sobredimensionados antes de la serialización usando una estrategia de conservar/descartar ponderada por relevancia, insertando una fila centinela para que Claude sepa que los datos fueron descargados.

Deshabilitado por defecto. Habilítalo solo después de ejecutar la evaluación de fidelidad contra tu propio modelo local.

Habilitar

# One-time env override (no config edit needed)
SAB_COMPRESSION_ENABLED=true node src/server.js

# Or permanently in src/config/backends.json:
# "compression": { "enabled": true }

Evaluación de Fidelidad (ejecutar antes de habilitar)

La evaluación sondea si las respuestas comprimidas preservan la precisión factual en comparación con los originales. Requiere una API local compatible con OpenAI — usa el modelo que normalmente ejecutas:

RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

Revisa la salida para original=N/15 vs crushed=M/15 por dimensión. Si las puntuaciones comprimidas caen más de 2 puntos en cualquier dimensión, deja la compresión deshabilitada — el modelo califica de manera diferente que la configuración de referencia.

Añadir un Backend

Vía Panel de Control (recomendado): Inicia el servidor con SAB_DASHBOARD=true, luego usa la interfaz web en http://localhost:3456 (anula con SAB_DASHBOARD_PORT) para añadir, eliminar, habilitar/deshabilitar y re-priorizar backends sin editar JSON. El panel también te permite establecer/limpiar una clave de API por backend (almacenada en el data/backends-secrets.json ignorado por git, modo 0600 — nunca escrita en el src/config/backends.json rastreado); una clave almacenada surte efecto inmediatamente, sin necesidad de reiniciar, y supera al respaldo process.env del backend.

El panel se vincula solo a 127.0.0.1 por defecto — no tiene autenticación, por lo que no debe ser accesible fuera del equipo. Anula con SAB_DASHBOARD_HOST si necesitas que sea accesible desde otro lugar; un host que no sea de bucle local imprime una advertencia al inicio nombrando el riesgo.

Vía Archivo de Configuración: Cualquier proveedor compatible con OpenAI puede añadirse como entrada de configuración en src/config/backends.json:

{
  "name": "my_provider",
  "type": "openai",
  "endpoint": "https://api.my-provider.com/v1",
  "model": "my-model",
  "apiKeyEnvVar": "MY_PROVIDER_API_KEY",
  "maxTokens": 8192,
  "priority": 7,
  "enabled": true
}

Consulta EXTENDING.md para detalles sobre cómo añadir tipos de adaptadores personalizados.

Documentación

Documento	Descripción
AGENTS.md	Contrato de instalación/ejecución para agentes de IA y arneses de agentes, más reglas del repositorio
CHANGELOG.md	Historial de versiones
CONFIGURATION.md	Referencia completa de configuración
EXTENDING.md	Añadir backends, manejadores y herramientas
EXAMPLES.md	Ejemplos de uso
docs/DASHBOARD.md	Configuración del panel y API
docs/COUNCIL.md	Detalles del sistema de consejo

Requisitos

• Node.js >= 18.0.0
• Al menos un backend configurado (modelo local o clave de API en la nube)
• Claude Code o Claude Desktop para la integración MCP

Pruebas

npm test              # Run the unit + integration suite (Vitest)
npm run test:watch    # Watch mode
npm run test:bench    # Performance benchmarks (25 benchmarks, 6 categories)
npm run audit:backends # Probe every configured backend with a real completion

# SmartCrusher fidelity eval (opt-in, requires a running local model):
RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

Notas de Seguridad

• Nunca comprometas claves de API al control de versiones. Usa variables de entorno exclusivamente.
• Los ejemplos de configuración de Claude Code anteriores usan valores de marcador de posición — reemplázalos con tus claves reales o referencia un archivo .env.
• Rota inmediatamente cualquier clave filtrada accidentalmente.

Modelo de Amenazas

Smart AI Bridge es un servidor MCP de confianza local. Está diseñado para ejecutarse como un subproceso stdio de un solo cliente que controlas (Claude Code o Claude Desktop) en tu propia máquina, y asume que ese cliente es de confianza.

Dentro de ese límite:

• Las herramientas de archivos tienen acceso completo al sistema de archivos por diseño. write_files_atomic, modify_file, backup_restore y las herramientas de lectura/análisis operan en las rutas que proporcione el cliente que llama. No están aisladas en una raíz de proyecto. safeReadFile resuelve rutas y rechaza bytes nulos (defensa contra trucos de inyección de rutas), pero no confina el acceso a un espacio de trabajo.
• La validación de argumentos ocurre en el límite de la herramienta. Las llamadas a herramientas se validan contra el esquema JSON de cada herramienta (vía Ajv) antes del despacho; las llamadas malformadas se rechazan con un error estructurado. Esto protege contra entrada malformada, no contra un cliente hostil.
• Las llamadas a herramientas se ejecutan con los privilegios del proceso del servidor. Ejecútalo como tu usuario normal, no como root.

Esta postura es apropiada para el caso de uso previsto de un solo usuario y agente local. No es adecuada para exponer el servidor a llamadores no confiables o multiinquilino a través de una red. Si necesitas eso, coloca un proxy autenticador delante y añade confinamiento de raíz de espacio de trabajo a los manejadores de archivos primero — ninguno se proporciona aquí.

Licencia

Apache-2.0