npm package: @rpironato/mcp-taskcloudman
Description: Model Context Protocol server for Task Management
Author: rpironato1
Latest version: 1.1.0

# 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:

```json
{
  "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

```bash
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:
```bash
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:

```json
{
  "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)