@hauptsache.net/clickup-mcp 1.0.4 → 1.1.0

package/README.md

@@ -1,30 +1,87 @@
 # ClickUp MCP for AI Assistants
 
-A Model Context Protocol (MCP) server that enables AI assistants like Claude, Windsurf, and Cursor to interact with your ClickUp tasks.
+Transform your AI assistant into a powerful ClickUp integration for both **agentic coding** and **productivity management**. This Model Context Protocol (MCP) server enables Claude, Windsurf, Cursor, and other AI assistants to seamlessly interact with your ClickUp workspace.
 
-## Why This MCP Is Great
+> **⚠️ Experimental Software Notice**  
+> This MCP is experimental and under active development. While implemented with great care to prevent data loss through append-only description updates and other safety measures, it cannot be guaranteed to be completely safe. Please use with caution, especially in production environments. Always test in a non-critical workspace first. 🧪
 
-This MCP excels at providing AI assistants with rich access to your ClickUp tasks:
+## Two Powerful Use Cases
 
-- **Complete Task Information**: View detailed task data including status, creation date, and assignees
-- **Full Comment History**: Access the entire conversation thread for context
-- **Inline Images Support**: View images embedded in task descriptions and comments
-- **Task Search**: Find relevant tasks using keywords
-- **Todo Management**: List all your open tasks
+### 🛠️ **For Developers & Agentic Coding**
+Originally built to supercharge coding sessions by providing complete task context to AI coding assistants:
 
-The standout feature is the ability to retrieve individual tickets with their complete comment history and inline images, giving your AI assistant the full context of your work.
+- **Instant Requirements**: *"Get task CU-abc123"* → AI gets full requirements, acceptance criteria, comments, and images
+- **Complete Context**: Pass entire task histories to Claude Code, Windsurf, or Cursor for informed development
+- **Visual Specifications**: Include embedded wireframes, mockups, and screenshots in your coding context
+- **Implementation History**: Access all previous discussions and decisions for better code alignment
 
-## Limitations
+### 📋 **For Project Management & Productivity**
+Extended capabilities for conversational ClickUp management and daily workflow optimization.
 
