@taazkareem/clickup-mcp-server 0.6.1 → 0.6.3

package/README.md

@@ -6,7 +6,7 @@
 
 A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.
 
-> 🚧 **Status Update:** Rolling out v0.6.1 which will add Complete Tag Support including natural language tag color commands, Subtasks Support, Custom ID Support, and Logging Fixes
+> 🚧 **Status Update:** Rolling out v0.6.3 will add Global Task Lookup with smart disambiguation, Start Date Support for tasks with natural language expressions, Complete Tag Support including natural language tag color commands, Subtasks Support, Custom ID Support, and Logging Fixes
 
 ## Setup
 
@@ -56,21 +56,21 @@ Or use this npx command:
 
 | 📝 Task Management | 🏷️ Tag Management |
 |----------------------------|----------------------------|
-| • Create, update, and delete tasks<br>• Move and duplicate tasks anywhere<br>• Support for single and bulk operations<br>• Set due dates with natural language<br>• Create and manage subtasks<br>• Add comments and attachments | • Create, update, and delete space tags<br>• Add and remove tags from tasks<br>• Use natural language color commands<br>• Automatic contrasting foreground colors<br>• View all space tags<br>• Tag-based task organization across workspace |
+| • Create, update, and delete tasks<br>• Move and duplicate tasks anywhere<br>• Support for single and bulk operations<br>• Set start/due dates with natural language<br>• Create and manage subtasks<br>• Add comments and attachments | • Create, update, and delete space tags<br>• Add and remove tags from tasks<br>• Use natural language color commands<br>• Automatic contrasting foreground colors<br>• View all space tags<br>• Tag-based task organization across workspace |
 | 🌳 **Workspace Organization** | ⚡ **Integration Features** |
