@taazkareem/clickup-mcp-server 0.6.5 → 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.4 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/server.js

@@ -7,7 +7,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.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, addTagToTaskTool, handleAddTagToTask, removeTagFromTaskTool, handleRemoveTagFromTask } from "./tools/tag.js";
@@ -19,7 +19,7 @@ const logger = new Logger('Server');
 const { workspace } = clickUpServices;
 export const server = new Server({
     name: "clickup-mcp-server",
-    version: "0.6.5",
+    version: "0.6.4",
 }, {
     capabilities: {
         tools: {},
@@ -40,7 +40,6 @@ export function configureServer() {
                 workspaceHierarchyTool,
                 createTaskTool,
                 getTaskTool,
-                getTasksTool,
                 updateTaskTool,
                 moveTaskTool,
                 duplicateTaskTool,
@@ -75,7 +74,7 @@ export function configureServer() {
     });
     // Register CallTool handler with proper logging
     logger.info("Registering tool handlers", {
-        toolCount: 28,
+        toolCount: 31,
         categories: ["workspace", "task", "list", "folder", "tag"]
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -99,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":

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) {

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

@@ -23,6 +23,8 @@ export class TaskServiceCore extends BaseClickUpService {
             tasks: new Map(),
             lists: new Map()
         };
+        // Cache for task name to ID mapping
+        this.nameToIdCache = new Map();
         // Cache TTL in milliseconds (5 minutes)
         this.CACHE_TTL = 5 * 60 * 1000;
         if (workspaceService) {
@@ -155,24 +157,40 @@ export class TaskServiceCore extends BaseClickUpService {
         try {
             return await this.makeRequest(async () => {
                 const response = await this.client.post(`/list/${listId}/task`, taskData);
-                return response.data;
+                // Handle both JSON and text responses
+                const data = response.data;
+                if (typeof data === 'string') {
+                    // If we got a text response, try to extract task ID from common patterns
+                    const idMatch = data.match(/task.*?(\w{9})/i);
+                    if (idMatch) {
+                        // If we found an ID, fetch the full task details
+                        return await this.getTask(idMatch[1]);
+                    }
+                    throw new ClickUpServiceError('Received unexpected text response from API', ErrorCode.UNKNOWN, data);
+                }
+                return data;
             });
         }
         catch (error) {
-            throw this.handleError(error, `Failed to create task in list ${listId}`);
+            throw this.handleError(error, 'Failed to create task');
         }
     }
     /**
-     * Get a specific task by ID
+     * Get a task by its ID
      * @param taskId The ID of the task to retrieve
-     * @returns The task details
+     * @returns The task
      */
     async getTask(taskId) {
         this.logOperation('getTask', { taskId });
         try {
             return await this.makeRequest(async () => {
                 const response = await this.client.get(`/task/${taskId}`);
-                return response.data;
+                // Handle both JSON and text responses
+                const data = response.data;
+                if (typeof data === 'string') {
+                    throw new ClickUpServiceError('Received unexpected text response from API', ErrorCode.UNKNOWN, data);
+                }
+                return data;
             });
         }
         catch (error) {
@@ -180,22 +198,27 @@ export class TaskServiceCore extends BaseClickUpService {
         }
     }
     /**
-     * Get all tasks in a list with optional filtering
+     * Get all tasks in a list
      * @param listId The ID of the list to get tasks from
      * @param filters Optional filters to apply
-     * @returns List of tasks matching the filters
+     * @returns Array of tasks
      */
     async getTasks(listId, filters = {}) {
         this.logOperation('getTasks', { listId, filters });
         try {
             return await this.makeRequest(async () => {
                 const params = this.buildTaskFilterParams(filters);
-                const response = await this.client.get(`/list/${listId}/task?${params.toString()}`);
-                return response.data.tasks;
+                const response = await this.client.get(`/list/${listId}/task`, { params });
+                // Handle both JSON and text responses
+                const data = response.data;
+                if (typeof data === 'string') {
+                    throw new ClickUpServiceError('Received unexpected text response from API', ErrorCode.UNKNOWN, data);
+                }
+                return Array.isArray(data) ? data : data.tasks || [];
             });
         }
         catch (error) {
-            throw this.handleError(error, `Failed to get tasks from list ${listId}`);
+            throw this.handleError(error, `Failed to get tasks for list ${listId}`);
         }
     }
     /**
@@ -247,7 +270,18 @@ export class TaskServiceCore extends BaseClickUpService {
         try {
             return await this.makeRequest(async () => {
                 const response = await this.client.put(`/task/${taskId}`, updateData);
-                return response.data;
+                // Handle both JSON and text responses
+                const data = response.data;
+                if (typeof data === 'string') {
+                    // If we got a text response, try to extract task ID from common patterns
+                    const idMatch = data.match(/task.*?(\w{9})/i);
+                    if (idMatch) {
+                        // If we found an ID, fetch the full task details
+                        return await this.getTask(idMatch[1]);
+                    }
+                    throw new ClickUpServiceError('Received unexpected text response from API', ErrorCode.UNKNOWN, data);
+                }
+                return data;
             });
         }
         catch (error) {
@@ -436,4 +470,35 @@ export class TaskServiceCore extends BaseClickUpService {
             throw error;
         }
     }
+    /**
+     * Try to get a task ID from the name cache
+     * @param taskName The name of the task
+     * @param listId Optional list ID for context
+     * @returns The cached task ID if found and not expired, otherwise null
+     */
+    getCachedTaskId(taskName, listId) {
+        const cached = this.nameToIdCache.get(taskName);
+        if (cached && Date.now() - cached.validatedAt < this.CACHE_TTL) {
+            // If listId is provided, ensure it matches the cached context
+            if (!listId || cached.listId === listId) {
+                this.logger.debug('Using cached task ID for name', { taskName, cachedId: cached.taskId });
+                return cached.taskId;
+            }
+        }
+        return null;
+    }
+    /**
+     * Cache a task name to ID mapping
+     * @param taskName The name of the task
+     * @param taskId The ID of the task
+     * @param listId Optional list ID for context
+     */
+    cacheTaskNameToId(taskName, taskId, listId) {
+        this.nameToIdCache.set(taskName, {
+            taskId,
+            validatedAt: Date.now(),
+            listId
+        });
+        this.logger.debug('Cached task name to ID mapping', { taskName, taskId, listId });
+    }
 }