@taazkareem/clickup-mcp-server 0.6.2 → 0.6.4

package/build/services/clickup/workspace.js

@@ -104,8 +104,11 @@ export class WorkspaceService extends BaseClickUpService {
         try {
             // If we have the hierarchy in memory and not forcing refresh, return it
             if (this.workspaceHierarchy && !forceRefresh) {
+                this.logger.debug('Returning cached workspace hierarchy');
                 return this.workspaceHierarchy;
             }
+            const startTime = Date.now();
+            this.logger.info('Starting workspace hierarchy fetch');
             // Start building the workspace tree
             const workspaceTree = {
                 root: {
@@ -115,51 +118,93 @@ export class WorkspaceService extends BaseClickUpService {
                 }
             };
             // Get all spaces
+            const spacesStartTime = Date.now();
             const spaces = await this.getSpaces();
-            // Process each space
-            for (const space of spaces) {
-                const spaceNode = {
-                    id: space.id,
-                    name: space.name,
-                    type: 'space',
-                    children: []
-                };
-                // Get folders for the space
-                const folders = await this.getFoldersInSpace(space.id);
-                for (const folder of folders) {
-                    const folderNode = {
-                        id: folder.id,
-                        name: folder.name,
-                        type: 'folder',
-                        parentId: space.id,
+            const spacesTime = Date.now() - spacesStartTime;
+            this.logger.info(`Fetched ${spaces.length} spaces in ${spacesTime}ms`);
+            // Process spaces in batches to respect rate limits
+            const batchSize = 3; // Process 3 spaces at a time
+            const spaceNodes = [];
+            let totalFolders = 0;
+            let totalLists = 0;
+            for (let i = 0; i < spaces.length; i += batchSize) {
+                const batchStartTime = Date.now();
+                const spaceBatch = spaces.slice(i, i + batchSize);
+                this.logger.debug(`Processing space batch ${i / batchSize + 1} of ${Math.ceil(spaces.length / batchSize)} (${spaceBatch.length} spaces)`);
+                const batchNodes = await Promise.all(spaceBatch.map(async (space) => {
+                    const spaceStartTime = Date.now();
+                    const spaceNode = {
+                        id: space.id,
+                        name: space.name,
+                        type: 'space',
                         children: []
                     };
-                    // Get lists in the folder
-                    const listsInFolder = await this.getListsInFolder(folder.id);
-                    for (const list of listsInFolder) {
-                        folderNode.children?.push({
-                            id: list.id,
-                            name: list.name,
-                            type: 'list',
-                            parentId: folder.id
-                        });
+                    // Fetch initial space data
+                    const [folders, listsInSpace] = await Promise.all([
+                        this.getFoldersInSpace(space.id),
+                        this.getListsInSpace(space.id)
+                    ]);
+                    totalFolders += folders.length;
+                    totalLists += listsInSpace.length;
+                    // Process folders in smaller batches
+                    const folderBatchSize = 5; // Process 5 folders at a time
+                    const folderNodes = [];
+                    for (let j = 0; j < folders.length; j += folderBatchSize) {
+                        const folderBatchStartTime = Date.now();
+                        const folderBatch = folders.slice(j, j + folderBatchSize);
+                        const batchFolderNodes = await Promise.all(folderBatch.map(async (folder) => {
+                            const folderNode = {
+                                id: folder.id,
+                                name: folder.name,
+                                type: 'folder',
+                                parentId: space.id,
+                                children: []
+                            };
+                            // Get lists in the folder
+                            const listsInFolder = await this.getListsInFolder(folder.id);
+                            totalLists += listsInFolder.length;
+                            folderNode.children = listsInFolder.map(list => ({
+                                id: list.id,
+                                name: list.name,
+                                type: 'list',
+                                parentId: folder.id
+                            }));
+                            return folderNode;
+                        }));
+                        folderNodes.push(...batchFolderNodes);
+                        const folderBatchTime = Date.now() - folderBatchStartTime;
+                        this.logger.debug(`Processed folder batch in space ${space.name} in ${folderBatchTime}ms (${folderBatch.length} folders)`);
                     }
-                    spaceNode.children?.push(folderNode);
-                }
-                // Get lists directly in the space (not in any folder)
-                const listsInSpace = await this.getListsInSpace(space.id);
-                this.logger.debug(`Adding ${listsInSpace.length} lists directly to space ${space.name} (${space.id})`);
-                for (const list of listsInSpace) {
-                    this.logger.debug(`Adding list directly to space: ${list.name} (${list.id})`);
-                    spaceNode.children?.push({
+                    // Add folder nodes to space
+                    spaceNode.children?.push(...folderNodes);
+                    // Add folderless lists to space
+                    this.logger.debug(`Adding ${listsInSpace.length} lists directly to space ${space.name}`);
+                    const listNodes = listsInSpace.map(list => ({
                         id: list.id,
                         name: list.name,
                         type: 'list',
                         parentId: space.id
-                    });
-                }
-                workspaceTree.root.children.push(spaceNode);
+                    }));
+                    spaceNode.children?.push(...listNodes);
+                    const spaceTime = Date.now() - spaceStartTime;
+                    this.logger.info(`Processed space ${space.name} in ${spaceTime}ms (${folders.length} folders, ${listsInSpace.length} lists)`);
+                    return spaceNode;
+                }));
+                spaceNodes.push(...batchNodes);
+                const batchTime = Date.now() - batchStartTime;
+                this.logger.info(`Processed space batch in ${batchTime}ms (${spaceBatch.length} spaces)`);
             }
+            // Add all space nodes to the workspace tree
+            workspaceTree.root.children.push(...spaceNodes);
+            const totalTime = Date.now() - startTime;
+            this.logger.info('Workspace hierarchy fetch completed', {
+                duration: totalTime,
+                spaces: spaces.length,
+                folders: totalFolders,
+                lists: totalLists,
+                averageTimePerSpace: totalTime / spaces.length,
+                averageTimePerNode: totalTime / (spaces.length + totalFolders + totalLists)
+            });
             // Store the hierarchy for later use
             this.workspaceHierarchy = workspaceTree;
             return workspaceTree;

package/build/tools/folder.js

@@ -156,7 +156,7 @@ Requirements:
 - EITHER folderId OR (folderName + space information) is REQUIRED
 - When using folderName, you MUST provide EITHER spaceId OR spaceName
 
-⚠️ CRITICAL WARNING:
+Warning:
 - This action CANNOT be undone
 - All lists and tasks within the folder will also be permanently deleted
 - Using folderName is risky as names may not be unique across different spaces`,

package/build/tools/list.js

@@ -8,11 +8,9 @@
  * retrieving, and deleting lists. It supports creating lists both in spaces
  * and in folders.
  */
-import { clickUpServices } from '../services/shared.js';
+import { listService, workspaceService } from '../services/shared.js';
 import config from '../config.js';
 import { sponsorService } from '../utils/sponsor-service.js';
-// Use shared services instance
-const { list: listService, workspace: workspaceService } = clickUpServices;
 /**
  * Tool definition for creating a list directly in a space
  */
@@ -216,7 +214,7 @@ Valid Usage:
 Requirements:
 - EITHER listId OR listName: REQUIRED
 
-⚠️ CRITICAL WARNING:
+Warning:
 - This action CANNOT be undone
 - All tasks within the list will also be permanently deleted
 - Using listName is risky as names may not be unique`,

package/build/tools/task/attachments.js

@@ -7,11 +7,12 @@
  * This module implements a tool for attaching files to ClickUp tasks
  * with automatic method selection based on file source and size.
  */
-import { taskService } from '../../services/shared.js';
-import { validateTaskIdentification, resolveTaskIdWithValidation } from './utilities.js';
+import { clickUpServices } from '../../services/shared.js';
+import { validateTaskIdentification } from './utilities.js';
 import { sponsorService } from '../../utils/sponsor-service.js';
+// Use shared services instance
+const { task: taskService } = clickUpServices;
 // Session storage for chunked uploads (in-memory for demonstration)
-// In production, this should use a more persistent store
 const chunkSessions = new Map();
 // Clean up expired sessions periodically
 setInterval(() => {
@@ -32,22 +33,39 @@ export const attachTaskFileTool = {
     description: `Purpose: Attaches a file to a ClickUp task.
 
 Valid Usage:
+1. Use taskId alone (preferred) - works with both regular and custom IDs
+2. Use taskName alone (will search across all lists)
+3. Use taskName + listName (for faster, targeted search)
+
+File Source Options:
 1. Upload from base64: Provide file_data + file_name
-2. Upload from URL or local file: Provide file_url + optional file_name
-   - For web URLs: Use http:// or https:// URLs
-   - For local files: Use absolute file paths (starting with / or drive letter)
-3. For large files, advanced options are available via chunk_* parameters
+2. Upload from URL: Provide file_url starting with http:// or https://
+3. Upload from local file: Provide file_url as absolute path (starting with / or drive letter)
+4. For large files: Use chunk_* parameters for advanced chunked uploading
 
 Requirements:
-- EITHER taskId OR (taskName + listName) is REQUIRED
-- EITHER file_data OR file_url is REQUIRED
+- EITHER taskId OR taskName: REQUIRED
+- listName: Optional, but recommended when using taskName
+- File Source: ONE of the following is REQUIRED:
+  - file_data + file_name
+  - file_url (web URL or local path)
+  - chunk_session (for continuing chunked upload)
 
 Notes:
-- The system automatically selects the best upload method based on file size and source
-- Base64 method has a 10MB size limit due to encoding overhead (file_data parameter)
-- URL method works for files hosted online (file_url parameter with http/https)
-- Local file method works with absolute paths only (file_url parameter with / or drive letter)
-- For large files, the system may use chunked uploading automatically`,
+- The tool automatically searches for tasks using smart name matching
+- When only taskName is provided, it searches across all lists
+- Adding listName narrows the search to a specific list for better performance
+- The system automatically selects the best upload method based on file size and source:
+  - Base64 method: Limited to 10MB due to encoding overhead
+  - URL method: Works for files hosted online
+  - Local file method: Works with absolute paths only
+  - Large files: Automatically uses chunked uploading
+
+Warning:
+- Using taskName without listName may match multiple tasks
+- If multiple matches are found, the operation will fail with a disambiguation error
+- For local files, relative paths are not supported
+- Base64 uploads over 10MB will automatically switch to chunked upload mode`,
     inputSchema: {
         type: "object",
         properties: {
@@ -57,11 +75,11 @@ Notes:
             },
             taskName: {
                 type: "string",
-                description: "Name of the task to attach the file to. When using this parameter, you MUST also provide listName."
+                description: "Name of the task to attach the file to. The tool will search for tasks with this name across all lists unless listName is specified."
             },
             listName: {
                 type: "string",
-                description: "Name of the list containing the task. REQUIRED when using taskName."
+                description: "Optional: Name of list containing the task. Providing this narrows the search to a specific list, improving performance and reducing ambiguity."
             },
             file_name: {
                 type: "string",
@@ -96,8 +114,7 @@ Notes:
                 type: "boolean",
                 description: "Optional: For advanced usage with large file chunking. Whether this is the final chunk."
             }
-        },
-        required: [] // Will validate based on context in the handler
+        }
     }
 };
 /**
@@ -113,7 +130,18 @@ async function attachTaskFileHandler(params) {
         throw new Error("Either file_data, file_url, or session_id must be provided");
     }
     // Resolve task ID
-    const resolvedTaskId = await resolveTaskIdWithValidation(taskId, taskName, listName);
+    const result = await taskService.findTasks({
+        taskId,
+        taskName,
+        listName,
+        allowMultipleMatches: false,
+        useSmartDisambiguation: true,
+        includeFullDetails: false
+    });
+    if (!result || Array.isArray(result)) {
+        throw new Error("Task not found");
+    }
+    const resolvedTaskId = result.id;
     try {
         // CASE 1: Chunked upload continuation
         if (session_id) {
@@ -254,7 +282,8 @@ async function handleChunkUpload(taskId, sessionToken, chunkIndex, chunkData, is
         // Sort chunks by index
         const sortedChunks = Array.from(session.chunks.entries())
             .sort((a, b) => a[0] - b[0]);
-        for (const [index, chunk] of sortedChunks) {
+        for (const entry of sortedChunks) {
+            const [index, chunk] = entry;
             chunk.copy(fileData, offset);
             offset += chunk.length;
         }

package/build/tools/task/attachments.types.js

@@ -0,0 +1,9 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp MCP Task Attachment Types
+ *
+ * This module defines types for file attachment operations.
+ */
+export {};

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

@@ -76,28 +76,21 @@ export const createBulkTasksTool = {
     description: `Purpose: Create multiple tasks in a list efficiently.
 
 Valid Usage:
-1. An array of tasks with required properties + listId (preferred)
-2. An array of tasks with required properties + listName
+1. Provide listId + array of tasks (preferred)
+2. Provide listName + array of tasks
 
 Requirements:
 - tasks: REQUIRED (array of tasks, each with at least a name)
 - EITHER listId OR listName: REQUIRED
+- All tasks will be created in the specified list
 
 Notes:
 - Configure batch size and concurrency via options for performance
 - Each task should have a name with emoji prefix
-- All tasks will be created in the same list`,
+- Custom fields can be set for each task using the custom_fields property (array of {id, value} objects)`,
     inputSchema: {
         type: "object",
         properties: {
-            listId: {
-                type: "string",
-                description: "ID of list for new tasks (preferred). Use this instead of listName if you have it."
-            },
-            listName: {
-                type: "string",
-                description: "Name of list for new tasks. Only use if you don't have listId."
-            },
             tasks: {
                 type: "array",
                 description: "Array of tasks to create. Each task must have at least a name.",
@@ -134,18 +127,43 @@ Notes:
                                 type: "string"
                             },
                             description: "Optional array of tag names to assign to the task. The tags must already exist in the space."
+                        },
+                        custom_fields: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    id: {
+                                        type: "string",
+                                        description: "ID of the custom field"
+                                    },
+                                    value: {
+                                        description: "Value for the custom field. Type depends on the field type."
+                                    }
+                                },
+                                required: ["id", "value"]
+                            },
+                            description: "Optional array of custom field values to set on the task."
                         }
                     },
                     required: ["name"]
                 }
             },
+            listId: {
+                type: "string",
+                description: "ID of list for new tasks (preferred). Use this instead of listName if you have it."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list for new tasks. Only use if you don't have listId."
+            },
             options: bulkOptionsSchema
         },
         required: ["tasks"]
     }
 };
 /**
- * Tool definition for updating multiple tasks at once
+ * Tool definition for updating multiple tasks efficiently
  */
 export const updateBulkTasksTool = {
     name: "update_bulk_tasks",
@@ -163,7 +181,11 @@ Requirements:
 Notes:
 - Only specified fields will be updated for each task
 - Configure batch size and concurrency via options for performance
-- Each task can have different fields to update`,
+- Each task can have different fields to update
+- Custom fields can be updated using the custom_fields property (array of {id, value} objects)
+
+Warning:
+- Using taskName without listName will fail as tasks may have identical names across lists`,
     inputSchema: {
         type: "object",
         properties: {
@@ -173,7 +195,22 @@ Notes:
                 items: {
                     type: "object",
                     properties: {
-                        ...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')."
+                        },
+                        taskName: {
+                            type: "string",
+                            description: "Task name. Requires listName when used."
+                        },
+                        listName: {
+                            type: "string",
+                            description: "REQUIRED with taskName: List containing the task."
+                        },
+                        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."
+                        },
                         name: {
                             type: "string",
                             description: "New name with emoji prefix"
@@ -198,6 +235,23 @@ Notes:
                         dueDate: {
                             type: "string",
                             description: "New due date. Supports Unix timestamps (in milliseconds) and natural language expressions like '1 hour from now', 'tomorrow', etc."
+                        },
+                        custom_fields: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    id: {
+                                        type: "string",
+                                        description: "ID of the custom field"
+                                    },
+                                    value: {
+                                        description: "Value for the custom field. Type depends on the field type."
+                                    }
+                                },
+                                required: ["id", "value"]
+                            },
+                            description: "Optional array of custom field values to set on the task."
                         }
                     }
                 }
