MCP Task Manager

A Model Context Protocol (MCP) server for comprehensive task management, deployed as a Cloudflare Worker. This open-source project enables AI assistants to plan, track, and manage complex multi-step requests efficiently with persistent storage using Cloudflare KV.

🚀 Features

Request Planning: Break down complex requests into manageable tasks
Task Management: Create, update, delete, and track task progress
Approval Workflow: Built-in approval system for task and request completion
Progress Tracking: Visual progress tables and detailed task information
Persistent Storage: Uses Cloudflare KV for reliable data persistence
Serverless Architecture: Deployed as a Cloudflare Worker for global availability
RESTful API: HTTP endpoints for easy integration with any application
CORS Support: Cross-origin requests enabled for web applications

📦 Deployment

Prerequisites

Cloudflare account (free tier works)
Wrangler CLI installed
Node.js 18+ and npm/pnpm/yarn
Git for cloning the repository

Quick Start

Clone and setup the repository

git clone https://github.com/Rudra-ravi/mcp-taskmanager.git
cd mcp-taskmanager
npm install

Login to Cloudflare
```
npx wrangler login
```
This will open your browser to authenticate with Cloudflare.
Create KV namespace
```
npx wrangler kv namespace create "TASKMANAGER_KV"
```
Copy the namespace ID from the output.

Update configuration Edit wrangler.toml and replace the KV namespace ID:

[[kv_namespaces]]
binding = "TASKMANAGER_KV"
id = "your-new-kv-namespace-id-here"

Build and deploy
```
npm run build
npx wrangler deploy
```

Your MCP Task Manager will be deployed and accessible at: https://mcp-taskmanager.your-subdomain.workers.dev

Advanced Configuration

Custom Worker Name

To deploy with a custom name, update wrangler.toml:

name = "my-custom-taskmanager"  # Change this to your preferred name
main = "worker.ts"
compatibility_date = "2024-03-12"

[build]
command = "npm run build"

[[kv_namespaces]]
binding = "TASKMANAGER_KV"
id = "your-kv-namespace-id-here"

Environment Variables

For different environments (development, staging, production):

[env.staging]
name = "mcp-taskmanager-staging"
[[env.staging.kv_namespaces]]
binding = "TASKMANAGER_KV"
id = "staging-kv-namespace-id"

[env.production]
name = "mcp-taskmanager-prod"
[[env.production.kv_namespaces]]
binding = "TASKMANAGER_KV"
id = "production-kv-namespace-id"

Deploy to specific environments:

npx wrangler deploy --env staging
npx wrangler deploy --env production

🔧 Usage

API Endpoints

The deployed worker provides two main endpoints:

POST /list-tools - Get available MCP tools
POST /call-tool - Execute MCP tool functions

Testing Your Deployment

After deployment, test your worker with curl:

# Replace with your actual worker URL
WORKER_URL="https://mcp-taskmanager.your-subdomain.workers.dev"

# Test list tools
curl -X POST $WORKER_URL/list-tools \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Test creating a request
curl -X POST $WORKER_URL/call-tool \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "request_planning",
      "arguments": {
        "originalRequest": "Test deployment",
        "tasks": [{"title": "Test task", "description": "Verify deployment works"}]
      }
    }
  }'

Available Tools

📋 Core Task Management

request_planning - Register a new user request and plan its associated tasks
get_next_task - Get the next pending task for a request
mark_task_done - Mark a task as completed with optional details
approve_task_completion - Approve a completed task
approve_request_completion - Approve the completion of an entire request

⚙️ Task Operations

add_tasks_to_request - Add new tasks to an existing request
update_task - Update task title or description (only for pending tasks)
delete_task - Remove a task from a request
open_task_details - Get detailed information about a specific task

📊 Information & Monitoring

list_requests - List all requests with their current status and progress

Example API Calls

List Available Tools

curl -X POST https://your-worker.your-subdomain.workers.dev/list-tools \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Plan a New Request

curl -X POST https://your-worker.your-subdomain.workers.dev/call-tool \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "request_planning",
      "arguments": {
        "originalRequest": "Build a web application for task management",
        "splitDetails": "Breaking down into frontend, backend, and deployment tasks",
        "tasks": [
          {
            "title": "Setup React frontend",
            "description": "Initialize React app with TypeScript and essential dependencies"
          },
          {
            "title": "Create backend API",
            "description": "Build REST API with Node.js and Express"
          },
          {
            "title": "Deploy application",
            "description": "Deploy to cloud platform with CI/CD pipeline"
          }
        ]
      }
    }
  }'

📊 Data Model

Task Structure

interface Task {
  id: string;              // Unique task identifier (e.g., "task-1")
  title: string;           // Task title
  description: string;     // Detailed task description
  done: boolean;           // Whether task is marked as done
  approved: boolean;       // Whether task completion is approved
  completedDetails: string; // Details provided when marking task as done
}

