Smart AI Bridge

Smart AI Bridge v2.12.0

Orquestração multi-IA orientada por configuração para Claude Code. Adicione qualquer provedor compatível com OpenAI, roteie de forma inteligente e deixe várias IAs colaborarem através do sistema de conselho.

O Que Ele Faz

O Smart AI Bridge é um servidor MCP que fica entre o Claude Code e seus backends de IA. Ele fornece 17 ferramentas para operações de arquivo que economizam tokens, fluxos de trabalho multi-IA, verificações de qualidade de código e roteamento inteligente — tudo configurado através de um único arquivo JSON.

• Qualquer provedor compatível com OpenAI funciona. Modelos locais (vLLM, LM Studio, Ollama), APIs em nuvem ou uma mistura de ambos. Os presets incluídos cobrem provedores comuns, mas adicionar o seu próprio é apenas uma entrada de configuração.
• Roteamento inteligente seleciona o melhor backend por tarefa usando um sistema de 4 níveis: seleção forçada, preferências aprendidas, heurísticas baseadas em regras e fallback baseado em saúde.
• Sistema de conselho consulta vários backends no mesmo prompt e retorna todas as respostas para o Claude sintetizar. Estratégias configuráveis (paralela, sequencial, debate, fallback) por tópico.
• Painel web para gerenciar backends e configuração do conselho sem editar arquivos JSON.

Início Rápido

1. Instalar

cd /path/to/smart-ai-bridge
npm install

2. Configurar Backends

A configuração dos backends fica em src/config/backends.json. Defina as chaves de API para os provedores que deseja usar:

# Examples -- set whichever keys apply to your backends
export NVIDIA_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"

Você só precisa de pelo menos um backend funcional (um modelo local ou uma chave de API em nuvem). Consulte CONFIGURATION.md para a referência completa de configuração.

3. Adicionar ao Claude Code

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

4. Reiniciar o Claude Code

Após reiniciar, todas as 17 ferramentas estarão disponíveis. Verifique com:

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

Ferramentas (17)

Operações de Arquivo que Economizam Tokens

Ferramenta	Descrição
analyze_file	Backend lê e analisa arquivos, retorna descobertas estruturadas
modify_file	Backend aplica edições em linguagem natural, retorna diff
batch_analyze	Analisa múltiplos arquivos via padrões glob
batch_modify	Aplica as mesmas instruções em múltiplos arquivos
generate_file	Gera código a partir de uma especificação em linguagem natural
explore	Responde perguntas sobre o código usando busca inteligente

Todas, exceto generate_file, retornam um campo tokens_saved medido para aquela chamada específica: os caracteres do conteúdo do arquivo que o backend leu em seu nome, menos os caracteres da resposta devolvida. Ambos os lados são medidos a partir dos dados reais, em vez de presumidos, então o valor reflete o que realmente aconteceu naquela chamada — embora a conversão de caracteres para tokens (~4 caracteres por token) seja em si aproximada, trate o resultado como um bom indicador, em vez de uma contagem exata de tokens. Varia enormemente com o tamanho do arquivo e o comprimento da resposta: um arquivo pequeno pode não economizar nada. Não publicamos nenhuma porcentagem principal porque não medimos uma que pudéssemos defender.

Fluxos de Trabalho Multi-IA

Ferramenta	Descrição
ask	Roteamento inteligente com seleção automática ou forçada de backend
council	Consenso multi-IA entre backends configuráveis
dual_iterate	Loop de gerar, revisar, corrigir entre dois backends
parallel_agents	Fluxo de trabalho TDD com decomposição e portões de qualidade
spawn_subagent	Agentes de IA especializados (10 papéis, incluindo TDD)

Qualidade de Código

Ferramenta	Descrição
review	Revisão de segurança, desempenho e qualidade
refactor	Refatoração entre arquivos com atualização de referências

Infraestrutura

