Workspace Tools (Automação e MCP)

O workspace Tools fornece a espinha dorsal de automação para o projeto Elo Orgânico. Ele centraliza servidores especializados de Model Context Protocol (MCP) e scripts de infraestrutura projetados para aumentar a produtividade dos desenvolvedores, garantir a paridade de ambiente por meio de compilações Docker multi-stage e permitir fluxos de trabalho de engenharia AI-native seguros e de alto contexto.

Ecossistema MCP

Ecossistema Model Context Protocol (MCP)

O monorepo Elo Orgânico apresenta um ecossistema MCP especializado e conteinerizado. Ele expõe capacidades de desenvolvimento estruturadas e contextos da base de código para clientes LLM (como o Antigravity CLI ou agentes externos) por meio de uma rede de gateway segura e de alto desempenho.

Adaptadores TypeScript Zero-Dependency

Servidores MCP padrão baseados em CLI se comunicam via fluxos de entrada/saída padrão (stdio). Para expô-los com segurança pela rede, cada serviço é empacotado com um wrapper TypeScript personalizado (sse-adapter.ts) executado no Fastify v5. Este adaptador implementa dois protocolos de rede distintos:

• Server-Sent Events (SSE) Tradicional: Estabelece um fluxo unidirecional persistente via GET /sse e aceita mensagens do cliente via POST /messages, direcionando eventos diretamente para a entrada padrão (stdin) do subprocesso subjacente.
• HTTP Streamable Stateless (POST /sse): Um adaptador transacional personalizado que simula requisição-resposta sem estado. Ele armazena as linhas de stdout do processo filho, extrai payloads JSON-RPC e resolve a requisição HTTP apenas quando captura o id da resposta JSON-RPC específico correspondente à requisição. Notificações (requisições sem um id) recebem uma resposta imediata 204 No Content.

Servidores de Contexto Integrados

Servidor MCP do GitHub

Visão Geral e Utilidade do Projeto

O servidor MCP do GitHub conecta nosso ambiente de desenvolvimento conteinerizado diretamente à API do GitHub. Ele permite que agentes de IA coordenem tarefas de controle de versão, gerenciem ciclos de vida de issues e realizem pesquisas de código ou revisões automatizadas de pull requests.

• Upstream: http://elo-mcp-github:3001/github/sse

Registro de Ferramentas e Capacidades

• search_repositories: Pesquisar repositórios que correspondam a uma consulta.
• create_repository: Criar um novo repositório no GitHub.
• search_code: Pesquisar trechos de código em repositórios.
• search_issues: Pesquisar issues e pull requests.
• search_commits: Pesquisar históricos de commits.
• create_branch: Criar um novo branch no Git.
• list_branches: Recuperar a lista de todos os branches no repositório.
• update_pull_request_branch: Atualizar um branch de pull request para mantê-lo em sincronia com o base.
• get_commit: Recuperar informações detalhadas para um commit específico.
• list_commits: Listar commits em um branch.
• get_tag: Obter detalhes de metadados para uma tag Git.
• list_tags: Listar todas as tags em um repositório.
• get_file_contents: Recuperar o conteúdo de um arquivo ou diretório específico.
• create_or_update_file: Gravar ou atualizar um arquivo no repositório.
• delete_file: Excluir um arquivo de um branch.
• push_files: Commit e push de múltiplos arquivos em uma única transação.
• issue_read: Visualizar detalhes de uma issue específica.
• issue_write: Criar ou atualizar uma issue.
• sub_issue_write: Adicionar relações de sub-issue.
• add_issue_comment: Adicionar um comentário a uma issue ou pull request.
• list_issues: Listar issues no repositório.
• list_issue_types: Listar tipos de issues suportados.
• pull_request_read: Visualizar detalhes de um pull request específico.
• create_pull_request: Abrir um novo pull request.
• update_pull_request: Atualizar metadados de um pull request.
• list_pull_requests: Listar pull requests no repositório.
• merge_pull_request: Fazer o merge de um pull request usando o método de merge especificado.
• add_comment_to_pending_review: Adicionar comentários a uma revisão de pull request pendente.
• add_reply_to_pull_request_comment: Responder a um comentário inline em uma revisão de pull request.
• pull_request_review_write: Enviar uma revisão de pull request.
• request_copilot_review: Solicitar uma revisão do GitHub Copilot.
• assign_copilot_to_issue: Atribuir o GitHub Copilot para resolver uma issue.
• get_latest_release: Obter a última release publicada.
• get_release_by_tag: Recuperar uma release pela sua tag Git.
• list_releases: Listar releases no repositório.
• get_label: Obter informações sobre uma label de repositório.
• list_repository_collaborators: Listar colaboradores de um repositório.
• get_me: Obter informações sobre o usuário autenticado.
• get_teams: Listar equipes na organização.
• get_team_members: Listar membros de uma equipe específica.
• fork_repository: Criar um fork de um repositório na sua conta.

