# Taskmaster MCP Server

**A Simplified Model Context Protocol Server for Task Management**

[![Smithery Compatible](https://img.shields.io/badge/Smithery-Compatible-green)](https://smithery.ai)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![MCP Protocol](https://img.shields.io/badge/MCP-v1.0-orange)](https://modelcontextprotocol.io)
[![Works with Any LLM](https://img.shields.io/badge/Works%20with%20Any%20LLM-brightgreen)](https://modelcontextprotocol.io)

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

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

### Running the Server

```bash
python server.py
```

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

### MCP Client Configuration

#### Cursor IDE
Add to your `mcp.json` configuration:

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

#### Claude Desktop
Add to your `claude_desktop_config.json`:

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

## 📋 Simple Workflow Guide

### 1. Create Session

```python
# 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

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

### 3. Execute Tasks

```python
# 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

```python
# 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`:

```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

```bash
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

```bash
# 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.