Request Structure

interface RequestEntry {
  requestId: string;       // Unique request identifier (e.g., "req-1")
  originalRequest: string; // Original user request description
  splitDetails: string;    // Details about how request was split into tasks
  tasks: Task[];          // Array of tasks for this request
  completed: boolean;     // Whether entire request is completed
}

Task Status Flow

❌ Pending → ⏳ Done (awaiting approval) → ✅ Approved

Tasks can only be updated when in "Pending" status. Once marked as done or approved, they become read-only.

🛠️ Development

Local Development

# Install dependencies
npm install

# Build the project
npm run build

# Start local development server (with remote KV)
npx wrangler dev

# Start local development server (with local KV for testing)
npx wrangler dev --local

# Deploy to preview environment
npx wrangler deploy --env preview

Testing

# Test the build
npm run build

# Test deployment (dry run - shows what would be deployed)
npx wrangler deploy --dry-run

# Run local tests
npm test  # If you add tests

# Test with local KV storage
npx wrangler dev --local

Debugging

View real-time logs:

# Tail logs from deployed worker
npx wrangler tail

# Tail logs with filtering
npx wrangler tail --format pretty

KV Data Management

# List all keys in your KV namespace
npx wrangler kv:key list --binding TASKMANAGER_KV

# Get a specific key value
npx wrangler kv:key get "tasks" --binding TASKMANAGER_KV

# Delete all data (be careful!)
npx wrangler kv:key delete "tasks" --binding TASKMANAGER_KV

🏗️ Architecture

The MCP Task Manager is built as a Cloudflare Worker with the following components:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │───▶│  Cloudflare      │───▶│  Cloudflare KV  │
│   (Claude, etc) │    │  Worker          │    │  Storage        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │ TaskManagerServer│
                       │ (Business Logic) │
                       └──────────────────┘

Components

TaskManagerServer Class: Core business logic for task management
Worker Interface: HTTP endpoints for MCP protocol communication
Cloudflare KV Storage: Persistent data storage for tasks and requests
MCP Protocol: Standard Model Context Protocol for AI assistant integration
CORS Support: Enables web application integration

Benefits

Global Edge Deployment: Low latency worldwide via Cloudflare's network
Serverless: No server management, automatic scaling
Persistent Storage: Data survives across deployments
Cost Effective: Cloudflare's generous free tier
High Availability: Built-in redundancy and failover

📈 Monitoring and Logs

Cloudflare Dashboard

View logs and metrics in the Cloudflare Dashboard:

Go to Cloudflare Dashboard
Navigate to Workers & Pages
Select your mcp-taskmanager worker
View logs, metrics, and analytics

Real-time Monitoring

# View live logs
npx wrangler tail

# View formatted logs
npx wrangler tail --format pretty

# Filter logs by status
npx wrangler tail --status error

Key Metrics to Monitor

Request Volume: Number of API calls
Response Times: Latency of operations
Error Rates: Failed requests and their causes
KV Operations: Storage read/write performance
Memory Usage: Worker memory consumption

Troubleshooting Common Issues

Issue	Cause	Solution
500 Internal Server Error	KV namespace not found	Check KV namespace ID in wrangler.toml
CORS errors	Missing headers	Verify CORS headers in worker.ts
Task not found	Invalid task/request ID	Check ID format and existence
Build failures	TypeScript errors	Run `npm run build` locally first

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/your-username/mcp-taskmanager.git
Create a feature branch: git checkout -b feature/amazing-feature
Install dependencies: npm install
Make your changes
Test locally: npx wrangler dev --local
Build and test: npm run build

Contribution Guidelines

Follow TypeScript best practices
Add tests for new features
Update documentation for API changes
Use conventional commit messages
Ensure all tests pass before submitting

Pull Request Process

Commit your changes: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a Pull Request with:
- Clear description of changes
- Screenshots/examples if applicable
- Reference to any related issues

Areas for Contribution

🐛 Bug fixes and improvements
📚 Documentation enhancements
✨ New MCP tools and features
🧪 Test coverage improvements

License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

Getting Help

GitHub Issues: Report bugs or request features
Discussions: Ask questions and share ideas
Documentation: Check this README and inline code comments

Community Resources

MCP Documentation: Model Context Protocol
Cloudflare Workers Docs: Learn more about Workers

Reporting Issues

When reporting bugs, please include:

Your Cloudflare Worker URL
Steps to reproduce the issue
Expected vs actual behavior
Error messages or logs
Browser/client information

🙏 Acknowledgments

Built with the Model Context Protocol SDK
Powered by Cloudflare Workers
Designed for seamless AI assistant integration
Inspired by the need for better task management in AI workflows

📄 License