Servidor MCP Context7

Visão Geral e Utilidade do Projeto

O servidor MCP Context7 faz a interface com a API Context7 para fornecer pesquisas de documentação em tempo real. Este é um mecanismo de contexto crítico para os agentes de IA consultarem as sintaxes de API mais recentes, padrões de uso e alterações de versão das nossas dependências principais (React 19, Fastify 5, Three.js) sem depender de dados de treinamento de modelo desatualizados.

• Upstream: http://elo-mcp-context7:3002/context7/sse

Registro de Ferramentas e Capacidades

• resolve-library-id: Resolve o nome de um pacote ou biblioteca para um ID exclusivo compatível com o Context7.
• query-docs: Recupera seções de documentação atualizadas, métodos de API e exemplos de código para um ID de biblioteca resolvido.

Servidor MCP do Navegador (Playwright)

Visão Geral e Utilidade do Projeto

O servidor MCP do Navegador é uma instância do Google Chrome headless gerenciada via Playwright. Ele permite que os agentes de IA interajam diretamente com as interfaces web do projeto, viabilizando verificações de regressão visual, auditoria de erros no console, inspeção da árvore de acessibilidade e análise de requisições de rede em um sandbox totalmente conteinerizado.

• Upstream: http://elo-mcp-browser:3003/browser/sse
• Roteamento Host-para-Container: Reescreve automaticamente as URLs de destino apontando para localhost ou 127.0.0.1 para host.docker.internal para rotear as requisições com sucesso do container bridge para a máquina host (ex: acessando o Docusaurus na porta 3002 ou a app React na porta 5173).

Registro de Ferramentas e Capacidades

• browser_navigate: Navegar para uma URL específica.
• browser_navigate_back: Navegar de volta para a página anterior no histórico.
• browser_wait_for: Pausar a execução até que um seletor específico ou estado da página seja resolvido.
• browser_click: Simular o clique em um elemento DOM correspondente a um seletor.
• browser_hover: Passar o ponteiro do mouse sobre um elemento específico.
• browser_type: Digitar texto em um campo de entrada.
• browser_fill_form: Preencher múltiplos campos de entrada em um formulário.
• browser_select_option: Selecionar opções em um elemento select dropdown.
• browser_press_key: Simular o pressionamento de uma tecla específica do teclado.
• browser_drag: Arrastar um elemento e soltá-lo sobre outro elemento.
• browser_drop: Soltar um arquivo ou elemento no local de destino.
• browser_file_upload: Fazer o upload de um arquivo para um elemento de entrada de arquivo.
• browser_take_screenshot: Capturar e salvar um screenshot do viewport da página atual.
• browser_snapshot: Capturar um instantâneo do DOM da página ou da árvore de acessibilidade.
• browser_console_messages: Recuperar logs e erros emitidos pelo console do navegador.
• browser_network_requests: Listar todas as requisições de rede iniciadas pela página.
• browser_network_request: Recuperar detalhes de uma requisição/resposta de rede específica.
• browser_tabs: Listar abas ativas do navegador.
• browser_handle_dialog: Aceitar, dispensar ou responder a popups de diálogo nativos do navegador.
• browser_evaluate: Executar código JavaScript personalizado no contexto da página.
• browser_run_code_unsafe: Executar código Node.js arbitrário dentro do sandbox do container.
• browser_close: Fechar a instância do navegador.
• browser_resize: Redimensionar as dimensões do viewport.

Servidor MCP Docker Hub

Visão Geral e Utilidade do Projeto

