MCP Agentic Framework

Um framework de comunicação agentiva para colaboração multiagente usando MCP.

GitHub
11
Experimente este MCPPatrocinado

Documentação

MCP Agentic Framework

Um framework de comunicação baseado no Model Context Protocol (MCP) que permite que múltiplos agentes de IA colaborem por meio de mensagens assíncronas. Construído com Desenvolvimento Orientado por Testes (TDD) e princípios de programação funcional.

Visão Geral

Este framework fornece uma maneira padronizada para múltiplos agentes Claude (ou outros agentes compatíveis com MCP) de:

  • Registrar-se com identidades únicas
  • Descobrir outros agentes registrados
  • Trocar mensagens de forma assíncrona
  • Enviar transmissões para todos os agentes
  • Trabalhar juntos em tarefas complexas

O framework usa armazenamento baseado em arquivos para simplicidade e portabilidade, facilitando a execução sem dependências externas.

Comparação com Sub-agentes do Claude Code

Este framework oferece uma abordagem diferente para colaboração multi-agente em comparação com o recurso de sub-agentes do Claude Code.

AspectoSub-agentes do Claude CodeMCP Agentic Framework
ArquiteturaArquivos de configuração estáticosRegistro dinâmico de agentes
ContextoIsolado por tarefaCompartilhado entre agentes com filas de mensagens individuais
ComunicaçãoUnidirecional (Claude invoca o agente)Bidirecional (agentes comunicam-se entre si)
ConfiguraçãoFrontmatter YAML + prompt de sistemaRegistro em tempo de execução com nome e descrição
FlexibilidadeComportamento predefinidoPadrões de interação adaptáveis em tempo de execução
ArmazenamentoDiretórios .claude/agents/Sistema de fila de mensagens baseado em arquivos
Acesso a FerramentasFixo no momento da configuraçãoDeterminado pela configuração do servidor MCP

Quando Usar Cada Abordagem

Use Sub-agentes do Claude Code quando:

  • As tarefas são bem definidas e repetitivas (revisão de código, depuração, testes)
  • Comportamento consistente e previsível é necessário
  • Trabalho independente em problemas específicos
  • Necessidade de preservar o contexto da conversa principal

Use MCP Agentic Framework quando:

  • Colaboração em tempo real entre múltiplos agentes é necessária
  • As tarefas exigem discussão, negociação ou consenso
  • A resolução de problemas se beneficia de perspectivas diversas
  • Construção de fluxos de trabalho distribuídos com coordenação de agentes

Ambos os sistemas podem ser complementares: agentes MCP podem colaborar para projetar e refinar configurações de sub-agentes, enquanto sub-agentes podem lidar com tarefas rotineiras identificadas nas discussões dos agentes MCP.

Implantação no Kubernetes

O MCP Agentic Framework pode ser implantado no Kubernetes para uso em produção com alta disponibilidade e gerenciamento fácil.

Pré-requisitos

  • Cluster Kubernetes com MetalLB LoadBalancer (ou similar)
  • Conta no Docker Hub (ou outro registro de contêineres)
  • Executor de comandos just instalado (cargo install just)

Início Rápido

  1. Clone e navegue até o framework:
cd /home/decoder/dev/mcp-agentic-framework
  1. Implante com o Justfile:
# First time: Update the docker_user in Justfile
vim Justfile  # Change docker_user to your Docker Hub username

# Deploy (builds, pushes, and deploys to Kubernetes)
just update
  1. Obtenha o IP do LoadBalancer:
just status
# Or manually:
kubectl get svc mcp-agentic-framework-lb
  1. Atualize a configuração do Claude (~/.claude.json):
"agentic-framework": {
  "type": "http",
  "url": "http://YOUR_LOADBALANCER_IP:3113/mcp"
}

Gerenciando a Implantação

# View all available commands
just

# Deploy updates (bumps version, builds, pushes, deploys)
just update          # Patch version bump (1.0.0 -> 1.0.1)
just update-minor    # Minor version bump (1.0.0 -> 1.1.0)
just update-major    # Major version bump (1.0.0 -> 2.0.0)

# Monitor deployment
just status          # Check deployment status
just logs            # Stream logs
just test-health     # Test health endpoint

# Operations
just restart         # Restart the deployment
just rollback        # Rollback to previous version

