Universal AI Bridge
This server is an MCP-based tool that lets an AI manage files and run commands on your computer, with security controls (safe/admin modes), auditing, and support for local (stdio) and remote (HTTP) clients.
Workspace info: Get name, mode (safe/admin), approval mode, and whether shell/Docker are enabled (optionally include absolute path).
File operations: List directories, read text files (full, partial by offset/limit, or tail), read multiple files at once, get file/dir metadata, write files (with parent dir creation), edit files (exact or regex replacement, all occurrences), create directories, move/rename paths, and create a project skeleton with multiple files at once.
Search: Find files by name (recursive, max 1000 results) and search file contents with regex, case-insensitivity, and max 2000 results.
Media and documents: Read images (returned as image) or other binaries (base64), extract text from PDFs, DOCX, and spreadsheets (XLSX/CSV) with pagination; create XLSX/CSV spreadsheets, DOCX documents, and simple PDFs from text.
File watching: Start watching a file/folder for changes, poll for accumulated events, and stop watching.
Policy: View the current allowlist, denylist, blocked command patterns, and mode.
Allows running Docker commands (e.g., docker build) on the host in admin mode, with Docker access controlled by configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Universal AI Bridge Create a new Node.js project in my workspace and run npm install"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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 (
confirmoulocal).
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 buildNo Windows, um atalho faz install + build + gera o .env com token criptográfico:
powershell -ExecutionPolicy Bypass -File .\setup.ps13. 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 |
|
|
| Só admin: precisa ser |
| Token Bearer do HTTP. Sem ele, o HTTP não sobe. |
| Porta loopback (padrão 8787). |
| Origins permitidos (CSV) — anti DNS-rebinding. |
| Raiz jaulada. Vazio = |
|
|
|
|
|
|
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.jsonsobmcpServers.
5. ChatGPT / Claude.ai no navegador (HTTP + túnel)
O navegador só conecta em MCP remoto (HTTPS).
npm run start:httpEscuta só em http://127.0.0.1:8787/mcp. Exponha com cloudflared:
cloudflared tunnel --url http://127.0.0.1:8787O 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.comO 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
/mcpe headerAuthorization: Bearer <BRIDGE_TOKEN>.Claude.ai (Settings → Connectors → custom): mesma URL e header.
Cole o conteúdo de
SKILL.mdnas 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_commandexecuta e espera terminar.Tarefa longa / streaming:
run_jobretorna umjob_id;job_outputdevolve a saída incremental (passe os cursores retornados para acompanhar em tempo real).Interativo:
job_writeenvia texto ao stdin do processo.Cancelamento:
job_cancelencerra o job e toda a árvore de processos-filho (taskkill /Tno Windows, kill de grupo no POSIX).
Só binários da allowlist (config/policy.json) rodam; encadeamento e
redirecionamento (&& | ; > <) são bloqueados.
run_command/run_jobnã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 porBRIDGE_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_TOKENe 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:httpou 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 /Tpara matar árvore de processos).Linux / macOS: suportado (kill de grupo de processos via
detached). Use caminhos POSIX no.enve nas configs dos clientes; o token pode ser gerado comnode -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 toolscreate_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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
A full backend your AI coding agent can set up over MCP
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseAqualityBmaintenanceSelf-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.39MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to securely operate isolated coding workspaces with file, command, Git, and deployment tools via authenticated remote MCP.110MIT
- AlicenseNot gradedqualityCmaintenanceGives 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
- AlicenseNot gradedqualityBmaintenanceA 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 npmMIT