MCP TaskCloudMan with Supabase

Model Context Protocol server for Task Management using Supabase database. This allows Claude Desktop (or any MCP client) to manage and execute tasks in a queue-based system with persistent storage.

🆔 ID Generation System

Request IDs: Unique 8-digit numeric format req-######## (e.g., req-49006899)

• Generated using cryptographically random 8-digit numbers (10000000-99999999)
• Uniqueness verified against existing requests
• Never duplicate, ensuring system integrity

Task IDs: Sequential format req-########-task-n within each request

• Tasks numbered sequentially: 1, 2, 3... n
• Maintains logical execution order
• Example: req-49006899-task-1, req-49006899-task-2, etc.

Prerequisites

• Node.js 18+ (install via brew install node)
• Claude Desktop (install from https://claude.ai/desktop)
• Supabase account and project

Quick Start

1. Setup Supabase Database

1. Create a Supabase project:

   • Go to https://supabase.com
   • Create a new account or login
   • Click "New Project"
   • Choose your organization, project name, and region
   • Set a secure database password

2. Create the database schema:

   • Go to your Supabase dashboard
   • Navigate to the "SQL Editor" tab
   • Copy the contents of schema.sql (from this repository) into the editor
   • Click "Run" to execute the SQL

3. Get your credentials:

   • Go to Project Settings > API
   • Copy your "Project URL" (SUPABASE_URL)
   • Copy your "anon public" key (SUPABASE_ANON_KEY)

2. Configure Claude Desktop

1. Open your Claude Desktop configuration file at: ~/Library/Application Support/Claude/claude_desktop_config.json

   You can find this through the Claude Desktop menu:

   1. Open Claude Desktop
   2. Click Claude on the Mac menu bar
   3. Click "Settings"
   4. Click "Developer"

2. Add the following configuration:

{
  "tools": {
    "taskcloudman": {
      "command": "npx",
      "args": ["-y", "@rpironato1/mcp-taskcloudman"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_ANON_KEY": "your_anon_key_here"
      }
    }
  }
}

3. Replace your-project.supabase.co with your actual Project URL
4. Replace your_anon_key_here with your actual anon key
5. Save the file and restart Claude Desktop

3. Verify Setup

Once configured, restart Claude Desktop and start a new conversation. You should be able to use task management commands like:

• "Create a task list for my project"
• "Show me my current tasks"
• "Mark task as complete"

🚀 Features

• Smart ID Generation: 8-digit unique request IDs (req-########) with sequential task numbering
• Persistent Storage: All data stored in Supabase PostgreSQL database
• Queue-based Execution: Tasks are executed in order with approval workflow
• Progress Tracking: Visual progress tables showing task status and approvals
• Request Management: Create, update, delete, and manage multiple requests
• Task Operations: Add, update, delete, and track individual tasks
• Approval System: Built-in approval workflow for task completion validation

Database Schema

The TaskManager uses two main tables in your Supabase database:

requests table:

• request_id (VARCHAR, PRIMARY KEY): Unique identifier for each request
• original_request (TEXT): The original user request
• split_details (TEXT): Details about how the request was split into tasks
• completed (BOOLEAN): Whether the entire request is completed
• created_at, updated_at (TIMESTAMP): Automatic timestamps

tasks table:

• id (VARCHAR, PRIMARY KEY): Unique identifier for each task
• request_id (VARCHAR, FOREIGN KEY): Links to the parent request
• title (VARCHAR): Task title
• description (TEXT): Task description
• done (BOOLEAN): Whether the task is completed
• approved (BOOLEAN): Whether the task completion was approved
• completed_details (TEXT): Details about task completion
• created_at, updated_at (TIMESTAMP): Automatic timestamps

Configuration Options

Environment Variables

• SUPABASE_URL (required): Your Supabase project URL
• SUPABASE_ANON_KEY (required): Your Supabase anon key
• SUPABASE_SERVICE_ROLE_KEY (optional): Can be used instead of anon key for elevated permissions

Important Security Notes:

• Set Supabase credentials ONLY in the MCP server configuration
• Do NOT use .env or .env.local files
• Do NOT commit credentials to version control

Row Level Security (RLS)

The provided schema includes commented-out RLS options. If you plan to use this in a multi-user environment, uncomment and configure appropriate RLS policies in your Supabase dashboard.

Troubleshooting

Connection Issues

• Verify your Supabase URL and key are correct
• Check that your Supabase project is active
• Ensure the database schema was created successfully

Permission Issues

• Make sure your anon key has the necessary permissions
• Check RLS policies if enabled
• Verify your database tables exist and are accessible

Common Errors

• "Supabase connection test failed": Check your credentials and network connection
• "Failed to load tasks": Verify the database schema is properly created
• "Missing Supabase configuration": Ensure environment variables are set in Claude Desktop config

For Developers

Prerequisites

• Node.js 18+ (install via brew install node)
• Claude Desktop (install from https://claude.ai/desktop)
• tsx (install via npm install -g tsx)

Installation

git clone https://github.com/rpironato1/mcp-taskcloudman.git
cd mcp-taskcloudman
npm install
npm run build

Development Configuration

1. Make sure Claude Desktop is installed and running.

2. Install tsx globally if you haven't:

npm install -g tsx
# or
pnpm add -g tsx

3. Modify your Claude Desktop config located at: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following to your MCP client's configuration:

{
  "tools": {
    "taskcloudman": {
      "args": ["tsx", "/path/to/mcp-taskcloudman/index.ts"]
    }
  }
}

Available Operations

The TaskManager supports a comprehensive workflow system:

Core Operations

• request_planning: Create new requests with multiple tasks
• get_next_task: Retrieve the next pending task for execution
• mark_task_done: Mark tasks as completed with optional details
• approve_task_completion: User approval for completed tasks
• approve_request_completion: Final approval for entire requests
• list_requests: View all requests and their status
• add_tasks_to_request: Add new tasks to existing requests
• update_task: Modify task titles and descriptions
• delete_task: Remove tasks from requests
• open_task_details: View detailed information about specific tasks

Workflow Process

1. Planning Phase: Create request with initial tasks
2. Execution Phase: Get next task, work on it, mark as done
3. Approval Phase: User approves each completed task
4. Completion Phase: All tasks done and approved, request completion approval

ID System

• Request IDs: Format req-######## (8 random digits)
• Task IDs: Format req-########-task-n (sequential numbering)