Recursos

  • Implantações sem tempo de inatividade com atualizações contínuas
  • Gerenciamento automático de versões com versionamento semântico
  • Verificações de saúde com reinicializações automáticas
  • IP persistente do LoadBalancer via MetalLB
  • Interface Web para monitorar comunicações dos agentes (abre automaticamente no primeiro agente)

Arquitetura

A implantação no Kubernetes inclui:

  • Deployment: Réplica única com sondas de saúde/prontidão
  • Serviço LoadBalancer: IP externo estável para acesso do Claude
  • Serviço ClusterIP: Comunicação interna do cluster

Manifestos Kubernetes

Localizados no diretório k8s/:

  • deployment.yaml - Implantação principal da aplicação
  • loadbalancer-service.yaml - Acesso externo via MetalLB

Arquitetura

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Developer Agent │     │  Tester Agent   │     │ Architect Agent │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┴───────────────────────┘
                                 │
                      ┌──────────┴──────────┐
                      │   MCP Server        │
                      │  ┌──────────────┐   │
                      │  │Agent Registry│   │
                      │  └──────────────┘   │
                      │  ┌──────────────┐   │
                      │  │ Message Store│   │
                      │  └──────────────┘   │
                      └─────────────────────┘
                                 │
                      ┌──────────┴──────────┐
                      │ File Storage        │
                      │/tmp/mcp-agentic-    │
                      │    framework/       │
                      └─────────────────────┘

Instalação

  1. Clone o repositório:
git clone https://github.com/Piotr1215/mcp-agentic-framework.git
cd mcp-agentic-framework
  1. Instale as dependências:
npm install
  1. Execute os testes para verificar a instalação:
npm test

Uso com Claude Desktop ou Claude Code

Usando Transporte HTTP

{
  "mcpServers": {
    "agentic-framework": {
      "type": "http",
      "url": "http://127.0.0.1:3113/mcp"
    }
  }
}

Para usar o transporte HTTP:

  1. Inicie o servidor HTTP: npm run start:http
  2. Adicione a configuração acima ao seu ~/.claude.json
  3. Reinicie o Claude Desktop

Nota: O transporte HTTP suporta Server-Sent Events (SSE)

Endpoints HTTP

Ao executar com npm run start:http, os seguintes endpoints estão disponíveis:

  • /mcp - Endpoint MCP principal para comunicação entre agentes
  • /health - Endpoint de verificação de saúde que retorna: 
    {
  "status": "ok",
  "name": "mcp-agentic-framework",
  "version": "1.0.0"
}

Ferramentas Disponíveis

register-agent

Registra um novo agente no sistema.

Parâmetros:

  • name (string, obrigatório): Nome de exibição do agente
  • description (string, obrigatório): Papel e capacidades do agente
  • instanceId (string, opcional): Identificador de instância para cancelamento automático de registro

Exemplo:

{
  "name": "DeveloperAgent",
  "description": "Responsible for writing code and implementing features"
}

unregister-agent

Remove um agente do sistema.

Parâmetros:

  • id (string, obrigatório): Identificador único do agente

discover-agents

Lista todos os agentes atualmente registrados.

Parâmetros: Nenhum

Exemplo de Resposta:

[
  {
    "id": "agent_abc123",
    "name": "DeveloperAgent",
    "description": "Responsible for writing code",
    "status": "online",
    "lastActivityAt": "2024-01-20T10:30:00.000Z"
  }
]

send-message

Envia uma mensagem de um agente para outro.

Parâmetros:

  • to (string, obrigatório): ID do agente destinatário
  • from (string, obrigatório): ID do agente remetente
  • message (string, obrigatório): Conteúdo da mensagem

check-for-messages

Recupera mensagens não lidas para um agente. As mensagens são excluídas automaticamente após a leitura.

Parâmetros:

  • agent_id (string, obrigatório): ID do agente para verificar mensagens

Exemplo de Resposta:

{
  "messages": [
    {
      "from": "agent_abc123",
      "fromName": "DeveloperAgent",
      "message": "Task completed",
      "timestamp": "2024-01-20T10:30:00.000Z"
    }
  ]
}

update-agent-status

Atualiza o status de um agente (online, offline, ocupado, ausente).

Parâmetros:

  • agent_id (string, obrigatório): ID do agente
  • status (string, obrigatório): Novo status (um de: online, offline, busy, away)

send-broadcast

Envia uma mensagem de transmissão para todos os agentes registrados (exceto o remetente).

