MCP Task Orchestrator

A Model Context Protocol server that breaks down complex tasks into structured workflows with specialized AI roles. Features workspace-aware task management that automatically detects your project context and saves artifacts in the right locations.

What it does - Input to Output Example

Instead of this:

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

You get this structured workflow:

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

Example Result: Structured web scraper implementation with:
✓ Error handling patterns ✓ Test coverage ✓ Documentation ✓ Development practices

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

Key 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 (package.json, pyproject.toml), and saves artifacts in appropriate locations
• Customizable roles: Edit .task_orchestrator/roles/project_roles.yaml to adapt roles for your project
• Universal MCP compatibility: Works across Claude Desktop, Cursor, Windsurf, VS Code + Cline
• Single-session completion: Finish complex projects in one conversation
• Smart artifact placement: Files are saved relative to your project root, not random locations

Quick Start

Prerequisites

• Python 3.8+
• One or more MCP clients (Claude Desktop, Cursor IDE, Windsurf, or VS Code with Cline extension)

Installation

Option 1: Install from PyPI (Recommended)

pip install mcp-task-orchestrator
mcp-task-orchestrator-cli setup
# Restart your MCP client and look for 'task-orchestrator' in available tools

Option 2: Install from Source

git clone https://github.com/EchoingVesper/mcp-task-orchestrator.git
cd mcp-task-orchestrator
mcp-task-orchestrator-cli check-deps  # Check and install dependencies
python run_installer.py
# Restart your MCP client and look for 'task-orchestrator' in available tools

Troubleshooting Dependencies

If you encounter import errors or missing modules:

mcp-task-orchestrator-cli check-deps
# This will check for missing dependencies and offer to install them

Verification

Try this in your MCP client:

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

How It Works

The orchestrator uses a 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

NEW in v1.8.0: Workspace paradigm automatically detects your project root and creates .task_orchestrator files in the appropriate location. No manual directory specification needed!

Tool	Purpose	Parameters
orchestrator_initialize_session	Start new workflow	working_directory (optional)
orchestrator_plan_task	Create task breakdown	Required
orchestrator_execute_subtask	Execute with specialist context	Required
orchestrator_complete_subtask	Mark tasks complete with artifacts	Required
orchestrator_synthesize_results	Combine results	Required
orchestrator_get_status	Check progress	Optional
orchestrator_maintenance_coordinator	NEW: Automated cleanup and optimization	Required

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

Client	Description	Status
Claude Desktop	Anthropic's desktop application	✅ Supported
Cursor IDE	AI-powered code editor	✅ Supported
Windsurf	Codeium's development environment	✅ Supported
VS Code	With Cline extension	✅ Supported

Configuration & Customization

The installer handles configuration automatically. For manual setup, see docs/MANUAL_INSTALLATION.md.

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.

Common Use Cases

Software Development: Full-stack web applications, API development with testing, database schema design, DevOps pipeline setup

Data Science: Machine learning pipelines, data analysis workflows, research project planning, model deployment strategies

Documentation & Content: Technical documentation, code review and refactoring, testing strategy development, content creation workflows

Troubleshooting

Common Issues

"No MCP clients detected" - Ensure at least one supported client is installed and run it once before installation

"Configuration failed" - Check file permissions, try running installer as administrator/sudo

"Module not found errors" - Delete venv_mcp folder and reinstall: rm -rf venv_mcp && python run_installer.py

Diagnostic Tools

python scripts/diagnostics/check_status.py        # System health check
python scripts/diagnostics/diagnose_db.py         # Database optimization  
python scripts/diagnostics/verify_tools.py        # Installation verification

For comprehensive troubleshooting, see docs/troubleshooting/.

Testing & Development

Enhanced Testing Infrastructure

The MCP Task Orchestrator now includes robust testing improvements that eliminate common issues:

• ✅ No Output Truncation: File-based output system prevents test output truncation
• ✅ No Resource Warnings: Proper database connection management eliminates ResourceWarnings
• ✅ No Test Hanging: Comprehensive hang detection and timeout mechanisms
• ✅ Alternative Test Runners: Bypass pytest limitations with specialized runners

Quick Test Commands

# Activate environment
source venv_mcp/bin/activate  # Linux/Mac
venv_mcp\Scripts\activate     # Windows

# Run enhanced testing suite
python tests/test_resource_cleanup.py     # Validate resource management
python tests/test_hang_detection.py       # Test hang prevention systems
python tests/enhanced_migration_test.py   # Run migration test with full output

# Demonstrate improved testing features
python tests/demo_file_output_system.py   # Show file-based output system
python tests/demo_alternative_runners.py  # Show alternative test runners

# Traditional pytest (still supported)
python -m pytest tests/ -v

Testing Best Practices

For reliable test execution, use the new testing infrastructure:

# File-based output (prevents truncation)
from mcp_task_orchestrator.testing import TestOutputWriter
writer = TestOutputWriter(output_dir)
with writer.write_test_output("my_test", "text") as session:
    session.write_line("Test output here...")

# Alternative test runners (more reliable than pytest)
from mcp_task_orchestrator.testing import DirectFunctionRunner
runner = DirectFunctionRunner(output_dir=Path("outputs"))
result = runner.execute_test(my_test_function, "test_name")

# Database connections (prevents resource warnings)
from tests.utils.db_test_utils import managed_sqlite_connection
with managed_sqlite_connection("test.db") as conn:
    # Database operations with guaranteed cleanup
    pass

📖 Documentation:

• Testing Best Practices - Quick reference guide
• Testing Improvements - Comprehensive documentation

See CONTRIBUTING.md for contribution guidelines and docs/ for complete documentation.

Important Disclaimers

This software is provided "as is" without warranty of any kind. It is intended for development and experimentation purposes. The authors make no claims about its suitability for production, critical systems, or any specific use case.

Use at your own risk. The authors disclaim all liability for any damages or losses resulting from the use of this software, including but not limited to data loss, system failure, or business interruption.

Not production-ready without thorough testing. This is a development tool that should be thoroughly tested and validated before any production use.

License & Resources

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

• Repository: https://github.com/EchoingVesper/mcp-task-orchestrator
• Issues: Report problems or request features
• Documentation: Complete docs

Copyright (c) 2025 Echoing Vesper