chukaibejih/mcp-task-manager

Task Manager MCP Server

A comprehensive task management MCP server built with FastMCP, featuring full CRUD operations, intelligent filtering, and productivity-focused prompts. This project serves as Phase 1 of building a production-ready MCP multi-tenant server.

Features

🛠️ Tools (Actions)

• create_task: Create new tasks with priority, due dates, and tags
• list_tasks: List tasks with filtering by status and priority
• get_task: Get detailed information for a specific task
• update_task: Update any aspect of existing tasks
• delete_task: Remove tasks from the system
• complete_task: Quick action to mark tasks as completed
• get_task_summary: Get comprehensive task statistics

📄 Resources (Data Access)

• tasks://all: Formatted list of all tasks
• tasks://task/{id}: Detailed view of specific task
• tasks://status/{status}: Tasks filtered by status
• tasks://priority/{priority}: Tasks filtered by priority
• tasks://summary: Task statistics dashboard
• tasks://overdue: All overdue tasks with urgency indicators

💬 Prompts (AI Assistance)

• Daily Planning: Context-aware daily planning with current task status
• Task Breakdown: Break complex tasks into manageable subtasks
• Weekly Review: Productivity review with accomplishment tracking
• Project Planning: Comprehensive project planning assistance
• Task Prioritization: Systematic task prioritization using current data

Installation

1. Clone and setup:

git clone <repository>
cd task-manager
uv venv && source .venv/bin/activate
uv add "mcp[cli]" pydantic python-dotenv

2. Configure environment:

cp .env.example .env
# Edit .env with your preferences

3. Run the server:

python -m server.task_server

Development Journey & Challenges Solved

This project was built as a learning exercise to understand MCP (Model Context Protocol) fundamentals before building a multi-tenant architecture. Here are the key challenges encountered and solutions implemented:

Challenge 1: Python Module Path Issues

Problem: ModuleNotFoundError: No module named 'database' when running the server.

Root Cause: Python couldn't find the database module because it wasn't in the Python path.

Solution: Added project root to Python path in server/task_server.py:

import sys
import os
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

Alternative Solution: Run from project root using module syntax:

python -m server.task_server

Challenge 2: Pydantic Validation Errors

Problem: ValidationError: Field required errors during server startup for TaskSummary model.

Root Cause: The Pydantic model defined more fields than the database query was providing.

Solution: Updated the get_summary() method in database/connection.py to provide all required fields:

return TaskSummary(
    total_tasks=total_tasks,
    pending_tasks=pending_tasks,
    in_progress_tasks=in_progress_tasks,
    completed_tasks=completed_tasks,
    cancelled_tasks=cancelled_tasks,  # Added missing field
    high_priority_tasks=high_priority_tasks,
    medium_priority_tasks=medium_priority_tasks,  # Added missing field
    low_priority_tasks=low_priority_tasks,  # Added missing field
    over_due_tasks=over_due_tasks,
)

Challenge 3: DateTime Type Mismatches

Problem: ValidationError: Input should be a valid string for datetime fields.

Root Cause: Pydantic model expected string dates but SQLite returned datetime objects.

Solution: Updated the Task model in database/models.py to use proper datetime types:

class Task(BaseModel):
    created_at: Optional[datetime] = None  # Changed from str to datetime
    updated_at: Optional[datetime] = None  # Changed from str to datetime
    due_date: Optional[datetime] = None    # Changed from str to datetime

Challenge 4: WSL + Windows Claude Desktop Integration

Problem: Developed in WSL (Ubuntu) but Claude Desktop runs on Windows, causing path and execution issues.

Root Cause: Claude Desktop on Windows couldn't directly access WSL file paths and commands.

Solutions Tried:

1. Direct WSL paths - Didn't work
2. Copying code to Windows - Would work but requires syncing
3. WSL integration - Final working solution

Working Solution: WSL command integration in Claude Desktop config:

{
  "mcpServers": {
    "task-manager": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "-e", "bash", "-c", "cd /home/ibejih/projects/task-manager && /home/ibejih/.local/bin/uv run python -m server.task_server"]
    }
  }
}

Key Discoveries:

• Used which uv to find the full uv path: /home/ibejih/.local/bin/uv
• PowerShell requires $env:APPDATA instead of %APPDATA%
• Claude Desktop config location: %APPDATA%\Claude\claude_desktop_config.json

Challenge 5: Claude Desktop Not Showing Tools

Problem: Tools not appearing in Claude Desktop interface after configuration.

Root Cause: Claude Desktop processes weren't fully restarted.

Solution: Complete process termination using Task Manager:

1. Press Ctrl+Shift+Esc to open Task Manager
2. Find all "Claude" processes
3. Right-click and "End Task" on each process
4. Restart Claude Desktop from Start menu

