Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rudra-ravi/mcp-taskmanager

A task management system built with Cloudflare Workers
https://github.com/rudra-ravi/mcp-taskmanager

Last synced: 2 months ago
JSON representation

A task management system built with Cloudflare Workers

Awesome Lists containing this project

README 

          
# 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](https://dash.cloudflare.com/sign-up) (free tier works)

- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed

- Node.js 18+ and npm/pnpm/yarn

- Git for cloning the repository



### Quick Start



1. **Clone and setup the repository**

   ```bash

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

   cd mcp-taskmanager

   npm install

   ```



2. **Login to Cloudflare**

   ```bash

   npx wrangler login

   ```

   This will open your browser to authenticate with Cloudflare.



3. **Create KV namespace**

   ```bash

   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:

   ```toml

   [[kv_namespaces]]

   binding = "TASKMANAGER_KV"

   id = "your-new-kv-namespace-id-here"

   ```



5. **Build and deploy**

   ```bash

   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`:

```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):

```toml

[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:

```bash

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:



```bash

# 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

```bash

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

```bash

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

```typescript

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

```typescript

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



```bash

# 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



```bash

# 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:

```bash

# Tail logs from deployed worker

npx wrangler tail



# Tail logs with filtering

npx wrangler tail --format pretty

```



### KV Data Management



```bash

# 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](https://dash.cloudflare.com)

2. Navigate to Workers & Pages

3. Select your `mcp-taskmanager` worker

4. View logs, metrics, and analytics



### Real-time Monitoring

```bash

# 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](LICENSE) file for details.



## 💬 Support



### Getting Help

- **GitHub Issues**: [Report bugs or request features](https://github.com/Rudra-ravi/mcp-taskmanager/issues)

- **Discussions**: [Ask questions and share ideas](https://github.com/Rudra-ravi/mcp-taskmanager/discussions)

- **Documentation**: Check this README and inline code comments



### Community Resources

- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)

- **Cloudflare Workers Docs**: [Learn more about Workers](https://developers.cloudflare.com/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](https://github.com/modelcontextprotocol/sdk)

- Powered by [Cloudflare Workers](https://workers.cloudflare.com/)

- 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](LICENSE) file for details.



---



**Made with ❤️ for the AI community**



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