GBR: ADR-0006 Adaptador Universal MCP via Erlang Ports (JSON-RPC/Stdio) (Proposto)

• *Status:* Feito(2026-05-17)
• *Data:* 2026-05-14

*Contexto:*

A versão atual do gleambr_ai executa ferramentas do Model Context Protocol (MCP) de forma "embutida" (Embedded), invocando módulos Gleam nativos diretamente (ex: filesystem.gleam). No entanto, o ecossistema global de MCP (Anthropic, OpenCode, integrações de BD) distribui seus servidores como binários independentes ou scripts (Node.js, Python) que se comunicam estritamente via JSON-RPC 2.0 sobre canais de I/O Padrão (stdin e stdout). Para que nosso Agente não fique isolado e possa alavancar ferramentas de terceiros, precisamos de uma ponte de comunicação assíncrona com processos do Sistema Operacional hospedeiro.

*Decisão:*

Implementaremos o *Driver Universal MCP* encapsulado no Ator mcp_client_worker.

1. *Gerenciamento de Processos:* Utilizaremos o mecanismo nativo erlang:open_port/2 com a opção {spawn, Command} para iniciar e supervisionar servidores MCP externos (ex: binários do OpenCode).
2. *Comunicação Assíncrona:* O Ator enviará requisições JSON-RPC injetando payloads na porta (que são roteados para o stdin do processo filho) e escutará mensagens da caixa de correio Erlang geradas pelo stdout do filho.
3. *Framing LSP:* Implementaremos um decodificador de fluxo (Stream Decoder) para processar os cabeçalhos Content-Length: <size>\r\n\r\n obrigatórios do protocolo, garantindo que o buffer em Gleam acumule os bytes exatos antes da decodificação do JSON.
4. *Descoberta Dinâmica:* Ao iniciar, o mcp_client_worker executará o handshake tools/list e repassará as capacidades descobertas para o Ator do Cérebro (llm_session_worker) atualizar seu prompt de sistema.

*Consequências:*

• *Positivas:* Desacoplamento absoluto. O gleambr_ai poderá utilizar qualquer ferramenta MCP do mercado sem que precisemos reescrever a integração nativamente em Gleam; aumento colossal das capacidades do Agente.
• *Negativas:* Necessidade de gerenciar a resiliência de processos do SO (o servidor Node.js pode consumir muita RAM ou ficar zumbi se o Erlang não matar a porta corretamente); exige o desenvolvimento de um parser de cabeçalhos binários.