@taazkareem/clickup-mcp-server 0.4.56 → 0.4.58

package/README.md

@@ -38,7 +38,6 @@ npx -y @taazkareem/clickup-mcp-server \
   - Full CRUD operations for workspace components
   - Efficient path-based navigation
 
-
 - 🔄 **Integration Features**
   - Name or ID-based item lookup
   - Case-insensitive name matching

package/build/index.js

@@ -109,7 +109,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Due date of the task (Unix timestamp in milliseconds). Convert dates to this format before submitting."
                         }
                     },
-                    required: ["name"]
+                    required: ["name"],
+                    oneOf: [
+                        { required: ["listId"] },
+                        { required: ["listName"] }
+                    ]
                 }
             },
             {
@@ -168,7 +172,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             }
                         }
                     },
-                    required: ["listId", "tasks"]
+                    required: ["tasks"],
+                    oneOf: [
+                        { required: ["listId"] },
+                        { required: ["listName"] }
+                    ]
                 }
             },
             {
@@ -179,11 +187,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         spaceId: {
                             type: "string",
-                            description: "ID of the space to create the list in (optional if using spaceName instead). If you have this ID from a previous response, use it directly rather than looking up by name."
+                            description: "ID of the space to create the list in (required if not using folderId). If you have this ID from a previous response, use it directly rather than looking up by name."
                         },
-                        spaceName: {
+                        folderId: {
                             type: "string",
-                            description: "Name of the space to create the list in - will automatically find the space by name (optional if using spaceId instead). Only use this if you don't already have the space ID from previous responses."
+                            description: "ID of the folder to create the list in (required if not using spaceId). If you have this ID from a previous response, use it directly rather than looking up by name."
                         },
                         name: {
                             type: "string",
@@ -193,24 +201,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Description or content of the list"
                         },
-                        dueDate: {
-                            type: "string",
-                            description: "Due date for the list (Unix timestamp in milliseconds). Convert dates to this format before submitting."
+                        assignee: {
+                            type: "number",
+                            description: "User ID to assign the list to"
                         },
                         priority: {
                             type: "number",
                             description: "Priority of the list (1-4), where 1 is urgent/highest priority and 4 is lowest priority. Only set when explicitly requested."
                         },
-                        assignee: {
-                            type: "number",
-                            description: "User ID to assign the list to"
+                        dueDate: {
+                            type: "string",
+                            description: "Due date for the list (Unix timestamp in milliseconds). Convert dates to this format before submitting."
                         },
                         status: {
                             type: "string",
                             description: "Status of the list"
                         }
                     },
-                    required: ["name"]
+                    allOf: [
+                        {
+                            oneOf: [
+                                { required: ["spaceId"] },
+                                { required: ["folderId"] }
+                            ]
+                        },
+                        {
+                            required: ["name"]
+                        }
+                    ]
                 }
             },
             {
@@ -236,7 +254,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Whether to override space statuses with folder-specific statuses"
                         }
                     },
-                    required: ["name"]
+                    required: ["name"],
+                    oneOf: [
+                        { required: ["spaceId"] },
+                        { required: ["spaceName"] }
+                    ]
                 }
             },
             {
@@ -274,7 +296,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Status of the list (uses folder default if not specified)"
                         }
                     },
-                    required: ["name"]
+                    required: ["name"],
+                    oneOf: [
+                        { required: ["folderId"] },
+                        { required: ["folderName", "spaceId"] },
+                        { required: ["folderName", "spaceName"] }
+                    ]
                 }
             },
             {
@@ -304,7 +331,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Name of the destination list - will automatically find the list by name (optional if using listId instead). Only use this if you don't already have the list ID from previous responses."
                         }
                     },
-                    required: ["taskName", "listName"]
+                    allOf: [
+                        {
+                            oneOf: [
+                                { required: ["taskId"] },
+                                { required: ["taskName"] }
+                            ]
+                        },
+                        {
+                            oneOf: [
+                                { required: ["listId"] },
+                                { required: ["listName"] }
+                            ]
+                        }
+                    ]
                 }
             },
             {
@@ -334,7 +374,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Name of the list to create the duplicate in - will automatically find the list by name (optional if using listId instead). Only use this if you don't already have the list ID from previous responses."
                         }
                     },
-                    required: ["taskName", "listName"]
+                    allOf: [
+                        {
+                            oneOf: [
+                                { required: ["taskId"] },
+                                { required: ["taskName"] }
+                            ]
+                        },
+                        {
+                            oneOf: [
+                                { required: ["listId"] },
+                                { required: ["listName"] }
+                            ]
+                        }
+                    ]
                 }
             },
             {
@@ -363,20 +416,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "New plain text description for the task"
                         },
