Verification

Try this in your MCP client:

"Initialize a new orchestration session and plan a Python script for processing CSV files"

See the Quick Start Guide for detailed setup instructions.

How It Works

Instead of monolithic responses:

User: "Build a Python web scraper for news articles"
Claude: [Provides a single, basic response with minimal code]

You get structured specialist workflows:

User: "Build a Python web scraper for news articles"

Step 1: Architect Role
├── System design with rate limiting and error handling
├── Technology selection (requests vs scrapy)
├── Data structure planning  
└── Scalability considerations

Step 2: Implementer Role
├── Core scraping logic implementation
├── Error handling and retries
├── Data parsing and cleaning
└── Configuration management

Step 3: Tester Role
├── Unit tests for core functions
├── Integration tests with live sites
├── Error condition testing
└── Performance validation

Step 4: Documenter Role
├── Usage documentation
├── API reference
├── Configuration guide
└── Troubleshooting guide

Result: Complete implementation with:
✓ Error handling patterns ✓ Test coverage ✓ Documentation ✓ Best practices

Each step provides specialist context and expertise rather than generic responses.

Core Features

• LLM-powered task decomposition: Automatically breaks complex projects into logical subtasks
• Specialist AI roles: Architect, Implementer, Debugger, Documenter with domain-specific expertise
• Automated maintenance: Built-in cleanup, optimization, and health monitoring
• Task persistence: SQLite database with automatic recovery and archival
• Artifact management: Prevents context limits with intelligent file storage
• Workspace intelligence: Automatically detects Git repositories, project files, and saves artifacts appropriately
• Customizable roles: Edit .task_orchestrator/roles/project_roles.yaml to adapt roles for your project
• Single-session completion: Finish complex projects in one conversation
• Smart artifact placement: Files are saved relative to your project root, not random locations

Installation

Universal Installer (Recommended)

The universal installer provides comprehensive support for all major MCP clients with flexible installation options.

Quick Install - Auto-detect all clients:

# Download and run the universal installer
git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
python install.py

# Auto-detects and configures all compatible MCP clients
# Restart your MCP clients - the orchestrator tools will be available automatically

PyPI Installation with Manual Configuration:

# Install from PyPI
pip install mcp-task-orchestrator

# Then configure your MCP client manually (see configuration section below)

Install to specific clients:

# Configure specific clients only
python install.py --clients claude,cursor

# Skip MCP configuration entirely (manual setup)
python install.py --no-clients

# Development installation with all tools
python install.py --dev

# Install in user directory
python install.py --user

Advanced installation options:

# Force PyPI installation even in development
python install.py --source pypi

# Install specific version
python install.py --version 2.0.0

# Install from git repository
python install.py --git https://github.com/EchoingVesper/mcp-task-orchestrator.git

# Install in custom virtual environment
python install.py --venv /path/to/venv

# Force overwrite existing installation
python install.py --force

For Externally Managed Environments (WSL, Ubuntu 23.04+):

# Create virtual environment first
python -m venv mcp-orchestrator-env
source mcp-orchestrator-env/bin/activate  # Linux/WSL/macOS
# OR: mcp-orchestrator-env\Scripts\activate  # Windows

# Clone and install
git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
python install.py --venv ../mcp-orchestrator-env

Alternative with pipx:

# Install via pipx for isolation
pipx install mcp-task-orchestrator

# Manual MCP configuration required (see configuration section)

Installation Features

• ✅ Zero vulnerabilities: All 38 security issues resolved
• ✅ Cross-platform: Windows, macOS, Linux support
• ✅ Multi-client: Claude Desktop, Cursor, Windsurf, VS Code, Zed, Claude Code
• ✅ Automatic backups: Configuration protection and rollback
• ✅ Performance: < 5 seconds installation, < 50MB memory usage
• ✅ Validation: Comprehensive post-installation verification

Supported MCP Clients

Troubleshooting Installation

Quick Diagnostics:

# View installation help and options
python install.py --help

# Check installation status
python install.py --status

# Force reconfiguration if already installed
python install.py --force

# Test dry-run mode to see what would be done
python install.py --dry-run --verbose

Common Issues:

• Claude Code not detected: Ensure Claude Code CLI is installed and claude --version works
• Config file not found: Make sure the MCP client is installed and has been run at least once
• Permission errors: Check file permissions for config directories
• Already configured: Use --force flag to overwrite existing configurations

Client-Specific Notes:

• Claude Desktop: Works globally across multiple projects using dynamic detection
• Claude Code: Works automatically with per-project detection for best experience
• Windsurf/Cursor: Automatically detect project context when opened in project folders

For comprehensive troubleshooting, see Installation Troubleshooting Guide.

Verification

Try this in your MCP client:

"Initialize a new orchestration session and plan a Python script for processing CSV files"

Workflow Process

The orchestrator follows a systematic five-step process:

1. Workspace Detection - Automatically identifies your project type and root directory
2. Task Analysis - LLM analyzes your request and creates structured subtasks
3. Task Planning - Organizes subtasks with dependencies and complexity assessment
4. Specialist Execution - Each subtask runs with role-specific context and expertise
5. Result Synthesis - Combines outputs into a comprehensive solution with workspace-aware artifact placement

Available Tools

Core orchestration tools for task management and execution:

Maintenance & Automation Features

The orchestrator includes intelligent maintenance capabilities:

• Automatic Cleanup: Detects and archives stale tasks (>24 hours)
• Performance Optimization: Prevents database bloat and maintains responsiveness
• Structure Validation: Ensures task hierarchies remain consistent
• Handover Preparation: Streamlines context transitions and project handoffs
• Health Monitoring: Provides system status and optimization recommendations

Quick maintenance: "Use the maintenance coordinator to scan and cleanup the current session"

For detailed guidance, see the Maintenance Coordinator Guide.

Supported Environments

Configuration & Customization

The universal installer handles all MCP client configuration automatically with zero-vulnerability design. For advanced configuration options, see the Installation Guide and Configuration Reference.

Custom Specialist Roles

Create project-specific specialists by editing .task_orchestrator/roles/project_roles.yaml:

security_auditor:
  role_definition: "You are a Security Analysis Specialist"
  expertise:
    - "OWASP security standards"
    - "Penetration testing methodologies"
    - "Secure coding practices"
  approach:
    - "Focus on security implications"
    - "Identify potential vulnerabilities"
    - "Ensure compliance with security standards"

The file is automatically created when you start a new orchestration session in any directory