@taazkareem/clickup-mcp-server 0.6.3 → 0.6.5

package/build/tools/task/attachments.js

@@ -33,22 +33,23 @@ export const attachTaskFileTool = {
     description: `Purpose: Attaches a file to a ClickUp task.
 
 Valid Usage:
-1. Upload from base64: Provide file_data + file_name
-2. Upload from URL or local file: Provide file_url + optional file_name
-   - For web URLs: Use http:// or https:// URLs
-   - For local files: Use absolute file paths (starting with / or drive letter)
-3. For large files, advanced options are available via chunk_* parameters
+1. Use taskId (preferred) - works with both regular and custom IDs
+2. Use taskName + listName for targeted search
+
+File Sources:
+- Base64: Provide file_data + file_name
+- URL: Provide file_url starting with http:// or https://
+- Local file: Provide file_url as absolute path
+- Chunked upload: Use chunk_* parameters for large files
 
 Requirements:
-- EITHER taskId OR (taskName + listName) is REQUIRED
-- EITHER file_data OR file_url is REQUIRED
+- Task identification: EITHER taskId OR taskName REQUIRED
+- File source: EITHER file_data+file_name OR file_url OR chunk_session REQUIRED
 
 Notes:
-- The system automatically selects the best upload method based on file size and source
-- Base64 method has a 10MB size limit due to encoding overhead (file_data parameter)
-- URL method works for files hosted online (file_url parameter with http/https)
-- Local file method works with absolute paths only (file_url parameter with / or drive letter)
-- For large files, the system may use chunked uploading automatically`,
+- System automatically selects best upload method based on file size
+- Base64 uploads limited to 10MB
+- Using taskName without listName may match multiple tasks`,
     inputSchema: {
         type: "object",
         properties: {
@@ -58,11 +59,11 @@ Notes:
             },
             taskName: {
                 type: "string",
-                description: "Name of the task to attach the file to. When using this parameter, you MUST also provide listName."
+                description: "Name of the task to attach the file to. The tool will search for tasks with this name across all lists unless listName is specified."
             },
             listName: {
                 type: "string",
-                description: "Name of the list containing the task. REQUIRED when using taskName."
+                description: "Optional: Name of list containing the task. Providing this narrows the search to a specific list, improving performance and reducing ambiguity."
             },
             file_name: {
                 type: "string",
@@ -97,8 +98,7 @@ Notes:
                 type: "boolean",
                 description: "Optional: For advanced usage with large file chunking. Whether this is the final chunk."
             }
-        },
-        required: [] // Will validate based on context in the handler
+        }
     }
 };
 /**

package/build/tools/task/bulk-operations.js

@@ -76,18 +76,16 @@ export const createBulkTasksTool = {
     description: `Purpose: Create multiple tasks in a list efficiently.
 
 Valid Usage:
-1. An array of tasks with required properties + listId (preferred)
-2. An array of tasks with required properties + listName
+1. Provide listId + array of tasks (preferred)
+2. Provide listName + array of tasks
 
 Requirements:
 - tasks: REQUIRED (array of tasks, each with at least a name)
-- EITHER listId OR listName: REQUIRED
+- List identification: EITHER listId OR listName REQUIRED
 
 Notes:
-- Configure batch size and concurrency via options for performance
-- Each task should have a name with emoji prefix
-- All tasks will be created in the same list
-- Custom fields can be set for each task using the custom_fields property (array of {id, value} objects)`,
+- Configure batch processing via options parameter
+- Custom fields supported for each task`,
     inputSchema: {
         type: "object",
         properties: {
@@ -157,37 +155,7 @@ Notes:
                 type: "string",
                 description: "Name of list for new tasks. Only use if you don't have listId."
             },
-            options: {
-                description: "Processing options (or JSON string representing options)",
-                oneOf: [
-                    {
-                        type: "object",
-                        description: "Optional processing settings",
-                        properties: {
-                            batchSize: {
-                                type: "number",
-                                description: "Tasks per batch (default: 10)"
-                            },
-                            concurrency: {
-                                type: "number",
-                                description: "Parallel operations (default: 3)"
-                            },
-                            continueOnError: {
-                                type: "boolean",
-                                description: "Continue if some tasks fail"
-                            },
-                            retryCount: {
-                                type: "number",
-                                description: "Retry attempts for failures"
-                            }
-                        }
-                    },
-                    {
-                        type: "string",
-                        description: "JSON string representing options. Will be parsed automatically."
-                    }
-                ]
-            }
+            options: bulkOptionsSchema
         },
         required: ["tasks"]
     }
