@taazkareem/clickup-mcp-server 0.6.5 → 0.6.6

package/build/tools/tag.js

@@ -13,8 +13,11 @@ import { clickUpServices } from '../services/shared.js';
 import { Logger } from '../logger.js';
 import { sponsorService } from '../utils/sponsor-service.js';
 import { processColorCommand } from '../utils/color-processor.js';
+import { validateTaskIdentification } from './task/utilities.js';
 // Create a logger specific to tag tools
 const logger = new Logger('TagTools');
+// Use shared services instance
+const { task: taskService } = clickUpServices;
 //=============================================================================
 // TOOL DEFINITIONS
 //=============================================================================
@@ -26,11 +29,15 @@ export const getSpaceTagsTool = {
     description: `Purpose: Get all tags available in a ClickUp space.
 
 Valid Usage:
-1. Provide spaceId (preferred)
-2. Provide spaceName
+1. Provide spaceId (preferred if available)
+2. Provide spaceName (will be resolved to a space ID)
 
 Requirements:
-- Space identification: EITHER spaceId OR spaceName REQUIRED`,
+- EITHER spaceId OR spaceName is REQUIRED
+
+Notes:
+- Tags are defined at the space level in ClickUp
+- You need to know the available tags before adding them to tasks`,
     inputSchema: {
         type: "object",
         properties: {
@@ -53,15 +60,18 @@ export const createSpaceTagTool = {
     description: `Purpose: Create a new tag in a ClickUp space.
 
 Valid Usage:
-1. Provide spaceId + tagName (preferred)
-2. Provide spaceName + tagName
+1. Provide spaceId (preferred if available)
+2. Provide spaceName (will be resolved to a space ID)
 
 Requirements:
 - tagName: REQUIRED
-- Space identification: EITHER spaceId OR spaceName REQUIRED
+- EITHER spaceId OR spaceName: REQUIRED
 
 Notes:
-- Specify colors with HEX values or natural language command`,
+- New tag will be available for all tasks in the space
+- You can specify background and foreground colors in HEX format (e.g., #FF0000)
+- You can also provide a color command (e.g., "blue tag") to automatically generate colors
+- After creating a tag, you can add it to tasks using add_tag_to_task`,
     inputSchema: {
         type: "object",
         properties: {
@@ -194,17 +204,18 @@ export const addTagToTaskTool = {
 
 Valid Usage:
 1. Provide taskId (preferred if available)
-2. Provide taskName + listName
+2. Provide taskName (optionally with listName for disambiguation)
 
 Requirements:
 - tagName: REQUIRED
-- EITHER taskId OR (taskName + listName): REQUIRED
+- EITHER taskId OR customTaskId OR taskName: REQUIRED
 - The tag MUST exist in the space containing the task before calling this tool
 
 Warning:
 - The operation will fail if the tag does not exist in the space
 - Always use get_space_tags first to verify the tag exists
 - If the tag doesn't exist, create it using create_space_tag before adding it to the task
+- If multiple tasks have the same name, provide listName to disambiguate
 
 Notes:
 - Use get_space_tags to see available tags
@@ -222,11 +233,11 @@ Notes:
             },
             taskName: {
                 type: "string",
-                description: "Name of the task to add tag to. When using this parameter, you MUST also provide listName."
+                description: "Name of the task to add tag to. Will search across all lists unless listName is provided."
             },
             listName: {
                 type: "string",
-                description: "Name of the list containing the task. REQUIRED when using taskName."
+                description: "Optional: Name of the list containing the task. Use to disambiguate when multiple tasks have the same name."
             },
             tagName: {
                 type: "string",
@@ -245,15 +256,16 @@ export const removeTagFromTaskTool = {
 
 Valid Usage:
 1. Provide taskId (preferred if available)
-2. Provide taskName + listName
+2. Provide taskName (optionally with listName for disambiguation)
 
 Requirements:
 - tagName: REQUIRED
-- EITHER taskId OR (taskName + listName): REQUIRED
+- EITHER taskId OR customTaskId OR taskName: REQUIRED
 
 Notes:
 - This only removes the association between the tag and task
-- The tag will still exist in the space`,
+- The tag will still exist in the space
+- If multiple tasks have the same name, provide listName to disambiguate`,
     inputSchema: {
         type: "object",
         properties: {
@@ -267,11 +279,11 @@ Notes:
             },
             taskName: {
                 type: "string",
-                description: "Name of the task to remove tag from. When using this parameter, you MUST also provide listName."
+                description: "Name of the task to remove tag from. Will search across all lists unless listName is provided."
             },
             listName: {
                 type: "string",
-                description: "Name of the list containing the task. REQUIRED when using taskName."
+                description: "Optional: Name of the list containing the task. Use to disambiguate when multiple tasks have the same name."
             },
             tagName: {
                 type: "string",
@@ -334,10 +346,18 @@ export const handleDeleteSpaceTag = createHandlerWrapper(deleteSpaceTag, () => (
 /**
  * Wrapper for addTagToTask handler
  */
-export const handleAddTagToTask = createHandlerWrapper(addTagToTask, () => ({
-    success: true,
-    message: "Tag added to task successfully"
-}));
+export const handleAddTagToTask = createHandlerWrapper(addTagToTask, (result) => {
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error
+        };
+    }
+    return {
+        success: true,
+        message: "Tag added to task successfully"
+    };
+});
 /**
  * Wrapper for removeTagFromTask handler
  */
@@ -666,28 +686,42 @@ export async function deleteSpaceTag(params) {
  */
 async function resolveTaskId(params) {
     const { taskId, customTaskId, taskName, listName } = params;
-    // If we have a direct taskId, use it
-    if (taskId) {
-        return { success: true, taskId };
-    }
-    // Custom task ID handling
-    if (customTaskId) {
-        return { success: true, taskId: customTaskId };
+    try {
+        // First validate task identification with global lookup enabled
+        const validationResult = validateTaskIdentification({ taskId, customTaskId, taskName, listName }, { useGlobalLookup: true });
+        if (!validationResult.isValid) {
+            return {
+                success: false,
+                error: { message: validationResult.errorMessage }
+            };
+        }
+        const result = await taskService.findTasks({
+            taskId,
+            customTaskId,
+            taskName,
+            listName,
+            allowMultipleMatches: false,
+            useSmartDisambiguation: true,
+            includeFullDetails: false
+        });
+        if (!result || Array.isArray(result)) {
+            return {
+                success: false,
+                error: { message: 'Task not found with the provided identification' }
+            };
+        }
+        return { success: true, taskId: result.id };
     }
-    // Task name lookup (requires list name)
-    if (taskName && listName) {
-        // Implementation would go here
+    catch (error) {
         return {
             success: false,
-            error: { message: 'Task name resolution not implemented yet' }
+            error: {
+                message: error.message || 'Failed to resolve task ID',
+                code: error.code,
+                details: error.data
+            }
         };
     }
-    return {
-        success: false,
-        error: {
-            message: 'Task identifier is required (taskId, customTaskId, or taskName+listName)'
-        }
-    };
 }
 /**
  * Add a tag to a task
@@ -705,12 +739,12 @@ export async function addTagToTask(params) {
             }
         };
     }
-    if (!taskId && !customTaskId && !(taskName && listName)) {
-        logger.error('addTagToTask called without proper task identifier');
+    if (!taskId && !customTaskId && !taskName) {
+        logger.error('addTagToTask called without task identifier');
         return {
             success: false,
             error: {
-                message: 'Either taskId, customTaskId, or both taskName and listName are required'
+                message: 'Either taskId, customTaskId, or taskName is required'
             }
         };
     }
@@ -728,6 +762,31 @@ export async function addTagToTask(params) {
         const result = await clickUpServices.tag.addTagToTask(taskIdResult.taskId, tagName);
         if (!result.success) {
             logger.error('Failed to add tag to task', result.error);
+            // Provide more specific error messages based on error code
+            if (result.error?.code === 'TAG_NOT_FOUND') {
+                return {
+                    success: false,
+                    error: {
+                        message: `The tag "${tagName}" does not exist in the space. Please create it first using create_space_tag.`
+                    }
+                };
+            }
+            else if (result.error?.code === 'SPACE_NOT_FOUND') {
+                return {
+                    success: false,
+                    error: {
+                        message: 'Could not determine which space the task belongs to.'
+                    }
+                };
+            }
+            else if (result.error?.code === 'TAG_VERIFICATION_FAILED') {
+                return {
+                    success: false,
+                    error: {
+                        message: 'The tag addition could not be verified. Please check if the tag was added manually.'
+                    }
+                };
+            }
             return {
                 success: false,
                 error: result.error || {
@@ -768,12 +827,12 @@ export async function removeTagFromTask(params) {
             }
         };
     }
-    if (!taskId && !customTaskId && !(taskName && listName)) {
-        logger.error('removeTagFromTask called without proper task identifier');
+    if (!taskId && !customTaskId && !taskName) {
+        logger.error('removeTagFromTask called without task identifier');
         return {
             success: false,
             error: {
-                message: 'Either taskId, customTaskId, or both taskName and listName are required'
+                message: 'Either taskId, customTaskId, or taskName is required'
             }
         };
     }

package/build/tools/task/attachments.js

@@ -10,8 +10,11 @@
 import { clickUpServices } from '../../services/shared.js';
 import { validateTaskIdentification } from './utilities.js';
 import { sponsorService } from '../../utils/sponsor-service.js';
+import { Logger } from '../../logger.js';
 // Use shared services instance
 const { task: taskService } = clickUpServices;
+// Create a logger instance for attachments
+const logger = new Logger('TaskAttachments');
 // Session storage for chunked uploads (in-memory for demonstration)
 const chunkSessions = new Map();
 // Clean up expired sessions periodically
@@ -21,7 +24,7 @@ setInterval(() => {
     for (const [token, session] of chunkSessions.entries()) {
         if (now - session.timestamp > expired) {
             chunkSessions.delete(token);
-            console.log(`Cleaned up expired upload session: ${token}`);
+            logger.debug(`Cleaned up expired upload session: ${token}`);
         }
     }
 }, 3600 * 1000); // Check every hour
@@ -33,23 +36,39 @@ export const attachTaskFileTool = {
     description: `Purpose: Attaches a file to a ClickUp task.
 
 Valid Usage:
-1. Use taskId (preferred) - works with both regular and custom IDs
-2. Use taskName + listName for targeted search
+1. Use taskId alone (preferred) - works with both regular and custom IDs
+2. Use taskName alone (will search across all lists)
+3. Use taskName + listName (for faster, 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
+File Source Options:
+1. Upload from base64: Provide file_data + file_name
+2. Upload from URL: Provide file_url starting with http:// or https://
+3. Upload from local file: Provide file_url as absolute path (starting with / or drive letter)
+4. For large files: Use chunk_* parameters for advanced chunked uploading
 
 Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
-- File source: EITHER file_data+file_name OR file_url OR chunk_session REQUIRED
+- EITHER taskId OR taskName: REQUIRED
+- listName: Optional, but recommended when using taskName
+- File Source: ONE of the following is REQUIRED:
+  - file_data + file_name
+  - file_url (web URL or local path)
+  - chunk_session (for continuing chunked upload)
 
 Notes:
-- System automatically selects best upload method based on file size
-- Base64 uploads limited to 10MB
-- Using taskName without listName may match multiple tasks`,
+- The tool automatically searches for tasks using smart name matching
+- When only taskName is provided, it searches across all lists
+- Adding listName narrows the search to a specific list for better performance
+- The system automatically selects the best upload method based on file size and source:
+  - Base64 method: Limited to 10MB due to encoding overhead
+  - URL method: Works for files hosted online
+  - Local file method: Works with absolute paths only
+  - Large files: Automatically uses chunked uploading
+
+Warning:
+- Using taskName without listName may match multiple tasks
+- If multiple matches are found, the operation will fail with a disambiguation error
+- For local files, relative paths are not supported
+- Base64 uploads over 10MB will automatically switch to chunked upload mode`,
     inputSchema: {
         type: "object",
         properties: {
@@ -106,9 +125,12 @@ Notes:
  */
 async function attachTaskFileHandler(params) {
     // Extract common parameters
-    const { taskId, taskName, listName, file_name, file_data, file_url, auth_header, chunk_total, chunk_size, chunk_index, session_id } = params;
+    const { taskId, taskName, listName, customTaskId, file_name, file_data, file_url, auth_header, chunk_total, chunk_size, chunk_index, session_id } = params;
     // Validate task identification
-    validateTaskIdentification(params);
+    const validationResult = validateTaskIdentification({ taskId, taskName, listName, customTaskId }, { useGlobalLookup: true });
+    if (!validationResult.isValid) {
+        throw new Error(validationResult.errorMessage);
+    }
     // Validate file source - either file_data or file_url must be provided
     if (!file_data && !file_url && !session_id) {
         throw new Error("Either file_data, file_url, or session_id must be provided");
@@ -134,13 +156,13 @@ async function attachTaskFileHandler(params) {
         // CASE 2: URL-based upload or local file path
         if (file_url) {
             // Check if it's a local file path
-            console.log(`Checking if path is local: ${file_url}`);
+            logger.debug(`Checking if path is local: ${file_url}`);
             if (file_url.startsWith('/') || /^[A-Za-z]:\\/.test(file_url)) {
-                console.log(`Detected as local path, proceeding to handle: ${file_url}`);
+                logger.debug(`Detected as local path, proceeding to handle: ${file_url}`);
                 return await handleLocalFileUpload(resolvedTaskId, file_url, file_name);
             }
             else if (file_url.startsWith('http://') || file_url.startsWith('https://')) {
-                console.log(`Detected as URL, proceeding with URL upload: ${file_url}`);
+                logger.debug(`Detected as URL, proceeding with URL upload: ${file_url}`);
                 return await handleUrlUpload(resolvedTaskId, file_url, file_name, auth_header);
             }
             else {
@@ -167,7 +189,7 @@ async function attachTaskFileHandler(params) {
         throw new Error("Invalid parameters: Unable to determine upload method");
     }
     catch (error) {
-        console.error(`Error attaching file to task:`, error);
+        logger.error(`Error attaching file to task:`, error);
         throw error;
     }
 }
@@ -315,7 +337,7 @@ async function handleLocalFileUpload(taskId, filePath, fileName) {
         // Import fs and path modules
         const fs = await import('fs');
         const path = await import('path');
-        console.log(`Processing absolute file path: ${filePath}`);
+        logger.debug(`Processing absolute file path: ${filePath}`);
         // Normalize the path to prevent directory traversal attacks
         const normalizedPath = path.normalize(filePath);
         // Check if file exists
@@ -332,7 +354,7 @@ async function handleLocalFileUpload(taskId, filePath, fileName) {
         // Read file
         const fileBuffer = fs.readFileSync(normalizedPath);
         const fileSize = fileBuffer.length;
-        console.log(`Successfully read file: ${extractedFileName} (${fileSize} bytes)`);
+        logger.debug(`Successfully read file: ${extractedFileName} (${fileSize} bytes)`);
         // Choose upload method based on file size
         if (fileSize > 10 * 1024 * 1024) {
             // For large files, start chunked upload process

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

@@ -81,11 +81,13 @@ Valid Usage:
 
 Requirements:
 - tasks: REQUIRED (array of tasks, each with at least a name)
-- List identification: EITHER listId OR listName REQUIRED
+- EITHER listId OR listName: REQUIRED
+- All tasks will be created in the specified list
 
 Notes:
-- Configure batch processing via options parameter
-- Custom fields supported for each task`,
+- Configure batch size and concurrency via options for performance
+- Each task should have a name with emoji prefix
+- Custom fields can be set for each task using the custom_fields property (array of {id, value} objects)`,
     inputSchema: {
         type: "object",
         properties: {
@@ -168,16 +170,22 @@ export const updateBulkTasksTool = {
     description: `Purpose: Update multiple tasks efficiently in a single operation.
 
 Valid Usage:
-1. Provide array of tasks with taskId (preferred)
-2. Provide array of tasks with taskName + listName
+1. For each task, provide taskId (preferred)
+2. For each task, provide taskName + listName
 
 Requirements:
 - tasks: REQUIRED (array of tasks to update)
-- Each task needs identification and update fields
+- For each task entry, EITHER taskId OR (taskName + listName) is REQUIRED
+- At least one update field per task (name, description, status, priority, dueDate)
 
 Notes:
 - Only specified fields will be updated for each task
-- Configure batch processing via options parameter`,
+- 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)
+
+Warning:
+- Using taskName without listName will fail as tasks may have identical names across lists`,
     inputSchema: {
         type: "object",
         properties: {
@@ -261,14 +269,21 @@ export const moveBulkTasksTool = {
     description: `Purpose: Move multiple tasks to a different list efficiently.
 
 Valid Usage:
-1. Provide tasks array + target list
+1. For each task, provide taskId + target list (preferred)
+2. For each task, provide taskName + listName + target list
 
 Requirements:
-- tasks: REQUIRED (array of task identifiers)
-- Target list: EITHER targetListId OR targetListName REQUIRED
+- 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
 
 Warning:
-- Task statuses may reset if destination list has different status options`,
+- 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`,
     inputSchema: {
         type: "object",
         properties: {
@@ -318,15 +333,20 @@ export const deleteBulkTasksTool = {
     description: `Purpose: PERMANENTLY DELETE multiple tasks at once.
 
 Valid Usage:
-1. Provide array of tasks with taskId (preferred)
-2. Provide array of tasks with taskName + listName
+1. For each task, provide taskId (preferred and safest)
+2. For each task, provide taskName + listName
 
 Requirements:
-- tasks: REQUIRED (array of task identifiers)
+- 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
 
 Warning:
-- This action CANNOT be undone
-- Always provide listName when using taskName`,
+- 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`,
     inputSchema: {
         type: "object",
         properties: {