npm package: @justmpm/comunicate
Description: Sistema de Comunicação Entre Agentes - @justmpm/comunicate File-Based para Windows
Latest version: 0.2.0

# @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:

```json
{
  "mcpServers": {
    "@justmpm/comunicate": {
      "command": "npx",
      "args": ["-y", "@justmpm/comunicate"],
      "env": {
        "COMUNICATE_ADMIN_TOKEN": "seu-token-admin-seguro-aqui"
      }
    }
  }
}
```

### Opção 2: Instalar Globalmente

```bash
npm install -g @justmpm/comunicate
```

Depois configure no Claude Desktop:

```json
{
  "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)

```bash
# 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:

```json
{
  "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:

```bash
# 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)

```json
{
  "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

```json
{
  "token": "a1b2c3d4e5f6789012345678abcdef00",
  "recipientId": "frontend",
  "message": "API /users pronta! Contrato: { id, name, email }",
  "type": "task_update",
  "priority": "high"
}
```

### Verificar e reservar arquivo

```json
// 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