Taskmaster MCP Server

A Simplified Model Context Protocol Server for Task Management

Taskmaster is a simplified MCP server that provides AI agents with straightforward task management. It works with any LLM - no complex thinking required!

🌟 Key Features

Simple 4-Step Workflow

• create_session: Start a new task session
• create_tasklist: Define your tasks
• execute_next: Get next task to work on
• mark_complete: Complete current task
• end_session: Finish when all tasks done

Works with Any LLM

• No Complex Thinking: No six-hat thinking or capability mapping required
• Auto-Assigned Tools: Standard tools (read_file, edit_file, run_terminal_cmd, codebase_search) auto-assigned
• Simple Guidance: Clear, concise instructions that any LLM can follow
• State Management: Full session persistence and task tracking

Streamlined Design

• Minimal Commands: Only 4 essential commands needed
• Clear Progression: Linear workflow that's easy to follow
• Persistent State: Session and task state maintained throughout
• Error Handling: Simple error messages and recovery guidance

🚀 Quick Start

Installation

git clone <repository-url>
cd taskmaster
pip install -r requirements.txt

Running the Server

python server.py

The server starts on http://localhost:8080/mcp by default.

MCP Client Configuration

Cursor IDE

Add to your mcp.json configuration:

{
  "servers": {
    "taskmaster": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "taskmaster": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

📋 Simple Workflow Guide

1. Create Session

# Start a new task session
taskmaster(
    action="create_session",
    session_name="My Development Project",
    task_description="Build a web application with authentication"
)

2. Create Task List

# Define your tasks
taskmaster(
    action="create_tasklist",
    tasklist=[
        {"description": "Set up project structure"},
        {"description": "Implement authentication"},
        {"description": "Create user interface"}
    ]
)

3. Execute Tasks

# Get next task to work on
taskmaster(action="execute_next")

# Complete current task and move to next
taskmaster(action="mark_complete")

# Repeat until all tasks done

4. End Session

# Finish when all tasks complete
taskmaster(action="end_session")

🛠️ Available Actions

Core Workflow Actions

Action	Purpose	Key Parameters
create_session	Start new task session	session_name, task_description
create_tasklist	Define your tasks	tasklist
execute_next	Get next task to work on	-
mark_complete	Complete current task	-
end_session	Finish when all tasks done	-

Utility Actions

Action	Purpose	Key Parameters
get_status	Check current workflow state	-
collaboration_request	Request human input/guidance	collaboration_context
edit_task	Modify existing task	task_id, updated_task_data

🔧 Architecture & Design

Core Components

• TaskmasterCommandHandler: Routes and processes all taskmaster actions
• SessionManager: Manages workflow sessions with persistent state
• WorkflowStateMachine: Simple state management for task execution
• AsyncSessionPersistence: High-performance file-based state persistence
• Command Handlers: Simple handlers for each action type

Design Principles

• Simplicity First: Easy to understand and use with any LLM
• State Management: Full session and task persistence
• Linear Workflow: Clear progression through tasks
• Minimal Complexity: No complex thinking or mapping required
• Extensible: Easy to add new features if needed

Data Flow

1. MCP Client connects via HTTP transport
2. Commands routed through TaskmasterCommandHandler
3. Simple command handlers process actions
4. Session state persisted automatically
5. Clear guidance for next steps

⚙️ Configuration

Customize server behavior by editing config.yaml:

state_directory: 'taskmaster/state'
session_backup_count: 5

🚀 Production Deployment

Smithery.ai Deployment

The server is optimized for deployment on Smithery.ai:

1. Repository Setup: Ensure all files are committed to GitHub
2. Smithery Configuration: smithery.yaml is pre-configured for container deployment
3. Automated Deployment: GitHub Actions workflow handles testing and container building

Docker Deployment

docker build -t taskmaster-mcp .
docker run -p 8080:8080 taskmaster-mcp

Environment Variables

• PORT: Server port (default: 8080)
• SMITHERY_DEPLOY: Set to "true" for Smithery deployment mode

🧪 Testing

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=taskmaster --cov-report=html

Test Coverage

The server maintains comprehensive test coverage across:

• Core workflow functionality
• Command handlers and routing
• Session management and persistence
• Error handling scenarios

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

For detailed development information, see the Developer Guide in the docs/ directory.

📜 License

MIT License - see LICENSE file for details.

---

Taskmaster MCP Server - Intelligent task management for AI agents with production-grade reliability, structured planning methodology, and advanced workflow orchestration.