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

MCP Client connects via HTTP transport
Commands routed through TaskmasterCommandHandler
Simple command handlers process actions
Session state persisted automatically
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:

Repository Setup: Ensure all files are committed to GitHub
Smithery Configuration: smithery.yaml is pre-configured for container deployment
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

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
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.