delegator-mcp

v1.1.0

Published

5 months ago

AI agent delegation system for Claude Desktop using Model Context Protocol (MCP)

0High
0Medium
0Low

mcp claude ai delegation worksona multi-agent llm anthropic openai task-automation model-context-protocol claude-desktop

Worksona Delegator MCP

A sophisticated Model Context Protocol (MCP) server that enables Claude and other MCP clients to perform complex task delegation using specialized AI agents and multiple coordination patterns.

🚀 Overview

The Worksona Delegator MCP transforms complex problem-solving by orchestrating multiple specialized AI agents through sophisticated delegation patterns. Instead of relying on a single AI response, tasks are intelligently decomposed and distributed across teams of specialized agents, each with distinct expertise and roles.

✨ Key Features

🏗️ 10+ Delegation Patterns: Hierarchical, Peer-to-Peer, Iterative, Competitive, Federation, Adaptive, and more
🤖 Dynamic Agent Creation: Intelligent agent selection based on task analysis and requirements
⚡ Real-time Monitoring: Live task status, progress tracking, and agent coordination
🔧 Anthropic Integration: Optimized for Claude models with seamless Claude Desktop integration
⏱️ Timeout Management: Configurable timeout handling for reliable operation
🔌 MCP Protocol: Full compliance with Model Context Protocol for seamless Claude integration
📊 Comprehensive Reporting: Detailed execution analytics and result synthesis
🎛️ Extensible Architecture: Plugin system for custom patterns, agents, and providers

🎯 Use Cases

📊 Business Analysis: Market research, competitive analysis, strategic planning
💻 Software Development: Code review, architecture analysis, documentation generation
📝 Content Creation: Multi-perspective writing, editing workflows, content strategy
🔬 Research Projects: Literature reviews, data analysis, comprehensive reporting
🎨 Creative Tasks: Brainstorming, design thinking, creative problem-solving
🏢 Enterprise Workflows: Complex business process automation and optimization

🏛️ Architecture

graph TB
    subgraph "MCP Client"
        C[Claude/Client]
        MCP[MCP Protocol]
    end
    
    subgraph "Delegator MCP Server"
        DS[Core Server]
        PM[Pattern Manager]
        AM[Agent Manager]
        TM[Task Manager]
    end
    
    subgraph "Delegation Engine"
        DP[Delegation Patterns]
        AF[Agent Framework]
        WS[Worksona.js]
    end
    
    subgraph "LLM Providers"
        OAI[OpenAI]
        ANT[Anthropic]
        GOO[Google]
    end
    
    C --> MCP
    MCP --> DS
    DS --> PM
    DS --> AM
    DS --> TM
    PM --> DP
    AM --> AF
    TM --> WS
    WS --> OAI
    WS --> ANT
    WS --> GOO

📋 Requirements

Node.js 18.0.0 or higher
npm or yarn package manager
Anthropic API key (or use with Claude Desktop for seamless integration)
MCP-compatible client (Claude Desktop, etc.)

⚡ Quick Start

1. Installation

# Clone the repository
git clone https://github.com/your-org/delegator-mcp.git
cd delegator-mcp

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

2. Configuration

Edit .env with your API keys and preferences:

# Anthropic API Key (required unless using Claude Desktop integration)
ANTHROPIC_API_KEY=your-anthropic-api-key

# Default Provider Configuration
WORKSONA_DEFAULT_PROVIDER=anthropic
WORKSONA_DEFAULT_MODEL=claude-3-5-sonnet-20241022

# Timeout Configuration
API_CALL_TIMEOUT=60000
DELEGATION_TIMEOUT=300000
PATTERN_TIMEOUT=600000

# Debug Settings
WORKSONA_DEBUG=false

3. Start the Server

# Development mode
npm run dev

# Production mode
npm start

# Using PM2 (recommended for production)
npm install -g pm2
pm2 start ecosystem.config.js

