@taazkareem/clickup-mcp-server 0.8.4 → 0.9.0

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

@@ -7,12 +7,20 @@
  * Handles tag operations for ClickUp tasks, including:
  * - Adding tags to a task
  * - Removing tags from a task
+ *
+ * REFACTORED: Now uses composition instead of inheritance.
+ * Only depends on TaskServiceCore for getTask() and base functionality.
  */
-import { TaskServiceComments } from './task-comments.js';
 /**
  * Tags functionality for the TaskService
+ *
+ * This service handles all tag-related operations for ClickUp tasks.
+ * It uses composition to access core functionality instead of inheritance.
  */
-export class TaskServiceTags extends TaskServiceComments {
+export class TaskServiceTags {
+    constructor(core) {
+        this.core = core;
+    }
     /**
      * Add a tag to a task
      *
@@ -21,16 +29,18 @@ export class TaskServiceTags extends TaskServiceComments {
      * @returns Success response
      */
     async addTagToTask(taskId, tagName) {
-        this.logOperation('addTagToTask', { taskId, tagName });
+        this.core.logOperation('addTagToTask', { taskId, tagName });
         try {
             const payload = {
                 tag_name: tagName,
             };
-            await this.client.post(`/task/${taskId}/tag/${encodeURIComponent(tagName)}`, payload);
+            await this.core.makeRequest(async () => {
+                return await this.core.client.post(`/task/${taskId}/tag/${encodeURIComponent(tagName)}`, payload);
+            });
             return true;
         }
         catch (error) {
-            throw this.handleError(error, `Failed to add tag "${tagName}" to task`);
+            throw this.core.handleError(error, `Failed to add tag "${tagName}" to task`);
         }
     }
     /**
@@ -41,13 +51,15 @@ export class TaskServiceTags extends TaskServiceComments {
      * @returns Success response
      */
     async removeTagFromTask(taskId, tagName) {
-        this.logOperation('removeTagFromTask', { taskId, tagName });
+        this.core.logOperation('removeTagFromTask', { taskId, tagName });
         try {
-            await this.client.delete(`/task/${taskId}/tag/${encodeURIComponent(tagName)}`);
+            await this.core.makeRequest(async () => {
+                return await this.core.client.delete(`/task/${taskId}/tag/${encodeURIComponent(tagName)}`);
+            });
             return true;
         }
         catch (error) {
-            throw this.handleError(error, `Failed to remove tag "${tagName}" from task`);
+            throw this.core.handleError(error, `Failed to remove tag "${tagName}" from task`);
         }
     }
     /**
@@ -57,14 +69,14 @@ export class TaskServiceTags extends TaskServiceComments {
      * @returns Array of task tags
      */
     async getTaskTags(taskId) {
-        this.logOperation('getTaskTags', { taskId });
+        this.core.logOperation('getTaskTags', { taskId });
         try {
             // We need to fetch the full task to get its tags
-            const task = await this.getTask(taskId);
+            const task = await this.core.getTask(taskId);
             return task.tags || [];
         }
         catch (error) {
-            throw this.handleError(error, 'Failed to get task tags');
+            throw this.core.handleError(error, 'Failed to get task tags');
         }
     }
     /**
@@ -75,7 +87,7 @@ export class TaskServiceTags extends TaskServiceComments {
      * @returns Success response
      */
     async updateTaskTags(taskId, tagNames) {
-        this.logOperation('updateTaskTags', { taskId, tagNames });
+        this.core.logOperation('updateTaskTags', { taskId, tagNames });
         try {
             // First get existing tags
             const existingTags = await this.getTaskTags(taskId);
@@ -95,7 +107,7 @@ export class TaskServiceTags extends TaskServiceComments {
             return true;
         }
         catch (error) {
-            throw this.handleError(error, 'Failed to update task tags');
+            throw this.core.handleError(error, 'Failed to update task tags');
         }
     }
 }

package/build/sse_server.js

@@ -244,11 +244,11 @@ export function startSSEServer() {
         }
         catch (error) {
             logger.error('Failed to start HTTPS server', {
-                error: error.message,
-                sslKeyPath: configuration.sslKeyPath,
-                sslCertPath: configuration.sslCertPath
+                error: 'An error occurred while starting HTTPS server.',
+                sslKeyPath: 'REDACTED',
+                sslCertPath: 'REDACTED'
             });
-            console.log(`❌ Failed to start HTTPS server: ${error.message}`);
+            console.log(`❌ Failed to start HTTPS server. Please check the server configuration and logs for details.`);
             return null;
         }
     }

package/build/tools/documents.js

@@ -19,7 +19,14 @@ const { document: documentService } = clickUpServices;
  */
 export const createDocumentTool = {
     name: "create_document",
-    description: `Creates a document in a ClickUp space, folder, or list. Requires name, parent info, visibility and create_page flag.`,
+    description: `Creates a document in a ClickUp space, folder, or list. Requires name, parent info, visibility and create_page flag.
+
+Example usage:
+- For list: parent: {"id": "901407953112", "type": 6}
+- For space: parent: {"id": "90141392755", "type": 4}
+- For folder: parent: {"id": "90144231850", "type": 5}
+
+Note: Document creation permissions may vary by ClickUp plan and parent container type.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -32,16 +39,16 @@ export const createDocumentTool = {
                 properties: {
                     id: {
                         type: "string",
-                        description: "ID of the parent container (space, folder, or list)"
+                        description: "ID of the parent container (space, folder, or list). Use actual ID from workspace hierarchy."
                     },
                     type: {
                         type: "number",
                         enum: [4, 5, 6, 7, 12],
-                        description: "Type of the parent container (4=space, 5=folder, 6=list, 7=everything, 12=workspace)"
+                        description: "Type of the parent container: 4=space, 5=folder, 6=list, 7=everything, 12=workspace. Most commonly use 6 for lists."
                     }
                 },
                 required: ["id", "type"],
-                description: "Parent container information"
+                description: "Parent container object with id and type properties. Example: {\"id\": \"901407953112\", \"type\": 6}"
             },
             visibility: {
                 type: "string",

package/build/tools/health.js

@@ -0,0 +1,23 @@
+/**
+ * Simple health‑check tool – returns a tiny JSON payload confirming the server is alive.
+ */
+export const healthCheckTool = {
+    name: "health_check",
+    description: "Returns a simple health status for the MCP server.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            status: { type: "string" },
+        },
+        required: ["status"],
+    },
+};
+/** Handler invoked by CallTool when the client requests "health_check" */
+export async function handleHealthCheck() {
+    return { status: "ok" };
+}

package/build/tools/member.js

@@ -97,12 +97,10 @@ export async function handleResolveAssignees(parameters) {
                 m.name?.toLowerCase() === input.toLowerCase());
             return found ? found.id : null;
         });
-        // Return a plain object, not wrapped in sponsorService.createResponse
-        return { userIds: resolved };
+        return sponsorService.createResponse({ userIds: resolved }, true);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        // Return a plain error object
-        return { error: `Failed to resolve assignees: ${errorMessage}` };
+        return sponsorService.createErrorResponse(`Failed to resolve assignees: ${errorMessage}`);
     }
 }

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

@@ -50,7 +50,7 @@ const bulkOptionsSchema = {
 const taskIdentifierSchema = {
     taskId: {
         type: "string",
-        description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+        description: "Task ID (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
     },
     taskName: {
         type: "string",
@@ -62,7 +62,7 @@ const taskIdentifierSchema = {
     },
     customTaskId: {
         type: "string",
-        description: "Custom task ID (e.g., 'DEV-1234'). Only use if you want to explicitly force custom ID lookup. In most cases, use taskId which auto-detects ID format."
+        description: "Custom task ID (e.g., 'DEV-1234'). This parameter is now optional since taskId automatically handles custom IDs. Use only for explicit custom ID lookup or backward compatibility."
     }
 };
 //=============================================================================
@@ -175,7 +175,7 @@ export const updateBulkTasksTool = {
                     properties: {
                         taskId: {
                             type: "string",
-                            description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                            description: "Task ID (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
                         },
                         taskName: {
                             type: "string",
@@ -267,7 +267,7 @@ export const moveBulkTasksTool = {
                     properties: {
                         taskId: {
                             type: "string",
-                            description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                            description: "Task ID (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
                         },
                         taskName: {
                             type: "string",
@@ -314,7 +314,7 @@ export const deleteBulkTasksTool = {
                     properties: {
                         taskId: {
                             type: "string",
-                            description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                            description: "Task ID (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
                         },
                         taskName: {
                             type: "string",

package/build/tools/task/handlers.js

@@ -110,10 +110,15 @@ async function resolveAssignees(assignees) {
     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);
+            // The result is wrapped by sponsorService.createResponse, so we need to parse the JSON
+            if (result.content && Array.isArray(result.content) && result.content.length > 0) {
+                const dataText = result.content[0].text;
+                const parsedData = JSON.parse(dataText);
+                if (parsedData.userIds && Array.isArray(parsedData.userIds)) {
+                    for (const userId of parsedData.userIds) {
+                        if (userId !== null && typeof userId === 'number') {
+                            resolved.push(userId);
+                        }
                     }
                 }
             }
@@ -143,12 +148,28 @@ async function buildUpdateData(params) {
         updateData.priority = toTaskPriority(params.priority);
     }
     if (params.dueDate !== undefined) {
-        updateData.due_date = parseDueDate(params.dueDate);
-        updateData.due_date_time = true;
+        const parsedDueDate = parseDueDate(params.dueDate);
+        if (parsedDueDate !== undefined) {
+            updateData.due_date = parsedDueDate;
+            updateData.due_date_time = true;
+        }
+        else {
+            // Clear the due date by setting it to null
+            updateData.due_date = null;
+            updateData.due_date_time = false;
+        }
     }
     if (params.startDate !== undefined) {
-        updateData.start_date = parseDueDate(params.startDate);
-        updateData.start_date_time = true;
+        const parsedStartDate = parseDueDate(params.startDate);
+        if (parsedStartDate !== undefined) {
+            updateData.start_date = parsedStartDate;
+            updateData.start_date_time = true;
+        }
+        else {
+            // Clear the start date by setting it to null
+            updateData.start_date = null;
+            updateData.start_date_time = false;
+        }
     }
     // Handle time estimate if provided - convert from string to minutes
     if (params.time_estimate !== undefined) {
@@ -165,7 +186,21 @@ async function buildUpdateData(params) {
     }
     // Handle assignees if provided - resolve emails/usernames to user IDs
     if (params.assignees !== undefined) {
-        updateData.assignees = await resolveAssignees(params.assignees);
+        // Parse assignees if it's a string (from MCP serialization)
+        let assigneesArray = params.assignees;
+        if (typeof params.assignees === 'string') {
+            try {
+                assigneesArray = JSON.parse(params.assignees);
+            }
+            catch (error) {
+                console.warn('Failed to parse assignees string:', params.assignees, error);
+                assigneesArray = [];
+            }
+        }
+        const resolvedAssignees = await resolveAssignees(assigneesArray);
+        // Store the resolved assignees for processing in the updateTask method
+        // The actual add/rem logic will be handled there based on current vs new assignees
+        updateData.assignees = resolvedAssignees;
     }
     return updateData;
 }
@@ -181,7 +216,7 @@ async function findTask(params) {
         throw new Error(validationResult.errorMessage);
     }
     try {
-        // Direct path for taskId - most efficient
+        // Direct path for taskId - most efficient (now includes automatic custom ID detection)
         if (taskId) {
             const task = await taskService.getTask(taskId);
             // Add subtasks if requested
@@ -191,7 +226,8 @@ async function findTask(params) {
             }
             return { task };
         }
-        // Direct path for customTaskId - also efficient
+        // Direct path for customTaskId - for explicit custom ID requests
+        // Note: This is now mainly for backward compatibility since getTask() handles custom IDs automatically
         if (customTaskId) {
             const task = await taskService.getTaskByCustomId(customTaskId);
             // Add subtasks if requested
@@ -429,7 +465,21 @@ export async function createTaskHandler(params) {
     const priority = toTaskPriority(params.priority);
     const listId = await getListId(params.listId, params.listName);
     // Resolve assignees if provided
-    const resolvedAssignees = assignees ? await resolveAssignees(assignees) : undefined;
+    let resolvedAssignees = undefined;
+    if (assignees) {
+        // Parse assignees if it's a string (from MCP serialization)
+        let assigneesArray = assignees;
+        if (typeof assignees === 'string') {
+            try {
+                assigneesArray = JSON.parse(assignees);
+            }
+            catch (error) {
+                console.warn('Failed to parse assignees string in createTask:', assignees, error);
+                assigneesArray = [];
+            }
+        }
+        resolvedAssignees = await resolveAssignees(assigneesArray);
+    }
     const taskData = {
         name,
         description,

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

@@ -144,7 +144,7 @@ export const updateTaskTool = {
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of 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). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
             },
             taskName: {
                 type: "string",
@@ -229,7 +229,7 @@ export const moveTaskTool = {
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of the task to move (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                description: "ID of the task to move (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
             },
             taskName: {
                 type: "string",
@@ -262,7 +262,7 @@ export const duplicateTaskTool = {
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to duplicate (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                description: "ID of task to duplicate (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
             },
             taskName: {
                 type: "string",
@@ -289,13 +289,13 @@ export const duplicateTaskTool = {
  */
 export const getTaskTool = {
     name: "get_task",
-    description: `Gets task details by taskId (works with regular/custom IDs) or taskName. For taskName search, provide listName for faster lookup. Set subtasks=true to include all subtask details.`,
+    description: `Gets task details by taskId (automatically handles both regular and custom IDs) or taskName. For taskName search, provide listName for faster lookup. Set subtasks=true to include all subtask details.`,
     inputSchema: {
         type: "object",
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to retrieve (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234'). The system automatically detects the ID format."
+                description: "ID of task to retrieve (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456'). Simply provide any task ID format here."
             },
             taskName: {
                 type: "string",
@@ -307,7 +307,7 @@ export const getTaskTool = {
             },
             customTaskId: {
                 type: "string",
-                description: "Custom task ID (e.g., 'DEV-1234'). Only use this if you want to explicitly force custom ID lookup. In most cases, you can just use taskId which auto-detects ID format."
+                description: "Custom task ID (e.g., 'DEV-1234'). This parameter is now optional since taskId automatically handles custom IDs. Use only for explicit custom ID lookup or backward compatibility."
             },
             subtasks: {
                 type: "boolean",
@@ -385,7 +385,7 @@ export const getTaskCommentsTool = {
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to retrieve comments for (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                description: "ID of task to retrieve comments for (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
             },
             taskName: {
                 type: "string",
@@ -417,7 +417,7 @@ export const createTaskCommentTool = {
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to comment on (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                description: "ID of task to comment on (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
             },
             taskName: {
                 type: "string",
@@ -454,7 +454,7 @@ export const deleteTaskTool = {
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to delete (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+                description: "ID of task to delete (preferred). Automatically detects and handles both regular task IDs (9 characters) and custom IDs (like 'DEV-1234', 'PROJ-456')."
             },
             taskName: {
                 type: "string",