Skip to main content
Glama
Universal AI Bridge

Universal AI Bridge

by LMPrado-DZ23

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.

⬇️ Download (Windows)

Baixe o instalador pronto em Releases → UniversalAI-Bridge-Setup.exe. Execute, siga o assistente e conecte ao ChatGPT. (O .exe não é assinado; o SmartScreen pode pedir "Mais informações → Executar assim mesmo".)

Prefere rodar do código? Veja Instalação.


Related MCP server: Cloud Harness MCP

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


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'))"

Variável

Efeito

BRIDGE_MODE

safe (padrão) ou admin.

BRIDGE_ADMIN_ACK

Só admin: precisa ser I_UNDERSTAND_FULL_PC_ACCESS.

BRIDGE_TOKEN

Token Bearer do HTTP. Sem ele, o HTTP não sobe.

BRIDGE_PORT

Porta loopback (padrão 8787).

BRIDGE_ALLOWED_ORIGINS

Origins permitidos (CSV) — anti DNS-rebinding.

BRIDGE_WORKSPACE

Raiz jaulada. Vazio = ./workspace.

BRIDGE_APPROVAL

auto · confirm (padrão) · local.

BRIDGE_ALLOW_SHELL

true liga o terminal (obrigatório no safe).

BRIDGE_ALLOW_DOCKER

true libera Docker (só tem efeito no admin).


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. O endpoint MCP é https://.../mcp.

URL fixa (túnel nomeado): o túnel rápido muda de URL a cada reinício. Para uma URL estável, crie um túnel nomeado no painel da Cloudflare (requer sua conta + um domínio na Cloudflare), mapeie o hostname para http://127.0.0.1:8787, e ponha no .env:

CLOUDFLARE_TUNNEL_TOKEN=<token do túnel nomeado>
TUNNEL_HOSTNAME=bridge.seudominio.com

O launcher passa a usar cloudflared tunnel run --token … (URL fixa) em vez do túnel efêmero, automaticamente.

  • 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 e controle operacional

  • O token do HTTP fica em BRIDGE_TOKEN (no .env, git-ignored). Comparação em tempo constante; nunca é logado.

  • Rate limiting + lockout progressivo: requisições por IP são limitadas e um IP com muitas tentativas de token inválido é bloqueado por um tempo crescente.

  • Limite de sessões: BRIDGE_MAX_SESSIONS (padrão 20) simultâneas.

  • Ownership por sessão: cada sessão HTTP tem seu próprio conjunto de jobs, watches e variáveis — uma sessão não vê nem cancela jobs de outra.

  • Plano de controle LOCAL numa porta separada (BRIDGE_PORT+1, não encaminhada pelo túnel), protegido por BRIDGE_ADMIN_SECRET (<dados>/admin.secret). Ações:

    • POST /admin/rotate — gera um novo token (o antigo para de valer na hora).

    • POST /admin/revoke — revoga o token e fecha as sessões (bridge segue de pé).

    • POST /admin/panic — parada de emergência: mata jobs/watches, fecha sessões e revoga o token.

    • POST /admin/status — nº de sessões e se há token (sem segredos). O Painel de Controle (Windows) tem botões para tudo isso.

Honestidade: o controle é local (nesta máquina). Não há dashboard hospedado nem pareamento de dispositivos na nuvem — o túnel é só transporte. Se um token vazar, use Rotacionar ou Revogar no painel (ou o endpoint local) — não é preciso editar o .env à mão.

  • 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, read_media_file, write_file, edit_file (regex / todas ocorrências), make_dir, move_path, create_project, search_files, search_content (grep). Documentos (ler): read_pdf, read_docx, read_sheet (XLSX/CSV) — com paginação. Documentos (criar): write_sheet (XLSX/CSV), write_docx, write_pdf. Monitoramento e política: watch_start, watch_poll, watch_stop, get_policy. Terminal e processos: run_command, run_job, job_status, job_output, job_write, job_cancel, pty_start/pty_output/pty_write/pty_resize/pty_kill (terminal interativo real), list_processes, kill_process, set_env, unset_env, list_env. Modo admin: docker, manage_allowlist, download_to_file.

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:

Universal AI Bridge

Desktop Commander

IAs no navegador (ChatGPT/Claude.ai)

✅ MCP remoto + túnel

❌ só stdio

Modos safe/admin + policy + audit + aprovação local

✅

parcial

Instalador 1-clique (Windows)

✅

❌

Arquivos (ler parcial, multi, info, editar regex)

✅

✅

Busca por nome e conteúdo (grep)

✅

✅

Jobs longos/interativos/cancel + processos

✅

✅

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


Licença

MIT — veja LICENSE.

Available Tools

23 tools
create_projectCriar esqueleto de projetoB

Cria uma pasta de projeto com múltiplos arquivos de uma vez. files = { 'caminho': 'conteúdo' }. Sujeito a aprovação.

Inputs: name (required), files (required), confirm_token.

edit_fileEditar arquivo (substituição)B

Substitui a primeira ocorrência exata de old_text por new_text num arquivo existente. Sujeito a aprovação.

Inputs: path (required), new_text (required), old_text (required), is_regex, +2 more.

get_file_infoInfo de arquivo/pastaA

Metadados de um caminho: tipo, tamanho, datas de criação/modificação.