Ferramenta	Descrição
check_backend_health	Diagnóstico de saúde para backends específicos
backup_restore	Gerenciamento de backups com carimbo de data/hora
write_files_atomic	Escritas atômicas multi-arquivo com backup
get_analytics	Análise de uso e recomendações de otimização

Roteamento Inteligente

O roteador seleciona backends usando um sistema de prioridade de 4 níveis:

1. Forçado — seleção explícita de backend (model="my_backend")
2. Aprendizado — preferências aprendidas de resultados anteriores (confiança >0.7)
3. Regras — heurísticas de complexidade e tipo de tarefa
4. Fallback — fallback baseado em saúde através da cadeia de prioridade

Quando um backend falha, as solicitações caem automaticamente para o próximo backend saudável. Disjuntores protegem cada backend (5 falhas consecutivas acionam um período de espera de 30 segundos).

Nomes de Backends

Existem duas camadas de nomenclatura de backends, e ambas são intencionais:

• Nomes amigáveis são o que você passa para as ferramentas (ex.: backend: "glm" ou model="groq"). São aliases estáveis e neutros em relação ao provedor.
• Nomes internos são os identificadores de registro/configuração usados em src/config/backends.json e análises.

Os presets mapeiam da seguinte forma:

Nome amigável	Nome interno	Tipo de adaptador
local	local	local
deepseek	nvidia_deepseek	nvidia_deepseek
glm	nvidia_glm	nvidia_glm
gemini	gemini	gemini
groq	groq_llama	groq

Aliases legados. A via de especialista em código era Qwen3 Coder 480B até a NVIDIA aposentá-lo em 2026-06-11; agora serve GLM-5.2 sob o nome nvidia_glm. Os nomes antigos ainda funcionam e continuarão a funcionar:

Nome legado	Resolve para
qwen3	nvidia_glm
nvidia_qwen	nvidia_glm

Um force_backend: "nvidia_qwen" salvo continua funcionando; atualize-o quando for conveniente. Uma configuração que ainda carrega "type": "nvidia_qwen" também ainda constrói o adaptador correto.

O backend compatível com OpenAI é fornecido sob o nome interno openai_chatgpt (tipo de adaptador openai) e é acessado através de roteamento inteligente, em vez de um alias amigável. Para a ferramenta ask, openai é aceito como um alias de compatibilidade para o backend compatível com OpenAI configurado. Backends personalizados que você adiciona via configuração usam seu campo name diretamente como o nome interno.

Deriva de Backend e Aposentadoria de Modelos

Provedores aposentam modelos sem aviso, e a falha é silenciosa até que uma solicitação falhe. Duas coisas detectam isso:

Uma auditoria de prontidão na inicialização. Ela verifica o modelo de cada backend configurado contra o catálogo do provedor e imprime descobertas em stderr. Ela é executada apenas após o handshake MCP ser concluído e nunca é aguardada, então não pode atrasar ou abortar a inicialização. Desative-a com SAB_DISABLE_READINESS_AUDIT=true.

Uma sonda sob demanda que envia a cada backend configurado uma conclusão real:

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

Uma conclusão real é a única verificação confiável — ids de modelos aparecem na listagem /v1/models de um provedor que ainda retornam 404 para uma determinada conta. Os backends são classificados como OK, RETIRED, TRANSIENT, ERROR, NO_MODEL ou NO_KEY. Ele sai com código não zero apenas em RETIRED, ERROR ou NO_MODEL, então pode controlar CI.

Um backend sem chave de API nunca é relatado como quebrado. Você fornece suas próprias chaves e a maioria das configurações usa um único provedor, então uma chave não definida é relatada como cannot verify — <VAR> not set e não falha a execução. O backend local é verificado apenas quanto à acessibilidade, nunca quanto ao catálogo: seu "model": "dynamic" configurado é um identificador, não um id de catálogo.

