@taazkareem/clickup-mcp-server 0.6.5 → 0.6.6

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

@@ -52,16 +52,17 @@ export const createTaskTool = {
 
 Valid Usage:
 1. Provide listId (preferred if available)
-2. Provide listName (will look up the list ID)
+2. Provide listName (system will look up the list ID)
 
 Requirements:
 - name: REQUIRED
-- List identification: EITHER listId OR listName REQUIRED
+- EITHER listId OR listName: REQUIRED
 
 Notes:
-- Use create_bulk_tasks for multiple tasks
-- Set parent parameter to create a subtask
-- Custom fields can be set via custom_fields parameter`,
+- For multiple tasks, use create_bulk_tasks instead
+- Reuse list IDs from previous responses when possible to avoid redundant lookups
+- To create a subtask, set the parent parameter to the ID of the parent task
+- Custom fields can be set using the custom_fields parameter (array of {id, value} objects)`,
     inputSchema: {
         type: "object",
         properties: {
@@ -144,17 +145,25 @@ export const updateTaskTool = {
     description: `Purpose: Modify properties of an existing 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)
 
 Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
-- Updates: At least one update field (name, description, status, priority, dueDate) REQUIRED
+- At least one update field (name, description, status, priority, dueDate) must be provided
+- EITHER taskId OR taskName: REQUIRED
+- listName: Optional, but recommended when using taskName
 
 Notes:
+- 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
 - Only specified fields will be updated
-- Custom fields can be set using the custom_fields parameter
-- Using taskName without listName may match multiple tasks`,
+- Custom fields can be set using the custom_fields parameter (array of {id, value} objects)
+
+Warning:
+- Using taskName without listName may match multiple tasks
+- If multiple matches are found, the operation will fail with a disambiguation error`,
     inputSchema: {
         type: "object",
         properties: {
@@ -227,15 +236,16 @@ export const moveTaskTool = {
     description: `Purpose: Move a task to a different list.
 
 Valid Usage:
-1. Use taskId + destination list (preferred)
-2. Use taskName + sourceListName + destination list
+1. Use taskId + (listId OR listName) - preferred
+2. Use taskName + sourceListName + (listId OR listName)
 
 Requirements:
-- Task identification: EITHER taskId OR (taskName + sourceListName) REQUIRED
-- Destination: EITHER listId OR listName REQUIRED
+- Destination list: EITHER listId OR listName REQUIRED
+- When using taskName, sourceListName is REQUIRED
 
 Warning:
-- Task statuses may reset if destination list has different status options`,
+- Task statuses may reset if destination list has different status options
+- System cannot find a task by name without knowing which list to search in`,
     inputSchema: {
         type: "object",
         properties: {
@@ -271,15 +281,18 @@ export const duplicateTaskTool = {
     description: `Purpose: Create a copy of a task in the same or different list.
 
 Valid Usage:
-1. Use taskId (preferred)
-2. Use taskName + sourceListName
+1. Use taskId + optional (listId OR listName) - preferred
+2. Use taskName + sourceListName + optional (listId OR listName)
 
 Requirements:
-- Task identification: EITHER taskId OR (taskName + sourceListName) REQUIRED
-- Destination: OPTIONAL - defaults to original list
+- When using taskName, sourceListName is REQUIRED
 
 Notes:
-- The duplicate preserves the original task's properties`,
+- The duplicate preserves the original task's properties
+- If no destination list specified, uses same list as original task
+
+Warning:
+- System cannot find a task by name without knowing which list to search in`,
     inputSchema: {
         type: "object",
         properties: {
@@ -315,14 +328,20 @@ export const getTaskTool = {
     description: `Purpose: Retrieve detailed information about a specific 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 (like "DEV-1234")
+2. Use taskName alone (will search across all lists in the workspace)
+3. Use taskName + listName (for faster, targeted search)
+4. Use customTaskId for explicit custom ID lookup
 
 Requirements:
-- Task identification: EITHER taskId OR (taskName + listName) REQUIRED
+- EITHER taskId OR taskName OR customTaskId: REQUIRED
+- listName: Optional, but recommended when using taskName for faster and more precise lookup
 
-Notes:
-- Task names are only unique within a list
+Note:
+- When using just taskName, the system performs a global search across all lists
+- Task names are most unique within a specific list, so providing listName increases reliability
+- Regular task IDs are always 9 characters long (e.g., "86b394eqa")
+- Custom IDs have an uppercase prefix followed by a hyphen and number (e.g., "DEV-1234")
 - Set subtasks=true to include all subtasks in the response`,
     inputSchema: {
         type: "object",
@@ -333,11 +352,11 @@ Notes:
             },
             taskName: {
                 type: "string",
-                description: "Name of task to retrieve. When using this parameter, you MUST also provide listName."
+                description: "Name of task to retrieve. Can be used alone for a global search, or with listName for faster lookup."
             },
             listName: {
                 type: "string",
-                description: "Name of list containing the task. REQUIRED when using taskName."
+                description: "Name of list containing the task. Optional but recommended when using taskName."
             },
             customTaskId: {
                 type: "string",
@@ -362,11 +381,12 @@ Valid Usage:
 2. Use listName
 
 Requirements:
-- List identification: EITHER listId OR listName REQUIRED
+- EITHER listId OR listName is REQUIRED
 
 Notes:
-- Use filters (archived, statuses) to narrow down results
-- Pagination and sorting available`,
+- Use filters (archived, statuses, etc.) to narrow down results
+- Pagination available through page parameter
+- Sorting available through order_by and reverse parameters`,
     inputSchema: {
         type: "object",
         properties: {
@@ -416,14 +436,12 @@ export const getTaskCommentsTool = {
 
 Valid Usage:
 1. Use taskId (preferred)
-2. Use taskName + listName for targeted search
-
-Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
+2. Use taskName + optional listName
 
 Notes:
+- If using taskName, providing listName helps locate the correct task
 - Task names may not be unique across different lists
-- Use start/startId parameters for pagination`,
+- Use start and startId parameters for pagination through comments`,
     inputSchema: {
         type: "object",
         properties: {
@@ -462,11 +480,13 @@ Valid Usage:
 2. Use taskName + listName
 
 Requirements:
-- Task identification: EITHER taskId OR (taskName + listName) REQUIRED
-- commentText: REQUIRED
+- EITHER taskId OR (taskName + listName) is REQUIRED
+- commentText is REQUIRED
 
 Notes:
-- Set notifyAll=true to notify all task assignees`,
+- When using taskName, providing listName helps locate the correct task
+- Set notifyAll to true to send notifications to all task assignees
+- Use assignee to assign the comment to a specific user (optional)`,
     inputSchema: {
         type: "object",
         properties: {
@@ -506,15 +526,24 @@ export const deleteTaskTool = {
     description: `Purpose: PERMANENTLY DELETE a task.
 
 Valid Usage:
-1. Use taskId (preferred and safest)
-2. Use taskName + listName for targeted search
+1. Use taskId alone (preferred and safest)
+2. Use taskName alone (will search across all lists)
+3. Use taskName + listName (for faster, targeted search)
 
 Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
+- EITHER taskId OR taskName: REQUIRED
+- listName: Optional, but recommended when using taskName
+
+Notes:
+- 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
+- Supports both regular task IDs and custom IDs (like 'DEV-1234')
 
 Warning:
 - This action CANNOT be undone
-- Using taskName without listName may match multiple tasks`,
+- Using taskName without listName may match multiple tasks
+- If multiple matches are found, the operation will fail with a disambiguation error`,
     inputSchema: {
         type: "object",
         properties: {

package/build/tools/task/utilities.js

@@ -11,7 +11,7 @@ import { formatDueDate } from '../utils.js';
 import { clickUpServices } from '../../services/shared.js';
 import { findListIDByName } from '../../tools/list.js';
 // Use shared services instance for ID resolution
-const { workspace: workspaceService } = clickUpServices;
+const { workspace: workspaceService, task: taskService } = clickUpServices;
 //=============================================================================
 // DATA FORMATTING UTILITIES
 //=============================================================================
@@ -65,22 +65,38 @@ export function formatTaskData(task, additional = {}) {
         ...additional
     };
 }
-//=============================================================================
-// VALIDATION UTILITIES
-//=============================================================================
 /**
  * Validates task identification parameters
- * Ensures either taskId, customTaskId, or both taskName and listName are provided
- * When useGlobalLookup is true, allows taskName without listName
+ *
+ * @param params - Task identification parameters
+ * @param options - Validation options
+ * @returns Validation result with error message if any
  */
-export function validateTaskIdentification(taskId, taskName, listName, customTaskId, useGlobalLookup = true) {
+export function validateTaskIdentification(params, options = {}) {
+    const { taskId, taskName, customTaskId, listName } = params;
+    const { requireTaskId = false, useGlobalLookup = true } = options;
+    // If taskId is required, it must be provided
+    if (requireTaskId && !taskId) {
+        return {
+            isValid: false,
+            errorMessage: 'Task ID is required for this operation'
+        };
+    }
+    // At least one identification method must be provided
     if (!taskId && !taskName && !customTaskId) {
-        throw new Error("Either taskId, customTaskId, or taskName must be provided");
+        return {
+            isValid: false,
+            errorMessage: 'Either taskId, taskName, or customTaskId must be provided to identify the task'
+        };
     }
-    // When global lookup is not enabled, we need list context for task name lookup
-    if (!useGlobalLookup && !taskId && !customTaskId && taskName && !listName) {
-        throw new Error("listName is required when using taskName and global lookup is disabled");
+    // When using taskName without global lookup, listName is required
+    if (taskName && !taskId && !customTaskId && !useGlobalLookup && !listName) {
+        return {
+            isValid: false,
+            errorMessage: 'When identifying a task by name, you must also provide the listName parameter'
+        };
     }
+    return { isValid: true };
 }
 /**
  * Validates list identification parameters
@@ -99,7 +115,7 @@ export function validateTaskUpdateData(updateData) {
     // Check if there are any valid update fields present
     const hasUpdates = Object.keys(updateData).some(key => {
         return ['name', 'description', 'markdown_description', 'status', 'priority',
-            'dueDate', 'startDate', 'taskId', 'taskName', 'custom_fields'].includes(key);
+            'dueDate', 'startDate', 'custom_fields'].includes(key);
     });
     if (!hasUpdates) {
         throw new Error("At least one field to update must be provided");
@@ -231,3 +247,34 @@ export function extractTreePath(root, targetId) {
     // Not found in this branch
     return [];
 }
+/**
+ * Get task ID from various identification methods
+ */
+export async function getTaskId(taskId, taskName, listName, customTaskId, requireId = false) {
+    // Validate task identification
+    const validationResult = validateTaskIdentification({ taskId, taskName, listName, customTaskId }, { requireTaskId: requireId, useGlobalLookup: true });
+    if (!validationResult.isValid) {
+        throw new Error(validationResult.errorMessage);
+    }
+    try {
+        const result = await taskService.findTasks({
+            taskId,
+            customTaskId,
+            taskName,
+            listName,
+            allowMultipleMatches: false,
+            useSmartDisambiguation: true,
+            includeFullDetails: false
+        });
+        if (!result || Array.isArray(result)) {
+            throw new Error(`Task not found with the provided identification`);
+        }
+        return result.id;
+    }
+    catch (error) {
+        if (error.message.includes('Multiple tasks found')) {
+            throw new Error(`Multiple tasks found with name "${taskName}". Please provide list name to disambiguate.`);
+        }
+        throw error;
+    }
+}

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

@@ -12,20 +12,27 @@
  */
 export const getWorkspaceTasksTool = {
     name: "get_workspace_tasks",
-    description: `Purpose: Retrieve tasks from across the entire workspace with filtering.
+    description: `Purpose: Retrieve tasks from across the entire workspace with powerful filtering options, including tag-based filtering.
 
 Valid Usage:
-1. Apply any combination of filters (tags, lists, statuses, etc.)
-2. Use pagination for large result sets
+1. Apply any combination of filters (tags, lists, folders, spaces, statuses, etc.)
+2. Use pagination to manage large result sets
 
 Requirements:
-- At least one filter parameter REQUIRED (tags, list_ids, statuses, etc.)
+- At least one filter parameter is REQUIRED (tags, list_ids, folder_ids, space_ids, statuses, assignees, or date filters)
+- Pagination parameters (page, order_by, reverse) alone are not considered filters
 
 Notes:
-- Searches across all lists in the workspace
-- Tag filtering allows cross-list organization
-- Set detail_level=summary for lightweight responses
-- detail_level=detailed (default) returns complete data`,
+- Provides workspace-wide task access (unlike get_tasks which only searches in one list)
+- Returns complete task details including descriptions, assignees, custom fields, and all metadata
+- Tag filtering is especially useful for cross-list organization (e.g., "project-x", "blocker", "needs-review")
+- Combine multiple filters to narrow down your search scope
+- Use pagination for large result sets
+- Use the detail_level parameter to control the amount of data returned:
+  - "summary": Returns lightweight task data (name, status, list, tags)
+  - "detailed": Returns complete task data with all fields (DEFAULT if not specified)
+- Responses exceeding 50,000 tokens automatically switch to summary format to avoid hitting LLM token limits
+`,
     parameters: {
         type: 'object',
         properties: {

package/build/utils/date-utils.js

@@ -6,6 +6,9 @@
  *
  * This module provides utilities for handling dates, timestamps, and due date parsing.
  */
+import { Logger } from '../logger.js';
+// Create a logger instance for date utilities
+const logger = new Logger('DateUtils');
 /**
  * Get a timestamp for a relative time
  *
@@ -197,8 +200,8 @@ export function parseDueDate(dateString) {
         return undefined;
     }
     catch (error) {
-        console.warn(`Failed to parse due date: ${dateString}`, error);
-        return undefined;
+        logger.warn(`Failed to parse due date: ${dateString}`, error);
+        throw new Error(`Invalid date format: ${dateString}`);
     }
 }
 /**
@@ -225,8 +228,8 @@ export function formatDueDate(timestamp) {
         }).replace(' at', ',');
     }
     catch (error) {
-        console.warn(`Failed to format due date: ${timestamp}`, error);
-        return undefined;
+        logger.warn(`Failed to format due date: ${timestamp}`, error);
+        throw new Error(`Invalid timestamp: ${timestamp}`);
     }
 }
 /**

package/build/utils/resolver-utils.js

@@ -9,37 +9,110 @@
 import { clickUpServices } from '../services/shared.js';
 import { findListIDByName } from '../tools/list.js';
 /**
- * Check if a task name matches search criteria
+ * Check if a name matches another name using a variety of matching strategies
+ * Returns a structured result with match quality information rather than just a boolean
  *
- * Performs flexible case-insensitive and emoji-aware text matching
- * Used by multiple components for consistent name matching behavior
+ * @param actualName The actual name to check
+ * @param searchName The name being searched for
+ * @returns A structured result with match details
  */
-export function isNameMatch(taskName, searchTerm) {
-    const normalizedTask = taskName.toLowerCase().trim();
-    const normalizedSearch = searchTerm.toLowerCase().trim();
-    // Handle empty strings - don't match empty task names
-    if (normalizedTask === '')
-        return false;
-    if (normalizedSearch === '')
-        return false;
-    // Exact match check
-    if (normalizedTask === normalizedSearch)
-        return true;
-    // Substring match check
-    if (normalizedTask.includes(normalizedSearch) || normalizedSearch.includes(normalizedTask))
-        return true;
-    // Handle emoji characters in names
-    if (/[\p{Emoji}]/u.test(normalizedSearch) || /[\p{Emoji}]/u.test(normalizedTask)) {
-        const taskWithoutEmoji = normalizedTask.replace(/[\p{Emoji}]/gu, '').trim();
-        const searchWithoutEmoji = normalizedSearch.replace(/[\p{Emoji}]/gu, '').trim();
-        // Don't match if either becomes empty after emoji removal
-        if (taskWithoutEmoji === '' || searchWithoutEmoji === '')
-            return false;
-        return taskWithoutEmoji === searchWithoutEmoji ||
-            taskWithoutEmoji.includes(searchWithoutEmoji) ||
-            searchWithoutEmoji.includes(taskWithoutEmoji);
-    }
-    return false;
+export function isNameMatch(actualName, searchName) {
+    if (!actualName || !searchName) {
+        return { isMatch: false, score: 0, exactMatch: false, reason: 'One of the names is empty' };
+    }
+    // Remove any extra whitespace
+    const normalizedActualName = actualName.trim();
+    const normalizedSearchName = searchName.trim();
+    // Handle empty names after normalization
+    if (normalizedActualName === '') {
+        return { isMatch: false, score: 0, exactMatch: false, reason: 'Actual name is empty' };
+    }
+    if (normalizedSearchName === '') {
+        return { isMatch: false, score: 0, exactMatch: false, reason: 'Search name is empty' };
+    }
+    // 1. Exact match (highest quality)
+    if (normalizedActualName === normalizedSearchName) {
+        return {
+            isMatch: true,
+            score: 100,
+            exactMatch: true,
+            reason: 'Exact match'
+        };
+    }
+    // 2. Case-insensitive exact match (high quality)
+    if (normalizedActualName.toLowerCase() === normalizedSearchName.toLowerCase()) {
+        return {
+            isMatch: true,
+            score: 90,
+            exactMatch: true,
+            reason: 'Case-insensitive exact match'
+        };
+    }
+    // 3. Match after removing emojis (moderate quality)
+    const actualNameWithoutEmoji = normalizedActualName.replace(/[\p{Emoji}\u{FE00}-\u{FE0F}\u200d]+/gu, '').trim();
+    const searchNameWithoutEmoji = normalizedSearchName.replace(/[\p{Emoji}\u{FE00}-\u{FE0F}\u200d]+/gu, '').trim();
+    if (actualNameWithoutEmoji === searchNameWithoutEmoji) {
+        return {
+            isMatch: true,
+            score: 80,
+            exactMatch: false,
+            reason: 'Exact match after removing emojis'
+        };
+    }
+    if (actualNameWithoutEmoji.toLowerCase() === searchNameWithoutEmoji.toLowerCase()) {
+        return {
+            isMatch: true,
+            score: 70,
+            exactMatch: false,
+            reason: 'Case-insensitive match after removing emojis'
+        };
+    }
+    // 4. Substring matches (lower quality)
+    const lowerActual = normalizedActualName.toLowerCase();
+    const lowerSearch = normalizedSearchName.toLowerCase();
+    // Full substring (term completely contained)
+    if (lowerActual.includes(lowerSearch)) {
+        return {
+            isMatch: true,
+            score: 60,
+            exactMatch: false,
+            reason: 'Search term found as substring in actual name'
+        };
+    }
+    if (lowerSearch.includes(lowerActual)) {
+        return {
+            isMatch: true,
+            score: 50,
+            exactMatch: false,
+            reason: 'Actual name found as substring in search term'
+        };
+    }
+    // 5. Fuzzy emoji-less matches (lowest quality)
+    const lowerActualNoEmoji = actualNameWithoutEmoji.toLowerCase();
+    const lowerSearchNoEmoji = searchNameWithoutEmoji.toLowerCase();
+    if (lowerActualNoEmoji.includes(lowerSearchNoEmoji)) {
+        return {
+            isMatch: true,
+            score: 40,
+            exactMatch: false,
+            reason: 'Search term (without emoji) found as substring in actual name'
+        };
+    }
+    if (lowerSearchNoEmoji.includes(lowerActualNoEmoji)) {
+        return {
+            isMatch: true,
+            score: 30,
+            exactMatch: false,
+            reason: 'Actual name (without emoji) found as substring in search term'
+        };
+    }
+    // No match found
+    return {
+        isMatch: false,
+        score: 0,
+        exactMatch: false,
+        reason: 'No match found with any matching strategy'
+    };
 }
 /**
  * Resolve a list ID from either a direct ID or list name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taazkareem/clickup-mcp-server",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
   "main": "build/index.js",