-| • Navigate spaces, folders, and lists<br>• Create and manage folders<br>• Organize lists within spaces<br>• Create lists in folders<br>• View workspace hierarchy<br>• Efficient path navigation | • Name or ID-based lookups<br>• Case-insensitive matching<br>• Markdown formatting support<br>• Built-in rate limiting<br>• Error handling and validation<br>• Comprehensive API coverage |
+| • Navigate spaces, folders, and lists<br>• Create and manage folders<br>• Organize lists within spaces<br>• Create lists in folders<br>• View workspace hierarchy<br>• Efficient path navigation | • Global name or ID-based lookups<br>• Case-insensitive matching<br>• Markdown formatting support<br>• Built-in rate limiting<br>• Error handling and validation<br>• Comprehensive API coverage |
 
 ## Available Tools
 
 | Tool | Description | Required Parameters |
 |------|-------------|-------------------|
 | [get_workspace_hierarchy](docs/api-reference.md#workspace-navigation) | Get workspace structure | None |
-| [create_task](docs/api-reference.md#task-management) | Create a task | `name`, (`listId`/`listName`), optional `parent` |
+| [create_task](docs/api-reference.md#task-management) | Create a task | `name`, (`listId`/`listName`) |
 | [create_bulk_tasks](docs/api-reference.md#task-management) | Create multiple tasks | `tasks[]` |
 | [update_task](docs/api-reference.md#task-management) | Modify task | `taskId`/`taskName` |
 | [update_bulk_tasks](docs/api-reference.md#task-management) | Update multiple tasks | `tasks[]` with IDs or names |
-| [get_tasks](docs/api-reference.md#task-management) | Get tasks from list | `listId`/`listName`, optional `subtasks` |
-| [get_task](docs/api-reference.md#task-management) | Get single task details | `taskId`/`taskName`, optional `subtasks` |
+| [get_tasks](docs/api-reference.md#task-management) | Get tasks from list | `listId`/`listName` |
+| [get_task](docs/api-reference.md#task-management) | Get single task details | `taskId`/`taskName` (with smart disambiguation) |
 | [get_workspace_tasks](docs/api-reference.md#task-management) | Get tasks with filtering | At least one filter (tags, list_ids, space_ids, etc.) |
 | [get_task_comments](docs/api-reference.md#task-management) | Get comments on a task | `taskId`/`taskName` |
 | [create_task_comment](docs/api-reference.md#task-management) | Add a comment to a task | `commentText`, (`taskId`/(`taskName`+`listName`)) |

package/build/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
  * SPDX-License-Identifier: MIT

package/build/logger.js

@@ -48,7 +48,32 @@ export function log(level, message, data) {
         return;
     }
     const timestamp = new Date().toISOString();
-    const logMessage = `[${timestamp}] [PID:${pid}] ${level.toUpperCase()}: ${message}${data ? '\n' + JSON.stringify(data, null, 2) : ''}`;
+    // Format the log message differently based on the level and data
+    let logMessage = `[${timestamp}] [PID:${pid}] ${level.toUpperCase()}: ${message}`;
+    // Format data differently based on content and log level
+    if (data) {
+        // For debugging and trace levels, try to make the data more readable
+        if (level === 'debug' || level === 'trace') {
+            // If data is a simple object with few properties, format it inline
+            if (typeof data === 'object' && data !== null && !Array.isArray(data) &&
+                Object.keys(data).length <= 4 && Object.keys(data).every(k => typeof data[k] !== 'object' || data[k] === null)) {
+                const dataStr = Object.entries(data)
+                    .map(([k, v]) => `${k}=${v === undefined ? 'undefined' :
+                    (v === null ? 'null' :
+                        (typeof v === 'string' ? `"${v}"` : v))}`)
+                    .join(' ');
+                logMessage += ` (${dataStr})`;
+            }
+            else {
+                // For more complex data, keep the JSON format but on new lines
+                logMessage += '\n' + JSON.stringify(data, null, 2);
+            }
+        }
+        else {
+            // For other levels, keep the original JSON format
+            logMessage += '\n' + JSON.stringify(data, null, 2);
+        }
+    }
     // When using stdio transport, log to stderr which is captured by host application
     console.error(logMessage);
     // Write to file

package/build/server.js

@@ -19,7 +19,7 @@ const logger = new Logger('Server');
 const { workspace } = clickUpServices;
 export const server = new Server({
     name: "clickup-mcp-server",
-    version: "0.6.1",
+    version: "0.6.3",
 }, {
     capabilities: {
         tools: {},

package/build/services/clickup/base.js

@@ -230,13 +230,30 @@ export class BaseClickUpService {
                 });
             });
         }
+        // Track request metadata
+        let requestMethod = 'unknown';
+        let requestPath = 'unknown';
+        let requestData = undefined;
+        // Set up interceptor to capture request details
+        const requestInterceptorId = this.client.interceptors.request.use((config) => {
+            // Capture request metadata
+            requestMethod = config.method?.toUpperCase() || 'unknown';
+            requestPath = config.url || 'unknown';
+            requestData = config.data;
+            return config;
+        });
         const startTime = Date.now();
         try {
             // Execute the request function
             const result = await fn();
             // Debug log for successful requests with timing information
             const duration = Date.now() - startTime;
-            this.logger.debug(`Request completed successfully in ${duration}ms`);
+            this.logger.debug(`Request completed successfully in ${duration}ms`, {
+                method: requestMethod,
+                path: requestPath,
+                duration,
+                responseType: result ? typeof result : 'undefined'
+            });
             return result;
         }
         catch (error) {
@@ -268,6 +285,10 @@ export class BaseClickUpService {
             // For other errors, just throw
             throw error;
         }
+        finally {
+            // Always remove the interceptor
+            this.client.interceptors.request.eject(requestInterceptorId);
+        }
     }
     /**
      * Gets the ClickUp team ID associated with this service instance

package/build/services/clickup/bulk.js

@@ -55,66 +55,97 @@ export class BulkService {
         }
     }
     /**
-     * Update multiple tasks efficiently
-     *
-     * @param tasks Array of task IDs and update data
-     * @param options Batch processing options
-     * @returns Results containing successful and failed task updates
+     * Update multiple tasks
+     * @param tasks Array of tasks to update with their new data
+     * @param options Optional batch processing settings
+     * @returns Array of updated tasks
      */
     async updateTasks(tasks, options) {
-        logger.info(`Updating ${tasks.length} tasks`, {
-            batchSize: options?.batchSize,
-            concurrency: options?.concurrency
-        });
+        logger.info('Starting bulk update operation', { taskCount: tasks.length });
         try {
-            return await processBatch(tasks, ({ id, data }, index) => {
-                logger.debug(`Updating task ${index + 1}/${tasks.length}`, {
-                    taskId: id
-                });
-                // Reuse the single-task update method
-                return this.taskService.updateTask(id, data);
+            // Extract all task IDs that need validation
+            const taskIds = tasks
+                .map(task => task.taskId)
+                .filter((id) => !!id);
+            // Validate all tasks exist in parallel
+            if (taskIds.length > 0) {
+                await this.taskService.validateTasksExist(taskIds);
+            }
+            // Process updates in batches
+            return await processBatch(tasks, async (task) => {
+                const { taskId, taskName, listName, customTaskId, ...updateData } = task;
+                if (taskId) {
+                    return await this.taskService.updateTask(taskId, updateData);
+                }
+                else if (customTaskId) {
+                    const resolvedTask = await this.taskService.getTaskByCustomId(customTaskId);
+                    return await this.taskService.updateTask(resolvedTask.id, updateData);
+                }
+                else if (taskName && listName) {
+                    // For tasks identified by name, we need to resolve the ID first
+                    const taskList = await this.taskService.getTasks(listName);
+                    const matchingTask = taskList.find(t => t.name === taskName);
+                    if (!matchingTask) {
+                        throw new ClickUpServiceError(`Task "${taskName}" not found in list "${listName}"`, ErrorCode.NOT_FOUND);
+                    }
+                    return await this.taskService.updateTask(matchingTask.id, updateData);
+                }
+                else {
+                    throw new ClickUpServiceError('Invalid task identification. Provide either taskId, customTaskId, or both taskName and listName', ErrorCode.INVALID_PARAMETER);
+                }
             }, options);
         }
         catch (error) {
-            logger.error(`Failed to update tasks in bulk`, {
-                taskCount: tasks.length,
-                error: error instanceof Error ? error.message : String(error)
-            });
-            throw new ClickUpServiceError(`Failed to update tasks in bulk: ${error instanceof Error ? error.message : String(error)}`, error instanceof ClickUpServiceError ? error.code : ErrorCode.UNKNOWN, { taskCount: tasks.length });
+            logger.error('Bulk update operation failed', error);
+            throw error;
         }
     }
     /**
-     * Move multiple tasks to a different list efficiently
-     *
-     * @param taskIds Array of task IDs to move
-     * @param targetListId ID of the list to move tasks to
-     * @param options Batch processing options
-     * @returns Results containing successful and failed moves
+     * Move multiple tasks to a different list
+     * @param tasks Array of tasks to move (each with taskId or taskName + listName)
+     * @param targetListId ID of the destination list
+     * @param options Optional batch processing settings
+     * @returns Array of moved tasks
      */
-    async moveTasks(taskIds, targetListId, options) {
-        logger.info(`Moving ${taskIds.length} tasks to list ${targetListId}`, {
-            batchSize: options?.batchSize,
-            concurrency: options?.concurrency
-        });
+    async moveTasks(tasks, targetListId, options) {
+        logger.info('Starting bulk move operation', { taskCount: tasks.length, targetListId });
         try {
-            // First validate that the target list exists - do this once for all tasks
+            // First validate the destination list exists
             await this.taskService.validateListExists(targetListId);
-            return await processBatch(taskIds, (taskId, index) => {
-                logger.debug(`Moving task ${index + 1}/${taskIds.length}`, {
-                    taskId,
-                    targetListId
-                });
-                // Reuse the single-task move method
-                return this.taskService.moveTask(taskId, targetListId);
+            // Extract all task IDs that need validation
+            const taskIds = tasks
+                .map(task => task.taskId)
+                .filter((id) => !!id);
+            // Validate all tasks exist in parallel
+            if (taskIds.length > 0) {
+                await this.taskService.validateTasksExist(taskIds);
+            }
+            // Process moves in batches
+            return await processBatch(tasks, async (task) => {
+                if (task.taskId) {
+                    return await this.taskService.moveTask(task.taskId, targetListId);
+                }
+                else if (task.customTaskId) {
+                    const resolvedTask = await this.taskService.getTaskByCustomId(task.customTaskId);
+                    return await this.taskService.moveTask(resolvedTask.id, targetListId);
+                }
+                else if (task.taskName && task.listName) {
+                    // For tasks identified by name, we need to resolve the ID first
+                    const taskList = await this.taskService.getTasks(task.listName);
+                    const matchingTask = taskList.find(t => t.name === task.taskName);
+                    if (!matchingTask) {
+                        throw new ClickUpServiceError(`Task "${task.taskName}" not found in list "${task.listName}"`, ErrorCode.NOT_FOUND);
+                    }
+                    return await this.taskService.moveTask(matchingTask.id, targetListId);
+                }
+                else {
+                    throw new ClickUpServiceError('Invalid task identification. Provide either taskId, customTaskId, or both taskName and listName', ErrorCode.INVALID_PARAMETER);
+                }
             }, options);
         }
         catch (error) {
-            logger.error(`Failed to move tasks in bulk`, {
-                targetListId,
-                taskCount: taskIds.length,
-                error: error instanceof Error ? error.message : String(error)
-            });
-            throw new ClickUpServiceError(`Failed to move tasks in bulk: ${error instanceof Error ? error.message : String(error)}`, error instanceof ClickUpServiceError ? error.code : ErrorCode.UNKNOWN, { targetListId, taskCount: taskIds.length });
+            logger.error('Bulk move operation failed', error);
+            throw error;
         }
     }
     /**

package/build/services/clickup/index.js

@@ -13,13 +13,13 @@ export { BaseClickUpService, ClickUpServiceError, ErrorCode } from './base.js';
 export * from './types.js';
 // Export service modules
 export { WorkspaceService } from './workspace.js';
-export { TaskService } from './task.js';
+export { TaskService } from './task/index.js';
 export { ListService } from './list.js';
 export { FolderService } from './folder.js';
 export { ClickUpTagService } from './tag.js';
 // Import service classes for the factory function
 import { WorkspaceService } from './workspace.js';
-import { TaskService } from './task.js';
+import { TaskService } from './task/index.js';
 import { ListService } from './list.js';
 import { FolderService } from './folder.js';
 import { ClickUpTagService } from './tag.js';

package/build/services/clickup/task/index.js

@@ -0,0 +1,32 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp Task Service - Module Exports
+ *
+ * Exports all task-related functionality:
+ * - Core task operations (CRUD)
+ * - Task searching and filtering
+ * - Task comments
+ * - File attachments
+ * - Task tags
+ * - Custom fields
+ */
+// Export the main TaskService class
+export { TaskService } from './task-service.js';
+// Export all component services
+export { TaskServiceCore } from './task-core.js';
+export { TaskServiceSearch } from './task-search.js';
+export { TaskServiceAttachments } from './task-attachments.js';
+export { TaskServiceComments } from './task-comments.js';
+export { TaskServiceTags } from './task-tags.js';
+export { TaskServiceCustomFields } from './task-custom-fields.js';
+// Export types and interfaces from all modules
+export * from './task-core.js';
+export * from './task-search.js';
+export * from './task-attachments.js';
+export * from './task-comments.js';
+export * from './task-tags.js';
+export * from './task-custom-fields.js';
+// Re-export TaskService as the default export
+export { TaskService as default } from './task-service.js';

package/build/services/clickup/task/task-attachments.js

@@ -0,0 +1,97 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp Task Service - Attachments Module
+ *
+ * Handles file attachment operations for ClickUp tasks, supporting three methods:
+ * - Uploading file attachments from base64/buffer data
+ * - Uploading file attachments from a URL (web URLs like http/https)
+ * - Uploading file attachments from local file paths (absolute paths)
+ */
+import { TaskServiceSearch } from './task-search.js';
+/**
+ * Attachment functionality for the TaskService
+ */
+export class TaskServiceAttachments extends TaskServiceSearch {
+    /**
+     * Upload a file attachment to a ClickUp task
+     * @param taskId The ID of the task to attach the file to
+     * @param fileData The file data as a Buffer
+     * @param fileName The name of the file
+     * @returns Promise resolving to the attachment response from ClickUp
+     */
+    async uploadTaskAttachment(taskId, fileData, fileName) {
+        this.logOperation('uploadTaskAttachment', { taskId, fileName, fileSize: fileData.length });
+        try {
+            return await this.makeRequest(async () => {
+                // Create FormData for multipart/form-data upload
+                const FormData = (await import('form-data')).default;
+                const formData = new FormData();
+                // Add the file to the form data
+                formData.append('attachment', fileData, {
+                    filename: fileName,
+                    contentType: 'application/octet-stream' // Let ClickUp determine the content type
+                });
+                // Use the raw axios client for this request since we need to handle FormData
+                const response = await this.client.post(`/task/${taskId}/attachment`, formData, {
+                    headers: {
+                        ...formData.getHeaders(),
+                        'Authorization': this.apiKey
+                    }
+                });
+                return response.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to upload attachment to task ${taskId}`);
+        }
+    }
+    /**
+     * Upload a file attachment to a ClickUp task from a URL
+     * @param taskId The ID of the task to attach the file to
+     * @param fileUrl The URL of the file to download and attach
+     * @param fileName Optional file name (if not provided, it will be extracted from the URL)
+     * @param authHeader Optional authorization header for the URL
+     * @returns Promise resolving to the attachment response from ClickUp
+     */
+    async uploadTaskAttachmentFromUrl(taskId, fileUrl, fileName, authHeader) {
+        this.logOperation('uploadTaskAttachmentFromUrl', { taskId, fileUrl, fileName });
+        try {
+            return await this.makeRequest(async () => {
+                // Import required modules
+                const axios = (await import('axios')).default;
+                const FormData = (await import('form-data')).default;
+                // Download the file from the URL
+                const headers = {};
+                if (authHeader) {
+                    headers['Authorization'] = authHeader;
+                }
+                const response = await axios.get(fileUrl, {
+                    responseType: 'arraybuffer',
+                    headers
+                });
+                // Extract filename from URL if not provided
+                const actualFileName = fileName || fileUrl.split('/').pop() || 'downloaded-file';
+                // Create FormData for multipart/form-data upload
+                const formData = new FormData();
+                // Add the file to the form data
+                formData.append('attachment', Buffer.from(response.data), {
+                    filename: actualFileName,
+                    contentType: 'application/octet-stream'
+                });
+                // Upload the file to ClickUp
+                const uploadResponse = await this.client.post(`/task/${taskId}/attachment`, formData, {
+                    headers: {
+                        ...formData.getHeaders(),
+                        'Authorization': this.apiKey
+                    }
+                });
+                return uploadResponse.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to upload attachment from URL to task ${taskId}`);
+        }
+    }
+}

package/build/services/clickup/task/task-comments.js

@@ -0,0 +1,104 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp Task Service - Comments Module
+ *
+ * Handles comment operations for ClickUp tasks, including:
+ * - Retrieving comments for a task
+ * - Creating comments on a task
+ */
+import { TaskServiceAttachments } from './task-attachments.js';
+/**
+ * Comments functionality for the TaskService
+ */
+export class TaskServiceComments extends TaskServiceAttachments {
+    /**
+     * Get all comments for a task
+     *
+     * @param taskId ID of the task to get comments for
+     * @param start Optional pagination start
+     * @param startId Optional comment ID to start from
+     * @returns Array of task comments
+     */
+    async getTaskComments(taskId, start, startId) {
+        this.logOperation('getTaskComments', { taskId, start, startId });
+        try {
+            // Build query parameters for pagination
+            const queryParams = new URLSearchParams();
+            if (start !== undefined) {
+                queryParams.append('start', start.toString());
+            }
+            if (startId) {
+                queryParams.append('start_id', startId);
+            }
+            const queryString = queryParams.toString() ? `?${queryParams.toString()}` : '';
+            const response = await this.client.get(`/task/${taskId}/comment${queryString}`);
+            return response.data.comments || [];
+        }
+        catch (error) {
+            throw this.handleError(error, 'Failed to get task comments');
+        }
+    }
+    /**
+     * Create a comment on a task
+     *
+     * @param taskId ID of the task to comment on
+     * @param commentText Text content of the comment
+     * @param notifyAll Whether to notify all assignees
+     * @param assignee Optional user ID to assign the comment to
+     * @returns The created comment
+     */
+    async createTaskComment(taskId, commentText, notifyAll = false, assignee) {
+        this.logOperation('createTaskComment', { taskId, commentText, notifyAll, assignee });
+        try {
+            const payload = {
+                comment_text: commentText,
+                notify_all: notifyAll
+            };
+            if (assignee) {
+                payload.assignee = assignee;
+            }
+            // Make the request directly without using makeRequest for better error handling
+            const response = await this.client.post(`/task/${taskId}/comment`, payload);
+            // Handle different response formats from ClickUp API
+            if (response.data) {
+                if (response.data.comment) {
+                    // Standard format: { comment: ClickUpComment }
+                    return response.data.comment;
+                }
+                else if (response.data.id && (response.data.comment_text || response.data.comment)) {
+                    // Direct format: the comment object itself
+                    return response.data;
+                }
+                else {
+                    // Fallback: construct a minimal valid comment object
+                    return {
+                        id: response.data.id || `custom-${Date.now()}`,
+                        comment: response.data.comment || commentText,
+                        comment_text: response.data.comment_text || commentText,
+                        user: response.data.user || { id: 0, username: 'Unknown', email: '', color: '' },
+                        date: response.data.date || new Date().toISOString(),
+                        resolved: false
+                    };
+                }
+            }
+            throw new Error('Invalid response from ClickUp API');
+        }
+        catch (error) {
+            // Check if comment might have been created despite error
+            if (error.response?.status === 200 || error.response?.status === 201) {
+                // Try to construct a comment object from what we know
+                return {
+                    id: `fallback-${Date.now()}`,
+                    comment: commentText,
+                    comment_text: commentText,
+                    user: { id: 0, username: 'Unknown', email: '', color: '' },
+                    date: new Date().toISOString(),
+                    resolved: false
+                };
+            }
+            throw this.handleError(error, 'Failed to create task comment');
+        }
+    }
+}