+                        markdown_description: {
+                            type: "string",
+                            description: "New markdown formatted description for the task. If provided, this takes precedence over description"
+                        },
                         status: {
                             type: "string",
                             description: "New status for the task (must be a valid status in the task's list)"
                         },
                         priority: {
-                            type: "number",
-                            description: "New priority for the task (1-4), where 1 is urgent/highest priority and 4 is lowest priority"
-                        },
-                        dueDate: {
-                            type: "string",
-                            description: "New due date for the task (Unix timestamp in milliseconds). Convert dates to this format before submitting."
+                            type: ["number", "null"],
+                            enum: [1, 2, 3, 4, null],
+                            description: "New priority for the task (1-4 or null), where 1 is urgent/highest priority and 4 is lowest priority. Set to null to clear priority.",
+                            optional: true
                         }
                     },
-                    required: ["taskName"]
+                    oneOf: [
+                        { required: ["taskId"] },
+                        { required: ["taskName"] }
+                    ]
                 }
             },
             {
@@ -456,7 +514,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Object with custom field IDs as keys and desired values for filtering"
                         }
                     },
-                    required: ["listName"]
+                    oneOf: [
+                        { required: ["listId"] },
+                        { required: ["listName"] }
+                    ]
                 }
             },
             {
@@ -478,7 +539,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Optional: Name of the list to narrow down task search when multiple tasks have the same name"
                         }
                     },
-                    required: ["taskName"]
+                    oneOf: [
+                        { required: ["taskId"] },
+                        { required: ["taskName"] }
+                    ]
                 }
             },
             {
@@ -526,7 +590,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Name of the space containing the folder (optional if using spaceId instead, and only needed when using folderName). Only use this if you don't already have the space ID from previous responses."
                         }
                     },
-                    required: []
+                    oneOf: [
+                        { required: ["folderId"] },
+                        { required: ["folderName", "spaceId"] },
+                        { required: ["folderName", "spaceName"] }
+                    ]
                 }
             },
             {
@@ -560,7 +628,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Whether to override space statuses with folder-specific statuses"
                         }
                     },
-                    required: []
+                    oneOf: [
+                        { required: ["folderId"] },
+                        { required: ["folderName", "spaceId"] },
+                        { required: ["folderName", "spaceName"] }
+                    ]
                 }
             },
             {
@@ -586,7 +658,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Name of the space containing the folder (optional if using spaceId instead, and only needed when using folderName). Only use this if you don't already have the space ID from previous responses."
                         }
                     },
-                    required: []
+                    oneOf: [
+                        { required: ["folderId"] },
+                        { required: ["folderName", "spaceId"] },
+                        { required: ["folderName", "spaceName"] }
+                    ]
                 }
             },
             {
@@ -604,7 +680,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Name of the list to retrieve - will automatically find the list by name (optional if using listId instead). Only use this if you don't already have the list ID from previous responses."
                         }
                     },
-                    required: []
+                    oneOf: [
+                        { required: ["listId"] },
+                        { required: ["listName"] }
+                    ]
                 }
             },
             {
@@ -634,7 +713,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "New status for the list"
                         }
                     },
-                    required: []
+                    oneOf: [
+                        { required: ["listId"] },
+                        { required: ["listName"] }
+                    ]
                 }
             },
             {
@@ -652,7 +734,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Name of the list to delete - will automatically find the list by name (optional if using listId instead). Only use this if you don't already have the list ID from previous responses."
                         }
                     },
-                    required: []
+                    oneOf: [
+                        { required: ["listId"] },
+                        { required: ["listName"] }
+                    ]
                 }
             }
         ]
