1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
# 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
|
