1 files changed, 195 insertions, 0 deletions
diff --git a/servers/taskwarrior/README.md b/servers/taskwarrior/README.md
new file mode 100644
index 0000000..70d258d
--- /dev/null
+++ b/servers/taskwarrior/README.md
@@ -0,0 +1,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