npm package: @iflow-mcp/piotr1215-mcp-agentic-framework
Description: MCP-based agentic communication framework for multi-agent collaboration
Latest version: 1.0.2

# 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](https://docs.anthropic.com/en/docs/claude-code/sub-agents#quick-start).

| 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

1. Clone and navigate to the framework:
```bash
cd /home/decoder/dev/mcp-agentic-framework
```

2. Deploy with the Justfile:
```bash
# 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
```

3. Get the LoadBalancer IP:
```bash
just status
# Or manually:
kubectl get svc mcp-agentic-framework-lb
```

4. Update Claude configuration (`~/.claude.json`):
```json
"agentic-framework": {
  "type": "http",
  "url": "http://YOUR_LOADBALANCER_IP:3113/mcp"
}
```

### Managing the Deployment

```bash
# 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

1. Clone the repository:
```bash
git clone https://github.com/Piotr1215/mcp-agentic-framework.git
cd mcp-agentic-framework
```

2. Install dependencies:
```bash
npm install
```

3. Run tests to verify installation:
```bash
npm test
```

## Usage with Claude Desktop or Claude Code

### Using HTTP Transport


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

To use the HTTP transport:
1. Start the HTTP server: `npm run start:http`
2. Add the above configuration to your `~/.claude.json`
3. 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:
  ```json
  {
    "status": "ok",
    "name": "mcp-agentic-framework",
    "version": "1.0.0"
  }
  ```

## Available Tools

### `register-agent`
Register a new agent in the system.

**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:**
```javascript
{
  "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:**
```javascript
[
  {
    "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:**
```javascript
{
  "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:**
```javascript
{
  "from": "orchestrator",
  "message": "System maintenance in 10 minutes",
  "priority": "high"
}
```

**Response:**
```javascript
{
  "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:

```javascript
// 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

```bash
# 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
```typescript
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
```typescript
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

1. **Broadcasts not received**
   - Ensure sender agent is registered
   - Check recipient agents are registered
   - Remember sender doesn't receive own broadcasts

2. **"Agent not found" errors**
   - Verify agent registration
   - Use `discover-agents` to list all agents
   - Check agent IDs are correct

3. **Messages not received**
   - Messages are deleted after reading
   - Each message can only be read once
   - Check correct agent ID

## License

MIT License