@taazkareem/clickup-mcp-server 0.4.72 → 0.4.73

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

@@ -0,0 +1,331 @@
+/**
+ * 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: "Create a single task in a ClickUp list. Use this tool for individual task creation only. For multiple tasks, use create_bulk_tasks instead. Before calling this tool, check if you already have the necessary list ID from previous responses in the conversation history, as this avoids redundant lookups. When creating a task, you MUST provide either a listId or listName.",
+    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: "Modify an existing task's properties. Valid parameter combinations:\n1. Use taskId alone (preferred if you have it)\n2. Use taskName + listName (listName is REQUIRED when using taskName, not optional)\n\nAt least one update field (name, description, status, priority) must be provided. Only specified fields will be updated.",
+    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: "Move a task to a different list. Valid parameter combinations:\n1. Use taskId + (listId or listName) - preferred\n2. Use taskName + sourceListName + (listId or listName)\n\nWARNING: When using taskName, sourceListName is ABSOLUTELY REQUIRED - the 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: {
+            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: "Create a copy of a task in the same or different list. Valid parameter combinations:\n1. Use taskId + optional (listId or listName) - preferred\n2. Use taskName + sourceListName + optional (listId or listName)\n\nWARNING: When using taskName, sourceListName is ABSOLUTELY REQUIRED - the 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: {
+            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: "Retrieve detailed information about a specific task. Valid parameter combinations:\n1. Use taskId alone (preferred)\n2. Use taskName + listName (listName is REQUIRED when using taskName). 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: "Retrieve tasks from a list with optional filtering. You MUST provide either:\n1. listId (preferred)\n2. listName\n\nUse filters to narrow down results by status, dates, etc.",
+    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: "⚠️ PERMANENTLY DELETE a task. This action cannot be undone. Valid parameter combinations:\n1. Use taskId alone (preferred and safest)\n2. Use taskName + optional listName (use with caution).",
+    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: "Retrieve comments for a ClickUp task. You can identify the task by either taskId or taskName. If using taskName, you can optionally provide listName to help locate the correct task if multiple tasks have the same name.",
+    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 [];
+}