ADR 0035: Estratégia Híbrida de Contexto para Servidores MCP

• *Status:* Aceito
• *Data:* 2026-06-11

Contexto

O ecossistema gleam-lang-br está migrando de servidores MCP em Python para implementações nativas em Gleam (gbr_mcp_lsp_gleam e gbr_mcp_gleam). O orquestrador AI (gbr_ai_gleam) precisa informar aos servidores MCP em qual projeto do monorepo ele está trabalhando no momento (o rootUri ou project_path).

O problema: 1. Caminhos absolutos (ex: C:\Users\...) no código do servidor geram acoplamento rígido ao ambiente do desenvolvedor, quebrando a portabilidade e a DX (Developer Experience). 2. O protocolo MCP oficial introduz capacidades de roots e de injeção experimental na requisição Initialize, mas a biblioteca core gbr_mcp esconde o handshake do ciclo de vida das ferramentas, inviabilizando a leitura sem criar complexidade e estado global (handlers impuros). 3. O ciclo de vida do compilador/LSP exige o rootUri antes da inicialização das ferramentas, tornando a injeção posterior (via CallTool) ineficiente ou suscetível a timeout no cliente de LSP.

Decisão

Adotamos a *Estratégia Híbrida de Injeção no Spawn*:

1. *Abstração do Spawn*: O Orquestrador (Client) injetará o contexto (project_path) de forma transparente e segura via *Variáveis de Ambiente* (GLEAM_BR_WORKSPACE) ao criar a Porta do SO (port.start) para o subprocesso do servidor LSP.
2. *Separação de Ciclos de Vida: - Para o *LSP (gbr_mcp_lsp_gleam)**: O contexto é estático para a vida do processo. Ao nascer, o main() do servidor captura o ENV, inicia a árvore de supervisão (Ator LspClient) e em seguida entra em loop bloqueante (stdio.start) sem ferir a pureza arquitetural da biblioteca gbr_mcp. - Para **Ferramentas (gbr_mcp_gleam)**: Como as ferramentas de build/test mudam de contexto dinamicamente, mantemos a injeção explícita de project_path na interface RPC da ferramenta.
3. *Pureza da Biblioteca Base*: É terminantemente evitada a alteração das estruturas geradas pelo defs.gleam e do fluxo core do gbr_mcp.

Consequências

• *Desacoplamento Seguro*: O servidor nunca se baseia em caminhos físicos estáticos no código, e os subprocessos operam em containeres isolados de ambiente através de ports Erlang.
• *Port.Env Atualizado*: A biblioteca gbr_os sofreu uma mutação (port.Env setting) para suportar injeção de ENV transparente ao processo filho.
• *Evolução Contínua*: O design nos permite transicionar futuramente para a implementação total do Handshake roots assim que o gerador de JSON Schema e o parse da Anthropic (2025-11-25) amadurecerem no monorepo, sem modificar os atores de negócio.