O servidor MCP do Docker Hub gerencia interações com o registro do Docker Hub. Ele permite que o sistema descubra imagens, verifique tags e inspecione metadados de repositórios de containers, garantindo que nossa infraestrutura de monorepo permaneça alinhada com as imagens de containers upstream.

• Upstream: http://elo-mcp-dockerhub:3004/dockerhub/sse

Registro de Ferramentas e Capacidades

• search: Pesquisar repositórios no Docker Hub.
• getRepositoryInfo: Recuperar informações de metadados para um repositório específico.
• updateRepositoryInfo: Atualizar detalhes de metadados de um repositório.
• checkRepository: Verificar se um repositório existe no Docker Hub.
• listRepositoryTags: Recuperar a lista de todas as tags de um repositório.
• getRepositoryTag: Obter metadados detalhados para uma tag de imagem específica.
• checkRepositoryTag: Verificar se existe uma tag de imagem específica.
• listNamespaces: Listar namespaces acessíveis pelo usuário.
• getPersonalNamespace: Obter o namespace pessoal do usuário autenticado.
• listAllNamespacesMemberOf: Listar todas as organizações/namespaces dos quais o usuário é membro.
• dockerHardenedImages: Buscar uma lista de imagens base recomendadas com segurança reforçada.

Agentes de IA (Docker)

Agentes de IA Conteinerizados

O workspace tools/agents provisiona as CLIs do GitHub Copilot e do Google Antigravity como serviços Docker de longa execução. Isso elimina as instalações manuais de CLI nas máquinas host dos desenvolvedores e garante a paridade de ambiente entre estações de trabalho locais e VMs na nuvem.

Visão Geral da Arquitetura

Os containers de agentes são executados dentro da mesma rede bridge elo-mcp-net que o gateway MCP, comunicando-se com ele por meio de roteamento de DNS interno. Nenhuma exposição de porta no nível do host é necessária para a comunicação entre serviços.

Estrutura de Diretórios

tools/agents/
├── .env.agents.example     # Modelo de variáveis de ambiente (rastreado)
├── .env.agents             # Segredos (ignorado pelo Git)
├── compose.yaml            # Orquestração para ambos os containers de agentes
├── mcp_config.json         # Configuração MCP unificada (injetada em ambos os containers)
├── skills/                 # Skills de agentes compartilhadas (injetadas em ambos os containers)
│   ├── code-expert/
│   └── doc-expert/
├── copilot/
│   ├── Dockerfile          # GitHub CLI + Copilot CLI + Docker CLI
│   ├── data/               # Ignorado pelo Git: estado da sessão do Copilot e tokens de autenticação
│   └── gh-config/          # Ignorado pelo Git: credenciais e extensões da CLI do GitHub
└── antigravity/
    ├── Dockerfile          # Antigravity CLI + Docker CLI
    ├── data/               # Ignorado pelo Git: conversas, estado do cérebro, buffers de log
    ├── settings.json       # Configurações da TUI controladas por versão (caminhos do container)
    ├── statusline.sh       # Script da barra de status da CLI
    └── title.sh            # Script do título da janela da CLI

Estratégia de Injeção de Configuração

Todas as configurações são injetadas via montagens bind do Docker na inicialização do container. Nenhum arquivo é embutido nas camadas de imagem, garantindo que as alterações de configuração tenham efeito sem a necessidade de reconstruir as imagens.

Origem da Montagem	Destino no Container	Objetivo
../../	/workspace	Diretório de trabalho completo do monorepo
./skills/	/workspace/.agents/skills	Skills compartilhadas visíveis para ambas as CLIs
./mcp_config.json	/workspace/.agents/mcp_config.json	Configuração unificada de endpoint MCP
./antigravity/data/	/root/.gemini/antigravity-cli/	Dados dinâmicos de tempo de execução persistentes
./antigravity/settings.json	/root/.gemini/antigravity-cli/settings.json	Configurações da TUI controladas por versão
./copilot/data/	/root/.copilot/	Estado de sessão persistente do Copilot
./copilot/gh-config/	/root/.config/gh/	Credenciais persistentes da CLI do GitHub
/var/run/docker.sock	/var/run/docker.sock	Orquestração Docker-out-of-Docker
~/.ssh	/root/.ssh (somente leitura)	Chaves SSH do host para operações Git
~/.gitconfig	/root/.gitconfig (somente leitura)	Identidade Git do host

