delegator-mcp

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: [e-mail]

🗺️ 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.