@taazkareem/clickup-mcp-server 0.8.0 → 0.8.2

package/README.md

@@ -6,7 +6,7 @@
 
 A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.
 
-> 🚀 **Status Update:** v0.8.0 is now available with HTTP Streamable transport support, Legacy SSE Support, Member Management tools, and more.
+> 🚀 **Status Update:** v0.8.1 is now available with HTTP Streamable transport support, Legacy SSE Support, Member Management tools, and more.  Next release will patch some bugs. See Unreleased section of [Changelog](changelog.md) for details.
 
 ## Setup
 
@@ -270,4 +270,4 @@ This software makes use of third-party APIs and may reference trademarks
 or brands owned by third parties. The use of such APIs or references does not imply
 any affiliation with or endorsement by the respective companies. All trademarks and
 brand names are the property of their respective owners. This project is an independent
-work and is not officially associated with or sponsored by any third-party company mentioned.
+work and is not officially associated with or sponsored by any third-party company mentioned.

package/build/server.js

@@ -22,7 +22,7 @@ const logger = new Logger('Server');
 const { workspace } = clickUpServices;
 export const server = new Server({
     name: "clickup-mcp-server",
-    version: "0.8.0",
+    version: "0.8.2",
 }, {
     capabilities: {
         tools: {},

package/build/services/clickup/task/task-core.js

@@ -59,6 +59,8 @@ export class TaskServiceCore extends BaseClickUpService {
             params.append('include_closed', String(filters.include_closed));
         if (filters.subtasks)
             params.append('subtasks', String(filters.subtasks));
+        if (filters.include_subtasks)
+            params.append('include_subtasks', String(filters.include_subtasks));
         if (filters.page)
             params.append('page', String(filters.page));
         if (filters.order_by)

package/build/tools/documents.js

@@ -134,8 +134,7 @@ export const listDocumentPagesTool = {
             },
             max_page_depth: {
                 type: "number",
-                description: "Maximum depth of pages to retrieve (-1 for unlimited)",
-                optional: true
+                description: "Maximum depth of pages to retrieve (-1 for unlimited)"
             }
         },
         required: ["documentId"]
@@ -164,8 +163,7 @@ export const getDocumentPagesTool = {
             content_format: {
                 type: "string",
                 enum: ["text/md", "text/html"],
-                description: "Format of the content to retrieve",
-                optional: true
+                description: "Format of the content to retrieve"
             }
         },
         required: ["documentId", "pageIds"]
@@ -186,8 +184,7 @@ export const createDocumentPageTool = {
             },
             content: {
                 type: "string",
-                description: "Content of the page",
-                optional: true
+                description: "Content of the page"
             },
             name: {
                 type: "string",
@@ -195,13 +192,11 @@ export const createDocumentPageTool = {
             },
             sub_title: {
                 type: "string",
-                description: "Subtitle of the page",
-                optional: true
+                description: "Subtitle of the page"
             },
             parent_page_id: {
                 type: "string",
-                description: "ID of the parent page (if this is a sub-page)",
-                optional: true
+                description: "ID of the parent page (if this is a sub-page)"
             }
         },
         required: ["documentId", "name"]
@@ -226,30 +221,25 @@ export const updateDocumentPageTool = {
             },
             name: {
                 type: "string",
-                description: "New name for the page",
-                optional: true
+                description: "New name for the page"
             },
             sub_title: {
                 type: "string",
-                description: "New subtitle for the page",
-                optional: true
+                description: "New subtitle for the page"
             },
             content: {
                 type: "string",
-                description: "New content for the page",
-                optional: true
+                description: "New content for the page"
             },
             content_edit_mode: {
                 type: "string",
                 enum: ["replace", "append", "prepend"],
-                description: "How to update the content. Defaults to replace",
-                optional: true
+                description: "How to update the content. Defaults to replace"
             },
             content_format: {
                 type: "string",
                 enum: ["text/md", "text/plain"],
-                description: "Format of the content. Defaults to text/md",
-                optional: true
+                description: "Format of the content. Defaults to text/md"
             },
         },
         required: ["documentId", "pageId"]

package/build/tools/task/handlers.js

@@ -12,6 +12,7 @@ import { clickUpServices } from '../../services/shared.js';
 import { BulkService } from '../../services/clickup/bulk.js';
 import { parseDueDate } from '../utils.js';
 import { validateTaskIdentification, validateListIdentification, validateTaskUpdateData, validateBulkTasks, parseBulkOptions, resolveListIdWithValidation } from './utilities.js';
+import { handleResolveAssignees } from '../member.js';
 import { workspaceService } from '../../services/shared.js';
 import { isNameMatch } from '../../utils/resolver-utils.js';
 import { Logger } from '../../logger.js';
@@ -79,10 +80,55 @@ function parseTimeEstimate(timeEstimate) {
     }
     return Math.round(totalMinutes); // Return minutes
 }
+/**
+ * Resolve assignees from mixed input (user IDs, emails, usernames) to user IDs
+ */
+async function resolveAssignees(assignees) {
+    if (!assignees || !Array.isArray(assignees) || assignees.length === 0) {
+        return [];
+    }
+    const resolved = [];
+    const toResolve = [];
+    // Separate numeric IDs from strings that need resolution
+    for (const assignee of assignees) {
+        if (typeof assignee === 'number') {
+            resolved.push(assignee);
+        }
+        else if (typeof assignee === 'string') {
+            // Check if it's a numeric string
+            const numericId = parseInt(assignee, 10);
+            if (!isNaN(numericId) && numericId.toString() === assignee) {
+                resolved.push(numericId);
+            }
+            else {
+                // It's an email or username that needs resolution
+                toResolve.push(assignee);
+            }
+        }
+    }
+    // Resolve emails/usernames to user IDs if any
+    if (toResolve.length > 0) {
+        try {
+            const result = await handleResolveAssignees({ assignees: toResolve });
+            if (result.userIds && Array.isArray(result.userIds)) {
+                for (const userId of result.userIds) {
+                    if (userId !== null && typeof userId === 'number') {
+                        resolved.push(userId);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.warn('Failed to resolve some assignees:', error.message);
+            // Continue with the IDs we could resolve
+        }
+    }
+    return resolved;
+}
 /**
  * Build task update data from parameters
  */
-function buildUpdateData(params) {
+async function buildUpdateData(params) {
     const updateData = {};
     if (params.name !== undefined)
         updateData.name = params.name;
@@ -116,6 +162,10 @@ function buildUpdateData(params) {
     if (params.custom_fields !== undefined) {
         updateData.custom_fields = params.custom_fields;
     }
+    // Handle assignees if provided - resolve emails/usernames to user IDs
+    if (params.assignees !== undefined) {
+        updateData.assignees = await resolveAssignees(params.assignees);
+    }
     return updateData;
 }
 /**
@@ -377,6 +427,8 @@ export async function createTaskHandler(params) {
     // Use our helper function to validate and convert priority
     const priority = toTaskPriority(params.priority);
     const listId = await getListId(params.listId, params.listName);
+    // Resolve assignees if provided
+    const resolvedAssignees = assignees ? await resolveAssignees(assignees) : undefined;
     const taskData = {
         name,
         description,
@@ -387,7 +439,7 @@ export async function createTaskHandler(params) {
         tags,
         custom_fields,
         check_required_custom_fields,
-        assignees
+        assignees: resolvedAssignees
     };
     // Add due date if specified
     if (dueDate) {
@@ -405,12 +457,14 @@ export async function createTaskHandler(params) {
  * Handler for updating a task
  */
 export async function updateTaskHandler(taskService, params) {
-    const { taskId, taskName, listName, customTaskId, ...updateData } = params;
+    const { taskId, taskName, listName, customTaskId, ...rawUpdateData } = params;
     // Validate task identification with global lookup enabled
     const validationResult = validateTaskIdentification(params, { useGlobalLookup: true });
     if (!validationResult.isValid) {
         throw new Error(validationResult.errorMessage);
     }
+    // Build properly formatted update data from raw parameters (now async)
+    const updateData = await buildUpdateData(rawUpdateData);
     // Validate update data
     validateTaskUpdateData(updateData);
     try {
@@ -564,7 +618,11 @@ export async function getWorkspaceTasksHandler(taskService, params) {
             date_updated_lt: params.date_updated_lt,
             assignees: params.assignees,
             page: params.page,
-            detail_level: params.detail_level || 'detailed'
+            detail_level: params.detail_level || 'detailed',
+            subtasks: params.subtasks,
+            include_subtasks: params.include_subtasks,
+            include_compact_time_entries: params.include_compact_time_entries,
+            custom_fields: params.custom_fields
         };
         // Get tasks with adaptive response format support
         const response = await taskService.getWorkspaceTasks(filters);
@@ -597,8 +655,10 @@ export async function createBulkTasksHandler(params) {
     validateBulkTasks(tasks, 'create');
     // Validate and resolve list ID
     const targetListId = await resolveListIdWithValidation(listId, listName);
-    // Format tasks for creation
-    const formattedTasks = tasks.map(task => {
+    // Format tasks for creation - resolve assignees for each task
+    const formattedTasks = await Promise.all(tasks.map(async (task) => {
+        // Resolve assignees if provided
+        const resolvedAssignees = task.assignees ? await resolveAssignees(task.assignees) : undefined;
         const taskData = {
             name: task.name,
             description: task.description,
@@ -607,7 +667,7 @@ export async function createBulkTasksHandler(params) {
             priority: toTaskPriority(task.priority),
             tags: task.tags,
             custom_fields: task.custom_fields,
-            assignees: task.assignees
+            assignees: resolvedAssignees
         };
         // Add due date if specified
         if (task.dueDate) {
@@ -620,7 +680,7 @@ export async function createBulkTasksHandler(params) {
             taskData.start_date_time = true;
         }
         return taskData;
-    });
+    }));
     // Parse bulk options
     const bulkOptions = parseBulkOptions(options);
     // Create tasks - pass arguments in correct order: listId, tasks, options

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

@@ -17,6 +17,7 @@ export const getWorkspaceTasksTool = {
 Valid Usage:
 1. Apply any combination of filters (tags, lists, folders, spaces, statuses, etc.)
 2. Use pagination to manage large result sets
+3. Include subtasks by setting subtasks=true
 
 Requirements:
 - At least one filter parameter is REQUIRED (tags, list_ids, folder_ids, space_ids, statuses, assignees, or date filters)
@@ -28,6 +29,8 @@ Notes:
 - 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
+- Set subtasks=true to include subtask details in the response
+  IMPORTANT: subtasks=true enables subtasks to appear in results, but subtasks must still match your other filter criteria (tags, lists, etc.) to be returned. To see all subtasks of a specific task regardless of filters, use the get_task tool with subtasks=true instead.
 - 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)
@@ -123,6 +126,22 @@ Notes:
                 type: 'string',
                 enum: ['summary', 'detailed'],
                 description: 'Level of detail to return. Use summary for lightweight responses or detailed for full task data. If not specified, defaults to "detailed".'
+            },
+            subtasks: {
+                type: 'boolean',
+                description: 'Include subtasks in the response. Set to true to retrieve subtask details for all returned tasks. Note: subtasks must still match your other filter criteria to appear in results.'
+            },
+            include_subtasks: {
+                type: 'boolean',
+                description: 'Alternative parameter for including subtasks (legacy support).'
+            },
+            include_compact_time_entries: {
+                type: 'boolean',
+                description: 'Include compact time entry data in the response.'
+            },
+            custom_fields: {
+                type: 'object',
+                description: 'Filter by custom field values. Provide as key-value pairs where keys are custom field IDs.'
             }
         }
     },
@@ -216,6 +235,22 @@ Notes:
                 type: 'string',
                 enum: ['summary', 'detailed'],
                 description: 'Level of detail to return. Use summary for lightweight responses or detailed for full task data. If not specified, defaults to "detailed".'
+            },
+            subtasks: {
+                type: 'boolean',
+                description: 'Include subtasks in the response. Set to true to retrieve subtask details for all returned tasks. Note: subtasks must still match your other filter criteria to appear in results.'
+            },
+            include_subtasks: {
+                type: 'boolean',
+                description: 'Alternative parameter for including subtasks (legacy support).'
+            },
+            include_compact_time_entries: {
+                type: 'boolean',
+                description: 'Include compact time entry data in the response.'
+            },
+            custom_fields: {
+                type: 'object',
+                description: 'Filter by custom field values. Provide as key-value pairs where keys are custom field IDs.'
             }
         }
     }

package/build/utils/date-utils.js

@@ -69,6 +69,14 @@ export function parseDueDate(dateString) {
     if (!dateString)
         return undefined;
     try {
+        // First, try to parse as a direct timestamp
+        const numericValue = Number(dateString);
+        if (!isNaN(numericValue) && numericValue > 0) {
+            // If it's a reasonable timestamp (after year 2000), use it
+            if (numericValue > 946684800000) { // Jan 1, 2000
+                return numericValue;
+            }
+        }
         // Handle natural language dates
         const lowerDate = dateString.toLowerCase().trim();
         // Handle "now" specifically
@@ -98,6 +106,44 @@ export function parseDueDate(dateString) {
             tomorrow.setHours(23, 59, 59, 999);
             return tomorrow.getTime();
         }
+        // Handle day names (Monday, Tuesday, etc.) - find next occurrence
+        const dayNames = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+        const dayMatch = lowerDate.match(/\b(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\b/);
+        if (dayMatch) {
+            const targetDayName = dayMatch[1];
+            const targetDayIndex = dayNames.indexOf(targetDayName);
+            const today = new Date();
+            const currentDayIndex = today.getDay();
+            // Calculate days until target day
+            let daysUntilTarget = targetDayIndex - currentDayIndex;
+            if (daysUntilTarget <= 0) {
+                daysUntilTarget += 7; // Next week
+            }
+            // Handle "next" prefix explicitly
+            if (lowerDate.includes('next ')) {
+                daysUntilTarget += 7;
+            }
+            const targetDate = new Date(today);
+            targetDate.setDate(today.getDate() + daysUntilTarget);
+            // Extract time if specified (e.g., "Friday at 3pm", "Saturday 2:30pm")
+            const timeMatch = lowerDate.match(/(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i);
+            if (timeMatch) {
+                let hours = parseInt(timeMatch[1]);
+                const minutes = timeMatch[2] ? parseInt(timeMatch[2]) : 0;
+                const meridian = timeMatch[3]?.toLowerCase();
+                // Convert to 24-hour format
+                if (meridian === 'pm' && hours < 12)
+                    hours += 12;
+                if (meridian === 'am' && hours === 12)
+                    hours = 0;
+                targetDate.setHours(hours, minutes, 0, 0);
+            }
+            else {
+                // Default to end of day if no time specified
+                targetDate.setHours(23, 59, 59, 999);
+            }
+            return targetDate.getTime();
+        }
         // Handle relative dates with specific times
         const relativeTimeRegex = /(?:(\d+)\s*(minutes?|hours?|days?|weeks?|months?)\s*from\s*now|tomorrow|next\s+(?:week|month|year))\s*(?:at\s+(\d+)(?::(\d+))?\s*(am|pm)?)?/i;
         const match = lowerDate.match(relativeTimeRegex);
@@ -191,10 +237,42 @@ export function parseDueDate(dateString) {
             }
             return date.getTime();
         }
-        // Try to parse as a date string
-        const date = new Date(dateString);
-        if (!isNaN(date.getTime())) {
-            return date.getTime();
+        // Enhanced fallback: Try JavaScript's native Date constructor with various formats
+        // This handles many natural language formats like "Saturday at 3pm EST", "next Friday", etc.
+        const nativeDate = new Date(dateString);
+        if (!isNaN(nativeDate.getTime())) {
+            // Check if the parsed date is reasonable (not too far in the past or future)
+            const now = Date.now();
+            const oneYearAgo = now - (365 * 24 * 60 * 60 * 1000);
+            const tenYearsFromNow = now + (10 * 365 * 24 * 60 * 60 * 1000);
+            if (nativeDate.getTime() > oneYearAgo && nativeDate.getTime() < tenYearsFromNow) {
+                return nativeDate.getTime();
+            }
+        }
+        // Try some common variations and transformations
+        const variations = [
+            dateString.replace(/\s+at\s+/i, ' '), // "Saturday at 3pm" -> "Saturday 3pm"
+            dateString.replace(/\s+EST|EDT|PST|PDT|CST|CDT|MST|MDT/i, ''), // Remove timezone
+            dateString.replace(/next\s+/i, ''), // "next Friday" -> "Friday"
+            dateString.replace(/this\s+/i, ''), // "this Friday" -> "Friday"
+        ];
+        for (const variation of variations) {
+            const varDate = new Date(variation);
+            if (!isNaN(varDate.getTime())) {
+                const now = Date.now();
+                const oneYearAgo = now - (365 * 24 * 60 * 60 * 1000);
+                const tenYearsFromNow = now + (10 * 365 * 24 * 60 * 60 * 1000);
+                if (varDate.getTime() > oneYearAgo && varDate.getTime() < tenYearsFromNow) {
+                    // If the parsed date is in the past, assume they meant next occurrence
+                    if (varDate.getTime() < now) {
+                        // Add 7 days if it's a day of the week
+                        if (dateString.match(/monday|tuesday|wednesday|thursday|friday|saturday|sunday/i)) {
+                            varDate.setDate(varDate.getDate() + 7);
+                        }
+                    }
+                    return varDate.getTime();
+                }
+            }
         }
         // If all parsing fails, return undefined
         return undefined;

package/package.json

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