# 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:**
```bash
git clone <repository>
cd task-manager
uv venv && source .venv/bin/activate
uv add "mcp[cli]" pydantic python-dotenv
```

2. **Configure environment:**
```bash
cp .env.example .env
# Edit .env with your preferences
```

3. **Run the server:**
```bash
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`:
```python
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:
```bash
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:
```python
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:
```python
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:
```json
{
  "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:

```bash
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:**
```bash
which uv
# Output: /home/username/.local/bin/uv
```

2. **Create config file at `%APPDATA%\Claude\claude_desktop_config.json`:**
```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:**
```cmd
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

```json
{
  "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

```bash
# 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.