📋 Task Tracker MCP Server

A practical Model Context Protocol (MCP) server built in Python using FastMCP and managed with 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).

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, an extremely fast Python package and project manager written in Rust by Astral.

1. Install uv

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

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

Verify installation:

uv --version

2. Clone and Setup Repository

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:

uv sync

---

🧪 Testing the Server

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

uv run test_client.py

Expected Output:

🚀 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:

  uv run fastmcp dev inspector task_server.py
  

• Inspect Server Summary:

  uv run fastmcp inspect task_server.py
  

• List All Tools:

  uv run fastmcp list task_server.py
  

• Run Standalone Server:

  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

{
  "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 file for details.