4. Configure MCP Client

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "delegator": {
      "command": "node",
      "args": ["/path/to/delegator-mcp/src/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

🎮 Usage Examples

Basic Task Delegation

// Create a delegation task
const task = await use_mcp_tool('delegator', 'create_delegation_task', {
  query: "Analyze the competitive landscape for renewable energy storage",
  pattern: "hierarchical",
  config: {
    maxAgents: 6,
    timeLimit: 600,
    temperature: 0.4
  }
});

// Execute the delegation
const execution = await use_mcp_tool('delegator', 'execute_delegation_pattern', {
  taskId: task.taskId
});

// Get results
const results = await use_mcp_tool('delegator', 'get_delegation_results', {
  taskId: task.taskId
});

Pattern-Specific Examples

Hierarchical Delegation

Perfect for structured analysis and research tasks:

const task = await use_mcp_tool('delegator', 'create_delegation_task', {
  query: "Create a comprehensive business plan for a sustainable tech startup",
  pattern: "hierarchical",
  config: {
    maxAgents: 8,
    roles: ["researcher", "analyst", "strategist", "writer", "critic", "synthesizer"]
  }
});

Competitive Evaluation

Ideal for comparing multiple solutions or approaches:

const task = await use_mcp_tool('delegator', 'create_delegation_task', {
  query: "Design three different user interface approaches for a mobile banking app",
  pattern: "competitive",
  config: {
    competitorCount: 3,
    evaluationCriteria: ["usability", "security", "accessibility", "innovation"]
  }
});

Iterative Refinement

Best for improving and polishing content through multiple iterations:

const task = await use_mcp_tool('delegator', 'create_delegation_task', {
  query: "Write and refine a technical article about quantum computing",
  pattern: "iterative",
  config: {
    maxIterations: 4,
    refinementAspects: ["clarity", "accuracy", "engagement", "structure"]
  }
});

Structured Queries with Configuration

For programmatic control, you can use structured queries with precise configuration:

// Example: 10-minute timeout with specific configuration
const result = await handleStructuredQuery({
  query: "how to identify and memorize prime numbers",
  config: {
    maxAgents: 4,
    timeLimit: 600, // 10 minutes in seconds
    focusAreas: [
      "identification methods",
      "memorization techniques", 
      "mathematical patterns",
      "practical applications"
    ],
    temperature: 0.6
  },
  pattern: "hierarchical"
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeLimit | number | 600 | Timeout in seconds (10 minutes) | | timeout | number | 600000 | Timeout in milliseconds (alternative to timeLimit) | | maxAgents | number | 5 | Maximum number of agents to create | | temperature | number | 0.7 | AI model temperature for creativity control | | focusAreas | array | [] | Specific areas to focus the analysis on | | pattern | string | "hierarchical" | Delegation pattern to use | | delegationTimeout | number | 600000 | Delegation timeout in milliseconds |

Dynamic Timeout Handling

The system dynamically handles timeout configuration with the following priority:

timeLimit (in seconds) - converted to milliseconds
timeout (in milliseconds) - used directly
delegationTimeout (in milliseconds) - used directly
Default: 600,000ms (10 minutes)

// All equivalent - 10 minute timeout
const configs = [
  { timeLimit: 600 },
  { timeout: 600000 },
  { delegationTimeout: 600000 }
];

🔧 Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ANTHROPIC_API_KEY | - | Anthropic API key | | WORKSONA_DEFAULT_PROVIDER | anthropic | Default LLM provider | | WORKSONA_DEFAULT_MODEL | claude-3-5-sonnet-20241022 | Default model | | API_CALL_TIMEOUT | 60000 | API call timeout (ms) | | DELEGATION_TIMEOUT | 600000 | Delegation timeout (ms) | | PATTERN_TIMEOUT | 600000 | Pattern execution timeout (ms) | | MAX_CONCURRENT_TASKS | 10 | Maximum concurrent tasks | | WORKSONA_DEBUG | false | Enable debug logging |

Pattern Configuration

Configure delegation patterns in config/patterns.json:

{
  "patterns": {
    "hierarchical": {
      "enabled": true,
      "defaultConfig": {
        "maxAgents": 5,
        "timeLimit": 300,
        "temperature": 0.4
      },
      "constraints": {
        "minAgents": 2,
        "maxAgents": 10
      }
    },
    "competitive": {
      "enabled": true,
      "defaultConfig": {
        "competitorCount": 3,
        "evaluationRounds": 2
      }
    }
  }
}

🎭 Delegation Patterns

1. Hierarchical Pattern 🏢

Best for: Structured analysis, research projects, content creation

Central coordinator delegates to specialized workers
Clear chain of command and responsibility
Sequential or parallel execution options

2. Peer-to-Peer Pattern 🤝

Best for: Collaborative tasks, brainstorming, consensus building

Agents work together as equals
Collaborative discussion and iteration
Consensus-based decision making

3. Iterative Pattern 🔄

Best for: Content refinement, progressive enhancement, quality improvement

Sequential refinement through multiple stages
Each iteration builds on previous work
Convergence towards optimal solution

4. Competitive Pattern 🏆

Best for: Optimization problems, creative tasks, solution comparison

Multiple agents provide different solutions
Comparative evaluation and selection
Best solution wins or hybrid approach

5. Federation Pattern 🌐

Best for: Large-scale projects, multi-domain problems

Multi-level hierarchy with domain coordinators
Specialized coordination for different domains
Integration of domain-specific results

6. Adaptive Pattern 🧠

Best for: Unknown complexity, experimental tasks, learning scenarios

Dynamic pattern selection based on task analysis
Self-adjusting approach based on intermediate results
Learning from execution patterns

🤖 Agent Framework

Available Agent Templates

Core Templates

base-delegator: Task coordination and breakdown
base-researcher: Information gathering and analysis
base-analyst: Data processing and insight generation
base-writer: Content creation and communication
base-critic: Evaluation and quality assessment
base-synthesizer: Result integration and summary

Specialized Templates

technical-agent: Code and architecture analysis
business-agent: Market and strategy analysis
creative-agent: Design and creative content
domain-expert: Subject-specific expertise

Custom Agent Templates

Create custom agent templates in agents/templates/:

{
  "id": "custom-agent",
  "name": "Custom Specialist",
  "description": "Specialized agent for custom tasks",
  "traits": {
    "personality": ["analytical", "thorough", "precise"],
    "knowledge": ["domain expertise", "analytical thinking"],
    "tone": "professional and detailed",
    "background": "Expert in specialized domain"
  },
  "config": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022",
    "temperature": 0.4,
    "maxTokens": 8000,
    "systemPrompt": "You are a specialized agent...",
    "examples": [
      {
        "user": "Example input",
        "assistant": "Example response"
      }
    ]
  }
}

🛠️ Development

Project Structure

delegator-mcp/
├── src/
│   ├── core/              # Core delegation logic
│   ├── api/               # API endpoints and handlers
│   ├── delegation/        # Delegation patterns and strategies
│   ├── state/             # State management
│   ├── ui/                # User interface components
│   └── utils/             # Utilities and helpers
├── agents/
│   ├── templates/         # Agent template definitions
│   └── patterns/          # Pattern-specific configurations
├── config/                # Configuration files
├── docs/                  # Documentation
├── tests/                 # Test suites
└── scripts/               # Build and deployment scripts

Running Tests

# Run all tests
npm test

# Run specific test suite
npm run test:patterns
npm run test:agents
npm run test:integration

# Run with coverage
npm run test:coverage

Development Commands

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Lint and format code
npm run lint
npm run format

# Type checking
npm run type-check

# Generate documentation
npm run docs

🐳 Docker Deployment

Quick Start with Docker

# Build image
docker build -t delegator-mcp .

# Run container
docker run -p 3000:3000 \
  -e OPENAI_API_KEY=your-key \
  -e ANTHROPIC_API_KEY=your-key \
  delegator-mcp

Docker Compose

version: '3.8'
services:
  delegator-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

📊 Monitoring and Observability

Health Checks

The server provides comprehensive health check endpoints:

# Basic health check
curl http://localhost:3000/health

# Detailed system status
curl http://localhost:3000/status

# Provider status
curl http://localhost:3000/providers/status

Metrics and Logging

# Enable debug logging
DEBUG=delegator:* npm start

# View performance metrics
curl http://localhost:3000/metrics

# Monitor active tasks
curl http://localhost:3000/tasks/active

Performance Optimization

Connection Pooling: HTTP keep-alive for LLM APIs
Result Caching: LRU cache for agent responses
Batch Processing: Parallel execution where possible
Resource Limits: Configurable concurrency and memory limits

🔐 Security

API Key Management

Environment variable configuration
Secure storage and rotation
Provider-specific key validation
Automatic failover on authentication errors

Rate Limiting

// Configure rate limits
{
  "rateLimits": {
    "perMinute": 60,
    "perHour": 1000,
    "perDay": 10000
  }
}

Input Validation

Query sanitization and validation
Configuration parameter validation
Agent template validation
Pattern input validation

🚨 Troubleshooting

Common Issues

Timeout Errors

# Increase timeout values
export API_CALL_TIMEOUT=120000
export DELEGATION_TIMEOUT=600000

# Check network connectivity
curl -I https://api.openai.com/v1/models

Agent Creation Failures

# Verify API keys
npm run test:providers

# Check agent templates
npm run validate:templates

# Review logs
tail -f logs/delegator.log

Performance Issues

# Monitor resource usage
npm run monitor

# Check active tasks
curl http://localhost:3000/tasks/active

# Review configuration
npm run config:validate

Debug Mode

Enable comprehensive debugging:

# Environment variable
export DEBUG=delegator:*

# Or in .env file
DEBUG=delegator:*
WORKSONA_DEBUG=true

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/delegator-mcp.git
cd delegator-mcp

# Install dependencies
npm install

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and test
npm test

# Submit pull request

Code Style

ESLint configuration for code quality
Prettier for code formatting
TypeScript for type safety
Conventional commits for changelog generation

Testing

Unit tests for core functionality
Integration tests for delegation patterns
End-to-end tests for MCP protocol
Performance tests for load validation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol for the MCP specification
Worksona.js for LLM provider abstraction
OpenAI, Anthropic, and Google AI for LLM services
The open-source community for inspiration and contributions

📞 Support

Documentation: Technical Documentation
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]

🗺️ Roadmap

Version 2.0

[ ] Advanced pattern composition
[ ] Multi-modal agent support
[ ] Real-time streaming responses
[ ] Enhanced error recovery

Version 2.1

[ ] Plugin marketplace
[ ] Custom provider integration
[ ] Advanced analytics dashboard
[ ] Enterprise security features

Version 3.0

[ ] Distributed execution
[ ] Machine learning optimization
[ ] Advanced workflow automation
[ ] Integration ecosystem

Built with ❤️ by the Worksona team

Empowering intelligent task delegation through sophisticated multi-agent orchestration.