@justmpm/comunicate

Sistema de Comunicação Entre Agentes usando arquivos JSON locais (File-Based Architecture).

🎯 Visão Geral

O @justmpm/comunicate é um servidor MCP (Model Context Protocol) que permite comunicação entre múltiplos agentes através de arquivos JSON locais, eliminando a necessidade de banco de dados ou servidor dedicado.

Conceitos Fundamentais:

• Pasta Local: Tudo acontece dentro de ./.comunicate/ no projeto
• JSON-First: Dados persistidos em arquivos JSON human-readable
• No-Lock: Cada agente escreve apenas no seu próprio inbox
• Domínios Separados: Cada agente edita arquivos em diretórios diferentes
• Claims: Sistema de reserva para arquivos compartilhados

📁 Estrutura

.comunicate/
├── registry/
│   ├── agents.json       # Registro de agentes
│   ├── tasks.json        # Tarefas
│   └── claims.json       # Arquivos reservados
├── messages/
│   ├── inbox-*.json      # Caixas de entrada
│   └── archive/          # Mensagens arquivadas (gzip)
└── context/
    ├── api-contracts.json
    ├── decisions.json
    └── progress.json

🚀 Instalação e Configuração

Escolha uma das opções abaixo:

Opção 1: Usar via npx (Recomendado - Sem instalação)

Não precisa instalar nada. O Claude vai baixar e executar automaticamente:

{
  "mcpServers": {
    "@justmpm/comunicate": {
      "command": "npx",
      "args": ["-y", "@justmpm/comunicate"],
      "env": {
        "COMUNICATE_ADMIN_TOKEN": "seu-token-admin-seguro-aqui"
      }
    }
  }
}

Opção 2: Instalar Globalmente

npm install -g @justmpm/comunicate

Depois configure no Claude Desktop:

{
  "mcpServers": {
    "@justmpm/comunicate": {
      "command": "comunicate",
      "env": {
        "COMUNICATE_ADMIN_TOKEN": "seu-token-admin-seguro-aqui"
      }
    }
  }
}

O comando comunicate estará disponível globalmente após a instalação.

Opção 3: Desenvolvimento Local (Clonar e Buildar)

# Clone o repositório
git clone https://github.com/justmpm/comunicate.git
cd comunicate

# Instale dependências
npm install

# Compile
npm run build

# Configure o token
$env:COMUNICATE_ADMIN_TOKEN="seu-token-admin-seguro-aqui"

Configure no Claude Desktop apontando para o arquivo local:

{
  "mcpServers": {
    "@justmpm/comunicate": {
      "command": "node",
      "args": [
        "C:/caminho/completo/para/dist/mcp-server.js"
      ],
      "env": {
        "COMUNICATE_ADMIN_TOKEN": "seu-token-admin-seguro-aqui"
      }
    }
  }
}

Gerar Token de Admin

Se não tiver um token, gere um aleatório:

# Windows PowerShell
-join ((48..57) + (97..102) | Get-Random -Count 32 | ForEach-Object { [char]$_ })

# Ou use o CLI do próprio pacote (se instalado)
comunicate-cli generate-token

🛠️ Tools Disponíveis

Comunicação entre Agentes

| Tool | Descrição | Quando Usar | |------|-----------|-------------| | send_agent_message | Envia mensagem para outro agente | Notificar progresso, solicitar ajuda, enviar updates | | get_agent_messages | Lê mensagens da inbox | Verificar novas mensagens, processar pendências | | get_unread_count | Conta mensagens não lidas | Verificação rápida sem carregar conteúdo | | delete_message | Deleta mensagem específica | Limpar mensagens irrelevantes | | clear_read_messages | Limpa mensagens lidas | Manutenção periódica da inbox |

Sistema de Claims (Reserva de Arquivos)

| Tool | Descrição | Quando Usar | |------|-----------|-------------| | can_edit_file | Verifica permissão de edição | SEMPRE chame antes de editar qualquer arquivo | | claim_file | Reserva arquivo para edição | Quando arquivo está fora do seu domínio | | renew_claim | Renova reserva prestes a expirar | Quando faltarem < 5 min e edição não terminou | | release_file | Libera arquivo reservado | Quando terminar edição antes da expiração | | get_agent_claims | Lista suas reservas ativas | Verificar claims existentes e tempos | | get_all_claims | Lista todas as reservas (admin) | Monitorar uso do sistema |

Administração

| Tool | Descrição | Quando Usar | |------|-----------|-------------| | create_agent | Cria novo agente | Novo projeto, nova área de responsabilidade | | list_agents | Lista agentes registrados | Ver configurações, descobrir agentIds | | get_inactive_agents | Lista agentes inativos | Monitoramento de saúde do sistema |

