📋 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)

2. Resources (Read-Only Data)

3. Prompts (Guided Workflows)

📦 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

🛠️ 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.