Quando um modelo foi aposentado, o erro resultante diz isso explicitamente — nomeando o backend, o modelo, o texto de fim de vida do provedor e candidatos de substituição ao vivo — em vez de aparecer como uma falha HTTP genérica. A aposentadoria é um erro de configuração, então abre o disjuntor imediatamente em vez de ser repetida; saturação (429/5xx) e falhas de autenticação (401) deliberadamente não são tratadas como aposentadoria.

Confiabilidade de Resposta (v2.4.0)

Todos os manipuladores usam um pipeline de resposta unificado (extractResponseText) que lida corretamente com todas as formas conhecidas de resposta LLM — strings brutas, formatos de chat/conclusão OpenAI, reasoning_content de modelos de pensamento, partes de conteúdo de array e candidatos Gemini. Saída repetitiva de modelos locais é automaticamente colapsada, e descobertas de análise são deduplicadas e limitadas.

Integridade de Escrita

fs.writeFile resolver não garante que os bytes no disco correspondam ao que foi solicitado — escritas curtas ou parciais, ENOSPC, corrupção de codificação ou um escritor concorrente sobrescrevendo o arquivo entre a escrita e o retorno deixam todo o conteúdo do disco divergente do conteúdo pretendido enquanto a própria chamada de escrita resolve limpa.

Todo caminho que escreve conteúdo que você considera importante lê de volta e compara antes de relatar sucesso:

Caminho	O que é verificado
modify_file auto-escrita	arquivo modificado, mais o backup que ele faz primeiro
generate_file auto-escrita	arquivo gerado e seu arquivo de testes gerado
write_files_atomic write	cada arquivo escrito, mais cada backup
write_files_atomic append	arquivo cresceu exatamente pelo comprimento anexado e termina exatamente com esses bytes
write_files_atomic rollback	cada arquivo restaurado (o backup só é desvinculado após a restauração ser confirmada)
batch_modify	modificações (via modify_file) e suas restaurações de rollback
parallel_agents	cada arquivo de código gerado
backup_restore	o backup, o snapshot pré-restauração e a própria restauração

Uma incompatibilidade levanta WRITE_VERIFY_MISMATCH — nomeando o arquivo, o comprimento esperado vs. real e a primeira linha divergente — em vez de relatar success: true sobre um arquivo corrompido.

Os caminhos de recuperação recebem o mesmo tratamento deliberadamente: um backup que falhou silenciosamente em ser criado é pior do que nenhum backup, porque um rollback posterior restauraria bytes corrompidos sobre o original.

Não verificado, por design: artefatos de execução internos e arquivos de estado que são registros em vez de entregáveis — parallel_agents' decomposed.json/results.json/quality-*.json/synthesis.json, backup_restore's .meta.json sidecar, o armazenamento de padrões e threads de conversa.

Sistema de Conselho

O conselho consulta vários backends no mesmo prompt e retorna todas as respostas para o Claude sintetizar. Tópicos como coding, architecture e security cada um mapeia para um conjunto de backends e uma estratégia (paralela, sequencial, debate ou fallback).

Consulte docs/COUNCIL.md para documentação completa.

Painel

Um painel web opcional fornece interface para gerenciamento de backends (ativar/desativar, prioridades, verificações de saúde) e configuração do conselho (estratégias, mapeamento de tópicos).

Consulte docs/DASHBOARD.md para configuração e referência de API.

SmartCrusher (Compressão de Resultados de Ferramentas)

Resultados grandes de ferramentas — análises longas de arquivos, respostas do conselho, saídas em lote — podem preencher a janela de contexto do Claude rapidamente. O SmartCrusher reduz arrays superdimensionados antes da serialização usando uma estratégia de manter/descartar ponderada por saliência, inserindo uma linha sentinela para que o Claude saiba que dados foram descarregados.

Desativado por padrão. Ative somente após executar a avaliação de fidelidade contra seu próprio modelo local.

Ativar

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

Avaliação de Fidelidade (execute antes de ativar)

A avaliação verifica se respostas compactadas preservam precisão factual em comparação com as originais. Requer uma API local compatível com OpenAI — use qualquer modelo que você normalmente executa:

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

