@taazkareem/clickup-mcp-server 0.4.72 → 0.4.74

package/build/tools/list.js

@@ -7,6 +7,7 @@
  */
 import { clickUpServices } from '../services/shared.js';
 import config from '../config.js';
+import { sponsorService } from '../utils/sponsor-service.js';
 // Use shared services instance
 const { list: listService, workspace: workspaceService } = clickUpServices;
 /**
@@ -14,7 +15,19 @@ const { list: listService, workspace: workspaceService } = clickUpServices;
  */
 export const createListTool = {
     name: "create_list",
-    description: "Create a new list directly in a ClickUp space (not in a folder). You MUST provide either spaceId or spaceName. For creating lists inside folders, use create_list_in_folder instead.",
+    description: `Purpose: Create a new list directly in a ClickUp space (not in a folder).
+
+Valid Usage:
+1. Provide spaceId + list name (preferred)
+2. Provide spaceName + list name
+
+Requirements:
+- name: REQUIRED
+- EITHER spaceId OR spaceName: REQUIRED
+
+Notes:
+- For creating lists inside folders, use create_list_in_folder instead
+- Optional fields include content, dueDate, priority, assignee, and status`,
     inputSchema: {
         type: "object",
         properties: {
@@ -59,7 +72,21 @@ export const createListTool = {
  */
 export const createListInFolderTool = {
     name: "create_list_in_folder",
-    description: "Create a new list within a ClickUp folder. You MUST provide either: 1) folderId alone, or 2) folderName WITH either spaceName or spaceId. Folder names may not be unique across spaces, which is why space information is required when using folderName.",
+    description: `Purpose: Create a new list within a ClickUp folder.
+
+Valid Usage:
+1. Provide folderId + list name (preferred)
+2. Provide folderName + (spaceId OR spaceName) + list name
+
+Requirements:
+- name: REQUIRED
+- EITHER folderId OR (folderName + space information): REQUIRED
+- When using folderName, EITHER spaceId OR spaceName is REQUIRED
+
+Notes:
+- Folder names may not be unique across spaces, which is why space information
+  is required when using folderName
+- Optional fields include content and status`,
     inputSchema: {
         type: "object",
         properties: {
@@ -100,7 +127,18 @@ export const createListInFolderTool = {
  */
 export const getListTool = {
     name: "get_list",
-    description: "Retrieve details about a specific ClickUp list. You MUST provide either listId or listName. Using listId is more reliable as list names might not be unique.",
+    description: `Purpose: Retrieve details about a specific ClickUp list.
+
+Valid Usage:
+1. Provide listId (preferred)
+2. Provide listName
+
+Requirements:
+- EITHER listId OR listName: REQUIRED
+
+Notes:
+- Using listId is more reliable as list names might not be unique
+- Returns list details including name, content, and space information`,
     inputSchema: {
         type: "object",
         properties: {
@@ -121,7 +159,19 @@ export const getListTool = {
  */
 export const updateListTool = {
     name: "update_list",
-    description: "Update an existing ClickUp list's properties. You MUST provide either listId or listName, and at least one field to update (name, content, or status).",
+    description: `Purpose: Update an existing ClickUp list's properties.
+
+Valid Usage:
+1. Provide listId + update fields (preferred)
+2. Provide listName + update fields
+
+Requirements:
+- EITHER listId OR listName: REQUIRED
+- At least one field to update (name, content, or status): REQUIRED
+
+Notes:
+- Using listId is more reliable as list names might not be unique
+- Only specified fields will be updated`,
     inputSchema: {
         type: "object",
         properties: {
@@ -154,7 +204,19 @@ export const updateListTool = {
  */
 export const deleteListTool = {
     name: "delete_list",
-    description: "Permanently delete a ClickUp list and all its tasks. You MUST provide either listId or listName. WARNING: This action cannot be undone.",
+    description: `Purpose: Permanently delete a ClickUp list and all its tasks.
+
+Valid Usage:
+1. Provide listId (preferred and safest)
+2. Provide listName
+
+Requirements:
+- EITHER listId OR listName: REQUIRED
+
+⚠️ CRITICAL WARNING:
+- This action CANNOT be undone
+- All tasks within the list will also be permanently deleted
+- Using listName is risky as names may not be unique`,
     inputSchema: {
         type: "object",
         properties: {
@@ -222,24 +284,20 @@ export async function handleCreateList(parameters) {
     try {
         // Create the list
         const newList = await listService.createList(targetSpaceId, listData);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        id: newList.id,
-                        name: newList.name,
-                        content: newList.content,
-                        space: {
-                            id: newList.space.id,
-                            name: newList.space.name
-                        },
-                        message: `List "${newList.name}" created successfully`
-                    }, null, 2)
-                }]
-        };
+        return sponsorService.createResponse({
+            id: newList.id,
+            name: newList.name,
+            content: newList.content,
+            space: {
+                id: newList.space.id,
+                name: newList.space.name
+            },
+            url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${newList.id}`,
+            message: `List "${name}" created successfully`
+        }, true);
     }
     catch (error) {
-        throw new Error(`Failed to create list: ${error.message}`);
+        return sponsorService.createErrorResponse(`Failed to create list: ${error.message}`);
     }
 }
 /**
@@ -290,24 +348,24 @@ export async function handleCreateListInFolder(parameters) {
     try {
         // Create the list in the folder
         const newList = await listService.createListInFolder(targetFolderId, listData);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        id: newList.id,
-                        name: newList.name,
-                        content: newList.content,
-                        space: {
-                            id: newList.space.id,
-                            name: newList.space.name
-                        },
-                        message: `List "${newList.name}" created successfully in folder`
-                    }, null, 2)
-                }]
-        };
+        return sponsorService.createResponse({
+            id: newList.id,
+            name: newList.name,
+            content: newList.content,
+            folder: {
+                id: newList.folder.id,
+                name: newList.folder.name
+            },
+            space: {
+                id: newList.space.id,
+                name: newList.space.name
+            },
+            url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${newList.id}`,
+            message: `List "${name}" created successfully in folder "${newList.folder.name}"`
+        }, true);
     }
     catch (error) {
-        throw new Error(`Failed to create list in folder: ${error.message}`);
+        return sponsorService.createErrorResponse(`Failed to create list in folder: ${error.message}`);
     }
 }
 /**
@@ -331,25 +389,19 @@ export async function handleGetList(parameters) {
     try {
         // Get the list
         const list = await listService.getList(targetListId);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        id: list.id,
-                        name: list.name,
-                        content: list.content,
-                        space: {
-                            id: list.space.id,
-                            name: list.space.name
-                        },
-                        status: list.status,
-                        url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${list.id}`
-                    }, null, 2)
-                }]
-        };
+        return sponsorService.createResponse({
+            id: list.id,
+            name: list.name,
+            content: list.content,
+            space: {
+                id: list.space.id,
+                name: list.space.name
+            },
+            url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${list.id}`
+        }, true);
     }
     catch (error) {
-        throw new Error(`Failed to retrieve list: ${error.message}`);
+        return sponsorService.createErrorResponse(`Failed to retrieve list: ${error.message}`);
     }
 }
 /**
@@ -385,26 +437,20 @@ export async function handleUpdateList(parameters) {
     try {
         // Update the list
         const updatedList = await listService.updateList(targetListId, updateData);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        id: updatedList.id,
-                        name: updatedList.name,
-                        content: updatedList.content,
-                        space: {
-                            id: updatedList.space.id,
-                            name: updatedList.space.name
-                        },
-                        status: updatedList.status,
-                        url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${updatedList.id}`,
-                        message: `List "${updatedList.name}" updated successfully`
-                    }, null, 2)
-                }]
-        };
+        return sponsorService.createResponse({
+            id: updatedList.id,
+            name: updatedList.name,
+            content: updatedList.content,
+            space: {
+                id: updatedList.space.id,
+                name: updatedList.space.name
+            },
+            url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${updatedList.id}`,
+            message: `List "${updatedList.name}" updated successfully`
+        }, true);
     }
     catch (error) {
-        throw new Error(`Failed to update list: ${error.message}`);
+        return sponsorService.createErrorResponse(`Failed to update list: ${error.message}`);
     }
 }
 /**
@@ -431,17 +477,12 @@ export async function handleDeleteList(parameters) {
         const listName = list.name;
         // Delete the list
         await listService.deleteList(targetListId);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        message: `List "${listName}" deleted successfully`,
-                        url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${targetListId}`
-                    }, null, 2)
-                }]
-        };
+        return sponsorService.createResponse({
+            success: true,
+            message: `List "${listName || targetListId}" deleted successfully`
+        }, true);
     }
     catch (error) {
-        throw new Error(`Failed to delete list: ${error.message}`);
+        return sponsorService.createErrorResponse(`Failed to delete list: ${error.message}`);
     }
 }

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

@@ -0,0 +1,284 @@
+/**
+ * ClickUp MCP Bulk Task Operations
+ *
+ * This module defines tools for bulk task operations including creating,
+ * updating, moving, and deleting multiple tasks at once.
+ */
+import { clickUpServices } from '../../services/shared.js';
+import { BulkService } from '../../services/clickup/bulk.js';
+// Initialize services
+const { task: taskService } = clickUpServices;
+const bulkService = new BulkService(taskService);
+//=============================================================================
+// COMMON SCHEMA DEFINITIONS
+//=============================================================================
+// Common schema definitions
+const bulkOptionsSchema = {
+    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."
+        }
+    ],
+    description: "Processing options (or JSON string representing options)"
+};
+const taskIdentifierSchema = {
+    taskId: {
+        type: "string",
+        description: "Task ID (preferred). Use instead of taskName if available."
+    },
+    taskName: {
+        type: "string",
+        description: "Task name. Requires listName when used."
+    },
+    listName: {
+        type: "string",
+        description: "REQUIRED with taskName: List containing the task."
+    }
+};
+//=============================================================================
+// BULK TASK OPERATION TOOLS
+//=============================================================================
+/**
+ * Tool definition for creating multiple tasks at once
+ */
+export const createBulkTasksTool = {
+    name: "create_bulk_tasks",
+    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
+
+Requirements:
+- tasks: REQUIRED (array of tasks, each with at least a name)
+- 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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            listId: {
+                type: "string",
+                description: "ID of list for new tasks (preferred). Use this instead of listName if you have it."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list for new tasks. Only use if you don't have listId."
+            },
+            tasks: {
+                type: "array",
+                description: "Array of tasks to create. Each task must have at least a name.",
+                items: {
+                    type: "object",
+                    properties: {
+                        name: {
+                            type: "string",
+                            description: "Task name with emoji prefix"
+                        },
+                        description: {
+                            type: "string",
+                            description: "Plain text description"
+                        },
+                        markdown_description: {
+                            type: "string",
+                            description: "Markdown description (overrides plain text)"
+                        },
+                        status: {
+                            type: "string",
+                            description: "Task status (uses list default if omitted)"
+                        },
+                        priority: {
+                            type: "number",
+                            description: "Priority 1-4 (1=urgent, 4=low)"
+                        },
+                        dueDate: {
+                            type: "string",
+                            description: "Due date. Supports Unix timestamps (in milliseconds) and natural language expressions like '1 hour from now', 'tomorrow', 'next week', etc."
+                        }
+                    },
+                    required: ["name"]
+                }
+            },
+            options: bulkOptionsSchema
+        },
+        required: ["tasks"]
+    }
+};
+/**
+ * Tool definition for updating multiple tasks at once
+ */
+export const updateBulkTasksTool = {
+    name: "update_bulk_tasks",
+    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
+
+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)
+
+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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            tasks: {
+                type: "array",
+                description: "Array of tasks to update",
+                items: {
+                    type: "object",
+                    properties: {
+                        ...taskIdentifierSchema,
+                        name: {
+                            type: "string",
+                            description: "New name with emoji prefix"
+                        },
+                        description: {
+                            type: "string",
+                            description: "New plain text description"
+                        },
+                        markdown_description: {
+                            type: "string",
+                            description: "New markdown description"
+                        },
+                        status: {
+                            type: "string",
+                            description: "New status"
+                        },
+                        priority: {
+                            type: ["number", "null"],
+                            enum: [1, 2, 3, 4, null],
+                            description: "New priority (1-4 or null)"
+                        },
+                        dueDate: {
+                            type: "string",
+                            description: "New due date. Supports Unix timestamps (in milliseconds) and natural language expressions like '1 hour from now', 'tomorrow', etc."
+                        }
+                    }
+                }
+            },
+            options: bulkOptionsSchema
+        },
+        required: ["tasks"]
+    }
+};
+/**
+ * Tool definition for moving multiple tasks at once
+ */
+export const moveBulkTasksTool = {
+    name: "move_bulk_tasks",
+    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
+
+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
+
+⚠️ 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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            tasks: {
+                type: "array",
+                description: "Array of tasks to move",
+                items: {
+                    type: "object",
+                    properties: {
+                        ...taskIdentifierSchema
+                    }
+                }
+            },
+            targetListId: {
+                type: "string",
+                description: "ID of destination list (preferred). Use instead of targetListName if available."
+            },
+            targetListName: {
+                type: "string",
+                description: "Name of destination list. Only use if you don't have targetListId."
+            },
+            options: bulkOptionsSchema
+        },
+        required: ["tasks"]
+    }
+};
+/**
+ * Tool definition for deleting multiple tasks at once
+ */
+export const deleteBulkTasksTool = {
+    name: "delete_bulk_tasks",
+    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
+
+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
+
+⚠️ CRITICAL 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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            tasks: {
+                type: "array",
+                description: "Array of tasks to delete",
+                items: {
+                    type: "object",
+                    properties: {
+                        ...taskIdentifierSchema
+                    }
+                }
+            },
+            options: bulkOptionsSchema
+        },
+        required: ["tasks"]
+    }
+};