Lesson Learned: Simply closing the window doesn't fully restart Claude Desktop - must kill all processes.

Testing

Comprehensive Test Suite

Run the complete test suite to verify all functionality:

python test_complete.py

This tests:

• ✅ Database operations (CRUD)
• ✅ MCP tools functionality
• ✅ MCP resources serving
• ✅ MCP prompts generation

Manual Testing Commands

Test with Claude Desktop using these commands:

"Create a task to review quarterly reports with high priority"
"Show me all my current tasks"
"Give me a task summary"
"Help me plan my day focusing on development work"

Claude Desktop Integration

For WSL + Windows Users

1. Find your uv path in WSL:

which uv
# Output: /home/username/.local/bin/uv

2. Create config file at %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "task-manager": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "-e", "bash", "-c", "cd /path/to/your/task-manager && /path/to/uv run python -m server.task_server"]
    }
  }
}

3. Test the WSL command first:

wsl -d Ubuntu -e bash -c "cd /path/to/task-manager && /path/to/uv run python -m server.task_server"

4. Completely restart Claude Desktop:

• Use Task Manager to end all Claude processes
• Restart from Start menu

For Native Linux/macOS Users

{
  "mcpServers": {
    "task-manager": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/task-manager",
        "run",
        "python",
        "-m",
        "server.task_server"
      ]
    }
  }
}

Architecture & Design Decisions

Database Design

• SQLite: Perfect for learning and single-tenant operations
• Pydantic Models: Type-safe data validation and serialization
• Proper Indexing: Optimized queries for status, priority, and due dates

MCP Implementation

• FastMCP SDK: Leverages Anthropic's official implementation
• Structured Output: Rich data exchange using Pydantic models
• Error Handling: Comprehensive validation throughout the stack
• Context Integration: Proper logging and progress reporting

Project Structure

task-manager/
├── database/           # Data models and connection logic
│   ├── models.py      # Pydantic models with validation
│   └── connection.py  # Database operations and queries
├── server/            # MCP server implementation
│   ├── task_server.py # Main server with lifecycle management
│   ├── tools.py       # MCP tools (actions)
│   ├── resources.py   # MCP resources (data serving)
│   └── prompts.py     # MCP prompts (AI assistance)
├── test_complete.py   # Comprehensive test suite
└── README.md         # This documentation

Usage Examples

Creating and Managing Tasks

User: "Create a task to review the quarterly reports with high priority and due date 2024-02-15"
Claude: [Calls create_task tool] "I've created the task 'Review quarterly reports' with high priority and due date February 15, 2024."

User: "Show me all pending tasks"
Claude: [Accesses tasks://status/pending resource] "Here are your pending tasks: ..."

User: "Mark task 1 as completed"
Claude: [Calls complete_task tool] "Task 1 has been marked as completed."

Planning and Productivity

User: "Help me plan my day focusing on development work"
Claude: [Uses daily_planning prompt with current task data] "Based on your current tasks, here's a focused plan for your development work today..."

Key Learning Outcomes

This project demonstrates:

• ✅ MCP Protocol Understanding: Complete implementation of tools, resources, and prompts
• ✅ Production Patterns: Error handling, validation, and lifecycle management
• ✅ Database Integration: SQLite with proper connection management
• ✅ Cross-Platform Development: WSL + Windows integration strategies
• ✅ Structured Data Exchange: Pydantic models for type-safe MCP communication

Next Steps: Multi-Tenant Architecture

This server serves as Phase 1 foundation for building a multi-tenant MCP platform. The next phase will involve:

1. Tenant Isolation: Schema-per-tenant database design
2. Server Factory: Programmatic MCP server instance creation
3. Django Integration: REST API for tenant management
4. Production Deployment: Scalable multi-tenant infrastructure

The solid understanding of MCP fundamentals gained from this project makes the multi-tenant challenge much more manageable.

Troubleshooting

Common Issues

Import Errors: Ensure you're running from project root or using module syntax Validation Errors: Check that Pydantic models match database schema Claude Desktop Connection: Verify config file location and restart all processes WSL Integration: Test WSL commands manually before adding to Claude Desktop config

Debug Commands

# Test basic functionality
python test_complete.py

# Test MCP Inspector (alternative to Claude Desktop)
uv run mcp dev server/task_server.py

# Check database operations
python -c "from database.connection import get_database; print(get_database().get_summary())"

Contributing

This project was built as a learning exercise, but improvements are welcome! Focus areas:

• Additional MCP tool implementations
• Enhanced prompt templates
• Better error messages
• Performance optimizations

License

MIT License - Built for learning and sharing MCP implementation patterns.