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

1. Clone and setup the repository

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

2. Login to Cloudflare

   npx wrangler login

   This will open your browser to authenticate with Cloudflare.

3. Create KV namespace

   npx wrangler kv namespace create "TASKMANAGER_KV"

   Copy the namespace ID from the output.

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

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

5. 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:

1. Go to Cloudflare Dashboard
2. Navigate to Workers & Pages
3. Select your mcp-taskmanager worker
4. 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

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/mcp-taskmanager.git
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Install dependencies: npm install
5. Make your changes
6. Test locally: npx wrangler dev --local
7. 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

1. Commit your changes: git commit -m 'Add amazing feature'
2. Push to your branch: git push origin feature/amazing-feature
3. 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

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

Made with ❤️ for the AI community

Deploy your own instance and start managing tasks efficiently with AI assistants!