GitHub - Piotr1215/mcp-agentic-framework: mcp implementation of an agentic framework (original) (raw)

MCP Agentic Framework

A Model Context Protocol (MCP) based communication framework that enables multiple AI agents to collaborate through asynchronous messaging. Built with Test-Driven Development (TDD) and functional programming principles.

Overview

This framework provides a standardized way for multiple Claude agents (or other MCP-compatible agents) to:

Register themselves with unique identities
Discover other registered agents
Exchange messages asynchronously
Send broadcasts to all agents
Work together on complex tasks

The framework uses file-based storage for simplicity and portability, making it easy to run without external dependencies.

Comparison with Claude Code Sub-agents

This framework provides a different approach to multi-agent collaboration compared to Claude Code's sub-agents feature.

Aspect	Claude Code Sub-agents	MCP Agentic Framework
Architecture	Static configuration files	Dynamic agent registration
Context	Isolated per task	Shared across agents with individual message queues
Communication	One-way (Claude invokes agent)	Bidirectional (agents communicate with each other)
Configuration	YAML frontmatter + system prompt	Runtime registration with name and description
Flexibility	Predefined behavior	Runtime-adaptable interaction patterns
Storage	.claude/agents/ directories	File-based message queue system
Tool Access	Fixed at configuration time	Determined by MCP server configuration

When to Use Each Approach

Use Claude Code Sub-agents when:

Tasks are well-defined and repetitive (code review, debugging, testing)
Consistent, predictable behavior is required
Working independently on specific problems
Need to preserve main conversation context

Use MCP Agentic Framework when:

Real-time collaboration between multiple agents is needed
Tasks require discussion, negotiation, or consensus
Problem-solving benefits from diverse perspectives
Building distributed workflows with agent coordination

Both systems can be complementary: MCP agents can collaborate to design and refine sub-agent configurations, while sub-agents can handle routine tasks identified by MCP agent discussions.

Kubernetes Deployment

The MCP Agentic Framework can be deployed on Kubernetes for production use with high availability and easy management.

Prerequisites

Kubernetes cluster with MetalLB LoadBalancer (or similar)
Docker Hub account (or other container registry)
just command runner installed (cargo install just)

Quick Start

Clone and navigate to the framework:

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

Deploy with the 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

Get the LoadBalancer IP:

just status

Or manually:

kubectl get svc mcp-agentic-framework-lb

Update Claude configuration (~/.claude.json):

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

Managing the Deployment

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

Features

Zero-downtime deployments with rolling updates
Automatic version management with semantic versioning
Health checks with automatic restarts
Persistent LoadBalancer IP via MetalLB
Web UI for monitoring agent communications (auto-opens on first agent)

Architecture

The Kubernetes deployment includes:

Deployment: Single replica with health/readiness probes
LoadBalancer Service: Stable external IP for Claude access
ClusterIP Service: Internal cluster communication

Kubernetes Manifests

Located in k8s/ directory:

deployment.yaml - Main application deployment
loadbalancer-service.yaml - External access via MetalLB

Architecture

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

Installation

Clone the repository:

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

Install dependencies:
Run tests to verify installation:

Usage with Claude Desktop or Claude Code

Using HTTP Transport

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

To use the HTTP transport:

Start the HTTP server: npm run start:http
Add the above configuration to your ~/.claude.json
Restart Claude Desktop

Note: The HTTP transport supports Server-Sent Events (SSE)

HTTP Endpoints

When running with npm run start:http, the following endpoints are available:

/mcp - Main MCP endpoint for agent communication
/health - Health check endpoint that returns:
{
"status": "ok",
"name": "mcp-agentic-framework",
"version": "1.0.0"
}

Available Tools

`register-agent`

Parameters:

name (string, required): Agent's display name
description (string, required): Agent's role and capabilities
instanceId (string, optional): Instance identifier for automatic deregistration

Example:

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

`unregister-agent`

Remove an agent from the system.

Parameters:

id (string, required): Agent's unique identifier

`discover-agents`

List all currently registered agents.

Parameters: None

Response Example:

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

`send-message`

Send a message from one agent to another.

Parameters:

to (string, required): Recipient agent's ID
from (string, required): Sender agent's ID
message (string, required): Message content

`check-for-messages`

Retrieve unread messages for an agent. Messages are automatically deleted after reading.

Parameters:

agent_id (string, required): Agent's ID to check messages for

Response Example:

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

`update-agent-status`

Update an agent's status (online, offline, busy, away).

Parameters:

agent_id (string, required): Agent's ID
status (string, required): New status (one of: online, offline, busy, away)

`send-broadcast`

Send a broadcast message to all registered agents (except the sender).

Parameters:

from (string, required): Sender agent's ID
message (string, required): Broadcast message content
priority (string, optional): Priority level (low, normal, high). Defaults to 'normal'

Features:

Messages are delivered to all agents except the sender
Works without requiring agents to subscribe
Returns the number of recipients
Messages are prefixed with priority level (e.g., "[BROADCAST HIGH]")

Example:

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

Response:

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

`get-pending-notifications`

Retrieve pending notifications for an agent.

Parameters:

agent_id (string, required): Agent's ID

Example Use Cases

Multi-Agent Collaboration

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"

Using Broadcasts

The improved broadcast feature allows efficient communication with all agents:

// 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..."

Development

Running Tests

Run all tests

npm test

Run tests in watch mode

npm run test:watch

Run tests with coverage

npm run test:coverage

Storage

The framework stores data in /tmp/mcp-agentic-framework/:

agents.json: Registered agents with status and activity tracking
messages/*.json: Individual message files (one per message)

Security Considerations

Input validation on all tool parameters
File-based locking prevents race conditions
No path traversal vulnerabilities
Messages are stored locally only
No external network calls

API Reference

Agent Object

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 }

Message Object

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 }

Practical Use Cases

1. Orchestrated Task Processing

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

2. Distributed Code Review

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

3. Emergency Coordination

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

Troubleshooting

Common Issues

Broadcasts not received
- Ensure sender agent is registered
- Check recipient agents are registered
- Remember sender doesn't receive own broadcasts
"Agent not found" errors
- Verify agent registration
- Use discover-agents to list all agents
- Check agent IDs are correct
Messages not received
- Messages are deleted after reading
- Each message can only be read once
- Check correct agent ID

License

MIT License