@@ -730,12 +815,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "create_bulk_tasks": {
                 const args = request.params.arguments;
-                if (!args.listId && !args.listName) {
-                    throw new Error("Either listId or listName is required");
-                }
-                if (!args.tasks || args.tasks.length === 0) {
+                // First validate tasks array
+                if (!args.tasks || !Array.isArray(args.tasks) || args.tasks.length === 0) {
                     throw new Error("tasks array is required and must not be empty");
                 }
+                // Validate each task has required fields
+                args.tasks.forEach((task, index) => {
+                    if (!task.name) {
+                        throw new Error(`Task at index ${index} is missing required field 'name'`);
+                    }
+                });
+                // Get listId from name if needed
                 let listId = args.listId;
                 if (!listId && args.listName) {
                     const result = await clickup.findListIDByName(args.listName);
@@ -744,33 +834,75 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                     listId = result.id;
                 }
+                // Now validate we have a listId
+                if (!listId) {
+                    throw new Error("Either listId or listName must be provided");
+                }
                 const { listId: _, listName: __, tasks } = args;
                 const createdTasks = await clickup.createBulkTasks(listId, { tasks });
                 return {
                     content: [{
                             type: "text",
-                            text: `Created ${createdTasks.length} tasks`
+                            text: JSON.stringify({
+                                message: `Created ${createdTasks.length} tasks`,
+                                tasks: createdTasks.map(task => ({
+                                    id: task.id,
+                                    name: task.name,
+                                    url: task.url
+                                }))
+                            }, null, 2)
                         }]
                 };
             }
             case "create_list": {
-                const args = request.params.arguments;
+                const args = request.params.arguments ? request.params.arguments : { name: '' };
                 if (!args.name) {
-                    throw new Error("name is required");
-                }
-                let spaceId = args.spaceId;
-                if (!spaceId && args.spaceName) {
-                    const foundId = await clickup.findSpaceIDByName(args.spaceName);
-                    if (!foundId) {
-                        throw new Error(`Space with name "${args.spaceName}" not found`);
+                    throw new Error("List name is required");
+                }
+                // Validate that we have either spaceId/spaceName OR folderId/folderName, but not both
+                const hasSpace = !!(args.spaceId || args.spaceName);
+                const hasFolder = !!(args.folderId || args.folderName);
+                if (!hasSpace && !hasFolder) {
+                    throw new Error("Either spaceId/spaceName or folderId/folderName must be provided");
+                }
+                if (hasSpace && hasFolder) {
+                    throw new Error("Cannot provide both space and folder identifiers. Use either spaceId/spaceName OR folderId/folderName");
+                }
+                // Prepare the list data
+                const listData = {
+                    name: args.name,
+                    content: args.content,
+                    due_date: args.dueDate,
+                    priority: args.priority,
+                    assignee: args.assignee,
+                    status: args.status
+                };
+                let list;
+                if (hasSpace) {
+                    // Handle space-based creation
+                    let spaceId = args.spaceId;
+                    if (!spaceId && args.spaceName) {
+                        const teamId = await clickup.getTeamId();
+                        const space = await clickup.findSpaceByName(args.spaceName, teamId);
+                        if (!space) {
+                            throw new Error(`Space with name "${args.spaceName}" not found`);
+                        }
+                        spaceId = space.id;
                     }
-                    spaceId = foundId;
+                    list = await clickup.createList(spaceId, listData);
                 }
-                if (!spaceId) {
-                    throw new Error("Either spaceId or spaceName must be provided");
+                else {
+                    // Handle folder-based creation
+                    let folderId = args.folderId;
+                    if (!folderId && args.folderName) {
+                        const result = await clickup.findFolderIDByName(args.folderName);
+                        if (!result) {
+                            throw new Error(`Folder with name "${args.folderName}" not found`);
+                        }
+                        folderId = result.id;
+                    }
+                    list = await clickup.createListInFolder(folderId, listData);
                 }
-                const { spaceId: _, spaceName: __, ...listData } = args;
-                const list = await clickup.createList(spaceId, listData);
                 return {
                     content: [{
                             type: "text",
@@ -902,9 +1034,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "update_task": {
                 const args = request.params.arguments;
+                // Require either taskId or taskName
                 if (!args.taskId && !args.taskName) {
                     throw new Error("Either taskId or taskName is required");
                 }
+                // Get taskId from taskName if needed
                 let taskId = args.taskId;
                 if (!taskId && args.taskName) {
                     const result = await clickup.findTaskByName(args.taskName, undefined, args.listName);
@@ -913,7 +1047,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                     taskId = result.id;
                 }
+                // Remove helper fields before updating
                 const { taskId: _, taskName: __, listName: ___, ...updateData } = args;
+                // Ensure priority is properly handled
+                if (updateData.priority !== undefined && updateData.priority !== null) {
+                    const priority = Number(updateData.priority);
+                    if (isNaN(priority) || ![1, 2, 3, 4].includes(priority)) {
+                        throw new Error("Priority must be a number between 1 and 4, or null to clear priority");
+                    }
+                    updateData.priority = priority;
+                }
                 const task = await clickup.updateTask(taskId, updateData);
                 return {
                     content: [{

package/build/services/clickup.js

@@ -59,16 +59,7 @@ export class ClickUpService {
      */
     async makeRequest(requestFn) {
         await this.checkRateLimit();
-        try {
-            return await requestFn();
-        }
-        catch (error) {
-            if (error.response?.status === 429) {
-                // Let the interceptor handle it
-                throw error;
-            }
-            throw error;
-        }
+        return await requestFn();
     }
     /**
      * Initializes the ClickUpService singleton instance.
@@ -94,6 +85,13 @@ export class ClickUpService {
         }
         return ClickUpService.instance;
     }
+    /**
+     * Gets the team/workspace ID that was set during initialization.
+     * @returns The team/workspace ID
+     */
+    getTeamId() {
+        return this.clickupTeamId;
+    }
     // Tasks
     /**
      * Retrieves tasks from a specific list with optional filtering.
@@ -183,10 +181,15 @@ export class ClickUpService {
     async createTask(listId, data) {
         return this.makeRequest(async () => {
             const taskData = { ...data };
-            if (taskData.description && /[#*`\-\[\]>]/.test(taskData.description)) {
-                taskData.markdown_description = taskData.description;
+            // If markdown_description is provided, it takes precedence
+            if (taskData.markdown_description) {
+                // Ensure we don't send both to avoid confusion
                 delete taskData.description;
             }
+            else if (taskData.description) {
+                // Only use description as-is, don't auto-convert to markdown
+                taskData.description = taskData.description.trim();
+            }
             const response = await this.client.post(`/list/${listId}/task`, taskData);
             return response.data;
         });
@@ -200,10 +203,15 @@ export class ClickUpService {
         for (const taskData of data.tasks) {
             await this.makeRequest(async () => {
                 const processedTask = { ...taskData };
-                if (processedTask.description && /[#*`\-\[\]>]/.test(processedTask.description)) {
-                    processedTask.markdown_description = processedTask.description;
+                // If markdown_description is provided, it takes precedence
+                if (processedTask.markdown_description) {
+                    // Ensure we don't send both to avoid confusion
                     delete processedTask.description;
                 }
+                else if (processedTask.description) {
+                    // Only use description as-is, don't auto-convert to markdown
+                    processedTask.description = processedTask.description.trim();
+                }
                 const response = await this.client.post(`/list/${listId}/task`, processedTask);
                 createdTasks.push(response.data);
             });
@@ -216,7 +224,21 @@ export class ClickUpService {
      */
     async updateTask(taskId, data) {
         return this.makeRequest(async () => {
-            const response = await this.client.put(`/task/${taskId}`, data);
+            const updateData = { ...data };
+            // If markdown_description is provided, it takes precedence
+            if (updateData.markdown_description) {
+                // Ensure we don't send both to avoid confusion
+                delete updateData.description;
+            }
+            else if (updateData.description) {
+                // Only use description as-is, don't auto-convert to markdown
+                updateData.description = updateData.description.trim();
+            }
+            // Handle null priority explicitly
+            if (updateData.priority === null) {
+                updateData.priority = null;
+            }
+            const response = await this.client.put(`/task/${taskId}`, updateData);
             return response.data;
         });
     }
@@ -285,6 +307,9 @@ export class ClickUpService {
     }
     /**
      * Creates a new list in a space.
+     * Note: ClickUp API requires lists to be in folders, so this will:
+     * 1. Create a default folder if none specified
+     * 2. Create the list within that folder
      * @param spaceId - ID of the space to create the list in
      * @param data - List creation data (name, content, due date, etc.)
      * @returns Promise resolving to the created ClickUpList
@@ -292,7 +317,17 @@ export class ClickUpService {
      */
     async createList(spaceId, data) {
         return this.makeRequest(async () => {
-            const response = await this.client.post(`/space/${spaceId}/list`, data);
+            // First, get or create a default folder
+            const folders = await this.getFolders(spaceId);
+            let defaultFolder = folders.find(f => f.name === 'Default Lists');
+            if (!defaultFolder) {
+                // Create a default folder if none exists
+                defaultFolder = await this.createFolder(spaceId, {
+                    name: 'Default Lists'
+                });
+            }
+            // Create the list within the default folder
+            const response = await this.client.post(`/folder/${defaultFolder.id}/list`, data);
             return response.data;
         });
     }
@@ -730,11 +765,4 @@ export class ClickUpService {
             : `${task.space.name} > ${task.list.name} > ${task.name}`;
         return { id: task.id, path };
     }
-    async getTaskStatuses(listId) {
-        const response = await this.getTasks(listId);
-        const statuses = [...new Set(response.tasks
-                .filter((task) => task.status !== undefined)
-                .map((task) => task.status.status))];
-        return statuses;
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taazkareem/clickup-mcp-server",
-  "version": "0.4.56",
+  "version": "0.4.58",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
   "main": "build/index.js",
@@ -44,10 +44,8 @@
   "homepage": "https://github.com/taazkareem/clickup-mcp-server#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "0.6.0",
-    "@types/express": "^5.0.0",
     "axios": "^1.6.7",
-    "dotenv": "^16.4.1",
-    "express": "^4.21.2"
+    "dotenv": "^16.4.1"
   },
   "devDependencies": {
     "@types/node": "^20.11.16",