📖 Fluxos de Trabalho Comuns

1. Criar e Configurar Agentes

Admin executa: create_agent
  ↓
Recebe token único (GUARDAR!)
  ↓
Entrega token ao respectivo agente
  ↓
Agente usa token em todas as operações

2. Enviar e Receber Mensagens

Agente A: send_agent_message(tokenA, "agente-b", "API pronta!")
  ↓
Mensagem vai para inbox-agente-b.json
  ↓
Agente B: get_agent_messages(tokenB)
  ↓
Recebe e processa mensagem

3. Editar Arquivos (Verificação de Domínios)

Antes de editar QUALQUER arquivo:

Agente: can_edit_file(token, "src/types/api.ts")
  ↓
Se PERMITIDO → edite diretamente
  ↓
Se NEGADO (fora do domínio):
  claim_file(token, "src/types/api.ts", 30, "Adicionando tipos")
  ↓
Edita o arquivo
  ↓
release_file(token, "src/types/api.ts") [opcional mas recomendado]

🔑 Conceitos Importantes

Tokens

Admin Token

• Configurado na variável de ambiente COMUNICATE_ADMIN_TOKEN no arquivo de configuração do MCP
• Usado para validar operações administrativas (create_agent, list_agents, get_inactive_agents, get_all_claims)
• Apenas o administrador do sistema deve ter acesso a este token
• Serve como camada de segurança para garantir que apenas administradores possam gerenciar agentes

Agent Token

• Gerado pelo create_agent quando um admin cria um novo agente
• CADA AGENTE TEM SEU PRÓPRIO TOKEN ÚNICO
• Usado em TODAS as operações do agente (mensagens, claims, etc.)
• GUARDE O TOKEN! Não será mostrado novamente

Segurança entre Agentes

O sistema garante que:

• ✅ Agentes normais não podem criar outros agentes (sem adminToken)
• ✅ Agentes normais não podem ver todos os claims do sistema (sem adminToken)
• ✅ Cada agente só acessa sua própria inbox
• ✅ Claims previnem conflitos de edição

Domínios

Domínios são pastas onde um agente pode editar arquivos sem precisar reservar.

Exemplo:
Agente Frontend: domains = ["src/components", "src/pages"]
  ✅ Pode editar: src/components/Button.tsx
  ✅ Pode editar: src/pages/Home.tsx
  ❌ Não pode editar: src/api/users.ts (precisa de claim)

Claims (Reservas)

Um claim é uma reserva temporária de um arquivo fora do domínio do agente.

1. Agente verifica: can_edit_file → "File not in agent domains"
2. Agente reserva: claim_file → "Arquivo reservado por 30 min"
3. Agente edita o arquivo
4. Agente libera: release_file [ou espera expirar]

Regras:

• Apenas um agente pode ter claim de um arquivo por vez
• Claims expiram automaticamente
• Renove quando faltarem < 5 minutos
• Libere assim que terminar para boa convivência

📋 Exemplos de Uso

Criar um agente (admin)

{
  "adminToken": "seu-token-admin",
  "agentId": "backend",
  "capabilities": ["api", "database", "auth"],
  "domains": ["src/api", "src/models"]
}

Retorno:

✅ Agente backend criado
Token: a1b2c3d4e5f6789012345678abcdef00

⚠️ Guarde este token! Ele não será mostrado novamente.

Enviar mensagem

{
  "token": "a1b2c3d4e5f6789012345678abcdef00",
  "recipientId": "frontend",
  "message": "API /users pronta! Contrato: { id, name, email }",
  "type": "task_update",
  "priority": "high"
}

Verificar e reservar arquivo

// 1. Verificar permissão
{
  "token": "a1b2c3d4e5f6789012345678abcdef00",
  "filePath": "src/types/api.ts"
}
// Retorno: ❌ Não pode editar (fora do domínio)

// 2. Reservar
{
  "token": "a1b2c3d4e5f6789012345678abcdef00",
  "filePath": "src/types/api.ts",
  "durationMinutes": 30,
  "reason": "Definindo contratos da API"
}
// Retorno: ✅ Arquivo reservado até 2026-02-08T23:30:00Z

🔒 Segurança

• Timing-Safe Token Comparison: Proteção contra timing attacks
• Retry com Backoff: Escrita atômica com retry automático
• Claims Auto-Limpo: Expirados são removidos automaticamente
• Sequence em Claims: Prevenção de race conditions
• Separação de Domínios: Agentes só acessam arquivos autorizados

🖥️ Otimizado para Windows

• File watcher com fallback para polling
• Caminhos normalizados para Windows
• Suporte nativo ao filesystem Windows

📝 Licença

MIT