@taazkareem/clickup-mcp-server 0.13.1 → 0.14.0

package/README.md

@@ -1,23 +1,23 @@
-# ClickUp MCP Server — Premium
+<h1 align="center">ClickUp MCP Server — Premium</h1>
 
-![ClickUp MCP Server Premium Image](https://raw.githubusercontent.com/taazkareem/clickup-mcp-server/main/assets/images/clickup_mcp_neon_logo_blue.jpg)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/taazkareem/clickup-mcp-server/main/assets/images/clickup_mcp_neon_logo_blue.jpg" alt="ClickUp MCP Server Premium Logo" width="100%">
+</p>
 
-<div align="center">
-
-[![npm version](https://img.shields.io/npm/v/@taazkareem/clickup-mcp-server.svg)](https://www.npmjs.com/package/@taazkareem/clickup-mcp-server)
-[![npm downloads](https://img.shields.io/npm/dm/@taazkareem/clickup-mcp-server.svg)](https://www.npmjs.com/package/@taazkareem/clickup-mcp-server)
-[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
-![Top 3 on Google](https://img.shields.io/badge/Ranked_Top_3_on_Google-🔥-orange.svg)
-![Trending MCP Server](https://img.shields.io/badge/Trending-MCP_Server-blueviolet.svg)
-[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-blue.svg)](https://github.com/TaazKareem/clickup-mcp-server/graphs/commit-activity)
-
-</div>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@taazkareem/clickup-mcp-server"><img src="https://img.shields.io/npm/v/@taazkareem/clickup-mcp-server.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@taazkareem/clickup-mcp-server"><img src="https://img.shields.io/npm/dm/@taazkareem/clickup-mcp-server.svg" alt="npm downloads"></a>
+  <img src="https://img.shields.io/badge/License-Proprietary-red.svg" alt="License">
+  <img src="https://img.shields.io/badge/Ranked_Top_3_on_Google-🔥-orange.svg" alt="Top 3 on Google">
+  <img src="https://img.shields.io/badge/Trending-MCP_Server-blueviolet.svg" alt="Trending MCP Server">
+  <a href="https://github.com/TaazKareem/clickup-mcp-server/graphs/commit-activity"><img src="https://img.shields.io/badge/Maintained%3F-yes-blue.svg" alt="Maintained"></a>
+</p>
 
 ---
 
 **Properly Connect ClickUp to AI Agents and Agentic Workflows**
 
-*A high-performance Model Context Protocol (MCP) server for managing tasks, checklists, comments, tags, spaces, lists, folders, files, docs, chat, and time using natural language.*
+*A high-performance Model Context Protocol (MCP) server for managing tasks, checklists, sprints, comments, tags, spaces, lists, folders, files, docs, chat, and time using natural language.*
 
 **⭐️ Proven Performance:** 460+ Stars (from previous public repo) & thousands of weekly NPM downloads.  
 The industry-standard ClickUp integration for AI.
@@ -28,7 +28,7 @@ The industry-standard ClickUp integration for AI.
 
 | Links&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Quick&nbsp;Start&nbsp;&&nbsp;Installation |
 | :--- | :--- |
-| •&nbsp;[Features](#features)<br>•&nbsp;[Premium&nbsp;Access](#premium-access)<br>•&nbsp;[Available&nbsp;Tools](#available-tools)<br>•&nbsp;[Adv.&nbsp;Config](#advanced-configuration)<br>•&nbsp;[FAQ](#faq)<br>•&nbsp;[Disclaimer](#disclaimer) | <table border="0" style="border: none; border-collapse: collapse; width: 575px;"> <tr style="border: none;"> <td width="140" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/cursor-white.svg" height="16" style="vertical-align: middle;"> Cursor](#cursor-setup)</td> <td width="155" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/windsurf-white.svg" height="16" style="vertical-align: middle;"> Windsurf](#windsurf-setup)</td> <td width="140" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/visual-studio-code.svg" height="16" style="vertical-align: middle;"> VS&nbsp;Code](#vscode-setup)</td> <td width="140" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://avatars.githubusercontent.com/u/211522643?s=200&v=4" height="16" style="vertical-align: middle; border-radius: 4px;"> Roo&nbsp;Code](#roocode-setup)</td> </tr> <tr style="border: none;"> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/claude.svg" height="16" style="vertical-align: middle;"> Claude](#claude-desktop-setup)</td> <td st yle="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://cdn.simpleicons.org/anthropic/D97757" height="16" style="vertical-align: middle;"> Claude&nbsp;Code](#claude-code-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://cdn.simpleicons.org/n8n/FF6D5A" height="16" style="vertical-align: middle;"> n8n](#n8n-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://cdn.simpleicons.org/googlegemini/8E75C2" height="16" style="vertical-align: middle;"> Gemini&nbsp;CLI](#gemini-setup)</td> </tr> <tr style="border: none;"> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/antigravity.svg" height="16" style="vertical-align: middle;"> Antigravity](#antigravity-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/openai-icon.svg" height="16" style="vertical-align: middle;"> Codex](#codex-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/openai-icon.svg" height="16" style="vertical-align: middle;"> ChatGPT](#chatgpt-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/augment-code.svg" height="16" style="vertical-align: middle;"> Augment](#augment-setup)</td> </tr> <tr style="border: none;"> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/augment-code.svg" height="16" style="vertical-align: middle;"> Auggie](#auggierun-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/openclaw-logo.svg" height="16" style="vertical-align: middle;"> OpenClaw](#openclaw-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[Other](#other-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[➕ Add Agent](mailto:info@taazkareem.com?subject=Redirect%20URI%20Whitelist%20Request)</td> </tr> </table> |
+| •&nbsp;[Features](#features)<br>•&nbsp;[Premium&nbsp;Access](#premium-access)<br>•&nbsp;[Available&nbsp;Tools](#available-tools)<br>•&nbsp;[Adv.&nbsp;Config](#advanced-configuration)<br>•&nbsp;[FAQ](#faq)<br>•&nbsp;[Disclaimer](#disclaimer) | <table border="0" style="border: none; border-collapse: collapse; width: 575px;"> <tr style="border: none;"> <td width="140" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/openclaw-logo.svg" height="16" style="vertical-align: middle;"> OpenClaw](#openclaw-setup)</td> <td width="155" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/cursor-white.svg" height="16" style="vertical-align: middle;"> Cursor](#cursor-setup)</td> <td width="140" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/visual-studio-code.svg" height="16" style="vertical-align: middle;"> VS&nbsp;Code](#vscode-setup)</td> <td width="140" style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://avatars.githubusercontent.com/u/211522643?s=200&v=4" height="16" style="vertical-align: middle; border-radius: 4px;"> Roo&nbsp;Code](#roocode-setup)</td> </tr> <tr style="border: none;"> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/claude.svg" height="16" style="vertical-align: middle;"> Claude](#claude-desktop-setup)</td> <td st yle="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://cdn.simpleicons.org/anthropic/D97757" height="16" style="vertical-align: middle;"> Claude&nbsp;Code](#claude-code-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://cdn.simpleicons.org/n8n/FF6D5A" height="16" style="vertical-align: middle;"> n8n](#n8n-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="https://cdn.simpleicons.org/googlegemini/8E75C2" height="16" style="vertical-align: middle;"> Gemini&nbsp;CLI](#gemini-setup)</td> </tr> <tr style="border: none;"> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/antigravity.svg" height="16" style="vertical-align: middle;"> Antigravity](#antigravity-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/openai-icon.svg" height="16" style="vertical-align: middle;"> Codex](#codex-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/openai-icon.svg" height="16" style="vertical-align: middle;"> ChatGPT](#chatgpt-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/augment-code.svg" height="16" style="vertical-align: middle;"> Augment](#augment-setup)</td> </tr> <tr style="border: none;"> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/augment-code.svg" height="16" style="vertical-align: middle;"> Auggie](#auggierun-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[<img src="./assets/logos/windsurf-white.svg" height="16" style="vertical-align: middle;"> Windsurf](#windsurf-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[Other](#other-setup)</td> <td style="border: none; vertical-align: middle; white-space: nowrap;">[➕ Add Agent](mailto:info@taazkareem.com?subject=Redirect%20URI%20Whitelist%20Request)</td> </tr> </table> |
 
 ---
 
@@ -38,7 +38,7 @@ The industry-standard ClickUp integration for AI.
   <tr style="border: none;">
     <td width="50%" style="vertical-align: top; border: none; padding-bottom: 20px;">
       <strong>🔐 Hybrid Authentication</strong><br>
-      MCP spec compliant OAuth 2.1 with advanced security hardening. Backwards compatible with API Key/Team ID. See [Security](docs/security.md).
+      MCP spec-compliant OAuth 2.1 with advanced security hardening and session-isolated caching for fast, secure multi-tenant operation. Backwards compatible with API Key/Team ID.
     </td>
     <td width="50%" style="vertical-align: top; border: none; padding-bottom: 20px;">
       <strong>🔍 Intelligent Search & Resolution</strong><br>
@@ -48,31 +48,41 @@ The industry-standard ClickUp integration for AI.
   <tr style="border: none;">
     <td style="vertical-align: top; border: none; padding-bottom: 20px;">
       <strong>📝 Task Management</strong><br>
-      Create, update, move, delete, duplicate, and link tasks. Supports bulk operations, nested subtasks, checklists, natural language dates, custom task IDs, custom task types, custom fields, and task templates.
+      Full CRUD, move, duplicate, link, and set dependencies between tasks. Supports bulk operations, nested subtasks, checklists, sprints (active detection), natural language dates, custom task IDs, custom task types, custom fields, task templates, and file attachments (upload via URL, local path, or base64).
     </td>
     <td style="vertical-align: top; border: none; padding-bottom: 20px;">
       <strong>⏱️ Time Tracking</strong><br>
-      Start/stop timers, log manual entries, and filter time entries across the entire workspace using natural language dates or date ranges.
+      Start/stop timers, log manual entries, edit existing entries, retrieve timer history, manage time entry tags, and filter time entries across the entire workspace using natural language dates or date ranges.
     </td>
   </tr>
   <tr style="border: none;">
     <td style="vertical-align: top; border: none; padding-bottom: 20px;">
       <strong>📄 Document Management</strong><br>
-      Create, read, and append to ClickUp Docs with full markdown text.
+      Create, read, and append to ClickUp Docs with full markdown text. Manage pages within documents for structured, long-form content (consolidated action-based tool).
+    </td>
+    <td style="vertical-align: top; border: none; padding-bottom: 20px;">
+      <strong>💬 Comments & Chat</strong><br>
+      Post, edit, resolve, and reply to comments on tasks, lists, and views. Create and manage chat channels (including DMs), send messages with threaded replies, reactions, and follower management. Both support rich text, subtypes, and @mentions.
+    </td>
+  </tr>
+  <tr style="border: none;">
+    <td style="vertical-align: top; border: none; padding-bottom: 20px;">
+      <strong>🎯 Goals & Key Results</strong><br>
+      Create and manage Goals with full lifecycle support—create, update, delete, and archive. Define and track nested Key Results to measure OKR progress across the workspace.
     </td>
     <td style="vertical-align: top; border: none; padding-bottom: 20px;">
-      <strong>💬 Chat & Collaboration</strong><br>
-      Send/retrieve messages in channels and comments with threaded replies, rich-text conversion and user @mention support.
+      <strong>📋 Views</strong><br>
+      Create, list, update, and delete views at any level of the workspace hierarchy—space, folder, or list. Fetch tasks scoped to a specific view for focused filtering.
     </td>
   </tr>
   <tr style="border: none;">
     <td style="vertical-align: top; border: none;">
-      <strong>🌳 Workspace Control</strong><br>
-      Create and navigate spaces, folders, lists, and tags. Switch workspaces mid-conversation.
+      <strong>🗂️ Task Templates</strong><br>
+      Browse available task templates and instantly create tasks from them. Streamlines repeatable workflows without manual setup each time.
     </td>
     <td style="vertical-align: top; border: none;">
-      <strong>🧠 Smart Defaults</strong><br>
-      Session-isolated caching for fast, secure multi-tenant operation.
+      <strong>🌳 Workspace Control</strong><br>
+      Full CRUD for spaces, folders, lists, webhooks, and tags across the entire workspace hierarchy. Manage access control (ACL) permissions at any level. Switch workspaces mid-conversation without reconfiguration.
     </td>
   </tr>
 </table>
@@ -81,19 +91,34 @@ The industry-standard ClickUp integration for AI.
 
 ## <a name="premium-access"></a>💎 Premium Access
 
-**This project operates on a Sponsorware model.** A license grants **full access to all 67 premium tools** with any of the following plans:
+<div align="center">
+
+<h3>Unlock 145 Enterprise-Grade Custom Tools</h3>
+
+This project transitioned from open-source to a paid model for sustainable full-time development and priority support.
+A license grants full, unrestricted access to all features across your agents⎯no limits.
 
-| [**Monthly ($9/mo)**](https://buy.polar.sh/polar_cl_3xQojQLgzQXKCLzsxc49YfL6z8hzSBBqh9ivy1qZdwW?utm_source=github&utm_medium=readme) | [**Annual ($59/yr)**](https://buy.polar.sh/polar_cl_3a8a3055T4CHIoVlSQPsNshOJLUwsM8AHAiIR3y9wTZ?utm_source=github&utm_medium=readme) | [**Lifetime ($89 w/ code**)](https://buy.polar.sh/polar_cl_4ha3uVyJTu4iPZJS1QbBYNTI1MKTvaXXCkZTb45vPPF?utm_source=github&utm_medium=readme) |
+<br>
+
+| [**Monthly ($9/mo)**](https://buy.polar.sh/polar_cl_3xQojQLgzQXKCLzsxc49YfL6z8hzSBBqh9ivy1qZdwW?utm_source=github&utm_medium=readme) | [**Annual ($59/yr)**](https://buy.polar.sh/polar_cl_3a8a3055T4CHIoVlSQPsNshOJLUwsM8AHAiIR3y9wTZ?utm_source=github&utm_medium=readme) | [**Lifetime ($89 w/ code)**](https://buy.polar.sh/polar_cl_4ha3uVyJTu4iPZJS1QbBYNTI1MKTvaXXCkZTb45vPPF?utm_source=github&utm_medium=readme) |
 | :--- | :--- | :--- |
-| • Pay-as-you-go flexibility<br>• 3 device activations<br>• Cancel anytime | • ONLY $4.92/mo <br>• 3 device activations<br>• Priority bug fixes | • **25% OFF** code: `MAR25` <br>• 3 device activations<br>• **Best Value** (One-time payment)|
+| • Pay-as-you-go flexibility<br>• 3 device activations<br>• Cancel anytime | • **Save 45%** ($4.92/mo)<br>• 3 device activations<br>• Priority support all year | • **Best Value** — One payment<br>• 3 device activations<br>• **25% OFF** code: `MAR25` |
+<br>
+
+<p align="center">
+  <img src="./assets/images/line.svg" width="150" alt="" style="vertical-align: middle;">&nbsp;&nbsp;<a href="https://buy.polar.sh/polar_cl_tZ2q8jRvtaaduurOkQKKJmRgdD43ZiB5K0GZn0aQcur?utm_source=github&utm_medium=readme"><img src="https://img.shields.io/badge/PURCHASE%20LICENSE-0069ff?style=for-the-badge&logo=polar&logoColor=white" alt="Purchase License" style="vertical-align: middle;"></a>&nbsp;&nbsp;<img src="./assets/images/line.svg" width="150" alt="" style="vertical-align: middle;">
+</p>
+
+<br>
 
-**⚡️ Instant Delivery:** Your License Key is delivered immediately via **Polar.sh**. Total setup time is under 2 minutes.
+**⚡️ Instant Key Delivery (Polar.sh)** &nbsp; • &nbsp; **Setup takes less than 2 mins** &nbsp; &nbsp; &nbsp;
+
+</div>
 
-[![Purchase License](https://img.shields.io/badge/Purchase%20License-0069ff?style=for-the-badge&logo=polar&logoColor=white)](https://buy.polar.sh/polar_cl_tZ2q8jRvtaaduurOkQKKJmRgdD43ZiB5K0GZn0aQcur?utm_source=github&utm_medium=readme)
 
 ---
 
-## 🚀 Quick Start & Installation
+## 🚀 Quick Start
 
 ### 1. Prerequisites
 * **License Key:** See above
@@ -106,53 +131,68 @@ The industry-standard ClickUp integration for AI.
   - Look at the URL: `https://app.clickup.com/1234567/v/li/987654321`.
   - The first number (`1234567`) directly after `clickup.com/` is your **Team ID** (Workspace ID).
 
-### 2. Choose your Integration
+### 2. Choose your MCP Host & Transport
 
-<a name="cursor-setup"></a>
-<details open>
-<summary>&nbsp;<img src="./assets/logos/cursor-white.svg" height="22" align="center"> <strong>Cursor</strong></summary>  
-
-**Configuration Path:** `<project-root>/.cursor/mcp.json`
+<a name="openclaw-setup"></a>
+<details>
+<summary>&nbsp;<img src="./assets/logos/openclaw-logo.svg" height="22" align="center"> <strong>OpenClaw (via mcporter) </strong> <sub>&nbsp;FEATURED</sub></summary>
 
-**Option A: Cloud / Remote (Easiest)**
+**1. Enable** mcporter in `~/.openclaw/openclaw.json`:
 ```json
-{
-  "mcpServers": {
-    "ClickUp": {
-      "url": "https://clickup-mcp.taazkareem.com/mcp",
-      "headers": {
-        "X-License-Key": "your-license-key"
-      }
-    }
-  }
-}
+{"skills": {"allowBundled": ["mcporter"]}}
 ```
 
-**Option B: Local (stdio)**
-```json
-{
-  "mcpServers": {
-    "ClickUp": {
-      "command": "npx",
-      "args": ["-y", "@taazkareem/clickup-mcp-server@latest"],
-      "env": {
-        "CLICKUP_API_KEY": "your-api-key",
-        "CLICKUP_TEAM_ID": "your-team-id",
-        "CLICKUP_MCP_LICENSE_KEY": "your-license-key"
-      }
-    }
-  }
-}
+**2. Configure & Auth**
+Connect the server and authorize via browser (tokens are cached):
+
+```bash
+# Add ClickUp as a remote server
+mcporter config add ClickUp https://clickup-mcp.taazkareem.com/mcp --auth oauth --header "X-License-Key=your-license-key"
+
+# Authenticate session
+mcporter auth ClickUp
+```
+
+**3. Optional: Multiple Personas**
+The most robust and flexible way to manage personas is to define multiple named servers in your **agent-specific** `mcporter.json` configuration. This isolates credentials and policies per-agent.
+
+```bash
+# Define an Auditor persona (Read-only) in your workspace config
+mcporter --config <agent-workspace>/config/mcporter.json config add ClickUp-Auditor https://clickup-mcp.taazkareem.com/mcp \
+  --header "X-Persona=auditor" \
+  --header "X-License-Key=your-license-key" \
+  --header "X-ClickUp-Key=api-key" \
+  --header "X-ClickUp-Team-Id=your-team-id"
+
+# Define a Task Worker persona (Daily CRUD)
+mcporter --config <agent-workspace>/config/mcporter.json config add ClickUp-Worker https://clickup-mcp.taazkareem.com/mcp \
+  --header "X-Persona=task_worker" \
+  --header "X-License-Key=your-license-key" \
+  --header "X-ClickUp-Key=api-key-2" \
+  --header "X-ClickUp-Team-Id=your-team-id"
+
+# Now the OpenClaw sub-agent can see the optimized schema and call its focused tools like:
+mcporter list ClickUp-Auditor --schema
+mcporter call ClickUp-Auditor.get_workspace
+
+mcporter list ClickUp-Worker --schema
+mcporter call ClickUp-Worker.create_task listId="123456789" name="New Task"
 ```
+
+>
+> **Isolation**: You can add X-Enabled-Tools or X-Disabled-Tools to mix and match tools and personas, or perhaps enable just a single tool. You can assign different ClickUp API Keys, Team IDs, or even different License Keys to each persona. Since the agent only reads the tool definitions and not the sensitive headers directly, this is the most secure way to handle multi-agent ClickUp configurations.
+
+To see all available personas and what they do, see the [Advanced Configuration](#advanced-configuration) section below.
+
 </details>
 
-<a name="windsurf-setup"></a>
+<a name="cursor-setup"></a>
 <details>
-<summary>&nbsp;<img src="./assets/logos/windsurf-white.svg" height="22" align="center"> <strong>Windsurf</strong></summary>  
+<summary>&nbsp;<img src="./assets/logos/cursor-white.svg" height="22" align="center"> <strong>Cursor</strong></summary>
 
-**Configuration Path:** `<project-root>/.codeium/windsurf/mcp_config.json`
+**Configuration Path:** `<project-root>/.cursor/mcp.json`
 
-**Option A: Cloud / Remote (Easiest)**
+**Option A: Remote / Streamable HTTP (Easiest)**
 ```json
 {
   "mcpServers": {
@@ -166,7 +206,7 @@ The industry-standard ClickUp integration for AI.
 }
 ```
 
-**Option B: Local (stdio)**
+**Option B: Local / STDIO**
 ```json
 {
   "mcpServers": {
@@ -192,7 +232,7 @@ The industry-standard ClickUp integration for AI.
 - **Global:** `~/Library/Application Support/Code/User/mcp.json`
 - **Local:** `<project-root>/.vscode/mcp.json`
 
-**Option A: Cloud / Remote (Easiest)**
+**Option A: Remote / Streamable HTTP (Easiest)**
 ```json
 {
   "mcpServers": {
@@ -206,7 +246,7 @@ The industry-standard ClickUp integration for AI.
 }
 ```
 
-**Option B: Local (stdio)**
+**Option B: Local / STDIO**
 ```json
 {
   "mcpServers": {
@@ -230,7 +270,7 @@ The industry-standard ClickUp integration for AI.
 
 **Configuration Path:** `<project-root>/.roo/mcp.json`
 
-**Option A: Cloud / Remote (Easiest)**
+**Option A: Remote / Streamable HTTP (Easiest)**
 ```json
 {
   "mcpServers": {
@@ -244,7 +284,7 @@ The industry-standard ClickUp integration for AI.
 }
 ```
 
-**Option B: Local (stdio)**
+**Option B: Local / STDIO**
 ```json
 {
   "mcpServers": {
@@ -300,9 +340,9 @@ claude mcp add --transport http ClickUp https://clickup-mcp.taazkareem.com/mcp \
 <details>
 <summary>&nbsp;<img src="https://cdn.simpleicons.org/n8n/FF6D5A" height="22" align="center"> <strong>n8n</strong></summary>  
 
-**Option A: Cloud / Remote (Recommended)**
+**Option A: Remote / Streamable HTTP (Recommended)**
 1. In n8n, add an **"MCP Client"** node.
-2. Set Connection Type to `HTTP Streamable`.
+2. Set Connection Type to `Streamable HTTP`.
 3. Auth Type: `Multiple Headers Auth`.
 4. Header: `X-License-Key` Value: `your-license-key`
 5. URL: `https://clickup-mcp.taazkareem.com/mcp`
@@ -359,14 +399,14 @@ Codex clients (CLI, Desktop App, and VS Code extension) share a single source of
 - **Global:** `~/.codex/config.toml`
 - **Local:** `<project-root>/.codex/config.toml`
 
-**Option A: Cloud / Remote (Easiest)**
+**Option A: Remote / Streamable HTTP (Easiest)**
 ```toml
 [mcp_servers.ClickUp]
 url = "https://clickup-mcp.taazkareem.com/mcp"
 http_headers = { "X-License-Key" = "your-license-key" }
 ```
 
-**Option B: Local (stdio)**
+**Option B: Local / STDIO**
 ```toml
 [mcp_servers.ClickUp]
 command = "npx"
@@ -431,48 +471,42 @@ auggie mcp add ClickUp --url https://clickup-mcp.taazkareem.com/mcp \
 ```
 </details>
 
-<a name="openclaw-setup"></a>
+<a name="windsurf-setup"></a>
 <details>
-<summary>&nbsp;<img src="./assets/logos/openclaw-logo.svg" height="22" align="center"> <strong>OpenClaw (via mcporter) </strong></summary>  
+<summary>&nbsp;<img src="./assets/logos/windsurf-white.svg" height="22" align="center"> <strong>Windsurf</strong></summary>
 
-**1. Enable** the mcporter skill in `~/.openclaw/openclaw.json`:
-```json
-{"skills": {"allowBundled": ["mcporter"]}}
-```
-
-**2. Configure**
-
-The fastest way to configure the server is using the `mcporter` CLI. Run one of the following commands in your terminal:
-
-**Option A: Local (Recommended)**
-*Saves to `<project-root>/config/mcporter.json`*
-```bash
-mcporter config add ClickUp https://clickup-mcp.taazkareem.com/mcp \
-  --auth oauth \
-  --header "X-License-Key=your-license-key"
-```
-
-**Option B: Global**
-*Saves to `~/.mcporter/mcporter.json`*
-```bash
-mcporter config add ClickUp https://clickup-mcp.taazkareem.com/mcp \
-  --scope home \
-  --auth oauth \
-  --header "X-License-Key=your-license-key"
-```
+**Configuration Path:** `<project-root>/.codeium/windsurf/mcp_config.json`
 
-**3. Authenticate** — run once to authorize via browser (tokens are cached):
-```bash
-mcporter auth ClickUp
+**Option A: Remote / Streamable HTTP (Easiest)**
+```json
+{
+  "mcpServers": {
+    "ClickUp": {
+      "url": "https://clickup-mcp.taazkareem.com/mcp",
+      "headers": {
+        "X-License-Key": "your-license-key"
+      }
+    }
+  }
+}
 ```
 
-**4. Use:**
-```bash
-mcporter call ClickUp.get_workspace_hierarchy team_id=0123456789
+**Option B: Local / STDIO**
+```json
+{
+  "mcpServers": {
+    "ClickUp": {
+      "command": "npx",
+      "args": ["-y", "@taazkareem/clickup-mcp-server@latest"],
+      "env": {
+        "CLICKUP_API_KEY": "your-api-key",
+        "CLICKUP_TEAM_ID": "your-team-id",
+        "CLICKUP_MCP_LICENSE_KEY": "your-license-key"
+      }
+    }
+  }
+}
 ```
-
-> **Tip:** Since mcporter is a one-shot CLI client, if using multiple workspaces, always pass `team_id` to target the correct workspace.
-
 </details>
 
 <a name="other-setup"></a>
@@ -517,13 +551,12 @@ Restart your MCP Host (e.g., Cursor IDE). The server will validate your License
 ## <a name="available-tools"></a>🛠️ Available Tools
 
 <details>
-<summary><strong>👇 Click to view all 67 available tools</strong></summary>  
+<summary><strong>👇 Click to view all 145 available tools</strong></summary>
 
 | Category | Tool | Description |
 | :--- | :--- | :--- |
-| **Workspace** | `get_workspace_hierarchy` | Get workspace structure |
-| | `get_workspace_members` | Get all workspace members |
-| | `find_member_by_name` | Find member by name or email |
+| **Workspace** | `get_workspace` | Get workspace structure and metadata (hierarchy, members, plan, seats, shared items, custom task types) |
+| | `get_audit_logs` | Retrieve workspace audit logs (Enterprise only) |
 | **Tasks** | `create_task` | Create a task |
 | | `get_task` | Get single task details |
 | | `update_task` | Modify task properties |
@@ -537,54 +570,133 @@ Restart your MCP Host (e.g., Cursor IDE). The server will validate your License
 | | `move_bulk_tasks` | Move multiple tasks |
 | | `delete_bulk_tasks` | Delete multiple tasks |
 | | `get_workspace_tasks` | Search tasks with Deep Search filtering |
-| | `get_task_comments` | Get comments on a task |
-| | `create_task_comment` | Add a comment to a task |
-| | `attach_task_file` | Attach file to a task |
+| | `get_comments` | Get comments on a task, list, or view |
+| | `create_comment` | Create a comment on a task, list, or view |
+| | `update_comment` | Edit or resolve a comment |
+| | `delete_comment` | Delete a comment |
+| | `get_comment_replies` | Get threaded replies for a comment |
+| | `create_comment_reply` | Reply to a comment in a thread |
+| | `add_comment_reaction` | Add an emoji reaction to a comment |
+| | `remove_comment_reaction` | Remove an emoji reaction from a comment |
+| | `get_comment_subtypes` | Get post subtype IDs for the workspace |
 | | `add_task_link` | Link two tasks together |
-| | `get_task_links` | Get task dependencies |
-| | `delete_task_link` | Remove task dependency |
+| | `get_task_links` | Get task links |
+| | `delete_task_link` | Remove a task link |
+| | `add_task_dependency` | Set a blocking dependency between tasks |
+| | `delete_task_dependency` | Remove a blocking dependency between tasks |
+| **Attachments** | `list_attachments` | List attachments for a task or file custom field (v3) |
+| | `get_attachment` | Get a specific attachment by ID or name (v3) |
+| | `upload_attachment` | Upload a file to a task or file custom field (v3) |
 | **Checklists** | `create_checklist` | Add a checklist to a task |
 | | `edit_checklist` | Rename or reorder a checklist |
 | | `delete_checklist` | Delete a checklist and all its items |
 | | `create_checklist_item` | Add an item to a checklist |
-| | `edit_checklist_item` | Update item (rename, check/uncheck, assign) |
+| | `edit_checklist_item` | Update a checklist item (name, resolved, assignee, nesting) |
 | | `delete_checklist_item` | Remove an item from a checklist |
-| **Lists** | `create_list` | Create list in space |
-| | `create_list_in_folder` | Create list in folder |
+| **Sprints** | `get_active_sprint` | Auto-detect the currently active sprint; returns tasks if exactly one found |
+| | `list_sprints` | List all sprints in a folder |
+| | `get_sprint_tasks` | Get tasks for a specific sprint list |
+| **Lists** | `list_lists` | Get all folderless lists in a space |
 | | `get_list` | Get list details |
+| | `create_list` | Create a list in a space or folder |
 | | `update_list` | Update list properties |
-| | `move_list` | Move list to new Space/Folder |
 | | `delete_list` | Delete a list |
-| **Custom Fields** | `manage_custom_fields` | Manage field definitions and task values (consolidated) |
-| **Spaces** | `manage_spaces` | List, get, create, update, or delete spaces |
-| **Goals** | `manage_goals` | List, get, create, update, or delete goals; manage key results |
-| **Views** | `manage_views` | List, get, create, update, or delete views; get tasks from view |
-| **Folders** | `create_folder` | Create folder |
-| | `get_folder` | Get folder details |
+| | `move_list` | Move a list to a different space or folder (high-integrity) |
+| | `set_list_permissions` | Update list privacy and sharing (ACLs) |
+| **Custom Fields** | `list_custom_fields` | List field definitions for a list, folder, or space |
+| | `create_custom_field` | Add a new field definition to a list |
+| | `set_custom_field_value` | Set a field value on a task |
+| | `remove_custom_field_value` | Clear a field value from a task |
+| **Spaces** | `list_spaces` | List all spaces in the workspace |
+| | `get_space` | Get space details |
+| | `create_space` | Create a new space |
+| | `update_space` | Update space properties |
+| | `delete_space` | Delete a space |
+| | `set_space_permissions` | Update space privacy and sharing (ACLs) |
+| **Goals** | `list_goals` | List all goals in the workspace |
+| | `get_goal` | Get a goal with its key results |
+| | `create_goal` | Create a new goal |
+| | `update_goal` | Update a goal's properties |
+| | `delete_goal` | Delete a goal |
+| | `create_key_result` | Add a key result to a goal |
+| | `update_key_result` | Update a key result |
+| | `delete_key_result` | Delete a key result |
+| **Views** | `list_views` | List views for a space, folder, list, or workspace |
+| | `get_view` | Get a single view |
+| | `create_view` | Create a new view |
+| | `update_view` | Update a view |
+| | `delete_view` | Delete a view |
+| | `get_view_tasks` | Get tasks in a view |
+| **Folders** | `get_folder` | Get folder details |
+| | `create_folder` | Create a folder in a space |
 | | `update_folder` | Update folder properties |
-| | `move_folder` | Move folder to new Space |
 | | `delete_folder` | Delete a folder |
-| **Tags** | `manage_space_tags` | List, create, update, or delete space tags |
+| | `move_folder` | Move a folder to a different space (high-integrity) |
+| | `set_folder_permissions` | Update folder privacy and sharing (ACLs) |
+| **Tags** | `list_space_tags` | List all tags in a space |
+| | `create_space_tag` | Create a new space tag |
+| | `update_space_tag` | Update a space tag's name or colors |
+| | `delete_space_tag` | Delete a tag from a space |
 | | `add_tag_to_task` | Add tag to task |
 | | `remove_tag_from_task` | Remove tag from task |
-| **Time Tracking** | `get_task_time_entries` | Get time entries with date filters |
-| | `get_workspace_time_entries` | Search all time entries |
-| | `start_time_tracking` | Start time tracking |
-| | `stop_time_tracking` | Stop current time tracking |
-| | `add_time_entry` | Add manual time entry |
-| | `delete_time_entry` | Delete time entry |
-| | `get_current_time_entry` | Get running timer |
-| **Docs** | `create_document` | Create a document |
-| | `get_document` | Get a document |
-| | `list_documents` | List documents |
-| | `list_document_pages` | List pages in a document |
-| | `get_document_pages` | Get page content |
-| | `create_document_page` | Add page to document |
-| | `update_document_page` | Update page content |
-| **Chat** | `create_chat_channel` | Create a chat channel |
-| | `get_chat_channels` | List chat channels |
+| **Time Tracking** | `get_time_entries` | Fetch historical time entries |
+| | `get_current_time_entry` | Get currently running timer |
+| | `start_time_entry` | Start tracking time for a task |
+| | `stop_time_entry` | Stop the active timer |
+| | `add_time_entry` | Manually log a time entry |
+| | `update_time_entry` | Modify an existing time entry |
+| | `delete_time_entry` | Delete a time entry |
+| | `get_time_entry_tags` | Fetch all workspace time entry tags |
+| | `add_time_entry_tags` | Add a tag to a time entry |
+| | `update_time_entry_tags` | Rename a workspace time entry tag globally |
+| | `delete_time_entry_tags` | Remove a tag from a time entry |
+| | `get_time_entry_history` | View edit history of a time entry |
+| | `get_time_in_status` | Get time-in-status for multiple tasks |
+| **Docs** | `list_documents` | List documents in a workspace or container |
+| | `get_document` | Get document metadata |
+| | `create_document` | Create a new standalone document |
+| | `list_document_pages` | List all pages in a document |
+| | `get_document_page` | Get content for a single page |
+| | `get_document_pages` | Get content for multiple pages in one call |
+| | `create_document_page` | Add a new page to a document |
+| | `update_document_page` | Modify an existing page (replace/append/prepend) |
+| **Chat** | `list_chat_channels` | List all channels in the workspace |
+| | `get_chat_channel` | Get a single channel |
+| | `create_chat_channel` | Create a new channel |
+| | `update_chat_channel` | Update a channel |
+| | `delete_chat_channel` | Delete a channel |
+| | `get_chat_channel_members` | Get members of a channel |
+| | `get_chat_channel_followers` | Get followers of a channel |
+| | `create_chat_dm` | Create a direct message channel |
+| | `get_chat_messages` | Get messages from a channel |
 | | `create_chat_message` | Send a message to a channel |
-| | `get_chat_messages` | Get message history |
+| | `update_chat_message` | Edit a message |
+| | `delete_chat_message` | Delete a message |
+| | `get_chat_message_replies` | Get threaded replies to a message |
+| | `create_chat_message_reply` | Reply to a message in a thread |
+| | `add_chat_reaction` | Add an emoji reaction to a message |
+| | `remove_chat_reaction` | Remove an emoji reaction |
+| | `get_chat_reactions` | Get all reactions on a message |
+| | `get_chat_tagged_users` | Get users tagged in a message |
+| | `get_chat_message_subtypes` | Get post subtype IDs for the workspace |
+| **Webhooks** | `list_webhooks` | List all webhooks in the workspace |
+| | `create_webhook` | Create a new webhook |
+| | `update_webhook` | Update an existing webhook |
+| | `delete_webhook` | Delete a webhook permanently |
+| **User Groups** | `list_user_groups` | List all user groups in the workspace |
+| | `create_user_group` | Create a new user group |
+| | `update_user_group` | Rename a group or add/remove members |
+| | `delete_user_group` | Delete a user group |
+| **Guests** | `invite_guest` | Invite a guest to the workspace (Enterprise) |
+| | `get_guest` | Get guest details (Enterprise) |
+| | `edit_guest` | Edit guest display name or permissions (Enterprise) |
+| | `remove_guest` | Remove a guest from the workspace (Enterprise) |
+| | `add_guest_to_task` | Grant guest access to a task (Enterprise) |
+| | `remove_guest_from_task` | Revoke guest access from a task (Enterprise) |
+| | `add_guest_to_list` | Grant guest access to a list (Enterprise) |
+| | `remove_guest_from_list` | Revoke guest access from a list (Enterprise) |
+| | `add_guest_to_folder` | Grant guest access to a folder (Enterprise) |
+| | `remove_guest_from_folder` | Revoke guest access from a folder (Enterprise) |
 | **Task Templates** | `get_task_templates` | List available workspace templates |
 | | `create_task_from_template` | Create a task from a template |
 | **Feedback** | `submit_feedback` | Submit feedback or bug reports |
@@ -611,103 +723,32 @@ Restart your MCP Host (e.g., Cursor IDE). The server will validate your License
 
 ### Preset Configurations
 
-Here are copy-pasteable recommended configurations for common agent personas. You can use these in your `mcp.json` (env) or via HTTP headers. Customization is easy - just add or remove tools you don't need.
-
-<details>
-<summary><strong>📋 Auditor</strong></summary>  
-
-Best for agents that need to view data without making any changes. Includes read access for tasks, structural elements, goals, docs, and chat.
-
-**HTTP Header:**
-`X-Enabled-Tools: get_workspace_hierarchy,get_workspace_members,find_member_by_name,get_task,get_workspace_tasks,get_task_comments,get_task_links,get_list,manage_custom_fields,manage_spaces,manage_goals,manage_views,get_folder,get_task_time_entries,get_workspace_time_entries,get_current_time_entry,get_document,list_documents,list_document_pages,get_document_pages,get_chat_channels,get_chat_messages,get_task_templates,submit_feedback`
-
-**JSON / Env:**
-```json
-"env": {
-  "ENABLED_TOOLS": "get_workspace_hierarchy,get_workspace_members,find_member_by_name,get_task,get_workspace_tasks,get_task_comments,get_task_links,get_list,manage_custom_fields,manage_spaces,manage_goals,manage_views,get_folder,get_task_time_entries,get_workspace_time_entries,get_current_time_entry,get_document,list_documents,list_document_pages,get_document_pages,get_chat_channels,get_chat_messages,get_task_templates,submit_feedback"
-}
-```
-</details>
-
-<details>
-<summary><strong>👷 Task Worker</strong></summary>  
-
-Focused on day-to-day task management. Can create/update/delete tasks, track time, manage checklists, and update goals. Cannot modify workspace structure (Lists/Folders).
-
-**HTTP Header:**
-`X-Enabled-Tools: get_workspace_hierarchy,find_member_by_name,create_task,get_task,update_task,manage_custom_fields,move_task,duplicate_task,delete_task,get_workspace_tasks,get_task_comments,create_task_comment,attach_task_file,add_task_to_list,remove_task_from_list,add_task_link,get_task_links,delete_task_link,create_checklist,edit_checklist,delete_checklist,create_checklist_item,edit_checklist_item,delete_checklist_item,get_list,manage_goals,manage_views,get_folder,add_tag_to_task,remove_tag_from_task,start_time_tracking,stop_time_tracking,get_task_templates,create_task_from_template,submit_feedback`
-
-**JSON / Env:**
-```json
-"env": {
-  "ENABLED_TOOLS": "get_workspace_hierarchy,find_member_by_name,create_task,get_task,update_task,manage_custom_fields,move_task,duplicate_task,delete_task,get_workspace_tasks,get_task_comments,create_task_comment,attach_task_file,add_task_to_list,remove_task_from_list,add_task_link,get_task_links,delete_task_link,create_checklist,edit_checklist,delete_checklist,create_checklist_item,edit_checklist_item,delete_checklist_item,get_list,manage_goals,manage_views,get_folder,add_tag_to_task,remove_tag_from_task,start_time_tracking,stop_time_tracking,get_task_templates,create_task_from_template,submit_feedback"
-}
-```
-</details>
-
-<details>
-<summary><strong>⏱️ Time Specialist</strong></summary>  
-
-For agents dedicated to logging time and generating timesheets.
-
-**HTTP Header:**
-`X-Enabled-Tools: get_workspace_hierarchy,find_member_by_name,get_task,get_workspace_tasks,get_task_time_entries,get_workspace_time_entries,start_time_tracking,stop_time_tracking,add_time_entry,delete_time_entry,get_current_time_entry,submit_feedback`
-
-**JSON / Env:**
-```json
-"env": {
-  "ENABLED_TOOLS": "get_workspace_hierarchy,find_member_by_name,get_task,get_workspace_tasks,get_task_time_entries,get_workspace_time_entries,start_time_tracking,stop_time_tracking,add_time_entry,delete_time_entry,get_current_time_entry,submit_feedback"
-}
-```
-</details>
-
-<details>
-<summary><strong>🏗️ Project Manager</strong></summary>  
+Simplify setup by using **Personas**. You can set a persona via the `CLICKUP_MCP_PERSONA` environment variable or the `X-Persona` HTTP header to automatically filter a set of tools. 
 
-Workspace building and alignment. Creates spaces, folders, lists, and goals. Handles bulk task operations and templates.
+Multiple personas can be combined (e.g., `"X-Persona": "task_worker,time_specialist"`).
 
-**HTTP Header:**
-`X-Enabled-Tools: get_workspace_hierarchy,get_workspace_members,find_member_by_name,create_task,get_task,update_task,get_workspace_tasks,create_bulk_tasks,update_bulk_tasks,move_bulk_tasks,delete_bulk_tasks,create_list,create_list_in_folder,get_list,update_list,move_list,delete_list,manage_custom_fields,manage_spaces,manage_goals,manage_views,create_folder,get_folder,update_folder,move_folder,delete_folder,manage_space_tags,get_task_templates,create_task_from_template,submit_feedback`
+| Persona | Description | Target Use Case |
+|---------|-------------|-----------------|
+| 📋 `auditor` | Read-only access | Viewing tasks, goals, docs, and chat without modification. |
+| 👷 `task_worker` | Daily management | Creating/updating tasks, time tracking, checklists. |
+| ⏱️ `time_specialist` | Time tracking focus | Logging time, timesheets, and entry history. |
+| 🏗️ `project_manager` | High-level control | Structural management, spaces, folders, bulk operations. |
+| 📚 `content_manager` | Communication & Files | Docs, chat, messaging, comments, and attachments. |
+| 🏢 `workspace_admin` | Administrative control | Permissions, guest management, and audit logs. |
+| 💻 `developer` | Programmatic focus | Webhooks, custom fields, and bulk automation. |
+| 🛡️ `safe_power_user` | Full access (Filtered) | All tools EXCEPT destructive ones (deletes/removals). |
 
-**JSON / Env:**
+**Local (Environment Variable):**
 ```json
-"env": {
-  "ENABLED_TOOLS": "get_workspace_hierarchy,get_workspace_members,find_member_by_name,create_task,get_task,update_task,get_workspace_tasks,create_bulk_tasks,update_bulk_tasks,move_bulk_tasks,delete_bulk_tasks,create_list,create_list_in_folder,get_list,update_list,move_list,delete_list,manage_custom_fields,manage_spaces,manage_goals,manage_views,create_folder,get_folder,update_folder,move_folder,delete_folder,manage_space_tags,get_task_templates,create_task_from_template,submit_feedback"
-}
+"CLICKUP_MCP_PERSONA": "task_worker"
 ```
-</details>
-
-<details>
-<summary><strong>📚 Content Manager</strong></summary>  
 
-For agents managing documentation and communication.
-
-**HTTP Header:**
-`X-Enabled-Tools: get_workspace_hierarchy,find_member_by_name,get_task,get_workspace_tasks,get_task_comments,create_task_comment,manage_views,create_document,get_document,list_documents,list_document_pages,get_document_pages,create_document_page,update_document_page,create_chat_channel,get_chat_channels,create_chat_message,get_chat_messages,submit_feedback`
-
-**JSON / Env:**
+-or- **Remote (Header):**
 ```json
-"env": {
-  "ENABLED_TOOLS": "get_workspace_hierarchy,find_member_by_name,get_task,get_workspace_tasks,get_task_comments,create_task_comment,manage_views,create_document,get_document,list_documents,list_document_pages,get_document_pages,create_document_page,update_document_page,create_chat_channel,get_chat_channels,create_chat_message,get_chat_messages,submit_feedback"
-}
+"X-Persona": "task_worker"
 ```
-</details>
 
-<details>
-<summary><strong>🛡️ Safe Power User</strong></summary>  
-
-Enabled everything **except** destructive tools. This configuration covers **all 67 tools** by default, only blocking the 8 specific deletion tools listed below. Useful for capable agents that need full access (including Folder/List management) but shouldn't destroy data.
-
-**HTTP Header:**
-`X-Disabled-Tools: delete_task,delete_bulk_tasks,delete_task_link,delete_checklist,delete_checklist_item,delete_list,delete_folder,delete_time_entry`
-
-**JSON / Env:**
-```json
-"env": {
-  "DISABLED_TOOLS": "delete_task,delete_bulk_tasks,delete_task_link,delete_checklist,delete_checklist_item,delete_list,delete_folder,delete_time_entry"
-}
-```
-</details>
+> **💡 Need to customize?** To view the exact tools included in each preset or to build a custom list based on a persona, see the [Personas Reference Guide](./docs/reference/personas.md).
 
 ---
 
@@ -732,4 +773,4 @@ This software makes use of third-party APIs and may reference trademarks or bran
 
 <div align="center">
   <sub>Created by <a href="https://github.com/taazkareem">taazkareem</a></sub>
-</div>
+</div>