Conectividade de Rede MCP

Dentro dos containers de agentes, os serviços MCP são resolvidos por meio do gateway do host usando o alias personalizado elo.internal.tools.mcp mapeado para host-gateway na porta 3005. Isso permite que a stack de agentes seja iniciada de forma totalmente independente da stack MCP.

{
  "mcpServers": {
    "github":    { "url": "http://elo.internal.tools.mcp:3005/github/sse" },
    "context7":  { "url": "http://elo.internal.tools.mcp:3005/context7/sse" },
    "browser":   { "url": "http://elo.internal.tools.mcp:3005/browser/sse" },
    "dockerhub": { "url": "http://elo.internal.tools.mcp:3005/dockerhub/sse" }
  }
}

Sequência de Inicialização Independente

As stacks de agentes e MCP são desacopladas ao nível de rede. Qualquer uma das stacks pode ser iniciada ou parada de forma independente. Os agentes se conectarão automaticamente ao gateway MCP assim que a stack MCP estiver em execução.

Comandos de Ciclo de Vida

Comando	Ação
pnpm agents:up	Compilar as imagens (se necessário) e iniciar ambos os containers de agentes em modo detached.
pnpm agents:down	Parar e remover os containers de agentes.
pnpm agents:reset	Remoção completa com exclusão de volumes, seguida de compilação limpa e reinicialização.
pnpm antigravity:auth	Executar o fluxo de autenticação Google OAuth na janela de terminal ativa.
pnpm copilot:auth	Executar o fluxo de autenticação GitHub OAuth device na janela de terminal ativa.

Integração de Tarefas do VS Code

As CLIs de agentes são invocados por meio de tarefas docker exec registradas em .vscode/tasks.json. As tarefas são rotuladas com o prefixo [Docker] ou [Host] para distinguir a execução conteinerizada das instalações globais da máquina host.

Rótulo da Tarefa	Alvo de Execução
[Docker] Antigravity CLI	docker exec -it agent-antigravity agy
[Docker] Copilot CLI	docker exec -it agent-copilot copilot
[Host] Antigravity CLI	Instalação global do agy no host
[Host] Copilot CLI	Instalação global do copilot no host

Autenticação e Persistência de Sessão

Ambas as CLIs usam autenticação OAuth device-flow. Para autenticar os agentes conteinerizados, execute os scripts de autenticação direta (pnpm copilot:auth ou pnpm antigravity:auth) no seu terminal ativo. A CLI exibe uma URL e um código de verificação. O desenvolvedor abre a URL no navegador do host, conclui o fluxo de autorização e os tokens resultantes são gravados no diretório home do container.

Armazenamento Persistente e Arquitetura Sem Reconstrução

Como os diretórios de credenciais são montados via bind mount para o host:

• agent-copilot monta ./copilot/data/ para /root/.copilot/ e ./copilot/gh-config/ para /root/.config/gh/
• agent-antigravity monta ./antigravity/data/ para /root/.gemini/antigravity-cli/

Qualquer token de autenticação gerado durante a configuração inicial é gravado diretamente nesses diretórios do host em tempo real. Como resultado:

• Nenhuma reconstrução de container é necessária: Reconstruir ou reiniciar o container não apaga as credenciais, pois o container lê os tokens dinamicamente dos volumes montados no host.
• Isolamento do Host: Embora o container esteja autenticado, essas credenciais não vazam para as pastas globais do usuário no host (ex: ~/.gemini ou ~/.config/gh), garantindo uma separação limpa entre a stack de containers e as instalações globais de CLI do host.
• Acesso Sincronizado Automático: Assim que o usuário conclui o fluxo de autorização do dispositivo, as credenciais tornam-se imediatamente ativas e funcionais. Nenhuma cópia manual de arquivos ou reinicialização é necessária.

observação

Os diretórios data/ e gh-config/ são ignorados pelo Git. Eles existem apenas na máquina local do desenvolvedor e nunca são commitados no repositório.

Segurança de IA e Rede

Infraestrutura Isolada e Roteamento de Rede

