# TaskWarrior MCP Server

A Model Context Protocol (MCP) server that provides task management capabilities through TaskWarrior.

## Features

This server provides the following MCP tools:

1. **list_tasks** - List tasks with optional filtering
2. **add_task** - Add new tasks with descriptions, priorities, due dates, projects, and tags
3. **done_task** - Mark tasks as completed
4. **delete_task** - Delete tasks
5. **context** - Manage TaskWarrior contexts (set, list, show, none)

## Prerequisites

- TaskWarrior must be installed and accessible in your PATH
- Python 3.11 or higher
- `uv` package manager

## Installation

```bash
# Clone the repository
git clone https://codeberg.org/knightdave/dawids-mcp-servers.git
cd dawids-mcp-servers
```

## Usage

### Running from repository root (recommended)

```bash
# Run with stdio transport (for MCP client integration)
uv --directory /path-to-repo/dawids-mcp-servers/servers/taskwarrior run mcp-taskwarrior --transport stdio

# Run with remote transport
uv --directory /path-to-repo/dawids-mcp-servers/servers/taskwarrior run mcp-taskwarrior --transport remote --host 0.0.0.0 --port 8080
```

Replace `/path-to-repo` with the actual path to where you cloned this repository.

### Alternative: Running from server directory

```bash
cd servers/taskwarrior

# Run with stdio transport
uv run mcp-taskwarrior --transport stdio

# Run with remote transport  
uv run mcp-taskwarrior --transport remote --host 0.0.0.0 --port 8080
```

## API Reference

### Tools

#### list_tasks

List tasks with optional filter expression.

**Parameters:**
- `filter` (optional): Filter expression (e.g., "project:Home", "+work", "status:pending")

**Returns:** JSON array of task objects

**Example:**
```json
{
  "filter": "project:Home"
}
```

#### add_task

Add a new task to TaskWarrior.

**Parameters:**
- `description` (required): Task description text
- `project` (optional): Project name
- `priority` (optional): Priority level ("H", "M", or "L")
- `due` (optional): Due date (ISO format or TaskWarrior date format like "tomorrow", "2024-12-25")
- `tags` (optional): List of tags

**Returns:** JSON object with task information including UUID

**Example:**
```json
{
  "description": "Call my sister",
  "priority": "H",
  "project": "Personal",
  "due": "tomorrow",
  "tags": ["family", "urgent"]
}
```

#### done_task

Mark a task as completed.

**Parameters:**
- `uuid` (required): Task UUID (stable identifier, not the numeric ID)

**Returns:** JSON object with completion information

**Example:**
```json
{
  "uuid": "ebeeab00-ccf8-464b-8b58-f7f2d606edfb"
}
```

#### delete_task

Delete a task.

**Parameters:**
- `uuid` (required): Task UUID (stable identifier, not the numeric ID)

**Returns:** JSON object with deletion information

**Example:**
```json
{
  "uuid": "ebeeab00-ccf8-464b-8b58-f7f2d606edfb"
}
```

#### context

Manage TaskWarrior contexts.

**Parameters:**
- `action` (required): One of "set", "list", "show", "none"
- `name` (optional): Context name (required for "set" action)

**Returns:** JSON object with context information

**Examples:**
```json
{
  "action": "set",
  "name": "work"
}
```

```json
{
  "action": "list"
}
```

```json
{
  "action": "show"
}
```

```json
{
  "action": "none"
}
```

## Important Notes

1. **UUID vs ID**: This server uses TaskWarrior UUIDs (not numeric IDs) for task identification because UUIDs are stable and don't change when tasks are added or removed.

2. **TaskWarrior Installation**: The server requires TaskWarrior to be installed and accessible. If TaskWarrior is not found, operations will fail with a clear error message.

3. **Contexts**: Contexts are user-defined filters that automatically apply to commands. Use the `context` tool to manage them.

4. **Filter Expressions**: TaskWarrior supports rich filter expressions. See the TaskWarrior manual for details on filter syntax.

## Development

### Running Tests

```bash
cd servers/taskwarrior
uv run pytest
```

### Running Tests with Coverage

```bash
cd servers/taskwarrior
uv run pytest --cov=mcp_server_taskwarrior
```

## License

MIT