@taazkareem/clickup-mcp-server 0.4.72 → 0.4.74

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

@@ -0,0 +1,421 @@
+/**
+ * ClickUp MCP Single Task Operations
+ *
+ * This module defines tools for single task operations including creating,
+ * updating, moving, duplicating, and deleting tasks, as well as retrieving
+ * task details and comments.
+ */
+import { clickUpServices } from '../../services/shared.js';
+// Use shared services instance
+const { task: taskService } = clickUpServices;
+//=============================================================================
+// COMMON VALIDATION UTILITIES
+//=============================================================================
+// Common validation functions
+const validateTaskName = (name) => {
+    if (!name || typeof name !== 'string') {
+        throw new Error("A task name is required");
+    }
+    const trimmedName = name.trim();
+    if (trimmedName.length === 0) {
+        throw new Error("Task name cannot be empty or only whitespace");
+    }
+    return trimmedName;
+};
+const validatePriority = (priority) => {
+    if (priority !== undefined && (typeof priority !== 'number' || priority < 1 || priority > 4)) {
+        throw new Error("Priority must be a number between 1 and 4");
+    }
+};
+const validateDueDate = (dueDate) => {
+    if (dueDate && typeof dueDate !== 'string') {
+        throw new Error("Due date must be a string in timestamp format or natural language");
+    }
+};
+// Common error handler
+const handleOperationError = (operation, error) => {
+    console.error(`Error ${operation}:`, error);
+    throw error;
+};
+//=============================================================================
+// SINGLE TASK OPERATION TOOLS
+//=============================================================================
+/**
+ * Tool definition for creating a single task
+ */
+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 (system will look up the list ID)
+
+Requirements:
+- name: REQUIRED
+- 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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "REQUIRED: Name of the task. Put a relevant emoji followed by a blank space before the name."
+            },
+            listId: {
+                type: "string",
+                description: "REQUIRED (unless listName provided): ID of the list to create the task in. If you have this ID from a previous response, use it directly rather than looking up by name."
+            },
+            listName: {
+                type: "string",
+                description: "REQUIRED (unless listId provided): Name of the list to create the task in - will automatically find the list by name."
+            },
+            description: {
+                type: "string",
+                description: "Optional plain text description for the task"
+            },
+            markdown_description: {
+                type: "string",
+                description: "Optional markdown formatted description for the task. If provided, this takes precedence over description"
+            },
+            status: {
+                type: "string",
+                description: "Optional: Override the default ClickUp status. In most cases, you should omit this to use ClickUp defaults"
+            },
+            priority: {
+                type: "number",
+                description: "Optional priority of the task (1-4), where 1 is urgent/highest priority and 4 is lowest priority. Only set this when explicitly requested."
+            },
+            dueDate: {
+                type: "string",
+                description: "Optional due date. Supports Unix timestamps (ms) or natural language like '1 hour from now', 'tomorrow', 'next week', etc."
+            }
+        }
+    }
+};
+/**
+ * Tool definition for updating a task
+ */
+export const updateTaskTool = {
+    name: "update_task",
+    description: `Purpose: Modify properties of an existing task.
+
+Valid Usage:
+1. Use taskId alone (preferred if available)
+2. Use taskName + listName
+
+Requirements:
+- At least one update field (name, description, status, priority, dueDate) must be provided
+- When using taskName, listName is REQUIRED
+
+Notes:
+- Only specified fields will be updated
+- Using taskId is more reliable than taskName`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of the task to update (preferred). Use this instead of taskName if you have it from a previous response."
+            },
+            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."
+            },
+            listName: {
+                type: "string",
+                description: "Name of the list containing the task. REQUIRED when using taskName."
+            },
+            name: {
+                type: "string",
+                description: "New name for the task. Include emoji prefix if appropriate."
+            },
+            description: {
+                type: "string",
+                description: "New plain text description. Will be ignored if markdown_description is provided."
+            },
+            markdown_description: {
+                type: "string",
+                description: "New markdown description. Takes precedence over plain text description."
+            },
+            status: {
+                type: "string",
+                description: "New status. Must be valid for the task's current list."
+            },
+            priority: {
+                type: ["number", "null"],
+                enum: [1, 2, 3, 4, null],
+                description: "New priority: 1 (urgent) to 4 (low). Set null to clear priority."
+            },
+            dueDate: {
+                type: "string",
+                description: "New due date. Supports both Unix timestamps (in milliseconds) and natural language expressions like '1 hour from now', 'tomorrow', 'next week', or '3 days from now'."
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for moving a task
+ */
+export const moveTaskTool = {
+    name: "move_task",
+    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)
+
+Requirements:
+- 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
+- System cannot find a task by name without knowing which list to search in`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of the task to move (preferred). Use this instead of taskName if you have it."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of the task to move. When using this, you MUST also provide sourceListName."
+            },
+            sourceListName: {
+                type: "string",
+                description: "REQUIRED with taskName: Current list containing the task."
+            },
+            listId: {
+                type: "string",
+                description: "ID of destination list (preferred). Use this instead of listName if you have it."
+            },
+            listName: {
+                type: "string",
+                description: "Name of destination list. Only use if you don't have listId."
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for duplicating a task
+ */
+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 + optional (listId OR listName) - preferred
+2. Use taskName + sourceListName + optional (listId OR listName)
+
+Requirements:
+- When using taskName, sourceListName is REQUIRED
+
+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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of task to duplicate (preferred). Use this instead of taskName if you have it."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of task to duplicate. When using this, you MUST provide sourceListName."
+            },
+            sourceListName: {
+                type: "string",
+                description: "REQUIRED with taskName: List containing the original task."
+            },
+            listId: {
+                type: "string",
+                description: "ID of list for the duplicate (optional). Defaults to same list as original."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list for the duplicate. Only use if you don't have listId."
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for retrieving a task
+ */
+export const getTaskTool = {
+    name: "get_task",
+    description: `Purpose: Retrieve detailed information about a specific task.
+
+Valid Usage:
+1. Use taskId alone (preferred)
+2. Use taskName + listName
+
+Requirements:
+- When using taskName, listName is REQUIRED
+
+Note:
+- Task names are only unique within a list, so the system needs to know which list to search in`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of task to retrieve (preferred). Use this instead of taskName if you have it."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of task to retrieve. When using this parameter, you MUST also provide listName."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list containing the task. REQUIRED when using taskName."
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for retrieving tasks from a list
+ */
+export const getTasksTool = {
+    name: "get_tasks",
+    description: `Purpose: Retrieve tasks from a list with optional filtering.
+
+Valid Usage:
+1. Use listId (preferred)
+2. Use listName
+
+Requirements:
+- EITHER listId OR listName is REQUIRED
+
+Notes:
+- 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: {
+            listId: {
+                type: "string",
+                description: "ID of list to get tasks from (preferred). Use this instead of listName if you have it."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list to get tasks from. Only use if you don't have listId."
+            },
+            archived: {
+                type: "boolean",
+                description: "Include archived tasks"
+            },
+            page: {
+                type: "number",
+                description: "Page number for pagination (starts at 0)"
+            },
+            order_by: {
+                type: "string",
+                description: "Sort field: due_date, created, updated"
+            },
+            reverse: {
+                type: "boolean",
+                description: "Reverse sort order (descending)"
+            },
+            subtasks: {
+                type: "boolean",
+                description: "Include subtasks"
+            },
+            statuses: {
+                type: "array",
+                items: {
+                    type: "string"
+                },
+                description: "Filter by status names (e.g. ['To Do', 'In Progress'])"
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for deleting a task
+ */
+export const deleteTaskTool = {
+    name: "delete_task",
+    description: `Purpose: PERMANENTLY DELETE a task.
+
+Valid Usage:
+1. Use taskId alone (preferred and safest)
+2. Use taskName + optional listName
+
+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`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of task to delete (preferred). Use this instead of taskName for safety."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of task to delete. Use with extreme caution as names may not be unique."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list containing the task. Helps ensure correct task deletion when using taskName."
+            }
+        }
+    }
+};
+/**
+ * Tool definition for retrieving task comments
+ */
+export const getTaskCommentsTool = {
+    name: "get_task_comments",
+    description: `Purpose: Retrieve comments for a ClickUp task.
+
+Valid Usage:
+1. Use taskId (preferred)
+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 and startId parameters for pagination through comments`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of task to retrieve comments for (preferred). Use this instead of taskName if you have it."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of task to retrieve comments for. Warning: Task names may not be unique."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list containing the task. Helps find the right task when using taskName."
+            },
+            start: {
+                type: "number",
+                description: "Timestamp (in milliseconds) to start retrieving comments from. Used for pagination."
+            },
+            startId: {
+                type: "string",
+                description: "Comment ID to start from. Used together with start for pagination."
+            }
+        }
+    }
+};