A segurança e a previsibilidade do ambiente são mantidas por meio de redes bridge do Docker isoladas (elo-agents-net para agentes e elo-mcp-net para ferramentas MCP), evitando o acesso não autorizado entre redes.

Configuração de Gateway e Roteamento

• Gateway Proxy HTTP Fastify: Um servidor Fastify v5 leve (elo-mcp-gateway) executado em Node.js serve como ponto de entrada. Ele expõe a porta 3005 para a máquina host. Usando o @fastify/http-proxy, ele encaminha prefixos de rotas (ex: /github) para os respectivos containers de backend.
• Tratamento de CORS e SSE no nível da rede: O gateway intercepta requisições OPTIONS e injeta os cabeçalhos CORS apropriados globalmente. Ele desativa os timeouts HTTP padrão nos proxies para evitar que as conexões ativas de Server-Sent Events (SSE) caiam durante tarefas de longa duração.
• Roteamento de Domínio Interno: Dentro da stack MCP, o gateway é apelidado como elo.internal.tools.mcp. Containers de agentes executados em namespaces de rede separados podem rotear requisições diretamente através de http://elo.internal.tools.mcp:3005/[service]/sse via mapeamento de ponte do host.
• Ponte Host-para-Container: Clientes de desenvolvimento local (como o Google Antigravity CLI) se comunicam com o gateway a partir da interface de loopback da máquina host usando:

  http://localhost:3005/github/sse

• Mapeamento de Fluxo stdio Bufferizado: O wrapper executa processos filhos localmente, evitando a fragmentação do stdout. Ao verificar os ids das transações JSON-RPC linha por linha, o adaptador resolve as requisições HTTP com payloads completos e sem truncamento.

Diretrizes de Engenharia

Regras de Engajamento para Agentes de IA

O workspace define diretrizes estritas de comportamento para agentes de IA por meio de arquivos de contexto estruturados. Estas diretrizes garantem que todas as alterações automatizadas sigam os padrões arquiteturais de todo o projeto e mantenham a integridade técnica.

Convenções Operacionais

• Core do Domínio Primeiro: A modificação de esquemas ou modelos de dados compartilhados deve originar-se nos pacotes core (Fonte Única de Verdade) antes de ser propagada para as camadas de aplicação.
• Tipagem e Linting Estritos: Os agentes são estritamente proibidos de usar any ou ignorar as configurações rigorosas de TypeScript/ESLint do projeto. A validação via typecheck é uma etapa obrigatória após qualquer modificação de código.
• Minimalismo Tecnológico: Evite sugerir dependências externas, a menos que nenhuma solução nativa ou já implementada exista dentro da stack atual (Fastify, React, Zustand, Zod).
• Documentação Convencional: As atualizações de documentação devem seguir um tom profissional e sênior, utilizando recursos do MDX como Tabs para gerenciamento de informações de alta densidade.

Manutenção e Lógica

Lógica Operacional e Manutenção

Comandos padronizados são fornecidos para manter a camada de automação e verificar a integridade dos workspaces em todo o monorepo.

Comando	Responsabilidade de Engenharia
pnpm typecheck	Valida a integridade do TypeScript em scripts e código fonte do MCP.
pnpm build	Compilação completa de produção, incluindo servidores MCP e ferramentas de automação.
pnpm clean	Manutenção agressiva do workspace usando npkill para podar dependências antigas.

Orquestração do Workspace

Comando	Ação de Engenharia
pnpm mcp:up	Inicializa todo o gateway conteinerizado e a stack do backend MCP.
pnpm mcp:down	Interrompe e remove o gateway e o ambiente de containers MCP.
pnpm mcp:reset	Limpeza agressiva da stack (volumes removidos) seguida de reconstrução completa de containers.

Estrutura do Workspace

• tools/mcp/compose.yaml: Define os serviços de container, dependências, volumes e redes bridge.
• tools/mcp/gateway/: Contém o servidor proxy de roteamento HTTP Fastify v5 (server.ts e seu Dockerfile).
• tools/mcp/infrastructure/: Contém Dockerfiles multi-stage individuais e o wrapper zero-dependency sse-adapter.ts.
• tools/mcp/config/: Gerencia ambientes específicos de contexto e configurações de segredos (ex: arquivos .env.*.example).