Labsco
EchoingVesper logo

Task Orchestrator

★ 29

from EchoingVesper

AI-powered task orchestration and workflow automation with specialized agent roles, intelligent task decomposition, and seamless integration across Claude Desktop, Cursor IDE, Windsurf, and VS Code.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#scraping#database#devops#git#maps#security#monitoring

MCP Task Orchestrator

License: MIT Python 3.8+ Version 2.0.0

A Model Context Protocol server that transforms how you work with AI by automatically documenting every decision, implementation, and test as you build. Think of it as the memory layer for AI-assisted development that ensures no context is ever lost.

Overview

The MCP Task Orchestrator provides intelligent task orchestration, specialized AI roles, and persistent memory for AI-assisted development. Built with Clean Architecture principles, it automatically detects project structure and saves artifacts appropriately.

Document Type: Project Overview & User Guide
Target Audience: Developers using MCP clients (Claude Desktop, Cursor, VS Code, etc.)
Prerequisites: Python 3.8+, MCP-compatible client
Last Updated: 2025-01-13

Key Features

  • Documentation Automation: Every task generates comprehensive, searchable artifacts
  • Specialist AI Roles: Architect, Implementer, Tester, Reviewer, Documenter, and more
  • Persistent Memory: Never lose context - all decisions and implementations are preserved
  • Workspace Awareness: Automatically detects project structure and saves artifacts appropriately
  • Template System: 13 tools for creating reusable task templates
  • Clean Architecture: Built with modern software design principles
  • Universal MCP Compatibility: Works across Claude Desktop, Cursor, Windsurf, VS Code + extensions

How It Works

Instead of monolithic responses:

Copy & paste — that's it
User: "Build a Python web scraper for news articles"
Claude: [Provides a single, basic response with minimal code]

You get structured specialist workflows:

Copy & paste — that's it
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

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:

ToolPurposeParameters
orchestrator_initialize_sessionStart new workflowworking_directory (optional)
orchestrator_plan_taskCreate task breakdownRequired
orchestrator_execute_taskExecute with specialist contextRequired
orchestrator_complete_taskMark tasks complete with artifactsRequired
orchestrator_synthesize_resultsCombine resultsRequired
orchestrator_get_statusCheck progressOptional
orchestrator_maintenance_coordinatorAutomated cleanup and optimizationRequired

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

ClientDescriptionStatus
Claude DesktopAnthropic's desktop application✅ Supported
Cursor IDEAI-powered code editor✅ Supported
WindsurfCodeium's development environment✅ Supported
VS CodeWith Cline extension✅ Supported

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

Testing & Development

Enhanced Testing Infrastructure

The MCP Task Orchestrator 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

Copy & paste — that's it
# Activate your virtual environment (if using one)
source your_venv/bin/activate  # Linux/Mac
your_venv\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:

Copy & paste — that's it
# 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:

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.

Development tool notice. 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.

Links

Copyright (c) 2025 Echoing Vesper