Universal AI Bridge

Um servidor MCP local que deixa qualquer IA que fale MCP — no navegador (ChatGPT, Claude.ai) ou local (Claude Desktop, Cursor, Gemini CLI) — programar no seu PC: criar/editar projetos, rodar terminal (inclusive tarefas longas e interativas) e, no modo admin, usar Docker. Com dois modos de segurança claramente separados.

Um código, dois transportes:

• stdio → clientes MCP locais (sem rede, sem token).

• Streamable HTTP → IAs no navegador, via túnel HTTPS (cloudflared).

Arquitetura: IA → Auth → Policy Engine → Executor → Audit.

Sumário

1. Modos de segurança

2. Instalação

3. Configuração .env

4. Claude Desktop / Cursor / Gemini CLI (stdio)

5. ChatGPT / Claude.ai no navegador (HTTP + túnel)

6. Terminal e tarefas longas

7. Docker (modo admin)

8. Tokens

9. Logs / auditoria

10. Desligamento de emergência

11. Recuperação após erro

12. Riscos de acesso total

13. Multiplataforma

14. Ferramentas

Related MCP server: CodeAgent MCP

1. Modos de segurança

O modo é escolhido por BRIDGE_MODE.

Modo seguro (safe) — padrão

• Workspace jaulado (nada sai da pasta configurada; symlinks para fora são bloqueados).

• Shell desligado por padrão; liga só com BRIDGE_ALLOW_SHELL=true.

• Docker sempre bloqueado.

• Ações com efeito colateral passam por aprovação (confirm ou local).

Modo administrador (admin) — opt-in deliberado

• Shell ligado por padrão; Docker liberável com BRIDGE_ALLOW_DOCKER=true.

• Exige reconhecimento explícito: BRIDGE_ADMIN_ACK=I_UNDERSTAND_FULL_PC_ACCESS. Sem essa frase exata, o servidor não sobe em modo admin (cai para safe/erro).

• Continua com workspace jaulado (o escopo é a raiz do workspace — amplie-a conscientemente se precisar).

⚠️ No modo administrador, qualquer pessoa que obtenha os tokens necessários poderá executar ações com os privilégios do processo no computador.

Recomendação: rode o modo admin em um usuário dedicado do sistema ou VM, e exponha o HTTP apenas atrás de VPN/Cloudflare Access — nunca por uma URL pública permanente.

2. Instalação

Requer Node.js 22+.

git clone https://github.com/LMPrado-DZ23/universal-ai-bridge.git
cd universal-ai-bridge
npm install
npm run build

No Windows, um atalho faz install + build + gera o .env com token criptográfico:

powershell -ExecutionPolicy Bypass -File .\setup.ps1

3. Configuração .env

Copie env.example para .env. O servidor carrega o .env automaticamente (via process.loadEnvFile, nativo do Node 22). Gere um token forte:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. Claude Desktop / Cursor / Gemini CLI (stdio)

Não precisa de túnel. Aponte o cliente para o transporte stdio.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "universal-ai-bridge": {
      "command": "node",
      "args": ["C:\\caminho\\para\\universal-ai-bridge\\dist\\index.js", "--transport", "stdio"],
      "env": {
        "BRIDGE_WORKSPACE": "C:\\caminho\\para\\ai-workspace",
        "BRIDGE_ALLOW_SHELL": "true"
      }
    }
  }
}

No Linux/macOS use caminhos POSIX (ex.: /home/voce/universal-ai-bridge/dist/index.js). Gemini CLI: mesma estrutura em ~/.gemini/settings.json sob mcpServers.

5. ChatGPT / Claude.ai no navegador (HTTP + túnel)

O navegador só conecta em MCP remoto (HTTPS).

npm run start:http

Escuta só em http://127.0.0.1:8787/mcp. Exponha com cloudflared:

cloudflared tunnel --url http://127.0.0.1:8787

O cloudflared devolve uma URL https://...trycloudflare.com. Acrescente esse host em BRIDGE_ALLOWED_ORIGINS e reinicie. O endpoint MCP é https://.../mcp.

• ChatGPT (Settings → Connectors / modo desenvolvedor): adicione conector MCP com a URL /mcp e header Authorization: Bearer <BRIDGE_TOKEN>.

• Claude.ai (Settings → Connectors → custom): mesma URL e header.

• Cole o conteúdo de SKILL.md nas instruções do GPT/projeto.

