# 📋 Task Tracker MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.4+-green.svg)](https://gofastmcp.com)
[![uv](https://img.shields.io/badge/managed_by-uv-purple.svg)](https://docs.astral.sh/uv/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A practical **Model Context Protocol (MCP)** server built in Python using **[FastMCP](https://gofastmcp.com/)** and managed with **[uv](https://docs.astral.sh/uv/)**. This server provides AI assistants (like Claude Desktop, Cursor, Antigravity, etc.) with structured task management capabilities.

---

## 🌟 Overview

The **Model Context Protocol (MCP)** is an open standard that allows LLMs and AI applications to interact safely and seamlessly with external tools and data sources.

This project implements the three core MCP primitives:
- 🛠️ **Tools**: Callable functions allowing the model to perform actions (`add_task`, `complete_task`, `delete_task`).
- 📦 **Resources**: Read-only data URIs allowing the model to inspect state (`tasks://all`, `tasks://pending`).
- 💡 **Prompts**: Predefined prompt templates that guide the AI to perform complex workflows (e.g., task analysis & prioritization).

```mermaid
flowchart LR
    Host["AI Host / Application<br/>(Claude Desktop / Cursor / Antigravity)"] 
    Client["MCP Client<br/>(Protocol Handler)"]
    Server["Task Tracker MCP Server<br/>(FastMCP)"]
    
    Host <--> Client
    Client <--> Server
    
    subgraph ServerCapabilities ["Server Capabilities"]
        Tools["🛠️ Tools<br/>add_task, complete_task, delete_task"]
        Resources["📦 Resources<br/>tasks://all, tasks://pending"]
        Prompts["💡 Prompts<br/>task_summary_prompt"]
    end
    
    Server --- ServerCapabilities
```

---

## 🚀 Features & MCP Primitives

### 1. Tools (Actions)
| Tool | Arguments | Description |
| :--- | :--- | :--- |
| `add_task` | `title: str`, `description: str = ""` | Adds a new task with a unique ID and ISO timestamp. |
| `complete_task` | `task_id: int` | Marks a task status as `"completed"` and adds a completion timestamp. |
| `delete_task` | `task_id: int` | Removes a task by ID and returns the deleted object. |

### 2. Resources (Read-Only Data)
| Resource URI | Description |
| :--- | :--- |
| `tasks://all` | Formats and returns all tasks with emojis (`✅` for completed, `⏳` for pending). |
| `tasks://pending` | Filters and returns only active/pending tasks. |

### 3. Prompts (Guided Workflows)
| Prompt | Description |
| :--- | :--- |
| `task_summary_prompt` | Guides the AI assistant to analyze pending vs completed tasks, identify overdue items, and recommend next actions using `tasks://all`. |

---

## 📦 Getting Started with `uv`

This project is built and managed with **[uv](https://docs.astral.sh/uv/)**, an extremely fast Python package and project manager written in Rust by Astral.

### 1. Install `uv`

**macOS / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows:**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Verify installation:
```bash
uv --version
```

### 2. Clone and Setup Repository

```bash
git clone https://github.com/<your-username>/task-tracker-mcp.git
cd task-tracker-mcp
```

### 3. Install Dependencies
`uv` will automatically create a virtual environment (`.venv`) and install all required dependencies:
```bash
uv sync
```

---

## 🧪 Testing the Server

You can run the built-in async client (`test_client.py`) which exercises every tool, resource, and prompt:

```bash
uv run test_client.py
```

### Expected Output:
```text
🚀 Starting FastMCP Test Client...
==================================================

1. Listing Available Tools:
   Found 3 tools: ['add_task', 'complete_task', 'delete_task']

2. Calling 'add_task' Tool:
   Task 1 Response: {"id":1,"title":"Learn MCP", ...}
   Task 2 Response: {"id":2,"title":"Master uv", ...}

3. Listing Available Resources:
   Found 2 resources: [AnyUrl('tasks://all'), AnyUrl('tasks://pending')]

4. Reading 'tasks://all' Resource:
   Current Tasks:
   ⏳ [1] Learn MCP
   ⏳ [2] Master uv

5. Completing Task ID 1:
   Completed Result: {"id":1, "status":"completed", ...}

6. Reading 'tasks://pending' Resource:
   Pending Tasks:
   ⏳ [2] Master uv

7. Listing Available Prompts:
   Found 1 prompts: ['task_summary_prompt']

8. Deleting Task ID 2:
   Delete Result: {"success": true, "deleted": {"id": 2, ...}}

==================================================
✨ All MCP Server tests completed successfully!
```

---

## 🔌 Connecting & Inspecting

### 1. FastMCP CLI Inspector & Dev Tools
FastMCP 3.x provides built-in CLI commands to inspect and debug your server:

- **Interactive Web Inspector**:
  ```bash
  uv run fastmcp dev inspector task_server.py
  ```
- **Inspect Server Summary**:
  ```bash
  uv run fastmcp inspect task_server.py
  ```
- **List All Tools**:
  ```bash
  uv run fastmcp list task_server.py
  ```
- **Run Standalone Server**:
  ```bash
  uv run fastmcp run task_server.py
  ```

### 2. Claude Desktop Integration
Add the server configuration to your `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "task-tracker": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/task-tracker-mcp",
        "run",
        "task_server.py"
      ]
    }
  }
}
```

---

## 📁 Project Structure

```
Task Tracker MCP/
├── pyproject.toml         # Dependency & project metadata (managed by uv)
├── task_server.py         # MCP Server definitions (tools, resources, prompts)
├── test_client.py         # FastMCP async automated test client
├── src/
│   └── task_tracker_mcp/  # Python package entrypoint
│       └── __init__.py
├── .python-version        # Locked Python version
├── .gitignore             # Python & uv exclusions
└── README.md              # Documentation
```

---

## 💡 Key `uv` Commands Cheat Sheet

| Command | Description |
| :--- | :--- |
| `uv init` | Initialize a new Python project with `pyproject.toml` |
| `uv add <pkg>` | Add a dependency to `pyproject.toml` and install it in `.venv` |
| `uv remove <pkg>` | Remove a dependency |
| `uv run <script.py>` | Run any Python script within the isolated project environment |
| `uv sync` | Sync installed packages with `uv.lock` |
| `uv venv` | Create a virtual environment explicitly |

---

## 🛠️ Next Steps & Extensions

- [ ] **Persistent Storage**: Replace in-memory list with SQLite via `aiosqlite` or `sqlite3`.
- [ ] **Priority & Due Dates**: Add task priority flags (`low`, `medium`, `high`) and due date filters.
- [ ] **Search Tool**: Add a `search_tasks(query: str)` tool to search title and descriptions.
- [ ] **Authentication**: Secure endpoints with FastMCP auth providers.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.