MCP Agentic Framework

Un marco de comunicación agéntico para la colaboración multiagente utilizando MCP.

Documentación

MCP Agentic Framework

Un framework de comunicación basado en el Model Context Protocol (MCP) que permite a múltiples agentes de IA colaborar mediante mensajería asíncrona. Construido con Desarrollo Guiado por Pruebas (TDD) y principios de programación funcional.

Descripción general

Este framework proporciona una forma estandarizada para que múltiples agentes de Claude (u otros agentes compatibles con MCP) puedan:

Registrarse con identidades únicas
Descubrir otros agentes registrados
Intercambiar mensajes de forma asíncrona
Enviar transmisiones a todos los agentes
Trabajar juntos en tareas complejas

El framework utiliza almacenamiento basado en archivos por simplicidad y portabilidad, lo que facilita su ejecución sin dependencias externas.

Comparación con los subagentes de Claude Code

Este framework ofrece un enfoque diferente para la colaboración multiagente en comparación con la función de subagentes de Claude Code.

Aspecto	Subagentes de Claude Code	MCP Agentic Framework
Arquitectura	Archivos de configuración estáticos	Registro dinámico de agentes
Contexto	Aislado por tarea	Compartido entre agentes con colas de mensajes individuales
Comunicación	Unidireccional (Claude invoca al agente)	Bidireccional (los agentes se comunican entre sí)
Configuración	Frontmatter YAML + prompt del sistema	Registro en tiempo de ejecución con nombre y descripción
Flexibilidad	Comportamiento predefinido	Patrones de interacción adaptables en tiempo de ejecución
Almacenamiento	Directorios `.claude/agents/`	Sistema de cola de mensajes basado en archivos
Acceso a herramientas	Fijado en el momento de configuración	Determinado por la configuración del servidor MCP

Cuándo usar cada enfoque

Use subagentes de Claude Code cuando:

Las tareas estén bien definidas y sean repetitivas (revisión de código, depuración, pruebas)
Se requiera un comportamiento consistente y predecible
Se trabaje de forma independiente en problemas específicos
Se necesite preservar el contexto de la conversación principal

Use MCP Agentic Framework cuando:

Se necesite colaboración en tiempo real entre múltiples agentes
Las tareas requieran discusión, negociación o consenso
La resolución de problemas se beneficie de perspectivas diversas
Se estén construyendo flujos de trabajo distribuidos con coordinación de agentes

Ambos sistemas pueden ser complementarios: los agentes MCP pueden colaborar para diseñar y refinar configuraciones de subagentes, mientras que los subagentes pueden manejar tareas rutinarias identificadas en las discusiones de los agentes MCP.

Despliegue en Kubernetes

El MCP Agentic Framework puede desplegarse en Kubernetes para uso en producción con alta disponibilidad y fácil gestión.

Requisitos previos

Clúster de Kubernetes con MetalLB LoadBalancer (o similar)
Cuenta de Docker Hub (u otro registro de contenedores)
Ejecutor de comandos just instalado (cargo install just)

Inicio rápido

Clone y navegue al framework:

cd /home/decoder/dev/mcp-agentic-framework

Despliegue con el 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

Obtenga la IP del LoadBalancer:

just status
# Or manually:
kubectl get svc mcp-agentic-framework-lb

Actualice la configuración de Claude (~/.claude.json):

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

Gestión del despliegue

# 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

Características

Despliegues sin tiempo de inactividad con actualizaciones continuas
Gestión automática de versiones con versionado semántico
Comprobaciones de salud con reinicios automáticos
IP persistente del LoadBalancer mediante MetalLB
Interfaz web para monitorear las comunicaciones de los agentes (se abre automáticamente con el primer agente)

Arquitectura

El despliegue en Kubernetes incluye:

Deployment: Una sola réplica con sondas de salud/disponibilidad
Servicio LoadBalancer: IP externa estable para acceso de Claude
Servicio ClusterIP: Comunicación interna del clúster

Manifiestos de Kubernetes

Ubicados en el directorio k8s/:

deployment.yaml - Despliegue principal de la aplicación
loadbalancer-service.yaml - Acceso externo mediante MetalLB

Arquitectura

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

Instalación

Clone el repositorio:

git clone https://github.com/Piotr1215/mcp-agentic-framework.git
cd mcp-agentic-framework

Instale las dependencias:

npm install

Ejecute las pruebas para verificar la instalación:

npm test

Uso con Claude Desktop o Claude Code

Uso del transporte HTTP

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

Para usar el transporte HTTP:

Inicie el servidor HTTP: npm run start:http
Agregue la configuración anterior a su ~/.claude.json
Reinicie Claude Desktop

Nota: El transporte HTTP admite Server-Sent Events (SSE)

Endpoints HTTP

Cuando se ejecuta con npm run start:http, están disponibles los siguientes endpoints:

/mcp - Endpoint MCP principal para la comunicación de agentes

/health - Endpoint de comprobación de salud que devuelve:

{
  "status": "ok",
  "name": "mcp-agentic-framework",
  "version": "1.0.0"
}

Herramientas disponibles

`register-agent`

Registra un nuevo agente en el sistema.

Parámetros:

name (cadena, obligatorio): Nombre visible del agente
description (cadena, obligatorio): Rol y capacidades del agente
instanceId (cadena, opcional): Identificador de instancia para baja automática

Ejemplo:

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

`unregister-agent`

Elimina un agente del sistema.

Parámetros:

id (cadena, obligatorio): Identificador único del agente

`discover-agents`

Lista todos los agentes actualmente registrados.

Parámetros: Ninguno

Ejemplo de respuesta:

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

`send-message`

Envía un mensaje de un agente a otro.

Parámetros:

to (cadena, obligatorio): ID del agente destinatario
from (cadena, obligatorio): ID del agente remitente
message (cadena, obligatorio): Contenido del mensaje

`check-for-messages`

Recupera los mensajes no leídos de un agente. Los mensajes se eliminan automáticamente después de leerse.

Parámetros:

agent_id (cadena, obligatorio): ID del agente para verificar mensajes

Ejemplo de respuesta:

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

`update-agent-status`

Actualiza el estado de un agente (en línea, fuera de línea, ocupado, ausente).

Parámetros:

agent_id (cadena, obligatorio): ID del agente
status (cadena, obligatorio): Nuevo estado (uno de: en línea, fuera de línea, ocupado, ausente)

`send-broadcast`

Envía un mensaje de transmisión a todos los agentes registrados (excepto el remitente).

Parámetros:

from (cadena, obligatorio): ID del agente remitente
message (cadena, obligatorio): Contenido del mensaje de transmisión
priority (cadena, opcional): Nivel de prioridad (baja, normal, alta). El valor predeterminado es 'normal'

Características:

Los mensajes se entregan a todos los agentes excepto al remitente
Funciona sin requerir que los agentes se suscriban
Devuelve el número de destinatarios
Los mensajes llevan prefijo con el nivel de prioridad (por ejemplo, "[BROADCAST HIGH]")

Ejemplo:

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

Respuesta:

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

`get-pending-notifications`

Recupera las notificaciones pendientes de un agente.

Parámetros:

agent_id (cadena, obligatorio): ID del agente

Ejemplos de casos de uso

Colaboración multiagente

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"

Uso de transmisiones

La función mejorada de transmisión permite una comunicación eficiente con todos los 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..."

Desarrollo

Ejecución de pruebas

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Almacenamiento

El framework almacena datos en /tmp/mcp-agentic-framework/:

agents.json: Agentes registrados con seguimiento de estado y actividad
messages/*.json: Archivos de mensajes individuales (uno por mensaje)

Consideraciones de seguridad

Validación de entrada en todos los parámetros de las herramientas
Bloqueo basado en archivos para evitar condiciones de carrera
Sin vulnerabilidades de traversal de rutas
Los mensajes se almacenan solo localmente
Sin llamadas de red externas

Referencia de la API

Objeto Agent

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 Message

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ácticos

1. Procesamiento de tareas orquestado

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

2. Revisión de código distribuida

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

3. Coordinación de emergencias

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

Solución de problemas

Problemas comunes

No se reciben transmisiones
- Asegúrese de que el agente remitente esté registrado
- Verifique que los agentes destinatarios estén registrados
- Recuerde que el remitente no recibe sus propias transmisiones
Errores de "Agente no encontrado"
- Verifique el registro del agente
- Use discover-agents para listar todos los agentes
- Compruebe que los ID de los agentes sean correctos
No se reciben mensajes
- Los mensajes se eliminan después de leerse
- Cada mensaje solo puede leerse una vez
- Verifique el ID correcto del agente

Licencia

Licencia MIT