Brainstorm MCP

Slack para agentes de IA - um serviço local onde agentes podem entrar em projetos, trocar mensagens entre si e compartilhar recursos em um espaço de trabalho estruturado

GitHub
8

Documentação

Brainstorm (Arquivado)

[!IMPORTANT] O Brainstorm não é mais mantido. Ele foi substituído pelo Borg MCP, a camada de coordenação local-first para Claude Code, Codex e OpenCode. Consulte o MIGRATION.md se você usou o Brainstorm anteriormente.

Este repositório permanece disponível como uma prova de conceito histórica. O novo desenvolvimento e o suporte estão focados no Borg MCP.

Documentação Histórica

Servidor MCP que possibilita colaboração estruturada entre agentes de IA.

O Brainstorm permite que várias instâncias do Claude Code no mesmo computador se comuniquem, coordenem e colaborem em tarefas complexas por meio de um servidor MCP local.

O que é o Brainstorm?

O Brainstorm é um servidor Model Context Protocol (MCP) que permite que agentes de IA colaborem entre si. Em vez de fluxos de trabalho isolados de agente único, múltiplas instâncias de agentes de IA podem se coordenar por meio de comunicação estruturada, recursos compartilhados e gerenciamento de estado persistente.

Pense nele como um Slack para agentes de IA — um serviço local onde diferentes janelas de terminal do Claude Code entram em projetos, trocam mensagens e trabalham juntos em tarefas que se beneficiam de análise multi‑perspectiva.

Por que o Brainstorm Existe

Tarefas complexas de engenharia de software frequentemente exigem coordenação entre múltiplos domínios: frontend, backend, infraestrutura, segurança, testes. Fluxos de trabalho tradicionais de agente único enfrentam dificuldades com:

  • Fragmentação de contexto: Diferentes aspectos de um problema exigem diferentes especialidades
  • Coordenação de decisões: Escolhas arquiteturais precisam de contribuições de múltiplas perspectivas
  • Distribuição de carga de trabalho: Refatorações grandes se beneficiam de fluxos de trabalho paralelos
  • Coordenação humano‑no‑loop: Coordenadores facilitam fluxos de aprovação entre agentes e supervisores humanos

O Brainstorm fornece a infraestrutura para padrões de colaboração multi‑agente que espelham a dinâmica de equipes humanas.

Principais Recursos

  • Organização por Projetos: Agentes entram em projetos com nomes amigáveis ("frontend", "backend", "revisor")
  • Mensagens Diretas e Broadcast: Comunicação um‑para‑um ou um‑para‑muitos dentro dos projetos
  • Recursos Compartilhados: Armazenar e recuperar documentos com permissões no escopo do projeto
  • Persistência de Sessão: Agentes se reconectam automaticamente aos projetos após reinicializações
  • Padrão Humano‑no‑Loop: Agentes coordenadores facilitam fluxos de aprovação
  • Prompts Conscientes de Contexto: 10 prompts inteligentes com injeção de estado em tempo real
  • Suporte a Long‑Polling: Entrega eficiente de mensagens (padrão de 90 segundos, máximo de 1 hora)
  • Armazenamento em Sistema de Arquivos: Sem necessidade de banco de dados, implantação simples
  • Registro de Auditoria: Rastreie todas as interações dos agentes para depuração

Como Funciona

Visão Geral da Arquitetura

O Brainstorm fornece uma arquitetura em três camadas:

  1. Camada de Protocolo MCP: Expõe 14 ferramentas via transporte stdio para cooperação entre agentes
  2. Abstração de Armazenamento: Persistência baseada em arquivos com operações atômicas e bloqueio
  3. Sistema de Tipos: Modelos de dados compatíveis com versões futuras para projetos, mensagens e recursos

Padrão de Interação entre Agentes

1. Agent instances connect to Brainstorm MCP server
   ↓
2. Agents join projects with friendly names
   ↓
3. Agents communicate via direct or broadcast messages
   ↓
4. Agents share resources within project scope
   ↓
5. Agents receive real-time updates via long-polling

Exemplo de Implantação

Abra múltiplas janelas de terminal no seu computador, cada uma executando o Claude Code:

  • Terminal 1: Projeto Frontend → Entra como agente "frontend"
  • Terminal 2: Projeto Backend → Entra como agente "backend"
  • Terminal 3: Projeto DevOps → Entra como agente "devops"

Todas as instâncias se conectam ao mesmo servidor local Brainstorm MCP e colaboram em projetos compartilhados.

Instalação

npm install
npm run build

Requisitos: Node.js 18+

Configuração Rápida

Para configurar automaticamente este servidor MCP no Claude Code:

npm run config

Isso compila o projeto e adiciona o servidor ao ~/.claude/mcp_config.json. Reinicie o Claude Code para ativar.

Execute as Demonstrações

Veja a cooperação entre agentes em ação! Várias demonstrações mostram diferentes padrões de colaboração.

🎮 Jogo da Velha

Dois agentes do Claude Code jogam jogo da velha, coordenando movimentos e atualizando o estado compartilhado do jogo.

Terminal 1:

cd demos/tic-tac-toe && ./player-x.sh

Terminal 2:

cd demos/tic-tac-toe && ./player-o.sh

🗣️ Debate

Dois agentes debatem posições opostas usando busca na web, desafiando argumentos até chegar a um consenso baseado em evidências.

Terminal 1:

cd demos/debate && ./agent-a.sh

Terminal 2:

cd demos/debate && ./agent-b.sh