package/build/tools/task/utilities.js

@@ -0,0 +1,163 @@
+/**
+ * ClickUp MCP Task Utilities
+ *
+ * This module provides utility functions for task-related operations including
+ * data formatting, validation, and resolution of IDs from names.
+ */
+import { formatDueDate } from '../utils.js';
+import { clickUpServices } from '../../services/shared.js';
+// Use shared services instance for ID resolution
+const { workspace: workspaceService } = clickUpServices;
+//=============================================================================
+// DATA FORMATTING UTILITIES
+//=============================================================================
+/**
+ * Formats task data for response
+ */
+export function formatTaskData(task, additional = {}) {
+    return {
+        id: task.id,
+        name: task.name,
+        url: task.url,
+        status: task.status?.status || "Unknown",
+        due_date: task.due_date ? formatDueDate(Number(task.due_date)) : undefined,
+        list: task.list.name,
+        space: task.space.name,
+        folder: task.folder?.name,
+        ...additional
+    };
+}
+//=============================================================================
+// VALIDATION UTILITIES
+//=============================================================================
+/**
+ * Validates task identification parameters
+ * Ensures either taskId is provided or both taskName and listName are provided
+ */
+export function validateTaskIdentification(taskId, taskName, listName) {
+    if (!taskId && !taskName) {
+        throw new Error("Either taskId or taskName must be provided");
+    }
+    if (!taskId && taskName && !listName) {
+        throw new Error("When using taskName, listName is required to locate the task");
+    }
+}
+/**
+ * Validates list identification parameters
+ * Ensures either listId or listName is provided
+ */
+export function validateListIdentification(listId, listName) {
+    if (!listId && !listName) {
+        throw new Error("Either listId or listName must be provided");
+    }
+}
+/**
+ * Validates task update data
+ * Ensures at least one update field is provided
+ */
+export function validateTaskUpdateData(updateData) {
+    const hasUpdates = Object.keys(updateData).length > 0;
+    if (!hasUpdates) {
+        throw new Error("At least one field to update must be provided");
+    }
+}
+/**
+ * Validate bulk operation tasks array
+ */
+export function validateBulkTasks(tasks) {
+    if (!tasks || !Array.isArray(tasks) || tasks.length === 0) {
+        throw new Error('You must provide a non-empty array of tasks');
+    }
+}
+/**
+ * Parse options for bulk operations
+ */
+export function parseBulkOptions(rawOptions) {
+    if (typeof rawOptions === 'string') {
+        try {
+            return JSON.parse(rawOptions);
+        }
+        catch (error) {
+            return undefined;
+        }
+    }
+    return rawOptions;
+}
+//=============================================================================
+// ID RESOLUTION UTILITIES
+//=============================================================================
+/**
+ * Resolves a task ID from either direct ID or name+list combination
+ * Handles validation and throws appropriate errors
+ */
+export async function resolveTaskIdWithValidation(taskId, taskName, listName) {
+    // Validate parameters
+    validateTaskIdentification(taskId, taskName, listName);
+    // If taskId is provided, use it directly
+    if (taskId)
+        return taskId;
+    // At this point we know we have taskName and listName (validation ensures this)
+    // Find the list ID from its name
+    const listId = await resolveListIdWithValidation(undefined, listName);
+    // Find the task in the list
+    const { task: taskService } = clickUpServices;
+    const foundTask = await taskService.findTaskByName(listId, taskName);
+    if (!foundTask) {
+        throw new Error(`Task "${taskName}" not found in list "${listName}"`);
+    }
+    return foundTask.id;
+}
+/**
+ * Resolves a list ID from either direct ID or name
+ * Handles validation and throws appropriate errors
+ */
+export async function resolveListIdWithValidation(listId, listName) {
+    // Validate parameters
+    validateListIdentification(listId, listName);
+    // If listId is provided, use it directly
+    if (listId)
+        return listId;
+    // At this point we know we have listName (validation ensures this)
+    // Find the list ID from its name
+    const hierarchy = await workspaceService.getWorkspaceHierarchy();
+    const listInfo = workspaceService.findIDByNameInHierarchy(hierarchy, listName, 'list');
+    if (!listInfo) {
+        throw new Error(`List "${listName}" not found`);
+    }
+    return listInfo.id;
+}
+//=============================================================================
+// PATH EXTRACTION HELPER FUNCTIONS
+//=============================================================================
+/**
+ * Extract path from node to root
+ */
+export function extractPath(node) {
+    if (!node)
+        return '';
+    if (!node.parent)
+        return node.name;
+    return `${extractPath(node.parent)} > ${node.name}`;
+}
+/**
+ * Extract path from root to a specific node
+ */
+export function extractTreePath(root, targetId) {
+    if (!root)
+        return [];
+    // If this node is the target, return it in an array
+    if (root.id === targetId) {
+        return [root];
+    }
+    // Check children if they exist
+    if (root.children) {
+        for (const child of root.children) {
+            const path = extractTreePath(child, targetId);
+            if (path.length > 0) {
+                return [root, ...path];
+            }
+        }
+    }
+    // Not found in this branch
+    return [];
+}