@taazkareem/clickup-mcp-server 0.6.3 → 0.6.5

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

@@ -52,17 +52,16 @@ export const createTaskTool = {
 
 Valid Usage:
 1. Provide listId (preferred if available)
-2. Provide listName (system will look up the list ID)
+2. Provide listName (will look up the list ID)
 
 Requirements:
 - name: REQUIRED
-- EITHER listId OR listName: REQUIRED
+- List identification: EITHER listId OR listName REQUIRED
 
 Notes:
-- 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)`,
+- Use create_bulk_tasks for multiple tasks
+- Set parent parameter to create a subtask
+- Custom fields can be set via custom_fields parameter`,
     inputSchema: {
         type: "object",
         properties: {
@@ -145,31 +144,31 @@ export const updateTaskTool = {
     description: `Purpose: Modify properties of an existing task.
 
 Valid Usage:
-1. Use taskId alone (preferred if available)
-2. Use taskName + listName
+1. Use taskId (preferred) - works with both regular and custom IDs
+2. Use taskName + listName for targeted search
 
 Requirements:
-- At least one update field (name, description, status, priority, dueDate) must be provided
-- When using taskName, listName is REQUIRED
+- 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
-- Using taskId is more reliable than taskName
-- You can set custom field values using the custom_fields parameter (array of {id, value} objects)`,
+- Custom fields can be set using the custom_fields parameter
+- Using taskName without listName may match multiple tasks`,
     inputSchema: {
         type: "object",
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of the task to update (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                description: "ID of task to update (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
             },
             taskName: {
                 type: "string",
-                description: "Name of the task to update. Only use this if you don't have taskId. When using this parameter, you MUST also provide listName."
+                description: "Name of task to update. 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."
             },
             name: {
                 type: "string",
@@ -228,16 +227,15 @@ export const moveTaskTool = {
     description: `Purpose: Move a task to a different list.
 
 Valid Usage:
-1. Use taskId + (listId OR listName) - preferred
-2. Use taskName + sourceListName + (listId OR listName)
+1. Use taskId + destination list (preferred)
+2. Use taskName + sourceListName + destination list
 
 Requirements:
-- Destination list: EITHER listId OR listName REQUIRED
-- When using taskName, sourceListName is REQUIRED
+- 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
-- System cannot find a task by name without knowing which list to search in`,
+- Task statuses may reset if destination list has different status options`,
     inputSchema: {
         type: "object",
         properties: {
@@ -273,18 +271,15 @@ export const duplicateTaskTool = {
     description: `Purpose: Create a copy of a task in the same or different list.
 
 Valid Usage:
-1. Use taskId + optional (listId OR listName) - preferred
-2. Use taskName + sourceListName + optional (listId OR listName)
+1. Use taskId (preferred)
+2. Use taskName + sourceListName
 
 Requirements:
-- When using taskName, sourceListName is REQUIRED
+- Task identification: EITHER taskId OR (taskName + sourceListName) REQUIRED
+- Destination: OPTIONAL - defaults to original list
 
 Notes:
-- 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`,
+- The duplicate preserves the original task's properties`,
     inputSchema: {
         type: "object",
         properties: {
@@ -320,18 +315,14 @@ export const getTaskTool = {
     description: `Purpose: Retrieve detailed information about a specific task.
 
 Valid Usage:
-1. Use taskId alone (preferred) - works with both regular and custom IDs (like "DEV-1234")
-2. Use taskName + listName
-3. Use customTaskId for explicit custom ID lookup
+1. Use taskId (preferred) - works with both regular and custom IDs
+2. Use taskName + listName for targeted search 
 
 Requirements:
-- When using taskName, listName is REQUIRED
-- When using customTaskId, listName is recommended for faster lookup
+- Task identification: EITHER taskId OR (taskName + listName) REQUIRED
 
-Note:
-- Task names are only unique within a list, so the system needs to know which list to search in
-- 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")
+Notes:
+- Task names are only unique within a list
 - Set subtasks=true to include all subtasks in the response`,
     inputSchema: {
         type: "object",
@@ -356,8 +347,7 @@ Note:
                 type: "boolean",
                 description: "Whether to include subtasks in the response. Set to true to retrieve full details of all subtasks."
             }
-        },
-        required: []
+        }
     }
 };
 /**
@@ -372,12 +362,11 @@ Valid Usage:
 2. Use listName
 
 Requirements:
-- EITHER listId OR listName is REQUIRED
+- List identification: EITHER listId OR listName REQUIRED
 
 Notes:
-- Use filters (archived, statuses, etc.) to narrow down results
-- Pagination available through page parameter
-- Sorting available through order_by and reverse parameters`,
+- Use filters (archived, statuses) to narrow down results
+- Pagination and sorting available`,
     inputSchema: {
         type: "object",
         properties: {
@@ -427,12 +416,14 @@ export const getTaskCommentsTool = {
 
 Valid Usage:
 1. Use taskId (preferred)
-2. Use taskName + optional listName
+2. Use taskName + listName for targeted search
+
+Requirements:
+- Task identification: EITHER taskId OR taskName REQUIRED
 
 Notes:
-- If using taskName, providing listName helps locate the correct task
 - Task names may not be unique across different lists
-- Use start and startId parameters for pagination through comments`,
+- Use start/startId parameters for pagination`,
     inputSchema: {
         type: "object",
         properties: {
@@ -471,13 +462,11 @@ Valid Usage:
 2. Use taskName + listName
 
 Requirements:
-- EITHER taskId OR (taskName + listName) is REQUIRED
-- commentText is REQUIRED
+- Task identification: EITHER taskId OR (taskName + listName) REQUIRED
+- commentText: REQUIRED
 
 Notes:
-- 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)`,
+- Set notifyAll=true to notify all task assignees`,
     inputSchema: {
         type: "object",
         properties: {
@@ -517,13 +506,15 @@ export const deleteTaskTool = {
     description: `Purpose: PERMANENTLY DELETE a task.
 
 Valid Usage:
-1. Use taskId alone (preferred and safest)
-2. Use taskName + optional listName
+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 is risky as names may not be unique
-- Provide listName when using taskName for more precise targeting`,
+- Using taskName without listName may match multiple tasks`,
     inputSchema: {
         type: "object",
         properties: {
@@ -533,11 +524,11 @@ Warning:
             },
             taskName: {
                 type: "string",
-                description: "Name of task to delete. Use with extreme caution as names may not be unique."
+                description: "Name of task to delete. The tool will search for tasks with this name across all lists unless listName is specified."
             },
             listName: {
                 type: "string",
-                description: "Name of list containing the task. Helps ensure correct task deletion 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."
             }
         }
     }

package/build/tools/task/utilities.js

@@ -117,12 +117,31 @@ export function validateTaskUpdateData(updateData) {
     }
 }
 /**
- * Validate bulk operation tasks array
+ * Validate bulk task array and task identification
+ * @param tasks Array of tasks to validate
+ * @param operation The bulk operation type ('create', 'update', 'move', 'delete')
  */
-export function validateBulkTasks(tasks) {
-    if (!tasks || !Array.isArray(tasks) || tasks.length === 0) {
-        throw new Error('You must provide a non-empty array of tasks');
+export function validateBulkTasks(tasks, operation = 'update') {
+    if (!Array.isArray(tasks) || tasks.length === 0) {
+        throw new Error("tasks must be a non-empty array");
     }
+    tasks.forEach((task, index) => {
+        if (!task || typeof task !== 'object') {
+            throw new Error(`Task at index ${index} must be an object`);
+        }
+        // Skip task identification validation for create operations
+        if (operation === 'create') {
+            return;
+        }
+        // For bulk operations, require listName when using taskName
+        if (task.taskName && !task.listName) {
+            throw new Error(`Task at index ${index} using taskName must also provide listName`);
+        }
+        // At least one identifier is required for non-create operations
+        if (!task.taskId && !task.taskName && !task.customTaskId) {
+            throw new Error(`Task at index ${index} must provide either taskId, taskName + listName, or customTaskId`);
+        }
+    });
 }
 /**
  * Parse options for bulk operations

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

@@ -12,27 +12,20 @@
  */
 export const getWorkspaceTasksTool = {
     name: "get_workspace_tasks",
-    description: `Purpose: Retrieve tasks from across the entire workspace with powerful filtering options, including tag-based filtering.
+    description: `Purpose: Retrieve tasks from across the entire workspace with filtering.
 
 Valid Usage:
-1. Apply any combination of filters (tags, lists, folders, spaces, statuses, etc.)
-2. Use pagination to manage large result sets
+1. Apply any combination of filters (tags, lists, statuses, etc.)
+2. Use pagination for large result sets
 
 Requirements:
-- 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
+- At least one filter parameter REQUIRED (tags, list_ids, statuses, etc.)
 
 Notes:
-- 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
-`,
+- 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`,
     parameters: {
         type: 'object',
         properties: {

package/package.json

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