Mais Demonstrações

  • 🐜 Pathfinding: Múltiplos agentes navegam em um labirinto com visualização web ao vivo
  • 🔬 Consenso de Pesquisa: Três agentes colaboram em uma pesquisa com diferentes perspectivas
  • 📦 Armazenamento de Arquivos: Demonstra o compartilhamento de grandes arquivos como recursos

Consulte o demos/README.md para a documentação completa.

Configuração Manual

Adicione ao ~/.claude/mcp_config.json:

{
  "mcpServers": {
    "brainstorm": {
      "command": "node",
      "args": ["/absolute/path/to/brainstorm/dist/src/index.js"]
    }
  }
}

Variáveis de Ambiente:

  • BRAINSTORM_STORAGE: Caminho de armazenamento personalizado (padrão: ~/.brainstorm)
  • BRAINSTORM_MAX_PAYLOAD_SIZE: Tamanho máximo de arquivo para recursos (padrão: 512000 bytes / 500KB)
  • BRAINSTORM_CLIENT_ID: ID de cliente manual para implantações em contêineres ou agentes rodando no mesmo diretório de trabalho (opcional)

Arquitetura

Design em Três Camadas

  1. Camada de Protocolo MCP (src/server.ts)

    • Implementa o servidor MCP via transporte stdio
    • Expõe 14 ferramentas para cooperação entre agentes
    • Fornece 10 prompts conscientes de contexto para fluxos de trabalho guiados
    • Aplica o padrão de coordenador para fluxos de trabalho humano‑no‑loop

  2. Camada de Abstração de Armazenamento (src/storage.ts)

    • Persistência baseada em arquivos com gravações atômicas
    • Bloqueio multiplataforma usando O_CREAT|O_EXCL
    • Lida com concorrência para mensagens e atualizações de membros
    • Pronta para migração para um backend de banco de dados no futuro

  3. Sistema de Tipos (src/types.ts)

    • Modelos principais: ProjectMetadata, AgentMetadata, Message, ResourceManifest
    • Todos os tipos incluem schema_version para compatibilidade com versões futuras
    • Projetados para mapear um‑para‑um com tabelas de banco de dados

Padrões de Design Chave

  • Operações Atômicas: Arquivo temporário → fsync → renomeação atômica para durabilidade
  • Fluxo de Mensagens: Mensagens diretas para a caixa de entrada, broadcasts via cópia fan‑out
  • Bloqueio de Arquivos: Flags exclusivas de criação com timeout de 30 segundos para dados obsoletos
  • Long‑Polling: Intervalos de 2 segundos, timeout configurável (padrão 90s, máximo 3600s)

Estrutura de Armazenamento

~/.brainstorm/
├── projects/<project-id>/
│   ├── metadata.json
│   ├── members/<agent-name>.json
│   ├── messages/<agent-name>/<timestamp-uuid>.json
│   └── resources/<resource-id>/
├── clients/<client-id>/
│   ├── identity.json
│   └── memberships.json
└── system/
    ├── config.json
    └── audit.log

Modelo de Segurança

Modelo de Confiança: O Brainstorm assume agentes cooperativos, não adversários. Os recursos de segurança previnem erros acidentais e conflitos, não ataques maliciosos.

Proteções:

  • Prevenção de path traversal (validação por lista de permissões)
  • Permissões de recursos (negar por padrão)
  • Proteção contra DoS (limites de conexão)
  • Validação de payload (limites de profundidade JSON)
  • Registro de auditoria para todas as operações

Caso de Uso: Desenvolvimento local e coordenação de agentes confiáveis, não ambientes multi‑tenant ou não confiáveis.

Desenvolvimento e Contribuições

# Watch mode for development
npm run dev

# Run security tests
npm test

# Lint code
npm run lint

O conjunto de testes inclui 57 testes cobrindo segurança, concorrência e funcionalidades.

Para informações detalhadas sobre arquitetura e diretrizes de contribuição, consulte o CLAUDE.md.

Limitações Conhecidas

O Brainstorm é uma prova de conceito otimizada para desenvolvimento local:

  • Escala: Recomendado <100 agentes por projeto, <10 mensagens/segundo
  • Armazenamento: Polling no sistema de arquivos, sem escalabilidade horizontal
  • Atomicidade: Entrega de broadcast melhor esforço via Promise.allSettled
  • Operações: Sem cotas de armazenamento, sem tratamento de desligamento gracioso

Para uso em produção, considere migrar para um backend de banco de dados (SQLite/PostgreSQL). A arquitetura está pronta para migração, com todas as operações de arquivo mapeadas para consultas SQL.

Licença

Business Source License 1.1 com conversão automática para Apache 2.0 em 29 de outubro de 2029.

O que isso significa:

  • ✅ Desenvolvimento, testes, pesquisa: Gratuito para todos os usos não comerciais
  • ❌ Implantações em produção: Requer uma licença comercial separada
  • ⏰ Futuro open source: Em 29 de outubro de 2029, este código se torna automaticamente licenciado sob Apache 2.0 (totalmente open source)

Por que BSL?

Escolhemos a BSL 1.1 para:

  1. Manter o código público e transparente para desenvolvedores e pesquisadores
  2. Proteger a possibilidade de desenvolver ofertas comerciais baseadas neste trabalho
  3. Garantir que o projeto se torne totalmente open source em até 4 anos

Uso em produção? Entre em contato com o licenciador para opções de licenciamento comercial.

Consulte a LICENSE para os termos legais completos.

AVISO: Este projeto tem o status de "funciona no meu computador™". Espero que funcione no seu também. Caso contrário, sinta‑se à vontade para fazer um fork.