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

Running the Server

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

MCP Client Configuration

Cursor IDE

Add to your mcp.json configuration:

Claude Desktop

Add to your claude_desktop_config.json:

📋 Simple Workflow Guide

1. Create Session

2. Create Task List

3. Execute Tasks

4. End Session

🛠️ Available Actions

Core Workflow Actions

Utility Actions

🔧 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:

🚀 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

Environment Variables

• PORT: Server port (default: 8080)

• SMITHERY_DEPLOY: Set to "true" for Smithery deployment mode

🧪 Testing

Running Tests

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.