# MCP Server Development Protocol - ClickUp Server

⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️

## Step 1: Planning (PLAN MODE)
- **What problem does this tool solve?**
  - Provides a standardized interface for AI assistants to interact with the ClickUp API
  - Enables AI systems to access and manipulate ClickUp data (workspaces, spaces, folders, lists, tasks, docs, comments, checklists)
  - Bridges the gap between AI assistants and the ClickUp platform without needing to understand the specifics of the ClickUp API

- **What API/service will it use?**
  - ClickUp API (https://clickup.com/api/)

- **What are the authentication requirements?**
  - ✓ Standard API key (ClickUp API Token)
  - ✓ OAuth (optional, supported through separate setup script)

## Step 2: Implementation (ACT MODE)
1. **Bootstrap**
   - Using the MCP SDK for TypeScript:
     ```bash
     npx @modelcontextprotocol/create-server clickup-mcp-server
     cd clickup-mcp-server
     npm install axios dotenv express zod @modelcontextprotocol/sdk
     ```

2. **Core Implementation**
   - Implemented using MCP SDK with modular architecture:
     ```
     clickup-mcp-server/
     ├── src/
     │   ├── index.ts                 # Main server entry point
     │   ├── app.ts                   # Express app setup (for HTTP transport)
     │   ├── clickup-client/          # API clients for ClickUp
     │   │   ├── auth.ts              # Authentication handling
     │   │   ├── tasks.ts             # Task-related API calls
     │   │   ├── lists.ts             # List-related API calls
     │   │   ├── spaces.ts            # Space-related API calls
     │   │   ├── folders.ts           # Folder-related API calls
     │   │   ├── docs.ts              # Doc-related API calls
     │   │   ├── comments.ts          # Comment-related API calls
     │   │   ├── checklists.ts        # Checklist-related API calls
     │   │   └── index.ts             # Client exports
     │   ├── tools/                   # MCP tool implementations
     │   ├── resources/               # MCP resource implementations
     │   ├── controllers/             # Business logic controllers
     │   ├── routes/                  # Express routes (for HTTP)
     │   └── services/                # Service layer
     └── scripts/
         └── get-access-token.js      # Helper for OAuth token retrieval
     ```
   - Comprehensive logging:
     ```typescript
     console.error('[ClickUp API] Requesting workspace data');
     console.error('[ClickUp API] Request to endpoint:', endpoint);
     console.error('[Error] API call failed with:', error);
     ```
   - Strong type definitions with TypeScript and Zod schemas for all inputs and outputs
   - Error handling with context in all API clients
   - Rate limiting through ClickUp API constraints

3. **Configuration**
   - API Token authentication:
     ```json
     {
       "mcpServers": {
         "clickup": {
           "command": "clickup-mcp-server",
           "env": {
             "CLICKUP_API_TOKEN": "your_api_token_here"
           },
           "disabled": false,
           "autoApprove": []
         }
       }
     }
     ```
   - Or if installed from source:
     ```json
     {
       "mcpServers": {
         "clickup": {
           "command": "node",
           "args": ["path/to/clickup-mcp-server/build/index.js"],
           "env": {
             "CLICKUP_API_TOKEN": "your_api_token_here"
           },
           "disabled": false,
           "autoApprove": []
         }
       }
     }
     ```

## Step 3: Testing (BLOCKER ⛔️)

<thinking>
BEFORE using attempt_completion, I MUST verify:
- Have I tested EVERY tool?
- Have I confirmed success from the user for each test?
- Have I documented the test results?

If ANY answer is "no", I MUST NOT use attempt_completion.
</thinking>

1. **Test Each Tool (REQUIRED)**
   - Testing workspace and space tools:
     ```javascript
     // Test get_workspaces
     use_mcp_tool({
       server_name: "clickup",
       tool_name: "get_workspaces",
       arguments: {}
     })
     
     // Test get_spaces
     use_mcp_tool({
       server_name: "clickup",
       tool_name: "get_spaces",
       arguments: { 
         workspace_id: "9011839976" 
       }
     })
     ```
   
   - Testing task tools:
     ```javascript
     // Test get_tasks
     use_mcp_tool({
       server_name: "clickup",
       tool_name: "get_tasks",
       arguments: {
         list_id: "901109776097",
         include_closed: false
       }
     })
     
     // Test create_task
     use_mcp_tool({
       server_name: "clickup",
       tool_name: "create_task",
       arguments: {
         list_id: "901109776097",
         name: "Test task from MCP",
         description: "This is a test task"
       }
     })
     ```
   
   - Testing document tools:
     ```javascript
     // Test get_docs_from_workspace
     use_mcp_tool({
       server_name: "clickup",
       tool_name: "get_docs_from_workspace",
       arguments: { 
         workspace_id: "9011839976",
         deleted: false,
         archived: false
       }
     })
     ```
   
   - Testing resource access:
     ```javascript
     // Test task resource
     access_mcp_resource({
       server_name: "clickup",
       uri: "clickup://task/86rkjvttt"
     })
     
     // Test lists in folder resource
     access_mcp_resource({
       server_name: "clickup",
       uri: "clickup://folder/90115795569/lists"
     })
     ```
   
   ⚠️ DO NOT PROCEED UNTIL ALL TOOLS TESTED

## Step 4: Completion
❗ STOP AND VERIFY:
- ✓ Every tool has been tested with valid inputs
- ✓ Output format is correct for each tool
- ✓ Error handling has been verified
- ✓ All resources are accessible

Only after ALL tools have been tested can attempt_completion be used.

## Available Tools and Resources

### Tools

The server provides tools for interacting with various ClickUp entities:

#### Workspace and Authentication Tools
- `get_workspaces`: Get the list of workspaces the user has access to
- `get_workspace_seats`: Get information about seats in a workspace

#### Space Tools
- `get_spaces`: Get spaces within a workspace
- `get_space`: Get details of a specific space

#### Folder Tools
- `create_folder`: Create a new folder in a space
- `update_folder`: Update an existing folder
- `delete_folder`: Delete a folder

#### List Tools
- `get_lists`: Get lists in a folder or space
- `get_folderless_lists`: Get lists not in any folder
- `get_list`: Get details of a specific list
- `create_list`: Create a new list in a folder or space
- `create_folderless_list`: Create a list not in any folder
- `update_list`: Update an existing list
- `delete_list`: Delete a list
- `create_list_from_template_in_folder`: Create a list from a template in a folder
- `create_list_from_template_in_space`: Create a list from a template in a space

#### Task Tools
- `get_tasks`: Get tasks from a list
- `get_task_details`: Get detailed information about a task
- `create_task`: Create a new task
- `update_task`: Update an existing task
- `add_task_to_list`: Add a task to a list
- `remove_task_from_list`: Remove a task from a list

#### Document Tools
- `get_docs_from_workspace`: Get all docs from a workspace
- `get_doc_content`: Get the content of a specific doc
- `get_doc_pages`: Get the pages of a doc
- `search_docs`: Search for docs in a workspace

#### Checklist Tools
- `create_checklist`: Create a new checklist in a task
- `update_checklist`: Update an existing checklist
- `delete_checklist`: Delete a checklist
- `create_checklist_item`: Create a new checklist item
- `update_checklist_item`: Update an existing checklist item
- `delete_checklist_item`: Delete a checklist item

#### Comment Tools
- `get_task_comments`: Get comments for a task
- `create_task_comment`: Create a comment on a task
- `get_chat_view_comments`: Get comments for a chat view
- `create_chat_view_comment`: Create a comment on a chat view
- `get_list_comments`: Get comments for a list
- `create_list_comment`: Create a comment on a list
- `update_comment`: Update an existing comment
- `delete_comment`: Delete a comment
- `get_threaded_comments`: Get threaded comments for a parent comment
- `create_threaded_comment`: Create a threaded comment

### Resources

The server exposes ClickUp data through URI-addressable resources:

- `clickup://task/{task_id}`: Details of a specific task
- `clickup://task/{task_id}/comments`: Comments for a specific task
- `clickup://task/{task_id}/checklist`: Checklists for a specific task
- `clickup://list/{list_id}`: Details of a specific list
- `clickup://list/{list_id}/comments`: Comments for a specific list
- `clickup://folder/{folder_id}`: Details of a specific folder
- `clickup://folder/{folder_id}/lists`: Lists in a specific folder
- `clickup://space/{space_id}`: Details of a specific space
- `clickup://space/{space_id}/folders`: Folders in a specific space
- `clickup://space/{space_id}/lists`: Folderless lists in a specific space
- `clickup://workspace/{workspace_id}/spaces`: Spaces in a specific workspace
- `clickup://workspace/{workspace_id}/doc/{doc_id}`: Content of a specific doc
- `clickup://view/{view_id}/comments`: Comments for a specific chat view
- `clickup://comment/{comment_id}/reply`: Threaded comments for a specific comment
- `clickup://checklist/{checklist_id}/items`: Items in a specific checklist

## Key Requirements
- ✓ Uses MCP SDK (@modelcontextprotocol/sdk v1.6.1)
- ✓ Comprehensive logging throughout all API clients
- ✓ Strong typing with TypeScript and Zod schemas
- ✓ Error handling in all API interactions
- ✓ No testing skipped before completion
- ✓ Available as npm package: `clickup-mcp-server`