Túnel público temporário serve para teste. Para uso permanente, prefira Cloudflare Access / VPN.

6. Terminal e tarefas longas

Disponível quando shell_enabled: true.

• Comando curto: run_command executa e espera terminar.

• Tarefa longa / streaming: run_job retorna um job_id; job_output devolve a saída incremental (passe os cursores retornados para acompanhar em tempo real).

• Interativo: job_write envia texto ao stdin do processo.

• Cancelamento: job_cancel encerra o job e toda a árvore de processos-filho (taskkill /T no Windows, kill de grupo no POSIX).

Só binários da allowlist (config/policy.json) rodam; encadeamento e redirecionamento (&& | ; > <) são bloqueados.

run_command/run_job não são uma sandbox. Rodam com os privilégios do processo; binários capazes de executar código (node, python) podem alcançar caminhos fora do workspace. Para isolamento real, use usuário/VM dedicados.

7. Docker (modo admin)

Bloqueado no modo safe. No admin, com BRIDGE_ALLOW_DOCKER=true, a ferramenta docker roda docker <args> como job (ex.: docker build -t app .).

Acesso ao Docker do host costuma equivaler a root. Prefira Docker rootless ou um daemon/VM separada.

8. Tokens

• O token do HTTP fica em BRIDGE_TOKEN (no .env, que é git-ignored).

• Comparação em tempo constante (timingSafeEqual); nunca é logado.

• Rotação: gere um novo token, atualize o .env, reinicie o servidor e o conector. Sessões antigas param de valer.

• Nunca compartilhe o token nem o cole em páginas/repos.

9. Logs / auditoria

• Auditoria append-only em audit/audit-AAAA-MM-DD.jsonl.

• Registra ferramenta, decisão (allow/deny/executed/…), metadados e resultado — nunca conteúdo integral de arquivos nem segredos.

• Falha de escrita do log não derruba a operação (é silenciosa).

10. Desligamento de emergência

• Feche o processo do servidor (Ctrl+C, ou encerre a janela/serviço).

• Ao receber SIGINT/SIGTERM, o servidor mata todos os jobs (árvore de processos) e fecha as sessões HTTP antes de sair.

• Corte imediato do acesso remoto: pare o cloudflared (o túnel some).

• Revogação: troque o BRIDGE_TOKEN e reinicie.

11. Recuperação após erro

• Erros de rede/desconexão no HTTP são tratados e não derrubam o processo.

• Sessões HTTP ociosas expiram (30 min) e são limpas automaticamente.

• Rejeições não tratadas são apenas logadas em stderr.

• Se um job travar, use job_cancel; se o servidor cair, basta reiniciar (npm run start:http ou o cliente stdio) — o estado vive no disco (workspace).

12. Riscos de acesso total

Dar a uma IA acesso ao seu computador é poderoso e perigoso:

• No modo admin, quem tiver o token pode agir com os privilégios do processo.

• run_command/Docker não isolam o host.

• Um prompt malicioso ou uma sessão de navegador roubada pode disparar ações.

Mitigações: mantenha o modo safe por padrão; use aprovação local; rode admin em usuário/VM dedicados; exponha só atrás de VPN/Access; gire tokens; revise o audit/.

13. Multiplataforma

• Windows: suportado (setup.ps1, taskkill /T para matar árvore de processos).

• Linux / macOS: suportado (kill de grupo de processos via detached). Use caminhos POSIX no .env e nas configs dos clientes; o token pode ser gerado com node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".

• Symlinks: a jaula resolve o caminho real em todos os SOs (no Windows, a criação de symlink pode exigir modo desenvolvedor — não afeta a proteção).

14. Ferramentas

Arquivos e busca: get_workspace_info, list_dir, read_file (parcial: offset/limit/tail), read_multiple_files, get_file_info, write_file, edit_file (regex / todas ocorrências), make_dir, move_path, create_project, search_files, search_content (grep). Terminal e processos: run_command, run_job, job_status, job_output, job_write, job_cancel, list_processes, kill_process. Docker (admin): docker.

Comparação com o Desktop Commander

O Desktop Commander é excelente, mas só fala stdio (clientes locais). O Universal AI Bridge cobre o mesmo terreno de arquivos/terminal e vai além:

Fluxo de uso detalhado em SKILL.md. Política em config/policy.json.

Licença

MIT — veja LICENSE.