-- **Todo Management**: The todo management feature is currently limited to 50 tasks since it would otherwise flood the context.
-- **No List/Space Support**: This MCP does not currently support browsing ClickUp Lists or Spaces due to performance issues with large instances.
-- **Image Limit**: The MCP processes only the 4 most recent images per task to prevent exceeding context limits. You can adjust this number by setting the `MAX_IMAGES` environment variable, though most AI tools have constraints that prevent using more than 4 images.
+## What You Can Do
+
+Turn natural language into powerful ClickUp actions:
+
+**Agentic Coding & Development:**
+- *"Look at CU-abc123, can you find the relevant code?"*
+- *"Can you build the dashboard like described in https://app.clickup.com/t/12a23b45c?"*
+- *"Check task CU-xyz789 and fix the bugs mentioned in the comments"*
+- *"Implement the API endpoints described in the integration task"*
+
+**Time Tracking & Productivity:**
+- *"Book 2 hours for the client meeting on the XYZ project"*
+- *"How much time did I spend on development tasks this week?"*
+- *"Log 30 minutes for code review on the authentication feature"*
+
+**Smart Search & Discovery:**
+- *"What task did I mention the CSV import in?"*
+- *"Find all tasks related to the payment gateway integration"*
+- *"Show me tasks where users reported login issues"*
+
+**Daily Workflow Management:**
+- *"What do I need to do today?"*
+- *"Create a task for fixing the dashboard bug in the frontend list"*
+- *"Update the API documentation task to 'in review' status"*
+- *"What tasks are blocking the mobile app release?"*
+
+**Rich Context & Collaboration:**
+- *"Show me all comments on the user authentication task"*
+- *"What's the latest update on the database migration?"*
+- *"Add a comment to the design task about the new wireframes"*
+
+## Key Features
+
+### 🔍 **Intelligent Search**
+- Fuzzy matching across task names, descriptions, and comments
+- Multi-language search support for international teams
+- Filter by assignees, projects, status, and metadata
+
+### 💬 **Complete Context**
+- Full comment histories and team discussions
+- Task descriptions with embedded images  
+- List descriptions and project guidelines
+- Access to complete task history and decisions
+
+### ⏱️ **Time Tracking**
+- Log time entries with descriptions
+- View historical time logs and entries
+- Query time entries by task or date range
+
+### 📋 **Task Management**
+- Create and update tasks with markdown descriptions
+- Add comments and collaborate with team members
+- Manage priorities, due dates, assignees, and tags
+- Handle time estimates and custom field values
+
+### 🔒 **Safety Features**
+- **Append-Only Descriptions**: Description fields are never overwritten - new content is safely appended with timestamps
+- **Normal Field Updates**: Status, priority, assignees, tags, and dates can be updated normally (easily revertible through ClickUp's history)
 
 ## Setup for Claude Desktop, Windsurf, or Cursor
 
 1. **Prerequisites**:
-   - A ClickUp account with API access (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)
-   - Your ClickUp API key and Team ID (The ~7 digit number in the url when you are in the settings)
+   - Your `CLICKUP_API_KEY` (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)
+   - and your `CLICKUP_TEAM_ID` (The ~7 digit number in the url when you are in the settings)
 
 2. **Configuration**:
    Add the following to your MCP configuration file:
@@ -36,7 +93,7 @@ The standout feature is the ability to retrieve individual tickets with their co
          "command": "npx",
          "args": [
            "-y",
-           "@hauptsache.net/clickup-mcp"
+           "@hauptsache.net/clickup-mcp@1"
          ],
          "env": {
            "CLICKUP_API_KEY": "your_api_key",
@@ -50,24 +107,51 @@ The standout feature is the ability to retrieve individual tickets with their co
    Replace `your_api_key` and `your_team_id` with your actual ClickUp credentials.
 
 3. **Connect Your AI Assistant**:
-   - **Claude Desktop**: Add this configuration in Settings > MCPs
+   - **Claude Desktop**: Add this configuration in Settings > Developer > Edit Config
    - **Windsurf**: Add to your MCP configuration file
    - **Cursor**: Configure through the MCP settings panel
 
-## Using with Your AI Assistant
-
-Once connected, your AI assistant can:
-
-1. **View Task Details**:
-   Ask: "Show me details for task CU-123456"
-
-2. **Search Tasks**:
-   Ask: "Find tasks related to login functionality"
-
-3. **Check Your Todo List**:
-   Ask: "What tasks are assigned to me?"
-
-The AI will retrieve the information directly from ClickUp, including all text content, comments, and images, providing you with comprehensive assistance on your tasks.
+## MCP Modes & Available Tools
+
+The ClickUp MCP supports three operational modes to balance functionality, security, and performance:
+
+- **🚀 `read-minimal`**: Perfect for AI coding assistants and context gathering
+- **📖 `read`**: Full read-only access for project exploration and workflow understanding  
+- **✏️ `write`** (Default): Complete functionality for task management and productivity workflows
+
+| Tool | read-minimal | read | write | Description |
+|------|:------------:|:----:|:-----:|-------------|
+| `getTaskById` | ✅ | ✅ | ✅ | Get complete task details including comments, images, and metadata |
+| `searchTasks` | ✅ | ✅ | ✅ | Find tasks by content, keywords, assignees, or project context |
+| `listSpaces` | ❌ | ✅ | ✅ | Browse workspace structure and project organization |
+| `listLists` | ❌ | ✅ | ✅ | Browse lists and folders within spaces |
+| `getListInfo` | ❌ | ✅ | ✅ | Get list details and available statuses for task creation |
+| `getTimeEntries` | ❌ | ✅ | ✅ | View time entries and analyze time spent across projects |
+| `createTask` | ❌ | ❌ | ✅ | Create new tasks with full markdown support |
+| `updateTask` | ❌ | ❌ | ✅ | Update tasks (status, priority, assignees, etc.) with **SAFE APPEND-ONLY** descriptions |
+| `updateListInfo` | ❌ | ❌ | ✅ | **SAFE APPEND-ONLY** updates to list descriptions (preserves existing content) |
+| `addComment` | ❌ | ❌ | ✅ | Add comments to tasks for collaboration |
+| `createTimeEntry` | ❌ | ❌ | ✅ | Log time entries for task tracking |
+
+### Setting the Mode
+
+Add the mode to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "clickup": {
+      "command": "npx",
+      "args": ["-y", "@hauptsache.net/clickup-mcp@1"],
+      "env": {
+        "CLICKUP_API_KEY": "your_api_key",
+        "CLICKUP_TEAM_ID": "your_team_id",
+        "CLICKUP_MCP_MODE": "read"
+      }
+    }
+  }
+}
+```
 
 ## Configuration
 
@@ -75,6 +159,7 @@ This MCP server can be configured using environment variables:
 
 - `CLICKUP_API_KEY`: (Required) Your ClickUp API key.
 - `CLICKUP_TEAM_ID`: (Required) Your ClickUp Team ID (formerly Workspace ID).
+- `CLICKUP_MCP_MODE`: (Optional) Controls which tools are available. Options: `read-minimal`, `read`, `write` (default).
 - `MAX_IMAGES`: (Optional) The maximum number of images to return for a task in `getTaskById`. Defaults to 4.
 - `CLICKUP_PRIMARY_LANGUAGE`: (Optional) A hint for the primary language used in your ClickUp tasks (e.g., "de" for German, "en" for English). This helps the `searchTask` tool provide more tailored guidance in its description for multilingual searches.
 - `LANG`: (Optional) If `CLICKUP_PRIMARY_LANGUAGE` is not set, the MCP will check this standard environment variable (e.g., "en_US.UTF-8", "de_DE") as a fallback to infer the primary language.
@@ -87,6 +172,64 @@ The `searchTask` tool's description will dynamically adjust based on the detecte
 
 This feature aims to improve search effectiveness when the language of user queries (often English) differs from the language of the tasks in ClickUp, without making the MCP itself perform translations. The responsibility for providing bilingual search terms still lies with the agent calling the MCP, but the MCP offers more specific advice if it has a language hint.
 
+## Markdown Formatting Support
+
+Task descriptions and list documentation support full markdown formatting:
+
+### Examples
+
+**Task Creation with Markdown:**
+```
+Create a task called "API Integration" with description:
+# API Integration Requirements
+
+## Authentication
+- Implement OAuth 2.0 flow
+- Add JWT token validation
+- **Priority**: High security standards
+
+## Endpoints
+1. `/api/users` - User management
+2. `/api/data` - Data retrieval
+3. `/api/webhook` - Event notifications
+
+## Testing
+- [ ] Unit tests for auth flow
+- [ ] Integration tests
+- [ ] Load testing with 1000+ concurrent users
+
+> **Note**: This replaces the legacy REST implementation
+
+See related task: https://app.clickup.com/t/abc123
+```
+
+**Append-Only Updates (Safe):**
+When updating task descriptions, content is safely appended:
+```markdown
+[Existing task description content]
+
+---
+**Edit (2024-01-15):** Added new acceptance criteria based on client feedback:
+- Must support mobile responsive design
+- Performance requirement: < 2s load time
+```
+
+This ensures no existing content is ever lost while maintaining a clear audit trail.
+
+## Performance & Limitations
+
+**Optimized for AI Workflows:**
+- **Image Processing**: Limited to 4 most recent images per task to prevent running into mcp client limitations (configurable via `MAX_IMAGES`)
+- **Search Scope**: Searches within the most recent 1000-3000 tasks to prevent running into rate limits (exact number varies by endpoint)
+- **Search Results**: Returns up to 50 most relevant matches to prevent flooding the agent with too many results
+
+**Current Scope:**
+- Focused on task-level operations rather than bulk workspace management
+- Optimized for conversational AI workflows rather than data migration
+- Designed for productivity enhancement, not administrative operations
+
+These limitations ensure reliable performance while covering the most common use cases for both development context and productivity management.
+
 ## License
 
 ISC

package/dist/cli.js

@@ -4,12 +4,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 require("dotenv/config"); // Load .env file
 const index_1 = require("./index");
 async function main() {
+    // Wait for server initialization to complete
+    const server = await index_1.serverPromise;
     const args = process.argv.slice(2);
     if (args.length < 1) {
         console.error("Usage: npm run cli <tool-name> [param1=value1 param2=value2 ...]");
         console.error("\nAvailable tools:");
         // @ts-ignore - Accessing private property for testing purposes
-        const tools = index_1.server._registeredTools;
+        const tools = server._registeredTools;
         if (tools) {
             for (const [name, tool] of Object.entries(tools)) {
                 console.error(`  - ${name}: ${tool.description}`);
@@ -42,7 +44,8 @@ async function main() {
             try {
                 if (value.startsWith('{') || value.startsWith('[') ||
                     value === 'true' || value === 'false' ||
-                    !isNaN(Number(value))) {
+                    (value.startsWith('"') && value.endsWith('"')) ||
+                    (!isNaN(Number(value)) && !key.includes('id') && !value.startsWith('"'))) {
                     params[key] = JSON.parse(value);
                 }
                 else {
@@ -56,7 +59,7 @@ async function main() {
     }
     try {
         // @ts-ignore - Accessing private property for testing purposes
-        const tools = index_1.server._registeredTools;
+        const tools = server._registeredTools;
         if (!tools || !tools[toolName]) {
             console.error(`Unknown tool: ${toolName}`);
             process.exit(1);

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const server: McpServer;
+declare const server: McpServer;
+declare const serverPromise: Promise<McpServer>;
+export { server, serverPromise };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyCpE,eAAO,MAAM,MAAM,WAGjB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAapE,QAAA,MAAM,MAAM,WAGV,CAAC;AAsCH,QAAA,MAAM,aAAa,oBAAqB,CAAC;AAGzC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC"}