Repository files navigation

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.

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

• 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

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

1. Install:pip install mcp-task-orchestrator
2. Configure: Add to your MCP client configuration
3. Use: "Initialize task orchestrator session and help me build a REST API"

Try this in your MCP client:

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

See theQuick Start Guide for detailed setup instructions.

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 considerationsStep 2: Implementer Role├── Core scraping logic implementation├── Error handling and retries├── Data parsing and cleaning└── Configuration managementStep 3: Tester Role├── Unit tests for core functions├── Integration tests with live sites├── Error condition testing└── Performance validationStep 4: Documenter Role├── Usage documentation├── API reference├── Configuration guide└── Troubleshooting guideResult: Complete implementation with:✓ Error handling patterns ✓ Test coverage ✓ Documentation ✓ Best practices

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

• 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

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 installergit clone https://github.com/EchoingVesper/mcp-task-orchestrator.gitcd mcp-task-orchestratorpython 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 PyPIpip install mcp-task-orchestrator# Then configure your MCP client manually (see configuration section below)

Install to specific clients:

# Configure specific clients onlypython install.py --clients claude,cursor# Skip MCP configuration entirely (manual setup)python install.py --no-clients# Development installation with all toolspython install.py --dev# Install in user directorypython install.py --user

Advanced installation options:

# Force PyPI installation even in developmentpython install.py --source pypi# Install specific versionpython install.py --version 2.0.0# Install from git repositorypython install.py --git https://github.com/EchoingVesper/mcp-task-orchestrator.git# Install in custom virtual environmentpython install.py --venv /path/to/venv# Force overwrite existing installationpython install.py --force

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

# Create virtual environment firstpython -m venv mcp-orchestrator-envsource mcp-orchestrator-env/bin/activate# Linux/WSL/macOS# OR: mcp-orchestrator-env\Scripts\activate  # Windows# Clone and installgit clone https://github.com/EchoingVesper/mcp-task-orchestrator.gitcd mcp-task-orchestratorpython install.py --venv ../mcp-orchestrator-env

Alternative with pipx:

# Install via pipx for isolationpipx install mcp-task-orchestrator# Manual MCP configuration required (see configuration section)

• ✅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

Quick Diagnostics:

# View installation help and optionspython install.py --help# Check installation statuspython install.py --status# Force reconfiguration if already installedpython install.py --force# Test dry-run mode to see what would be donepython install.py --dry-run --verbose

Common Issues:

• Claude Code not detected: Ensure Claude Code CLI is installed andclaude --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, seeInstallation Troubleshooting Guide.

Try this in your MCP client:

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

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

Core orchestration tools for task management and execution:

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 theMaintenance Coordinator Guide.

The universal installer handles all MCP client configuration automatically with zero-vulnerability design. For advanced configuration options, see theInstallation Guide andConfiguration Reference.

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.

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

"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" - Try reinstalling in a fresh virtual environment:

python -m venv fresh_env&&source fresh_env/bin/activate&& pip install mcp-task-orchestrator

# System health checkpython scripts/diagnostics/check_status.py# Database optimizationpython scripts/diagnostics/diagnose_db.py# Installation verificationpython scripts/diagnostics/verify_tools.py

For comprehensive troubleshooting, see theTroubleshooting Guide andDocumentation Portal.

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

# Activate your virtual environment (if using one)source your_venv/bin/activate# Linux/Macyour_venv\Scripts\activate# Windows# Run enhanced testing suitepython tests/test_resource_cleanup.py# Validate resource managementpython tests/test_hang_detection.py# Test hang prevention systemspython tests/enhanced_migration_test.py# Run migration test with full output# Demonstrate improved testing featurespython tests/demo_file_output_system.py# Show file-based output systempython tests/demo_alternative_runners.py# Show alternative test runners# Traditional pytest (still supported)python -m pytest tests/ -v

For reliable test execution, use the new testing infrastructure:

# File-based output (prevents truncation)frommcp_task_orchestrator.testingimportTestOutputWriterwriter=TestOutputWriter(output_dir)withwriter.write_test_output("my_test","text")assession:session.write_line("Test output here...")# Alternative test runners (more reliable than pytest)frommcp_task_orchestrator.testingimportDirectFunctionRunnerrunner=DirectFunctionRunner(output_dir=Path("outputs"))result=runner.execute_test(my_test_function,"test_name")# Database connections (prevents resource warnings)fromtests.utils.db_test_utilsimportmanaged_sqlite_connectionwithmanaged_sqlite_connection("test.db")asconn:# Database operations with guaranteed cleanuppass

📖Documentation:

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

SeeCONTRIBUTING.md for contribution guidelines anddocs/ for complete documentation.

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.

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

• Repository:https://github.com/EchoingVesper/mcp-task-orchestrator
• Issues:Report problems or request features
• Documentation:Documentation Portal |Installation Guide |API Reference

Copyright (c) 2025 Echoing Vesper