@taazkareem/clickup-mcp-server 0.6.4 → 0.6.6

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:** Rolling out v0.6.3 will add Global Task Lookup with smart disambiguation, Start Date Support for tasks with natural language expressions, Complete Tag Support including natural language tag color commands, Subtasks Support, Custom ID Support, and Logging Fixes
+> 🚧 **Status Update:** Rolling out v0.6.5 will add Global Task Lookup with smart disambiguation, Start Date Support for tasks with natural language expressions, Complete Tag Support including natural language tag color commands, Subtasks Support, Custom ID Support, and Logging Fixes
 
 ## Setup
 
@@ -18,7 +18,7 @@ A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI appl
 
 ## Smithery Installation (Quick Start)
 
-[![smithery badge](https://smithery.ai/badge/@TaazKareem/clickup-mcp-server)](https://smithery.ai/server/@TaazKareem/clickup-mcp-server)
+[![smithery badge](https://smithery.ai/badge/@taazkareem/clickup-mcp-server)](https://smithery.ai/server/@TaazKareem/clickup-mcp-server)
 
 The server is hosted on [Smithery](https://smithery.ai/server/@TaazKareem/clickup-mcp-server). There, you can preview the available tools or copy the commands to run on your specific client app. 
 

package/build/config.js

@@ -43,7 +43,7 @@ export const parseLogLevel = (levelStr) => {
         case 'WARN': return LogLevel.WARN;
         case 'ERROR': return LogLevel.ERROR;
         default:
-            console.error(`Invalid LOG_LEVEL: ${levelStr}, defaulting to ERROR`);
+            // Don't use console.error as it interferes with JSON-RPC communication
             return LogLevel.ERROR;
     }
 };
@@ -54,8 +54,7 @@ const configuration = {
     enableSponsorMessage: process.env.ENABLE_SPONSOR_MESSAGE !== 'false',
     logLevel: parseLogLevel(envArgs.logLevel || process.env.LOG_LEVEL)
 };
-// Log the configured log level (but only to console to avoid circular dependency)
-console.debug(`Log level set to: ${LogLevel[configuration.logLevel]}`);
+// Don't log to console as it interferes with JSON-RPC communication
 // Validate only the required variables are present
 const requiredVars = ['clickupApiKey', 'clickupTeamId'];
 const missingEnvVars = requiredVars

package/build/index.js

@@ -23,43 +23,27 @@
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { configureServer, server } from "./server.js";
-import { info, error, warn } from "./logger.js";
-import { exec } from 'child_process';
-import { promisify } from 'util';
-const execAsync = promisify(exec);
-/**
- * Check if another instance of the server is already running
- * @returns Boolean indicating if this is the only instance
- */
-async function checkSingleInstance() {
-    try {
-        const { stdout } = await execAsync(`ps aux | grep "node.*clickup-mcp-server" | grep -v grep | wc -l`);
-        const instanceCount = parseInt(stdout.trim(), 10);
-        // If there's more than one instance (including this one), warn and exit
-        if (instanceCount > 1) {
-            error(`Multiple server instances detected (${instanceCount}). This may cause issues.`);
-            info("Use 'pkill -9 -f clickup-mcp-server' to kill all instances before starting a new one.");
-            return false;
-        }
-        return true;
-    }
-    catch (err) {
-        error("Failed to check for other running instances", err);
-        // Continue execution even if check fails
-        return true;
-    }
-}
+import { info, error } from "./logger.js";
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+// Get directory name for module paths
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Handle uncaught exceptions
+process.on('uncaughtException', (err) => {
+    error("Uncaught Exception", { message: err.message, stack: err.stack });
+    process.exit(1);
+});
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, promise) => {
+    error("Unhandled Rejection", { reason });
+    process.exit(1);
+});
 /**
  * Application entry point that configures and starts the MCP server.
  */
 async function main() {
     try {
         info("Starting ClickUp MCP Server...");
-        // Check if we're the only instance
-        const isSingleInstance = await checkSingleInstance();
-        if (!isSingleInstance) {
-            warn("Continuing startup despite multiple instances detected");
-        }
         // Log essential information about the environment
         info("Server environment", {
             pid: process.pid,
@@ -77,11 +61,11 @@ async function main() {
         info("Server startup complete - ready to handle requests");
     }
     catch (err) {
-        error("Error during server startup", err);
+        error("Error during server startup", { message: err.message, stack: err.stack });
         process.exit(1);
     }
 }
 main().catch((err) => {
-    error("Unhandled server error", err);
+    error("Unhandled server error", { message: err.message, stack: err.stack });
     process.exit(1);
 });

package/build/logger.js

@@ -5,7 +5,7 @@
  * Logger module for MCP Server
  *
  * This module provides logging functionality for the server,
- * writing logs to both the console and a log file in the build folder.
+ * writing logs to only the log file to avoid interfering with JSON-RPC.
  */
 import { createWriteStream } from 'fs';
 import { join, dirname } from 'path';
@@ -18,7 +18,8 @@ const pid = process.pid;
 // Create a write stream for logging - use a fixed filename in the build directory
 const logFileName = 'server.log';
 const logStream = createWriteStream(join(__dirname, logFileName), { flags: 'w' });
-console.error(`Logging to ${join(__dirname, logFileName)}`);
+// Write init message to log file only
+logStream.write(`Logging initialized to ${join(__dirname, logFileName)}\n`);
 // Use the configured log level from config.ts
 const configuredLevel = config.logLevel;
 // Re-export LogLevel enum
@@ -32,7 +33,7 @@ export function isLevelEnabled(level) {
     return level >= configuredLevel;
 }
 /**
- * Log function that writes to both console and file
+ * Log function that writes only to file to avoid interfering with JSON-RPC
  * @param level Log level (trace, debug, info, warn, error)
  * @param message Message to log
  * @param data Optional data to include in log
@@ -74,9 +75,7 @@ export function log(level, message, data) {
             logMessage += '\n' + JSON.stringify(data, null, 2);
         }
     }
-    // When using stdio transport, log to stderr which is captured by host application
-    console.error(logMessage);
-    // Write to file
+    // Write to file only, not to stderr which would interfere with JSON-RPC
     logStream.write(logMessage + '\n');
 }
 /**

package/build/server.js

@@ -5,12 +5,12 @@
  * MCP Server for ClickUp integration
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { workspaceHierarchyTool, handleGetWorkspaceHierarchy } from "./tools/workspace.js";
-import { createTaskTool, updateTaskTool, moveTaskTool, duplicateTaskTool, getTaskTool, getTasksTool, deleteTaskTool, getTaskCommentsTool, createTaskCommentTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, attachTaskFileTool, getWorkspaceTasksTool, handleCreateTask, handleUpdateTask, handleMoveTask, handleDuplicateTask, handleGetTasks, handleDeleteTask, handleGetTaskComments, handleCreateTaskComment, handleCreateBulkTasks, handleUpdateBulkTasks, handleMoveBulkTasks, handleDeleteBulkTasks, handleGetTask, handleAttachTaskFile, handleGetWorkspaceTasks } from "./tools/task/index.js";
+import { createTaskTool, updateTaskTool, moveTaskTool, duplicateTaskTool, getTaskTool, deleteTaskTool, getTaskCommentsTool, createTaskCommentTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, attachTaskFileTool, getWorkspaceTasksTool, handleCreateTask, handleUpdateTask, handleMoveTask, handleDuplicateTask, handleDeleteTask, handleGetTaskComments, handleCreateTaskComment, handleCreateBulkTasks, handleUpdateBulkTasks, handleMoveBulkTasks, handleDeleteBulkTasks, handleGetTask, handleAttachTaskFile, handleGetWorkspaceTasks } from "./tools/task/index.js";
 import { createListTool, handleCreateList, createListInFolderTool, handleCreateListInFolder, getListTool, handleGetList, updateListTool, handleUpdateList, deleteListTool, handleDeleteList } from "./tools/list.js";
 import { createFolderTool, handleCreateFolder, getFolderTool, handleGetFolder, updateFolderTool, handleUpdateFolder, deleteFolderTool, handleDeleteFolder } from "./tools/folder.js";
-import { getSpaceTagsTool, handleGetSpaceTags, createSpaceTagTool, handleCreateSpaceTag, updateSpaceTagTool, handleUpdateSpaceTag, deleteSpaceTagTool, handleDeleteSpaceTag, addTagToTaskTool, handleAddTagToTask, removeTagFromTaskTool, handleRemoveTagFromTask } from "./tools/tag.js";
+import { getSpaceTagsTool, handleGetSpaceTags, addTagToTaskTool, handleAddTagToTask, removeTagFromTaskTool, handleRemoveTagFromTask } from "./tools/tag.js";
 import { Logger } from "./logger.js";
 import { clickUpServices } from "./services/shared.js";
 // Create a logger instance for server
@@ -24,6 +24,7 @@ export const server = new Server({
     capabilities: {
         tools: {},
         prompts: {},
+        resources: {},
     },
 });
 /**
@@ -39,7 +40,6 @@ export function configureServer() {
                 workspaceHierarchyTool,
                 createTaskTool,
                 getTaskTool,
-                getTasksTool,
                 updateTaskTool,
                 moveTaskTool,
                 duplicateTaskTool,
@@ -62,14 +62,16 @@ export function configureServer() {
                 updateFolderTool,
                 deleteFolderTool,
                 getSpaceTagsTool,
-                createSpaceTagTool,
-                updateSpaceTagTool,
-                deleteSpaceTagTool,
                 addTagToTaskTool,
                 removeTagFromTaskTool
             ]
         };
     });
+    // Add handler for resources/list
+    server.setRequestHandler(ListResourcesRequestSchema, async (req) => {
+        logger.debug("Received ListResources request");
+        return { resources: [] };
+    });
     // Register CallTool handler with proper logging
     logger.info("Registering tool handlers", {
         toolCount: 31,
@@ -96,8 +98,6 @@ export function configureServer() {
                     return handleDuplicateTask(params);
                 case "get_task":
                     return handleGetTask(params);
-                case "get_tasks":
-                    return handleGetTasks(params);
                 case "delete_task":
                     return handleDeleteTask(params);
                 case "get_task_comments":
@@ -136,24 +136,39 @@ export function configureServer() {
                     return handleDeleteFolder(params);
                 case "get_space_tags":
                     return handleGetSpaceTags(params);
-                case "create_space_tag":
-                    return handleCreateSpaceTag(params);
-                case "update_space_tag":
-                    return handleUpdateSpaceTag(params);
-                case "delete_space_tag":
-                    return handleDeleteSpaceTag(params);
                 case "add_tag_to_task":
                     return handleAddTagToTask(params);
                 case "remove_tag_from_task":
                     return handleRemoveTagFromTask(params);
                 default:
                     logger.error(`Unknown tool requested: ${name}`);
-                    throw new Error(`Unknown tool: ${name}`);
+                    const error = new Error(`Unknown tool: ${name}`);
+                    error.name = "UnknownToolError";
+                    throw error;
             }
         }
         catch (err) {
             logger.error(`Error executing tool: ${name}`, err);
-            throw err;
+            // Transform error to a more descriptive JSON-RPC error
+            if (err.name === "UnknownToolError") {
+                throw {
+                    code: -32601,
+                    message: `Method not found: ${name}`
+                };
+            }
+            else if (err.name === "ValidationError") {
+                throw {
+                    code: -32602,
+                    message: `Invalid params for tool ${name}: ${err.message}`
+                };
+            }
+            else {
+                // Generic server error
+                throw {
+                    code: -32000,
+                    message: `Error executing tool ${name}: ${err.message}`
+                };
+            }
         }
     });
     server.setRequestHandler(ListPromptsRequestSchema, async () => {

package/build/services/clickup/base.js

@@ -40,6 +40,23 @@ export class ClickUpServiceError extends Error {
         this.context = context;
     }
 }
+/**
+ * Helper function to safely parse JSON
+ * @param data Data to parse
+ * @param fallback Optional fallback value if parsing fails
+ * @returns Parsed JSON or fallback value
+ */
+function safeJsonParse(data, fallback = undefined) {
+    if (typeof data !== 'string') {
+        return data;
+    }
+    try {
+        return JSON.parse(data);
+    }
+    catch (error) {
+        return fallback;
+    }
+}
 /**
  * Base ClickUp service class that handles common functionality
  */
@@ -70,7 +87,20 @@ export class BaseClickUpService {
                 'Authorization': apiKey,
                 'Content-Type': 'application/json'
             },
-            timeout: this.timeout
+            timeout: this.timeout,
+            transformResponse: [
+                // Add custom response transformer to handle both JSON and text responses
+                (data) => {
+                    if (!data)
+                        return data;
+                    // If it's already an object, return as is
+                    if (typeof data !== 'string')
+                        return data;
+                    // Try to parse as JSON, fall back to raw text if parsing fails
+                    const parsed = safeJsonParse(data, null);
+                    return parsed !== null ? parsed : data;
+                }
+            ]
         });
         this.logger.debug(`Initialized ${className}`, { teamId, baseUrl });
         // Add response interceptor for error handling
@@ -93,80 +123,69 @@ export class BaseClickUpService {
             path,
             status,
             method: error.config?.method?.toUpperCase() || 'UNKNOWN',
-            requestData: error.config?.data ? JSON.parse(error.config.data) : undefined
+            requestData: error.config?.data ? safeJsonParse(error.config.data, error.config.data) : undefined
         };
         // Pick the appropriate error code based on status
         let code;
         let logMessage;
+        let errorMessage;
         if (error.code === 'ECONNABORTED' || error.message?.includes('timeout')) {
             code = ErrorCode.NETWORK_ERROR;
             logMessage = `Request timeout for ${path}`;
+            errorMessage = 'Request timed out. Please try again.';
         }
         else if (!error.response) {
             code = ErrorCode.NETWORK_ERROR;
             logMessage = `Network error accessing ${path}: ${error.message}`;
+            errorMessage = 'Network error. Please check your connection and try again.';
         }
         else if (status === 429) {
             code = ErrorCode.RATE_LIMIT;
             this.handleRateLimitHeaders(error.response.headers);
+            // Calculate time until reset
+            const reset = error.response.headers['x-ratelimit-reset'];
+            const now = Date.now() / 1000; // Convert to seconds
+            const timeToReset = Math.max(0, reset - now);
+            const resetMinutes = Math.ceil(timeToReset / 60);
             logMessage = `Rate limit exceeded for ${path}`;
+            errorMessage = `Rate limit exceeded. Please wait ${resetMinutes} minute${resetMinutes === 1 ? '' : 's'} before trying again.`;
+            // Add more context to the error
+            errorContext.rateLimitInfo = {
+                limit: error.response.headers['x-ratelimit-limit'],
+                remaining: error.response.headers['x-ratelimit-remaining'],
+                reset: reset,
+                timeToReset: timeToReset
+            };
         }
         else if (status === 401 || status === 403) {
             code = ErrorCode.UNAUTHORIZED;
             logMessage = `Authorization failed for ${path}`;
+            errorMessage = 'Authorization failed. Please check your API key.';
         }
         else if (status === 404) {
             code = ErrorCode.NOT_FOUND;
             logMessage = `Resource not found: ${path}`;
+            errorMessage = 'Resource not found.';
         }
         else if (status >= 400 && status < 500) {
             code = ErrorCode.VALIDATION;
             logMessage = `Validation error for ${path}: ${errorMsg}`;
+            errorMessage = errorMsg;
         }
         else if (status >= 500) {
             code = ErrorCode.SERVER_ERROR;
             logMessage = `ClickUp server error: ${errorMsg}`;
+            errorMessage = 'ClickUp server error. Please try again later.';
         }
         else {
             code = ErrorCode.UNKNOWN;
             logMessage = `Unknown API error: ${errorMsg}`;
+            errorMessage = 'An unexpected error occurred. Please try again.';
         }
         // Log the error with context
         this.logger.error(logMessage, errorContext);
-        // Throw a well-structured error
-        throw new ClickUpServiceError(errorMsg, code, responseData, status, errorContext);
-    }
-    /**
-     * Process the request queue, respecting rate limits by spacing out requests
-     * @private
-     */
-    async processQueue() {
-        if (this.requestQueue.length === 0) {
-            this.logger.debug('Queue empty, exiting queue processing mode');
-            this.processingQueue = false;
-            return;
-        }
-        this.logger.debug(`Processing request queue (${this.requestQueue.length} items)`);
-        const startTime = Date.now();
-        try {
-            // Take the first request from the queue
-            const request = this.requestQueue.shift();
-            if (request) {
-                // Wait for the request spacing interval
-                await new Promise(resolve => setTimeout(resolve, this.requestSpacing));
-                // Run the request
-                await request();
-            }
-        }
-        catch (error) {
-            this.logger.error('Error executing queued request', error);
-        }
-        finally {
-            const duration = Date.now() - startTime;
-            this.logger.trace(`Queue item processed in ${duration}ms, ${this.requestQueue.length} items remaining`);
-            // Continue processing the queue after a short delay
-            setTimeout(() => this.processQueue(), this.requestSpacing);
-        }
+        // Throw a formatted error with user-friendly message
+        throw new ClickUpServiceError(errorMessage, code, error);
     }
     /**
      * Handle rate limit headers from ClickUp API
@@ -192,14 +211,44 @@ export class BaseClickUpService {
                 const now = Date.now();
                 const resetTime = reset * 1000; // convert to milliseconds
                 const timeToReset = Math.max(0, resetTime - now);
-                if (timeToReset > 0 && remaining > 0) {
-                    // Calculate time between requests to stay under limit
-                    // Add 10% buffer to be safe
-                    const safeSpacing = Math.ceil((timeToReset / remaining) * 1.1);
+                // Proactively adjust spacing when remaining requests get low
+                // This helps avoid hitting rate limits in the first place
+                if (remaining < limit * 0.3) {
+                    // More aggressive spacing when close to limit
+                    let safeSpacing;
+                    if (remaining <= 5) {
+                        // Very aggressive spacing for last few requests
+                        safeSpacing = Math.ceil((timeToReset / remaining) * 2);
+                        // Start processing in queue mode preemptively
+                        if (!this.processingQueue) {
+                            this.logger.info('Preemptively switching to queue mode (low remaining requests)', {
+                                remaining,
+                                limit
+                            });
+                            this.processingQueue = true;
+                            this.processQueue().catch(err => {
+                                this.logger.error('Error processing request queue', err);
+                            });
+                        }
+                    }
+                    else if (remaining <= 20) {
+                        // More aggressive spacing
+                        safeSpacing = Math.ceil((timeToReset / remaining) * 1.5);
+                    }
+                    else {
+                        // Standard safe spacing with buffer
+                        safeSpacing = Math.ceil((timeToReset / remaining) * 1.1);
+                    }
+                    // Apply updated spacing, but with a reasonable maximum
+                    const maxSpacing = 5000; // 5 seconds max spacing
+                    const adjustedSpacing = Math.min(safeSpacing, maxSpacing);
                     // Only adjust if it's greater than our current spacing
-                    if (safeSpacing > this.requestSpacing) {
-                        this.logger.debug(`Adjusting request spacing: ${this.requestSpacing}ms → ${safeSpacing}ms`);
-                        this.requestSpacing = safeSpacing;
+                    if (adjustedSpacing > this.requestSpacing) {
+                        this.logger.debug(`Adjusting request spacing: ${this.requestSpacing}ms → ${adjustedSpacing}ms`, {
+                            remaining,
+                            timeToReset
+                        });
+                        this.requestSpacing = adjustedSpacing;
                     }
                 }
             }
@@ -208,6 +257,55 @@ export class BaseClickUpService {
             this.logger.warn('Failed to parse rate limit headers', error);
         }
     }
+    /**
+     * Process the request queue, respecting rate limits by spacing out requests
+     * @private
+     */
+    async processQueue() {
+        if (this.requestQueue.length === 0) {
+            this.logger.debug('Queue empty, exiting queue processing mode');
+            this.processingQueue = false;
+            return;
+        }
+        const queueLength = this.requestQueue.length;
+        this.logger.debug(`Processing request queue (${queueLength} items)`);
+        const startTime = Date.now();
+        try {
+            // Take the first request from the queue
+            const request = this.requestQueue.shift();
+            if (request) {
+                // Adjust delay based on queue size
+                // Longer delays for bigger queues to prevent overwhelming the API
+                let delay = this.requestSpacing;
+                if (queueLength > 20) {
+                    delay = this.requestSpacing * 2;
+                }
+                else if (queueLength > 10) {
+                    delay = this.requestSpacing * 1.5;
+                }
+                // Wait for the calculated delay
+                await new Promise(resolve => setTimeout(resolve, delay));
+                // Run the request
+                await request();
+            }
+        }
+        catch (error) {
+            if (error instanceof ClickUpServiceError && error.code === ErrorCode.RATE_LIMIT) {
+                // If we still hit rate limits, increase the spacing
+                this.requestSpacing = Math.min(this.requestSpacing * 1.5, 10000); // Max 10s
+                this.logger.warn(`Rate limit hit during queue processing, increasing delay to ${this.requestSpacing}ms`);
+            }
+            else {
+                this.logger.error('Error executing queued request', error);
+            }
+        }
+        finally {
+            const duration = Date.now() - startTime;
+            this.logger.trace(`Queue item processed in ${duration}ms, ${this.requestQueue.length} items remaining`);
+            // Continue processing the queue after the calculated delay
+            setTimeout(() => this.processQueue(), this.requestSpacing);
+        }
+    }
     /**
      * Makes an API request with rate limiting.
      * @protected
@@ -217,7 +315,13 @@ export class BaseClickUpService {
     async makeRequest(fn) {
         // If we're being rate limited, queue the request rather than executing immediately
         if (this.processingQueue) {
-            this.logger.debug('Queue active, adding request to queue');
+            const queuePosition = this.requestQueue.length + 1;
+            const estimatedWaitTime = Math.ceil((queuePosition * this.requestSpacing) / 1000);
+            this.logger.info('Request queued due to rate limiting', {
+                queuePosition,
+                estimatedWaitSeconds: estimatedWaitTime,
+                currentSpacing: this.requestSpacing
+            });
             return new Promise((resolve, reject) => {
                 this.requestQueue.push(async () => {
                     try {
@@ -225,7 +329,14 @@ export class BaseClickUpService {
                         resolve(result);
                     }
                     catch (error) {
-                        reject(error);
+                        // Enhance error message with queue context if it's a rate limit error
+                        if (error instanceof ClickUpServiceError && error.code === ErrorCode.RATE_LIMIT) {
+                            const enhancedError = new ClickUpServiceError(`${error.message} (Request was queued at position ${queuePosition})`, error.code, error.data);
+                            reject(enhancedError);
+                        }
+                        else {
+                            reject(error);
+                        }
                     }
                 });
             });

package/build/services/clickup/bulk.js

@@ -65,30 +65,18 @@ export class BulkService {
      */
     async findTaskInList(taskName, listName) {
         try {
-            // First get the list ID using the global lookup utility
-            const listInfo = await findListIDByName(clickUpServices.workspace, listName);
-            if (!listInfo) {
-                throw new ClickUpServiceError(`List "${listName}" not found`, ErrorCode.NOT_FOUND);
-            }
-            logger.info(`List "${listName}" resolved to ID: ${listInfo.id}`);
-            // Get tasks from the list using the resolved ID
-            const taskList = await this.taskService.getTasks(listInfo.id);
-            // Find the task by name - first try exact match
-            let matchingTask = taskList.find(t => t.name === taskName);
-            // If no exact match, try case-insensitive match
-            if (!matchingTask) {
-                matchingTask = taskList.find(t => t.name.toLowerCase() === taskName.toLowerCase());
-                // If still no match, try substring match as a fallback
-                if (!matchingTask) {
-                    matchingTask = taskList.find(t => t.name.toLowerCase().includes(taskName.toLowerCase()) ||
-                        taskName.toLowerCase().includes(t.name.toLowerCase()));
-                }
-            }
-            if (!matchingTask) {
+            const result = await this.taskService.findTasks({
+                taskName,
+                listName,
+                allowMultipleMatches: false,
+                useSmartDisambiguation: true,
+                includeFullDetails: false
+            });
+            if (!result || Array.isArray(result)) {
                 throw new ClickUpServiceError(`Task "${taskName}" not found in list "${listName}"`, ErrorCode.NOT_FOUND);
             }
-            logger.info(`Task "${taskName}" found with ID: ${matchingTask.id}`);
-            return matchingTask.id;
+            logger.info(`Task "${taskName}" found with ID: ${result.id}`);
+            return result.id;
         }
         catch (error) {
             // Enhance the error message

package/build/services/clickup/tag.js

@@ -135,16 +135,65 @@ export class ClickUpTagService extends BaseClickUpService {
      * Add a tag to a task
      * @param taskId - ID of the task
      * @param tagName - Name of the tag to add
-     * @returns Promise with success status
+     * @returns Promise with success status and tag data
      */
     async addTagToTask(taskId, tagName) {
         try {
             this.logger.debug(`Adding tag "${tagName}" to task: ${taskId}`);
+            // First get the task to get its space ID
+            const taskResponse = await this.client.get(`/task/${taskId}`);
+            if (!taskResponse.data?.space?.id) {
+                return {
+                    success: false,
+                    error: {
+                        message: 'Could not determine space ID from task',
+                        code: 'SPACE_NOT_FOUND'
+                    }
+                };
+            }
+            // Get space tags to verify tag exists
+            const spaceId = taskResponse.data.space.id;
+            const spaceTags = await this.getSpaceTags(spaceId);
+            if (!spaceTags.success || !spaceTags.data) {
+                return {
+                    success: false,
+                    error: {
+                        message: 'Failed to verify tag existence in space',
+                        code: 'TAG_VERIFICATION_FAILED',
+                        details: spaceTags.error
+                    }
+                };
+            }
+            // Check if tag exists
+            const tagExists = spaceTags.data.some(tag => tag.name === tagName);
+            if (!tagExists) {
+                return {
+                    success: false,
+                    error: {
+                        message: `Tag "${tagName}" does not exist in the space`,
+                        code: 'TAG_NOT_FOUND'
+                    }
+                };
+            }
             // Encode the tag name in the URL
             const encodedTagName = encodeURIComponent(tagName);
+            // Add the tag
             await this.client.post(`/task/${taskId}/tag/${encodedTagName}`, {});
+            // Verify the tag was added by getting the task again
+            const verifyResponse = await this.client.get(`/task/${taskId}`);
+            const tagAdded = verifyResponse.data?.tags?.some(tag => tag.name === tagName) ?? false;
+            if (!tagAdded) {
+                return {
+                    success: false,
+                    error: {
+                        message: 'Tag addition failed verification',
+                        code: 'TAG_VERIFICATION_FAILED'
+                    }
+                };
+            }
             return {
-                success: true
+                success: true,
+                data: { tagAdded: true }
             };
         }
         catch (error) {