@taazkareem/clickup-mcp-server 0.4.74 → 0.5.0

package/build/tools/task/handlers.js

@@ -38,9 +38,9 @@ function buildUpdateData(params) {
 /**
  * Process a task identification validation, returning the task ID
  */
-async function getTaskId(taskId, taskName, listName) {
-    validateTaskIdentification(taskId, taskName, listName);
-    return await resolveTaskIdWithValidation(taskId, taskName, listName);
+async function getTaskId(taskId, taskName, listName, customTaskId) {
+    validateTaskIdentification(taskId, taskName, listName, customTaskId);
+    return await resolveTaskIdWithValidation(taskId, taskName, listName, customTaskId);
 }
 /**
  * Process a list identification validation, returning the list ID
@@ -72,8 +72,8 @@ function buildTaskFilters(params) {
  */
 async function mapTaskIds(tasks) {
     return Promise.all(tasks.map(async (task) => {
-        validateTaskIdentification(task.taskId, task.taskName, task.listName);
-        return await resolveTaskIdWithValidation(task.taskId, task.taskName, task.listName);
+        validateTaskIdentification(task.taskId, task.taskName, task.listName, task.customTaskId);
+        return await resolveTaskIdWithValidation(task.taskId, task.taskName, task.listName, task.customTaskId);
     }));
 }
 //=============================================================================
@@ -129,7 +129,8 @@ export async function duplicateTaskHandler(params) {
  * Handler for getting a task
  */
 export async function getTaskHandler(params) {
-    const taskId = await getTaskId(params.taskId, params.taskName, params.listName);
+    // resolveTaskIdWithValidation now auto-detects whether taskId is a regular ID or custom ID
+    const taskId = await getTaskId(params.taskId, params.taskName, params.listName, params.customTaskId);
     return await taskService.getTask(taskId);
 }
 /**
@@ -155,6 +156,36 @@ export async function getTaskCommentsHandler(params) {
     const { start, startId } = params;
     return await taskService.getTaskComments(taskId, start, startId);
 }
+/**
+ * Handler for creating a task comment
+ */
+export async function createTaskCommentHandler(params) {
+    // Validate required parameters
+    if (!params.commentText) {
+        throw new Error('Comment text is required');
+    }
+    try {
+        // Resolve the task ID
+        const taskId = await getTaskId(params.taskId, params.taskName, params.listName);
+        // Extract other parameters with defaults
+        const { commentText, notifyAll = false, assignee = null } = params;
+        // Create the comment
+        return await taskService.createTaskComment(taskId, commentText, notifyAll, assignee);
+    }
+    catch (error) {
+        // If this is a task lookup error, provide more helpful message
+        if (error.message?.includes('not found') || error.message?.includes('identify task')) {
+            if (params.taskName) {
+                throw new Error(`Could not find task "${params.taskName}" in list "${params.listName}"`);
+            }
+            else {
+                throw new Error(`Task with ID "${params.taskId}" not found`);
+            }
+        }
+        // Otherwise, rethrow the original error
+        throw error;
+    }
+}
 //=============================================================================
 // BULK TASK OPERATIONS
 //=============================================================================

package/build/tools/task/index.js

@@ -6,13 +6,15 @@
 // Re-export from main module
 export * from './main.js';
 // Re-export single task operation tools
-export { createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, getTaskCommentsTool } from './single-operations.js';
+export { createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, getTaskCommentsTool, createTaskCommentTool } from './single-operations.js';
 // Re-export bulk task operation tools
 export { createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool } from './bulk-operations.js';
+// Re-export attachment tool
+export { attachTaskFileTool, handleAttachTaskFile } from './attachments.js';
 // Re-export handlers
 export { 
 // Single task operation handlers
-createTaskHandler, getTaskHandler, getTasksHandler, updateTaskHandler, moveTaskHandler, duplicateTaskHandler, deleteTaskHandler, getTaskCommentsHandler, 
+createTaskHandler, getTaskHandler, getTasksHandler, updateTaskHandler, moveTaskHandler, duplicateTaskHandler, deleteTaskHandler, getTaskCommentsHandler, createTaskCommentHandler, 
 // Bulk task operation handlers
 createBulkTasksHandler, updateBulkTasksHandler, moveBulkTasksHandler, deleteBulkTasksHandler } from './handlers.js';
 // Re-export utilities

package/build/tools/task/main.js

@@ -6,10 +6,10 @@
  */
 import { sponsorService } from '../../utils/sponsor-service.js';
 // Import tool definitions
-import { createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, getTaskCommentsTool } from './single-operations.js';
+import { createTaskTool, getTaskTool, getTasksTool, updateTaskTool, moveTaskTool, duplicateTaskTool, deleteTaskTool, getTaskCommentsTool, createTaskCommentTool } from './single-operations.js';
 import { createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool } from './bulk-operations.js';
 // Import handlers
-import { createTaskHandler, getTaskHandler, getTasksHandler, updateTaskHandler, moveTaskHandler, duplicateTaskHandler, deleteTaskHandler, getTaskCommentsHandler, createBulkTasksHandler, updateBulkTasksHandler, moveBulkTasksHandler, deleteBulkTasksHandler } from './handlers.js';
+import { createTaskHandler, getTaskHandler, getTasksHandler, updateTaskHandler, moveTaskHandler, duplicateTaskHandler, deleteTaskHandler, getTaskCommentsHandler, createTaskCommentHandler, createBulkTasksHandler, updateBulkTasksHandler, moveBulkTasksHandler, deleteBulkTasksHandler } from './handlers.js';
 //=============================================================================
 // HANDLER WRAPPER UTILITY
 //=============================================================================
@@ -47,6 +47,14 @@ export const handleGetTaskComments = createHandlerWrapper(getTaskCommentsHandler
     comments,
     count: comments.length
 }));
+export const handleCreateTaskComment = createHandlerWrapper(createTaskCommentHandler, (comment) => ({
+    success: true,
+    message: "Comment added successfully",
+    comment: comment && typeof comment === 'object' ? comment : {
+        id: `generated-${Date.now()}`,
+        comment_text: typeof comment === 'string' ? comment : "Comment text unavailable"
+    }
+}));
 //=============================================================================
 // BULK TASK OPERATIONS - HANDLER IMPLEMENTATIONS
 //=============================================================================
@@ -81,6 +89,7 @@ export const taskTools = [
     { definition: duplicateTaskTool, handler: handleDuplicateTask },
     { definition: deleteTaskTool, handler: handleDeleteTask },
     { definition: getTaskCommentsTool, handler: handleGetTaskComments },
+    { definition: createTaskCommentTool, handler: handleCreateTaskComment },
     // Bulk task operations
     { definition: createBulkTasksTool, handler: handleCreateBulkTasks },
     { definition: updateBulkTasksTool, handler: handleUpdateBulkTasks },

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

@@ -119,7 +119,7 @@ Notes:
         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."
+                description: "ID of the task to update (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
             },
             taskName: {
                 type: "string",
@@ -181,7 +181,7 @@ Warning:
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of the task to move (preferred). Use this instead of taskName if you have it."
+                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')."
             },
             taskName: {
                 type: "string",
@@ -228,7 +228,7 @@ Warning:
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to duplicate (preferred). Use this instead of taskName if you have it."
+                description: "ID of task to duplicate (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
             },
             taskName: {
                 type: "string",
@@ -258,20 +258,24 @@ export const getTaskTool = {
     description: `Purpose: Retrieve detailed information about a specific task.
 
 Valid Usage:
-1. Use taskId alone (preferred)
+1. Use taskId alone (preferred) - works with both regular and custom IDs (like "DEV-1234")
 2. Use taskName + listName
+3. Use customTaskId for explicit custom ID lookup
 
 Requirements:
 - When using taskName, listName is REQUIRED
+- When using customTaskId, listName is recommended for faster lookup
 
 Note:
-- Task names are only unique within a list, so the system needs to know which list to search in`,
+- Task names are only unique within a list, so the system needs to know which list to search in
+- Regular task IDs are always 9 characters long (e.g., "86b394eqa")
+- Custom IDs have an uppercase prefix followed by a hyphen and number (e.g., "DEV-1234")`,
     inputSchema: {
         type: "object",
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to retrieve (preferred). Use this instead of taskName if you have it."
+                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."
             },
             taskName: {
                 type: "string",
@@ -280,6 +284,10 @@ Note:
             listName: {
                 type: "string",
                 description: "Name of list containing the task. REQUIRED when using taskName."
+            },
+            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."
             }
         },
         required: []
@@ -365,7 +373,7 @@ Warning:
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to delete (preferred). Use this instead of taskName for safety."
+                description: "ID of task to delete (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
             },
             taskName: {
                 type: "string",
@@ -398,7 +406,7 @@ Notes:
         properties: {
             taskId: {
                 type: "string",
-                description: "ID of task to retrieve comments for (preferred). Use this instead of taskName if you have it."
+                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')."
             },
             taskName: {
                 type: "string",
@@ -419,3 +427,53 @@ Notes:
         }
     }
 };
+/**
+ * Tool definition for creating a comment on a task
+ */
+export const createTaskCommentTool = {
+    name: "create_task_comment",
+    description: `Purpose: Create a comment on a ClickUp task.
+
+Valid Usage:
+1. Use taskId (preferred)
+2. Use taskName + listName
+
+Requirements:
+- EITHER taskId OR (taskName + listName) is REQUIRED
+- commentText is REQUIRED
+
+Notes:
+- When using taskName, providing listName helps locate the correct task
+- Set notifyAll to true to send notifications to all task assignees
+- Use assignee to assign the comment to a specific user (optional)`,
+    inputSchema: {
+        type: "object",
+        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')."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of task to comment on. When using this parameter, you MUST also provide listName."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list containing the task. REQUIRED when using taskName."
+            },
+            commentText: {
+                type: "string",
+                description: "REQUIRED: Text content of the comment to create."
+            },
+            notifyAll: {
+                type: "boolean",
+                description: "Whether to notify all assignees. Default is false."
+            },
+            assignee: {
+                type: "number",
+                description: "Optional user ID to assign the comment to."
+            }
+        },
+        required: ["commentText"]
+    }
+};

package/build/tools/task/utilities.js

@@ -32,14 +32,14 @@ export function formatTaskData(task, additional = {}) {
 //=============================================================================
 /**
  * Validates task identification parameters
- * Ensures either taskId is provided or both taskName and listName are provided
+ * Ensures either taskId, customTaskId, 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");
+export function validateTaskIdentification(taskId, taskName, listName, customTaskId) {
+    if (!taskId && !taskName && !customTaskId) {
+        throw new Error("Either taskId, customTaskId, or taskName must be provided");
     }
-    if (!taskId && taskName && !listName) {
-        throw new Error("When using taskName, listName is required to locate the task");
+    if (!taskId && !customTaskId && taskName && !listName) {
+        throw new Error("listName is required when using taskName");
     }
 }
 /**
@@ -84,18 +84,79 @@ export function parseBulkOptions(rawOptions) {
     return rawOptions;
 }
 //=============================================================================
+// ID DETECTION UTILITIES
+//=============================================================================
+/**
+ * Determines if an ID is a custom ID based on its format
+ * Custom IDs typically have an uppercase prefix followed by a hyphen and number (e.g., DEV-1234)
+ * Regular task IDs are always 9 characters long
+ *
+ * @param id The task ID to check
+ * @returns True if the ID appears to be a custom ID
+ */
+export function isCustomTaskId(id) {
+    if (!id)
+        return false;
+    // Regular task IDs are exactly 9 characters
+    if (id.length === 9) {
+        return false;
+    }
+    // Custom IDs have an uppercase prefix followed by a hyphen and numbers
+    const customIdPattern = /^[A-Z]+-\d+$/;
+    return customIdPattern.test(id);
+}
+//=============================================================================
 // ID RESOLUTION UTILITIES
 //=============================================================================
 /**
- * Resolves a task ID from either direct ID or name+list combination
+ * Resolves a task ID from direct ID, custom ID, or name
  * Handles validation and throws appropriate errors
  */
-export async function resolveTaskIdWithValidation(taskId, taskName, listName) {
+export async function resolveTaskIdWithValidation(taskId, taskName, listName, customTaskId) {
     // Validate parameters
-    validateTaskIdentification(taskId, taskName, listName);
-    // If taskId is provided, use it directly
-    if (taskId)
+    validateTaskIdentification(taskId, taskName, listName, customTaskId);
+    // If customTaskId is explicitly provided, use it
+    if (customTaskId) {
+        const { task: taskService } = clickUpServices;
+        try {
+            // First try to get the task by custom ID
+            // If listName is provided, we can also look up in a specific list for better performance
+            let listId;
+            if (listName) {
+                listId = await resolveListIdWithValidation(undefined, listName);
+            }
+            // Look up by custom ID
+            const foundTask = await taskService.getTaskByCustomId(customTaskId, listId);
+            return foundTask.id;
+        }
+        catch (error) {
+            throw new Error(`Task with custom ID "${customTaskId}" not found`);
+        }
+    }
+    // If taskId is provided, check if it looks like a custom ID
+    if (taskId) {
+        if (isCustomTaskId(taskId)) {
+            console.log(`Detected task ID "${taskId}" as a custom ID, using custom ID lookup`);
+            // If it looks like a custom ID, try to get it as a custom ID first
+            const { task: taskService } = clickUpServices;
+            try {
+                // Look up by custom ID
+                let listId;
+                if (listName) {
+                    listId = await resolveListIdWithValidation(undefined, listName);
+                }
+                const foundTask = await taskService.getTaskByCustomId(taskId, listId);
+                return foundTask.id;
+            }
+            catch (error) {
+                // If it fails as a custom ID, try as a regular ID
+                console.log(`Failed to find task with custom ID "${taskId}", falling back to regular ID`);
+                return taskId;
+            }
+        }
+        // Regular task ID
         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);

package/build/utils/sponsor-service.js

@@ -30,16 +30,35 @@ export class SponsorService {
      */
     createResponse(data, includeSponsorMessage = false) {
         const content = [];
+        // Special handling for workspace hierarchy which contains a preformatted tree
+        if (data && typeof data === 'object' && 'hierarchy' in data && typeof data.hierarchy === 'string') {
+            // Handle workspace hierarchy specially - it contains a preformatted tree
+            content.push({
+                type: "text",
+                text: data.hierarchy
+            });
+        }
+        else if (typeof data === 'string') {
+            // If it's already a string, use it directly
+            content.push({
+                type: "text",
+                text: data
+            });
+        }
+        else {
+            // Otherwise, stringify the JSON object
+            content.push({
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            });
+        }
+        // Then add sponsorship message if enabled
         if (this.isEnabled && includeSponsorMessage) {
             content.push({
                 type: "text",
-                text: `❤️ Support this project by sponsoring the developer at ${this.sponsorUrl}\n\n`
+                text: `\n\n❤️ Support this project by sponsoring the developer at ${this.sponsorUrl}`
             });
         }
-        content.push({
-            type: "text",
-            text: JSON.stringify(data, null, 2)
-        });
         return { content };
     }
     /**

package/package.json

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

package/build/mcp-tools.js

@@ -1,64 +0,0 @@
-import { Logger } from "./logger.js";
-// Create a logger instance
-const logger = new Logger('MCPTools');
-/**
- * Register a handler for a tool that may receive JSON string parameters
- * This wrapper ensures that array and object parameters are properly parsed
- *
- * @param server MCP Server instance
- * @param name Tool name
- * @param handler Handler function
- */
-export function registerToolHandler(server, name, handler) {
-    // Create a wrapper handler that pre-processes parameters
-    const wrappedHandler = async (params) => {
-        logger.debug(`Processing parameters for tool ${name}`, { params });
-        try {
-            // Process the parameters before passing them to the actual handler
-            const processedParams = {};
-            // Process each parameter - try to parse strings that might be JSON
-            for (const [key, value] of Object.entries(params)) {
-                if (typeof value === 'string') {
-                    try {
-                        // Check if this might be a JSON array or object
-                        if ((value.startsWith('[') && value.endsWith(']')) ||
-                            (value.startsWith('{') && value.endsWith('}'))) {
-                            try {
-                                processedParams[key] = JSON.parse(value);
-                                logger.debug(`Parsed JSON parameter: ${key}`, { original: value, parsed: processedParams[key] });
-                            }
-                            catch (parseError) {
-                                // If parsing fails, use the original string
-                                processedParams[key] = value;
-                                logger.debug(`Failed to parse JSON for parameter: ${key}, using original`, { error: parseError.message });
-                            }
-                        }
-                        else {
-                            processedParams[key] = value;
-                        }
-                    }
-                    catch (error) {
-                        // If there's any error, use the original value
-                        processedParams[key] = value;
-                        logger.debug(`Error processing parameter: ${key}`, { error: error.message });
-                    }
-                }
-                else {
-                    // Non-string values are used as-is
-                    processedParams[key] = value;
-                }
-            }
-            logger.debug(`Processed parameters for tool ${name}`, { processedParams });
-            // Call the original handler with processed parameters
-            return handler(processedParams);
-        }
-        catch (error) {
-            logger.error(`Error in wrapped handler for tool ${name}:`, { error: error.stack || error.message });
-            throw error;
-        }
-    };
-    // Use setRequestHandler to register the wrapped handler
-    logger.info(`Registering wrapped handler for tool: ${name}`);
-    // Override the tool's handler in the CallTool switch statement
-    // The server.ts file will use the switch case to call this handler
-}

package/build/server-state.js

@@ -1,93 +0,0 @@
-/**
- * Server State Management Module
- *
- * This module provides shared state management for the MCP server,
- * particularly for controlling shutdown behavior and tracking busy states.
- */
-// State variables
-let serverBusyState = false; // Tracks if server is doing critical work
-let gracePeriodActive = false; // Tracks if we're in post-initialization grace period
-let gracePeriodTimer = null;
-export const GRACE_PERIOD_MS = 10000; // 10 second grace period after startup
-/**
- * Logging helper that avoids circular dependency
- */
-function safeLog(level, message, data) {
-    // Use console as a fallback to avoid circular dependency with logger
-    const timestamp = new Date().toISOString();
-    if (level === 'error') {
-        console.error(`[${timestamp}] ${level.toUpperCase()}: ${message}`, data || '');
-    }
-    else if (level === 'debug' && process.env.DEBUG) {
-        console.debug(`[${timestamp}] ${level.toUpperCase()}: ${message}`, data || '');
-    }
-    else if (level !== 'debug') {
-        console.log(`[${timestamp}] ${level.toUpperCase()}: ${message}`, data || '');
-    }
-}
-/**
- * Set the server as busy doing critical work that shouldn't be interrupted
- * @param busy Whether the server is currently busy with critical operations
- */
-export function setServerBusy(busy) {
-    serverBusyState = busy;
-    safeLog('debug', `Server busy state set to: ${busy}`);
-}
-/**
- * Start grace period after initialization to prevent immediate shutdown
- */
-export function startGracePeriod() {
-    gracePeriodActive = true;
-    safeLog('debug', `Starting ${GRACE_PERIOD_MS}ms grace period to prevent premature shutdown`);
-    if (gracePeriodTimer) {
-        clearTimeout(gracePeriodTimer);
-    }
-    gracePeriodTimer = setTimeout(() => {
-        gracePeriodActive = false;
-        safeLog('debug', 'Grace period ended, server will now respond to shutdown signals');
-        gracePeriodTimer = null;
-    }, GRACE_PERIOD_MS);
-}
-/**
- * Cancel the grace period if needed
- */
-export function cancelGracePeriod() {
-    if (gracePeriodTimer) {
-        clearTimeout(gracePeriodTimer);
-        gracePeriodTimer = null;
-    }
-    gracePeriodActive = false;
-    safeLog('debug', 'Grace period canceled, server will now respond to shutdown signals');
-}
-/**
- * Check if the server should ignore shutdown signals
- * @returns true if shutdown signals should be ignored
- */
-export function shouldIgnoreShutdown() {
-    // Ignore shutdown if explicitly configured via environment variable
-    if (process.env.FORCE_KEEP_ALIVE === 'true') {
-        return true;
-    }
-    // Ignore shutdown during the grace period after startup
-    if (gracePeriodActive) {
-        return true;
-    }
-    // Ignore shutdown if the server is doing critical work
-    if (serverBusyState) {
-        return true;
-    }
-    // Otherwise, allow normal shutdown
-    return false;
-}
-/**
- * Check if grace period is currently active
- */
-export function isGracePeriodActive() {
-    return gracePeriodActive;
-}
-/**
- * Check if server is currently in busy state
- */
-export function isServerBusy() {
-    return serverBusyState;
-}