@@ -200,19 +168,16 @@ export const updateBulkTasksTool = {
     description: `Purpose: Update multiple tasks efficiently in a single operation.
 
 Valid Usage:
-1. For each task, provide taskId (preferred)
-2. For each task, provide taskName + listName
+1. Provide array of tasks with taskId (preferred)
+2. Provide array of tasks with taskName + listName
 
 Requirements:
 - tasks: REQUIRED (array of tasks to update)
-- For each task entry, EITHER taskId OR (taskName + listName) is REQUIRED
-- At least one update field per task (name, description, status, priority, dueDate)
+- Each task needs identification and update fields
 
 Notes:
 - Only specified fields will be updated for each task
-- Configure batch size and concurrency via options for performance
-- Each task can have different fields to update
-- Custom fields can be updated using the custom_fields property (array of {id, value} objects)`,
+- Configure batch processing via options parameter`,
     inputSchema: {
         type: "object",
         properties: {
@@ -222,7 +187,22 @@ Notes:
                 items: {
                     type: "object",
                     properties: {
-                        ...taskIdentifierSchema,
+                        taskId: {
+                            type: "string",
+                            description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                        },
+                        taskName: {
+                            type: "string",
+                            description: "Task name. Requires listName when used."
+                        },
+                        listName: {
+                            type: "string",
+                            description: "REQUIRED with taskName: List containing the task."
+                        },
+                        customTaskId: {
+                            type: "string",
+                            description: "Custom task ID (e.g., 'DEV-1234'). Only use if you want to explicitly force custom ID lookup. In most cases, use taskId which auto-detects ID format."
+                        },
                         name: {
                             type: "string",
                             description: "New name with emoji prefix"
@@ -268,37 +248,7 @@ Notes:
                     }
                 }
             },
-            options: {
-                description: "Processing options (or JSON string representing options)",
-                oneOf: [
-                    {
-                        type: "object",
-                        description: "Optional processing settings",
-                        properties: {
-                            batchSize: {
-                                type: "number",
-                                description: "Tasks per batch (default: 10)"
-                            },
-                            concurrency: {
-                                type: "number",
-                                description: "Parallel operations (default: 3)"
-                            },
-                            continueOnError: {
-                                type: "boolean",
-                                description: "Continue if some tasks fail"
-                            },
-                            retryCount: {
-                                type: "number",
-                                description: "Retry attempts for failures"
-                            }
-                        }
-                    },
-                    {
-                        type: "string",
-                        description: "JSON string representing options. Will be parsed automatically."
-                    }
-                ]
-            }
+            options: bulkOptionsSchema
         },
         required: ["tasks"]
     }
@@ -311,21 +261,14 @@ export const moveBulkTasksTool = {
     description: `Purpose: Move multiple tasks to a different list efficiently.
 
 Valid Usage:
-1. For each task, provide taskId + target list (preferred)
-2. For each task, provide taskName + listName + target list
+1. Provide tasks array + target list
 
 Requirements:
-- tasks: REQUIRED (array of tasks to move)
-- EITHER targetListId OR targetListName: REQUIRED
-- For each task entry, EITHER taskId OR (taskName + listName) is REQUIRED
-
-Notes:
-- Configure batch size and concurrency via options for performance
-- All tasks will be moved to the same destination list
+- tasks: REQUIRED (array of task identifiers)
+- Target list: EITHER targetListId OR targetListName REQUIRED
 
 Warning:
-- Task statuses may reset if destination list has different status options
-- Using taskName without listName will fail as tasks may have identical names across lists`,
+- Task statuses may reset if destination list has different status options`,
     inputSchema: {
         type: "object",
         properties: {
@@ -335,7 +278,22 @@ Warning:
                 items: {
                     type: "object",
                     properties: {
-                        ...taskIdentifierSchema
+                        taskId: {
+                            type: "string",
+                            description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                        },
+                        taskName: {
+                            type: "string",
+                            description: "Task name. Requires listName when used."
+                        },
+                        listName: {
+                            type: "string",
+                            description: "REQUIRED with taskName: List containing the task."
+                        },
+                        customTaskId: {
+                            type: "string",
+                            description: "Custom task ID (e.g., 'DEV-1234'). Only use if you want to explicitly force custom ID lookup. In most cases, use taskId which auto-detects ID format."
+                        }
                     }
                 }
             },
@@ -360,20 +318,15 @@ export const deleteBulkTasksTool = {
     description: `Purpose: PERMANENTLY DELETE multiple tasks at once.
 
 Valid Usage:
-1. For each task, provide taskId (preferred and safest)
-2. For each task, provide taskName + listName
+1. Provide array of tasks with taskId (preferred)
+2. Provide array of tasks with taskName + listName
 
 Requirements:
-- tasks: REQUIRED (array of tasks to delete)
-- For each task entry, EITHER taskId OR (taskName + listName) is REQUIRED
-
-Notes:
-- Configure batch size and concurrency via options for performance
+- tasks: REQUIRED (array of task identifiers)
 
 Warning:
-- This action CANNOT be undone for any of the tasks
-- Using taskName without listName is dangerous as names may not be unique
-- Always provide listName when using taskName for safer targeting`,
+- This action CANNOT be undone
+- Always provide listName when using taskName`,
     inputSchema: {
         type: "object",
         properties: {
@@ -383,7 +336,22 @@ Warning:
                 items: {
                     type: "object",
                     properties: {
-                        ...taskIdentifierSchema
+                        taskId: {
+                            type: "string",
+                            description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                        },
+                        taskName: {
+                            type: "string",
+                            description: "Task name. Requires listName when used."
+                        },
+                        listName: {
+                            type: "string",
+                            description: "REQUIRED with taskName: List containing the task."
+                        },
+                        customTaskId: {
+                            type: "string",
+                            description: "Custom task ID (e.g., 'DEV-1234'). Only use if you want to explicitly force custom ID lookup. In most cases, use taskId which auto-detects ID format."
+                        }
                     }
                 }
             },

package/build/tools/task/handlers.js

@@ -392,58 +392,76 @@ export async function getWorkspaceTasksHandler(taskService, params) {
  * Handler for creating multiple tasks
  */
 export async function createBulkTasksHandler(params) {
-    validateBulkTasks(params.tasks);
-    const listId = await getListId(params.listId, params.listName);
-    // Process tasks - prepare data for each task
-    const tasks = params.tasks.map(task => {
-        const processedTask = { ...task };
+    const { tasks, listId, listName, options } = params;
+    // Validate tasks array
+    validateBulkTasks(tasks, 'create');
+    // Validate and resolve list ID
+    const targetListId = await resolveListIdWithValidation(listId, listName);
+    // Format tasks for creation
+    const formattedTasks = tasks.map(task => {
+        const taskData = {
+            name: task.name,
+            description: task.description,
+            markdown_description: task.markdown_description,
+            status: task.status,
+            priority: toTaskPriority(task.priority),
+            tags: task.tags,
+            custom_fields: task.custom_fields
+        };
+        // Add due date if specified
         if (task.dueDate) {
-            processedTask.due_date = parseDueDate(task.dueDate);
-            delete processedTask.dueDate;
+            taskData.due_date = parseDueDate(task.dueDate);
+            taskData.due_date_time = true;
         }
-        // Make sure custom_fields is preserved in the processed task
-        if (task.custom_fields) {
-            processedTask.custom_fields = task.custom_fields;
+        // Add start date if specified
+        if (task.startDate) {
+            taskData.start_date = parseDueDate(task.startDate);
+            taskData.start_date_time = true;
         }
-        return processedTask;
+        return taskData;
     });
-    const result = await bulkService.createTasks(listId, tasks, parseBulkOptions(params.options));
-    return result.successful;
+    // Parse bulk options
+    const bulkOptions = parseBulkOptions(options);
+    // Create tasks - pass arguments in correct order: listId, tasks, options
+    return await bulkService.createTasks(targetListId, formattedTasks, bulkOptions);
 }
 /**
  * Handler for updating multiple tasks
  */
 export async function updateBulkTasksHandler(params) {
-    validateBulkTasks(params.tasks);
-    const updates = await Promise.all(params.tasks.map(async (task) => {
-        validateTaskUpdateData(task);
-        const taskId = await getTaskId(task.taskId, task.taskName, task.listName);
-        return { id: taskId, data: buildUpdateData(task) };
-    }));
-    const result = await bulkService.updateTasks(updates, parseBulkOptions(params.options));
-    return result.successful;
+    const { tasks, options } = params;
+    // Validate tasks array
+    validateBulkTasks(tasks, 'update');
+    // Parse bulk options
+    const bulkOptions = parseBulkOptions(options);
+    // Update tasks
+    return await bulkService.updateTasks(tasks, bulkOptions);
 }
 /**
  * Handler for moving multiple tasks
  */
 export async function moveBulkTasksHandler(params) {
-    validateBulkTasks(params.tasks);
-    if (!params.targetListId && !params.targetListName) {
-        throw new Error("Either targetListId or targetListName must be provided");
-    }
-    const targetListId = await getListId(params.targetListId, params.targetListName);
-    const taskIds = await mapTaskIds(params.tasks);
-    const result = await bulkService.moveTasks(taskIds.map(taskId => ({ taskId })), targetListId, parseBulkOptions(params.options));
-    return result.successful;
+    const { tasks, targetListId, targetListName, options } = params;
+    // Validate tasks array
+    validateBulkTasks(tasks, 'move');
+    // Validate and resolve target list ID
+    const resolvedTargetListId = await resolveListIdWithValidation(targetListId, targetListName);
+    // Parse bulk options
+    const bulkOptions = parseBulkOptions(options);
+    // Move tasks
+    return await bulkService.moveTasks(tasks, resolvedTargetListId, bulkOptions);
 }
 /**
  * Handler for deleting multiple tasks
  */
 export async function deleteBulkTasksHandler(params) {
-    validateBulkTasks(params.tasks);
-    const taskIds = await mapTaskIds(params.tasks);
-    await bulkService.deleteTasks(taskIds, parseBulkOptions(params.options));
-    return taskIds.map(() => true);
+    const { tasks, options } = params;
+    // Validate tasks array
+    validateBulkTasks(tasks, 'delete');
+    // Parse bulk options
+    const bulkOptions = parseBulkOptions(options);
+    // Delete tasks
+    return await bulkService.deleteTasks(tasks, bulkOptions);
 }
 /**
  * Handler for deleting a task

package/build/tools/task/main.js

@@ -100,22 +100,37 @@ export const handleCreateTaskComment = createHandlerWrapper(createTaskCommentHan
 //=============================================================================
 // BULK TASK OPERATIONS - HANDLER IMPLEMENTATIONS
 //=============================================================================
-export const handleCreateBulkTasks = createHandlerWrapper(createBulkTasksHandler, (tasks) => ({
-    tasks,
-    count: tasks.length
+export const handleCreateBulkTasks = createHandlerWrapper(createBulkTasksHandler, (result) => ({
+    successful: result.successful,
+    failed: result.failed,
+    count: result.totals.total,
+    success_count: result.totals.success,
+    failure_count: result.totals.failure,
+    errors: result.failed.map(f => f.error)
 }));
-export const handleUpdateBulkTasks = createHandlerWrapper(updateBulkTasksHandler, (tasks) => ({
-    tasks,
-    count: tasks.length
+export const handleUpdateBulkTasks = createHandlerWrapper(updateBulkTasksHandler, (result) => ({
+    successful: result.successful,
+    failed: result.failed,
+    count: result.totals.total,
+    success_count: result.totals.success,
+    failure_count: result.totals.failure,
+    errors: result.failed.map(f => f.error)
 }));
-export const handleMoveBulkTasks = createHandlerWrapper(moveBulkTasksHandler, (tasks) => ({
-    tasks,
-    count: tasks.length
+export const handleMoveBulkTasks = createHandlerWrapper(moveBulkTasksHandler, (result) => ({
+    successful: result.successful,
+    failed: result.failed,
+    count: result.totals.total,
+    success_count: result.totals.success,
+    failure_count: result.totals.failure,
+    errors: result.failed.map(f => f.error)
 }));
-export const handleDeleteBulkTasks = createHandlerWrapper(deleteBulkTasksHandler, (results) => ({
-    success: true,
-    count: results.length,
-    results
+export const handleDeleteBulkTasks = createHandlerWrapper(deleteBulkTasksHandler, (result) => ({
+    successful: result.successful,
+    failed: result.failed,
+    count: result.totals.total,
+    success_count: result.totals.success,
+    failure_count: result.totals.failure,
+    errors: result.failed.map(f => f.error)
 }));
 //=============================================================================
 // WORKSPACE TASK OPERATIONS - HANDLER IMPLEMENTATIONS
@@ -128,22 +143,101 @@ export const handleGetWorkspaceTasks = createHandlerWrapper(
 // TOOL DEFINITIONS AND HANDLERS EXPORT
 //=============================================================================
 // Tool definitions with their handler mappings
-export const taskTools = [
-    // Single task operations
-    { definition: createTaskTool, handler: handleCreateTask },
-    { definition: getTaskTool, handler: handleGetTask },
-    { definition: getTasksTool, handler: handleGetTasks },
-    { definition: updateTaskTool, handler: handleUpdateTask },
-    { definition: moveTaskTool, handler: handleMoveTask },
-    { definition: duplicateTaskTool, handler: handleDuplicateTask },
-    { definition: deleteTaskTool, handler: handleDeleteTask },
-    { definition: getTaskCommentsTool, handler: handleGetTaskComments },
-    { definition: createTaskCommentTool, handler: handleCreateTaskComment },
-    // Bulk task operations
-    { definition: createBulkTasksTool, handler: handleCreateBulkTasks },
-    { definition: updateBulkTasksTool, handler: handleUpdateBulkTasks },
-    { definition: moveBulkTasksTool, handler: handleMoveBulkTasks },
-    { definition: deleteBulkTasksTool, handler: handleDeleteBulkTasks },
-    // Team task operations
-    { definition: getWorkspaceTasksTool, handler: handleGetWorkspaceTasks }
+export const tools = [
+    {
+        definition: createTaskTool,
+        handler: createTaskHandler
+    },
+    {
+        definition: updateTaskTool,
+        handler: updateTaskHandler
+    },
+    {
+        definition: moveTaskTool,
+        handler: moveTaskHandler
+    },
+    {
+        definition: duplicateTaskTool,
+        handler: duplicateTaskHandler
+    },
+    {
+        definition: getTaskTool,
+        handler: getTaskHandler
+    },
+    {
+        definition: getTasksTool,
+        handler: getTasksHandler
+    },
+    {
+        definition: getTaskCommentsTool,
+        handler: getTaskCommentsHandler
+    },
+    {
+        definition: createTaskCommentTool,
+        handler: createTaskCommentHandler
+    },
+    {
+        definition: deleteTaskTool,
+        handler: deleteTaskHandler
+    },
+    {
+        definition: getWorkspaceTasksTool,
+        handler: getWorkspaceTasksHandler
+    },
+    {
+        definition: createBulkTasksTool,
+        handler: async (params) => {
+            const result = await createBulkTasksHandler(params);
+            return {
+                successful: result.successful,
+                failed: result.failed,
+                count: result.totals.total,
+                success_count: result.totals.success,
+                failure_count: result.totals.failure,
+                errors: result.failed.map(f => f.error)
+            };
+        }
+    },
+    {
+        definition: updateBulkTasksTool,
+        handler: async (params) => {
+            const result = await updateBulkTasksHandler(params);
+            return {
+                successful: result.successful,
+                failed: result.failed,
+                count: result.totals.total,
+                success_count: result.totals.success,
+                failure_count: result.totals.failure,
+                errors: result.failed.map(f => f.error)
+            };
+        }
+    },
+    {
+        definition: moveBulkTasksTool,
+        handler: async (params) => {
+            const result = await moveBulkTasksHandler(params);
+            return {
+                successful: result.successful,
+                failed: result.failed,
+                count: result.totals.total,
+                success_count: result.totals.success,
+                failure_count: result.totals.failure,
+                errors: result.failed.map(f => f.error)
+            };
+        }
+    },
+    {
+        definition: deleteBulkTasksTool,
+        handler: async (params) => {
+            const result = await deleteBulkTasksHandler(params);
+            return {
+                successful: result.successful,
+                failed: result.failed,
+                count: result.totals.total,
+                success_count: result.totals.success,
+                failure_count: result.totals.failure,
+                errors: result.failed.map(f => f.error)
+            };
+        }
+    }
 ];