Parâmetros:

  • from (string, obrigatório): ID do agente remetente
  • message (string, obrigatório): Conteúdo da mensagem de transmissão
  • priority (string, opcional): Nível de prioridade (low, normal, high). Padrão: 'normal'

Recursos:

  • As mensagens são entregues a todos os agentes, exceto o remetente
  • Funciona sem exigir que os agentes se inscrevam
  • Retorna o número de destinatários
  • As mensagens são prefixadas com o nível de prioridade (ex.: "[BROADCAST HIGH]")

Exemplo:

{
  "from": "orchestrator",
  "message": "System maintenance in 10 minutes",
  "priority": "high"
}

Resposta:

{
  "success": true,
  "recipientCount": 5,
  "errors": []  // Any delivery failures
}

get-pending-notifications

Recupera notificações pendentes para um agente.

Parâmetros:

  • agent_id (string, obrigatório): ID do agente

Exemplos de Casos de Uso

Colaboração Multi-Agente

1. Register agents:
   - "Register an orchestrator agent for coordinating tasks"
   - "Register worker1 agent for processing"
   - "Register worker2 agent for analysis"

2. Orchestrator delegates tasks:
   - "Send message from orchestrator to worker1: Process customer data"
   - "Send message from orchestrator to worker2: Analyze market trends"

3. Workers communicate:
   - "Send message from worker1 to worker2: Data ready for analysis"

4. Broadcast updates:
   - "Send broadcast from orchestrator: All tasks completed"

Usando Transmissões

O recurso aprimorado de transmissão permite comunicação eficiente com todos os agentes:

// Orchestrator sends high-priority announcement
await sendBroadcast(
  orchestratorId,
  "Emergency: System overload detected, pause all operations",
  "high"
);

// All other agents receive: "[BROADCAST HIGH] Emergency: System overload..."

// Regular status update
await sendBroadcast(
  orchestratorId,
  "Daily standup meeting in 5 minutes",
  "normal"
);

// All agents receive: "[BROADCAST NORMAL] Daily standup meeting..."

Desenvolvimento

Executando Testes

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Armazenamento

O framework armazena dados em /tmp/mcp-agentic-framework/:

  • agents.json: Agentes registrados com rastreamento de status e atividade
  • messages/*.json: Arquivos de mensagens individuais (um por mensagem)

Considerações de Segurança

  • Validação de entrada em todos os parâmetros das ferramentas
  • Bloqueio baseado em arquivos previne condições de corrida
  • Sem vulnerabilidades de travessia de caminho
  • As mensagens são armazenadas apenas localmente
  • Sem chamadas de rede externas

Referência da API

Objeto Agente

interface Agent {
  id: string;             // Unique identifier
  name: string;           // Display name
  description: string;    // Role description
  status: string;         // online|offline|busy|away
  registeredAt: string;   // ISO timestamp
  lastActivityAt: string; // ISO timestamp
}

Objeto Mensagem

interface Message {
  id: string;          // Message ID
  from: string;        // Sender agent ID
  to: string;          // Recipient agent ID
  message: string;     // Content
  timestamp: string;   // ISO timestamp
  read: boolean;       // Read status
}

Casos de Uso Práticos

1. Processamento de Tarefas Orquestrado

Orchestrator → assigns tasks → Worker agents
Worker agents → process in parallel → report back
Orchestrator → broadcasts completion → all agents notified

2. Revisão de Código Distribuída

Developer → sends code → multiple Reviewers
Reviewers → work independently → send feedback
Developer → broadcasts updates → all reviewers see changes

3. Coordenação de Emergência

Monitor agent → detects issue → broadcasts alert
All agents → receive alert → adjust behavior
Coordinator → broadcasts all-clear → normal operations resume

Solução de Problemas

Problemas Comuns

  1. Transmissões não recebidas

    • Certifique-se de que o agente remetente está registrado
    • Verifique se os agentes destinatários estão registrados
    • Lembre-se de que o remetente não recebe suas próprias transmissões

  2. Erros de "Agente não encontrado"

    • Verifique o registro do agente
    • Use discover-agents para listar todos os agentes
    • Verifique se os IDs dos agentes estão corretos

  3. Mensagens não recebidas

    • As mensagens são excluídas após a leitura
    • Cada mensagem só pode ser lida uma vez
    • Verifique o ID correto do agente

Licença

Licença MIT