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 loginThis 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.tomland 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 toolsPOST /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 tasksget_next_task- Get the next pending task for a requestmark_task_done- Mark a task as completed with optional detailsapprove_task_completion- Approve a completed taskapprove_request_completion- Approve the completion of an entire request
⚙️ Task Operations
add_tasks_to_request- Add new tasks to an existing requestupdate_task- Update task title or description (only for pending tasks)delete_task- Remove a task from a requestopen_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-taskmanagerworker - 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
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!