@taazkareem/clickup-mcp-server 0.6.5 → 0.6.7

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

@@ -48,20 +48,7 @@ const handleOperationError = (operation, error) => {
  */
 export const createTaskTool = {
     name: "create_task",
-    description: `Purpose: Create a single task in a ClickUp list.
-
-Valid Usage:
-1. Provide listId (preferred if available)
-2. Provide listName (will look up the list ID)
-
-Requirements:
-- name: REQUIRED
-- List identification: 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`,
+    description: `Creates a single task in a ClickUp list. Use listId (preferred) or listName. Required: name + list info. For multiple tasks use create_bulk_tasks. Can create subtasks via parent param. Supports custom fields as array of {id, value}.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -141,20 +128,7 @@ Notes:
  */
 export const updateTaskTool = {
     name: "update_task",
-    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
-
-Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
-- Updates: At least one update field (name, description, status, priority, dueDate) REQUIRED
-
-Notes:
-- Only specified fields will be updated
-- Custom fields can be set using the custom_fields parameter
-- Using taskName without listName may match multiple tasks`,
+    description: `Updates task properties. Use taskId (preferred) or taskName + optional listName. At least one update field required. Custom fields supported as array of {id, value}. WARNING: Using taskName without listName may match multiple tasks.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -224,18 +198,7 @@ Notes:
  */
 export const moveTaskTool = {
     name: "move_task",
-    description: `Purpose: Move a task to a different list.
-
-Valid Usage:
-1. Use taskId + destination list (preferred)
-2. Use taskName + sourceListName + destination list
-
-Requirements:
-- Task identification: EITHER taskId OR (taskName + sourceListName) REQUIRED
-- Destination: EITHER listId OR listName REQUIRED
-
-Warning:
-- Task statuses may reset if destination list has different status options`,
+    description: `Moves task to different list. Use taskId + (listId/listName) preferred, or taskName + sourceListName + (listId/listName). WARNING: Task statuses may reset if destination list has different status options.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -268,18 +231,7 @@ Warning:
  */
 export const duplicateTaskTool = {
     name: "duplicate_task",
-    description: `Purpose: Create a copy of a task in the same or different list.
-
-Valid Usage:
-1. Use taskId (preferred)
-2. Use taskName + sourceListName
-
-Requirements:
-- Task identification: EITHER taskId OR (taskName + sourceListName) REQUIRED
-- Destination: OPTIONAL - defaults to original list
-
-Notes:
-- The duplicate preserves the original task's properties`,
+    description: `Creates copy of task in same/different list. Use taskId + optional (listId/listName), or taskName + sourceListName + optional (listId/listName). Preserves original properties. Default: same list as original.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -308,22 +260,11 @@ Notes:
     }
 };
 /**
- * Tool definition for retrieving a task
+ * Tool definition for retrieving task details
  */
 export const getTaskTool = {
     name: "get_task",
-    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 
-
-Requirements:
-- Task identification: EITHER taskId OR (taskName + listName) REQUIRED
-
-Notes:
-- Task names are only unique within a list
-- Set subtasks=true to include all subtasks in the response`,
+    description: `Gets task details by taskId (works with regular/custom IDs) or taskName. For taskName search, provide listName for faster lookup. Set subtasks=true to include all subtask details.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -333,11 +274,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 +303,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: {
@@ -412,18 +354,7 @@ Notes:
  */
 export const getTaskCommentsTool = {
     name: "get_task_comments",
-    description: `Purpose: Retrieve comments for a ClickUp task.
-
-Valid Usage:
-1. Use taskId (preferred)
-2. Use taskName + listName for targeted search
-
-Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
-
-Notes:
-- Task names may not be unique across different lists
-- Use start/startId parameters for pagination`,
+    description: `Gets task comments. Use taskId (preferred) or taskName + optional listName. Use start/startId params for pagination. Task names may not be unique across lists.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -455,18 +386,7 @@ Notes:
  */
 export const createTaskCommentTool = {
     name: "create_task_comment",
-    description: `Purpose: Create a comment on a ClickUp task.
-
-Valid Usage:
-1. Use taskId (preferred)
-2. Use taskName + listName
-
-Requirements:
-- Task identification: EITHER taskId OR (taskName + listName) REQUIRED
-- commentText: REQUIRED
-
-Notes:
-- Set notifyAll=true to notify all task assignees`,
+    description: `Creates task comment. Use taskId (preferred) or taskName + listName. Required: commentText. Optional: notifyAll to notify assignees, assignee to assign comment.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -503,18 +423,7 @@ Notes:
  */
 export const deleteTaskTool = {
     name: "delete_task",
-    description: `Purpose: PERMANENTLY DELETE a task.
-
-Valid Usage:
-1. Use taskId (preferred and safest)
-2. Use taskName + listName for targeted search
-
-Requirements:
-- Task identification: EITHER taskId OR taskName REQUIRED
-
-Warning:
-- This action CANNOT be undone
-- Using taskName without listName may match multiple tasks`,
+    description: `PERMANENTLY deletes task. Use taskId (preferred/safest) or taskName + optional listName. WARNING: Cannot be undone. Using taskName without listName may match multiple tasks.`,
     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/tools/workspace.js

@@ -19,18 +19,7 @@ const { workspace: workspaceService } = clickUpServices;
  */
 export const workspaceHierarchyTool = {
     name: 'get_workspace_hierarchy',
-    description: `Purpose: Retrieve the complete workspace hierarchy including spaces, folders, and lists.
-
-Valid Usage:
-1. Call without parameters to get the full hierarchy
-
-Requirements:
-- No parameters required
-
-Notes:
-- Returns a tree structure showing all spaces, folders, and lists
-- Each item includes its name and ID
-- Use this to navigate the workspace and understand its organization`,
+    description: `Gets complete workspace hierarchy (spaces, folders, lists). No parameters needed. Returns tree structure with names and IDs for navigation.`,
     inputSchema: {
         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.7",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
   "main": "build/index.js",