Verifique a saída para original=N/15 vs crushed=M/15 por dimensão. Se as pontuações compactadas caírem mais de 2 pontos em qualquer dimensão, deixe a compressão desativada — o modelo avalia de forma diferente da configuração de referência.

Adicionando um Backend

Via Dashboard (recomendado): Inicie o servidor com SAB_DASHBOARD=true, depois use a interface web em http://localhost:3456 (substitua por SAB_DASHBOARD_PORT) para adicionar, remover, habilitar/desabilitar e reordenar prioridades dos backends sem editar JSON. O dashboard também permite definir/limpar uma chave de API por backend (armazenada no arquivo data/backends-secrets.json ignorado pelo git, modo 0600 — nunca gravada no src/config/backends.json rastreado); uma chave armazenada entra em vigor imediatamente, sem necessidade de reinicialização, e tem precedência sobre o fallback process.env do backend.

O dashboard vincula-se apenas a 127.0.0.1 por padrão — ele não possui autenticação, portanto não deve ser acessível fora da máquina. Substitua com SAB_DASHBOARD_HOST se precisar que seja acessível em outro lugar; um host não-loopback exibe um aviso na inicialização indicando o risco.

Via Arquivo de Configuração: Qualquer provedor compatível com OpenAI pode ser adicionado como uma entrada de configuração em 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
}

Consulte EXTENDING.md para detalhes sobre como adicionar tipos de adaptadores personalizados.

Documentação

Documento	Descrição
CHANGELOG.md	Histórico de versões
CONFIGURATION.md	Referência completa de configuração
EXTENDING.md	Adicionando backends, manipuladores e ferramentas
EXAMPLES.md	Exemplos de uso
docs/DASHBOARD.md	Configuração do dashboard e API
docs/COUNCIL.md	Detalhes do sistema de conselho

Requisitos

• Node.js >= 18.0.0
• Pelo menos um backend configurado (modelo local ou chave de API em nuvem)
• Claude Code ou Claude Desktop para integração MCP

Testes

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 Segurança

• Nunca envie chaves de API para o controle de versão. Use variáveis de ambiente exclusivamente.
• Os exemplos de configuração do Claude Code acima usam valores de espaço reservado — substitua-os pelas suas chaves reais ou faça referência a um arquivo .env.
• Gire imediatamente quaisquer chaves vazadas acidentalmente.

Modelo de Ameaças

Smart AI Bridge é um servidor MCP local confiável. Ele foi projetado para ser executado como um subprocesso stdio de um único cliente que você controla (Claude Code ou Claude Desktop) na sua própria máquina, e assume que esse cliente é confiável.

Dentro desse limite:

• As ferramentas de arquivo têm acesso total ao sistema de arquivos por design. write_files_atomic, modify_file, backup_restore e as ferramentas de leitura/análise operam em quaisquer caminhos fornecidos pelo cliente chamador. Elas não são isoladas em uma raiz de projeto. safeReadFile resolve caminhos e rejeita bytes nulos (defesa contra truques de injeção de caminho), mas não confina o acesso a um espaço de trabalho.
• A validação de argumentos ocorre no limite da ferramenta. As chamadas de ferramenta são validadas contra o JSON Schema de cada ferramenta (via Ajv) antes do despacho; chamadas malformadas são rejeitadas com um erro estruturado. Isso protege contra entrada malformada, não contra um cliente hostil.
• As chamadas de ferramenta são executadas com os privilégios do processo do servidor. Execute-o como seu usuário normal, não como root.

Essa postura é apropriada para o caso de uso pretendido de agente local de usuário único. Não é adequada para expor o servidor a chamadores não confiáveis ou multi-tenant pela rede. Se precisar disso, coloque um proxy autenticador na frente e adicione confinamento de raiz do espaço de trabalho aos manipuladores de arquivos primeiro — nenhum dos dois é fornecido aqui.

Licença

Apache-2.0