@taazkareem/clickup-mcp-server 0.4.40 → 0.4.41

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 taazkareem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -88,6 +88,8 @@ To add this server to Roo Code:
    **Note:** Do not use the example settings and credentials provided here; use your own.
 5. Save the `cline_mcp_settings.json` file.
 
+
+
 > **Security Note**: Your API key will be stored securely and will not be exposed to AI models.
 
 ### Available Tools

package/build/config.js

@@ -1,13 +1,23 @@
 import dotenv from 'dotenv';
+// Function to format messages as JSON-RPC 2.0
+function logMessage(method, params) {
+    const jsonRpcMessage = {
+        jsonrpc: "2.0",
+        method,
+        params,
+        id: Date.now()
+    };
+    console.log(JSON.stringify(jsonRpcMessage));
+}
 // Load environment variables from .env file
 dotenv.config();
-console.log('Environment variables received:', {
+logMessage('config.env.received', {
     CLICKUP_API_KEY: process.env.CLICKUP_API_KEY,
     TEAM_ID: process.env.TEAM_ID
 });
 // Parse command line arguments for --env flags
 const args = process.argv.slice(2);
-console.log('Command line arguments:', args);
+logMessage('config.args.received', args);
 const envArgs = {};
 for (let i = 0; i < args.length; i++) {
     if (args[i] === '--env' && i + 1 < args.length) {
@@ -19,12 +29,12 @@ for (let i = 0; i < args.length; i++) {
         i++; // Skip the next argument since we used it
     }
 }
-console.log('Parsed environment arguments:', envArgs);
+logMessage('config.args.parsed', envArgs);
 const configuration = {
     clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
     teamId: envArgs.teamId || process.env.TEAM_ID || ''
 };
-console.log('Final configuration:', configuration);
+logMessage('config.final', configuration);
 // Check for missing environment variables
 const missingEnvVars = Object.entries(configuration)
     .filter(([_, value]) => !value)

package/build/handlers/prompts.js

@@ -1,4 +1,28 @@
+/**
+ * Prompt handlers for ClickUp MCP server.
+ * Implements handlers for AI-powered analysis and summarization of ClickUp data.
+ * Each handler processes ClickUp data and returns formatted text output.
+ * @module handlers/prompts
+ */
 import { getAllTasks } from '../utils/resolvers.js';
+/**
+ * Generates a summary of all tasks in the workspace
+ * Lists each task with its name and description, providing a quick overview
+ * of all work items across spaces and lists.
+ *
+ * @param clickup - ClickUp service instance for API operations
+ * @param teamId - Team ID to fetch tasks for
+ * @returns Promise resolving to formatted text summary of all tasks
+ *
+ * @example
+ * Output format:
+ * ```
+ * Summarized Tasks:
+ *
+ * - Task Name 1: Description of first task
+ * - Task Name 2: Description of second task
+ * ```
+ */
 export async function handleSummarizeTasks(clickup, teamId) {
     const { tasks } = await getAllTasks(clickup, teamId);
     let output = "Summarized Tasks:\n\n";
@@ -7,6 +31,35 @@ export async function handleSummarizeTasks(clickup, teamId) {
     }
     return output;
 }
+/**
+ * Analyzes task priorities across the workspace
+ * Provides a statistical breakdown of task priorities, showing the distribution
+ * of priority levels and identifying potential workload patterns.
+ *
+ * @param clickup - ClickUp service instance for API operations
+ * @param teamId - Team ID to analyze tasks for
+ * @returns Promise resolving to formatted text analysis of task priorities
+ *
+ * @example
+ * Output format:
+ * ```
+ * Task Priorities Analysis:
+ *
+ * Available Priorities: 1, 2, 3, 4
+ *
+ * Priority Counts:
+ * - Priority 1: 5
+ * - Priority 2: 3
+ * - Priority 3: 8
+ * - Priority 4: 2
+ * ```
+ *
+ * Priority levels:
+ * 1 - Urgent
+ * 2 - High
+ * 3 - Normal
+ * 4 - Low
+ */
 export async function handleAnalyzeTaskPriorities(clickup, teamId) {
     const { tasks } = await getAllTasks(clickup, teamId);
     const priorities = tasks.map(task => task.priority?.priority);

package/build/handlers/tools.js

@@ -1,38 +1,311 @@
-import { resolveListId } from '../utils/resolvers.js';
+/**
+ * Tool handlers for ClickUp MCP server.
+ * Implements the business logic for each tool operation.
+ * @module handlers/tools
+ */
+import { resolveListId, resolveSpaceId, resolveFolderId } from '../utils/resolvers.js';
+import { logError } from '../utils/logger.js';
+/**
+ * Handles the workspace_hierarchy tool request
+ * Returns a formatted tree view of the ClickUp workspace structure
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to fetch hierarchy for
+ * @returns Promise resolving to MCP-formatted response
+ */
 export async function handleWorkspaceHierarchy(clickup, teamId) {
-    const spaces = await clickup.getSpaces(teamId);
-    const allLists = await clickup.getAllLists(teamId);
-    let output = "ClickUp Workspace Hierarchy:\n\n";
-    for (const space of spaces) {
-        output += `Space: ${space.name} (ID: ${space.id})\n`;
-        const folders = await clickup.getFolders(space.id);
-        for (const folder of folders) {
-            output += `  ├─ Folder: ${folder.name} (ID: ${folder.id})\n`;
-            const folderLists = folder.lists || [];
-            for (const list of folderLists) {
-                const { statuses } = await clickup.getTasks(list.id);
-                output += `  │  └─ List: ${list.name} (ID: ${list.id})\n`;
-                output += `  │     Available Statuses: ${statuses.join(', ')}\n`;
+    try {
+        const spaces = await clickup.getSpaces(teamId);
+        const allLists = await clickup.getAllLists(teamId);
+        let output = "ClickUp Workspace Hierarchy:\n\n";
+        for (const space of spaces) {
+            output += `Space: ${space.name} (ID: ${space.id})\n`;
+            const folders = await clickup.getFolders(space.id);
+            for (const folder of folders) {
+                output += `  ├─ Folder: ${folder.name} (ID: ${folder.id})\n`;
+                const folderLists = folder.lists || [];
+                for (const list of folderLists) {
+                    const { statuses } = await clickup.getTasks(list.id);
+                    output += `  │  └─ List: ${list.name} (ID: ${list.id})\n`;
+                    output += `  │     Available Statuses: ${statuses.join(', ')}\n`;
+                }
             }
-        }
-        const spaceLists = allLists.filter(list => list.space &&
-            list.space.id === space.id &&
-            !folders.some(folder => folder.lists?.some(fl => fl.id === list.id)));
-        if (spaceLists.length > 0) {
-            output += "  ├─ Lists (not in folders):\n";
-            for (const list of spaceLists) {
-                const { statuses } = await clickup.getTasks(list.id);
-                output += `  │  └─ List: ${list.name} (ID: ${list.id})\n`;
-                output += `  │     Available Statuses: ${statuses.join(', ')}\n`;
+            const spaceLists = allLists.filter(list => list.space &&
+                list.space.id === space.id &&
+                !folders.some(folder => folder.lists?.some(fl => fl.id === list.id)));
+            if (spaceLists.length > 0) {
+                output += "  ├─ Lists (not in folders):\n";
+                for (const list of spaceLists) {
+                    const { statuses } = await clickup.getTasks(list.id);
+                    output += `  │  └─ List: ${list.name} (ID: ${list.id})\n`;
+                    output += `  │     Available Statuses: ${statuses.join(', ')}\n`;
+                }
             }
+            output += "\n";
         }
-        output += "\n";
+        return {
+            content: [{
+                    type: 'text',
+                    text: output
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.workspace_hierarchy', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to fetch workspace hierarchy: ${errorMessage}`
+                }]
+        };
     }
-    return output;
 }
+/**
+ * Handles the create_task tool request
+ * Creates a new task in the specified list
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to create task in
+ * @param args - Task creation arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
 export async function handleCreateTask(clickup, teamId, args) {
-    const listId = await resolveListId(clickup, teamId, args.listId, args.listName);
-    const { listId: _, listName: __, ...taskData } = args;
-    return await clickup.createTask(listId, taskData);
+    try {
+        const listId = await resolveListId(clickup, teamId, args.listId, args.listName);
+        const { listId: _, listName: __, ...taskData } = args;
+        const task = await clickup.createTask(listId, taskData);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully created task "${task.name}" (ID: ${task.id})`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.create_task', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to create task: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the create_bulk_tasks tool request
+ * Creates multiple tasks in the specified list
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to create tasks in
+ * @param args - Bulk task creation arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleCreateBulkTasks(clickup, teamId, args) {
+    try {
+        const listId = await resolveListId(clickup, teamId, args.listId, args.listName);
+        const { listId: _, listName: __, tasks } = args;
+        const createdTasks = await Promise.all(tasks.map(taskData => clickup.createTask(listId, taskData)));
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully created ${createdTasks.length} tasks in list ${listId}`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.create_bulk_tasks', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to create bulk tasks: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the create_list tool request
+ * Creates a new list in the specified space
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to create list in
+ * @param args - List creation arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleCreateList(clickup, teamId, args) {
+    try {
+        const spaceId = await resolveSpaceId(clickup, teamId, args.spaceId, args.spaceName);
+        const { spaceId: _, spaceName: __, ...listData } = args;
+        const list = await clickup.createList(spaceId, listData);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully created list "${list.name}" (ID: ${list.id})`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.create_list', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to create list: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the create_folder tool request
+ * Creates a new folder in the specified space
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to create folder in
+ * @param args - Folder creation arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleCreateFolder(clickup, teamId, args) {
+    try {
+        const spaceId = await resolveSpaceId(clickup, teamId, args.spaceId, args.spaceName);
+        const { spaceId: _, spaceName: __, ...folderData } = args;
+        const folder = await clickup.createFolder(spaceId, folderData);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully created folder "${folder.name}" (ID: ${folder.id})`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.create_folder', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to create folder: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the create_list_in_folder tool request
+ * Creates a new list within a specified folder
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to create list in
+ * @param args - List creation arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleCreateListInFolder(clickup, teamId, args) {
+    try {
+        let folderId = args.folderId;
+        if (!folderId) {
+            const spaceId = await resolveSpaceId(clickup, teamId, args.spaceId, args.spaceName);
+            folderId = await resolveFolderId(clickup, teamId, undefined, args.folderName);
+        }
+        const { folderId: _, folderName: __, spaceId: ___, spaceName: ____, ...listData } = args;
+        const list = await clickup.createListInFolder(folderId, listData);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully created list "${list.name}" (ID: ${list.id}) in folder`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.create_list_in_folder', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to create list in folder: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the move_task tool request
+ * Moves a task to a different list
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID
+ * @param args - Task move arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleMoveTask(clickup, teamId, args) {
+    try {
+        const listId = await resolveListId(clickup, teamId, args.listId, args.listName);
+        await clickup.moveTask(args.taskId, listId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully moved task ${args.taskId} to list ${listId}`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.move_task', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to move task: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the duplicate_task tool request
+ * Creates a copy of a task in a specified list
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID
+ * @param args - Task duplication arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleDuplicateTask(clickup, teamId, args) {
+    try {
+        const listId = await resolveListId(clickup, teamId, args.listId, args.listName);
+        const task = await clickup.duplicateTask(args.taskId, listId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully duplicated task "${task.name}" (ID: ${task.id})`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.duplicate_task', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to duplicate task: ${errorMessage}`
+                }]
+        };
+    }
+}
+/**
+ * Handles the update_task tool request
+ * Updates an existing task with new data
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID
+ * @param args - Task update arguments
+ * @returns Promise resolving to MCP-formatted response
+ */
+export async function handleUpdateTask(clickup, teamId, args) {
+    try {
+        const { taskId, ...updateData } = args;
+        const task = await clickup.updateTask(taskId, updateData);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Successfully updated task "${task.name}" (ID: ${task.id})`
+                }]
+        };
+    }
+    catch (error) {
+        logError('tool.update_task', error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'error',
+                    text: `Failed to update task: ${errorMessage}`
+                }]
+        };
+    }
 }
-// Add other handler functions for each tool...