# Personal Task Manager — MCP Server

A **Model Context Protocol (MCP)** server that turns any AI assistant into a powerful task management system. Built with Python and SQLite, it exposes **19 tools** for full lifecycle task management from quick to-dos to multi project workflows with priorities, tags, subtasks, and more.

```
AI Assistant  <-->  MCP Protocol (stdio)  <-->  Task Manager Server  <-->  SQLite DB
```

---

## Features

| Feature | Description |
|---------|-------------|
| **Due Dates & Deadlines** | Set, update, or clear deadlines on any task |
| **Priorities** | Classify tasks as `high`, `medium`, or `low` |
| **Status Workflow** | Full lifecycle: `todo` > `in_progress` > `blocked` > `done` > `archived` |
| **Tags & Labels** | Flexible many-to-many tagging (e.g. `@work`, `@home`, `urgent`) |
| **Notes & Descriptions** | Rich markdown notes attached to any task |
| **Subtasks & Checklists** | Break tasks into ordered, toggleable checklist items |
| **Lists & Projects** | Organize tasks by context — work, personal, side-project |

---

## All 19 MCP Tools

### Core CRUD

| Tool | Signature | Description |
|------|-----------|-------------|
| `get_schema` | `()` | Get the full database schema |
| `run_select_query` | `(query)` | Run a read-only SQL SELECT query |
| `add_task` | `(title, description?, due_date?, priority?, list_id?, notes?)` | Create a new task |
| `update_task` | `(task_id, title?, description?, status?, due_date?, priority?, list_id?, notes?)` | Update any task field |
| `delete_task` | `(task_id)` | Delete a task and its subtasks/tags |

### Due Dates

| Tool | Signature | Description |
|------|-----------|-------------|
| `set_due_date` | `(task_id, due_date)` | Set or clear a deadline (YYYY-MM-DD) |

### Priorities

| Tool | Signature | Description |
|------|-----------|-------------|
| `set_priority` | `(task_id, level)` | Set priority: `high` / `medium` / `low` |

### Status Workflow

| Tool | Signature | Description |
|------|-----------|-------------|
| `set_status` | `(task_id, status)` | Set status: `todo` / `in_progress` / `blocked` / `done` / `archived` |

### Tags & Labels

| Tool | Signature | Description |
|------|-----------|-------------|
| `add_tag` | `(task_id, tag)` | Add a tag to a task (creates if new) |
| `remove_tag` | `(task_id, tag)` | Remove a tag from a task |
| `list_by_tag` | `(tag)` | List all tasks with a given tag |

### Notes

| Tool | Signature | Description |
|------|-----------|-------------|
| `update_notes` | `(task_id, markdown_text)` | Set/replace markdown notes on a task |

### Subtasks & Checklists

| Tool | Signature | Description |
|------|-----------|-------------|
| `add_subtask` | `(parent_id, title)` | Add a checklist item to a task |
| `toggle_subtask` | `(subtask_id)` | Toggle completion (done / not done) |
| `delete_subtask` | `(subtask_id)` | Remove a subtask |
| `list_subtasks` | `(parent_id)` | List all subtasks of a task |

### Lists & Projects

| Tool | Signature | Description |
|------|-----------|-------------|
| `create_list` | `(name, description?)` | Create a new list/project |
| `delete_list` | `(list_id)` | Delete a list (tasks become unassigned) |
| `move_task_to_list` | `(task_id, list_id)` | Move a task to a list (use `0` to unassign) |
| `list_tasks_in_list` | `(list_id)` | List all tasks in a list |

---

## Quick Start

### Prerequisites

- Python 3.10+
- An MCP-compatible client (e.g. Claude Desktop, Cursor, VS Code + Copilot)

### Installation

```bash
# Clone the repository
git clone https://github.com/arghyapolley/personal-task-manager-mcp.git
cd personal-task-manager-mcp

# Install dependencies
pip install -r requirements.txt
```

### Run the Server

```bash
python server.py
```

The server communicates via **stdio** using the MCP protocol. It automatically creates/migrates the `tasks.db` SQLite database on startup.

### Connect to Claude Desktop

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}
```

Then restart Claude Desktop. You can now say things like:

> *"Add a high-priority task called 'Deploy v2' to my Work project, due May 10th"*
>
> *"Show me all tasks tagged @urgent"*
>
> *"Add subtasks to task 3: write tests, update docs, deploy"*
>
> *"What's overdue?"*

---

## Database Schema

```
+---------------+       +---------------+
|    lists      |       |     tags      |
+---------------+       +---------------+
| id (PK)       |       | id (PK)       |
| name (UQ)     |       | name (UQ)     |
| description   |       +-------+-------+
| created_at    |               |
+-------+-------+               |
        |                +------+------+
        | 1:N            | task_tags   |
        |                +-------------+
+-------+-------+       | task_id(FK) |--+
|    tasks      |       | tag_id(FK)  |  |
+---------------+       +-------------+  |
| id (PK)       |<-----------------------+
| title         |
| description   |       +-------------+
| status        |       |  subtasks   |
| due_date      |       +-------------+
| priority      |  1:N  | id (PK)     |
| list_id (FK)  |<------| parent_id   |
| notes         |       | title       |
| created_at    |       |is_completed |
| updated_at    |       | sort_order  |
+---------------+       | created_at  |
                        +-------------+
```

---

## Testing

Run the full test suite (63 tests, uses a temporary DB):

```bash
python test_server.py
```

```
  Results:  63 passed,  0 failed
```

Tests cover: schema creation, CRUD, priorities, status workflow, tags (add/remove/list/duplicates), notes, subtasks (add/toggle/delete/ordering), lists (create/move/unassign/delete), cascade deletes, and SQL injection guards.

---

## Project Structure

```
personal-task-manager-mcp/
|-- server.py          # MCP server -- 19 tools, DB init, schema migration
|-- test_server.py     # Comprehensive test suite (63 assertions)
|-- requirements.txt   # Python dependencies (mcp, pydantic)
|-- tasks.db           # SQLite database (auto-created on first run)
+-- README.md          # This file
```

---