Inputs: path (required).

get_policyVer políticaA

Mostra allowlist, denylist e padrões bloqueados de comandos, e o modo atual.

Inputs: no named parameters.

get_workspace_infoInformações do workspaceA

Retorna nome do workspace, modo (safe/admin), aprovação e se shell/docker estão habilitados. Chame primeiro. Não revela o caminho absoluto por padrão (use include_absolute_path=true se precisar).

Inputs: include_absolute_path.

list_dirListar diretórioA

Lista arquivos e pastas de um diretório dentro do workspace.

Inputs: path.

make_dirCriar diretórioB

Cria um diretório (e pais) dentro do workspace.

Inputs: path (required), confirm_token.

move_pathMover / renomearA

Move ou renomeia um arquivo/pasta dentro do workspace. Sujeito a aprovação.

Inputs: to (required), from (required), confirm_token.

read_docxLer DOCX (texto)A

Extrai o texto de um arquivo .docx do workspace. Paginação por offset/limit de caracteres.

Inputs: path (required), limit, offset.

read_fileLer arquivoA

Lê um arquivo de texto do workspace. Suporta leitura parcial: offset_lines/limit_lines (fatia) ou tail_lines (últimas N linhas) para arquivos grandes.

Inputs: path (required), tail_lines, limit_lines, offset_lines.

read_media_fileLer imagem/binárioA

Lê um arquivo de imagem (retorna como imagem) ou outro binário (retorna base64). Respeita o limite de tamanho.

Inputs: path (required).

read_multiple_filesLer vários arquivosA

Lê vários arquivos de texto do workspace de uma vez.

Inputs: paths (required).

read_pdfLer PDF (texto)A

Extrai o texto de um PDF do workspace. Suporta paginação por offset/limit de caracteres.

Inputs: path (required), limit, offset.

read_sheetLer planilha (XLSX/CSV)A

Lê uma planilha .xlsx ou .csv do workspace e retorna as linhas como JSON. Paginação por offset/max_rows.

Inputs: path (required), sheet, offset, max_rows.

search_contentBuscar dentro de arquivos (grep)A

Procura texto/regex dentro dos arquivos do workspace e retorna arquivo:linha: trecho. Ignora .git/node_modules/dist, nao segue symlinks e pula binarios.

Inputs: query (required), max, path, is_regex, +1 more.

search_filesBuscar arquivos por nomeA

Procura arquivos cujo nome contem o termo (recursivo, ignora .git/node_modules/dist, nao segue symlinks).

Inputs: query (required), max, path.

watch_pollVer mudanças observadasA

Retorna e limpa os eventos acumulados de um watch (ou lista os watches se omitir watch_id).

Inputs: watch_id.

watch_startMonitorar arquivosC

Começa a observar um arquivo ou pasta do workspace. Retorna um watch_id.

Inputs: path, recursive.

watch_stopParar de monitorarB

Encerra um watch pelo watch_id.

Inputs: watch_id (required).

write_docxCriar DOCXA

Cria um .docx a partir de parágrafos (array de strings). Sujeito a aprovação.

Inputs: path (required), paragraphs (required), confirm_token.

write_fileEscrever arquivoA

Cria ou sobrescreve um arquivo de texto no workspace. Cria diretórios pais. Sujeito a política e aprovação.

Inputs: path (required), content (required), confirm_token.

write_pdfCriar PDFB

Cria um .pdf simples a partir de texto (uma linha por parágrafo). Sujeito a aprovação.

Inputs: path (required), text (required), font_size, confirm_token.

write_sheetCriar planilha (XLSX/CSV)A

Cria uma planilha .xlsx ou .csv (pela extensão) a partir de linhas (array de arrays). Sujeito a aprovação.

Inputs: path (required), rows (required), sheet, confirm_token.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 23 tools

    Disambiguation5/5

    Each tool targets a distinct action/resource pair: generic text reading, format-specific readers/writers, filesystem operations, search, watch, and policy/info. Even the similar-looking read_file and read_multiple_files are clearly separated by singular vs. batch purpose.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern such as read_file, write_sheet, watch_start, and search_content. The naming is predictable and makes the purpose of each tool easy to infer.

    Tool Count3/5

    With 23 tools, the server sits in the heavy range for a workspace file bridge. The count is understandable given the variety of file formats, watch operations, and search capabilities, but it still feels like more surface area than strictly necessary.

    Completeness3/5

    The toolset covers listing, reading, writing, editing, moving, searching, watching, and project creation well. However, there is no delete/remove operation for files or directories, and document-format writers are create-only, leaving a notable lifecycle gap.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Self-hosted MCP server that gives AI assistants a real Linux development environment: file editing, shell commands, tmux terminals, and browser screenshots, with bounded access through a project registry and write gates.
      39
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives any MCP-compatible AI chat or agent a safe, model-neutral coding runtime with file read/search, structured multi-file patches, command execution, interactive sessions, and git operations, all confined to a single workspace and gated by permission modes.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local-first MCP server that enables AI-assisted coding through workspace-scoped tools for file reading/editing, command execution, jobs, Git, LSP, media, browser, and desktop workflows. It enforces OAuth, workspace ACL, trust policies, and file/secret guards so owners can safely grant inspect, edit, or trusted capabilities.
      346 npm
      MIT