@@ -227,7 +281,7 @@ Notes:
 - Configure batch size and concurrency via options for performance
 - All tasks will be moved to the same destination list
 
-⚠️ Warning:
+Warning:
 - Task statuses may reset if destination list has different status options
 - Using taskName without listName will fail as tasks may have identical names across lists`,
     inputSchema: {
@@ -239,7 +293,22 @@ Notes:
                 items: {
                     type: "object",
                     properties: {
-                        ...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')."
+                        },
+                        taskName: {
+                            type: "string",
+                            description: "Task name. Requires listName when used."
+                        },
+                        listName: {
+                            type: "string",
+                            description: "REQUIRED with taskName: List containing the task."
+                        },
+                        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."
+                        }
                     }
                 }
             },
@@ -274,7 +343,7 @@ Requirements:
 Notes:
 - Configure batch size and concurrency via options for performance
 
-⚠️ CRITICAL WARNING:
+Warning:
 - This action CANNOT be undone for any of the tasks
 - Using taskName without listName is dangerous as names may not be unique
 - Always provide listName when using taskName for safer targeting`,
@@ -287,7 +356,22 @@ Notes:
                 items: {
                     type: "object",
                     properties: {
-                        ...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')."
+                        },
+                        taskName: {
+                            type: "string",
+                            description: "Task name. Requires listName when used."
+                        },
+                        listName: {
+                            type: "string",
+                            description: "REQUIRED with taskName: List containing the task."
+                        },
+                        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."
+                        }
                     }
                 }
             },