@taazkareem/clickup-mcp-server 0.4.16 → 0.4.18

package/build/index.js

@@ -1,38 +1,59 @@
 #!/usr/bin/env node
+/**
+ * ClickUp MCP Server
+ * A Model Context Protocol server implementation for ClickUp integration.
+ * Provides tools and resources for AI agents to interact with ClickUp tasks,
+ * spaces, lists, and folders through a standardized protocol.
+ *
+ * @module clickup-mcp-server
+ */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { ClickUpService } from "./services/clickup.js";
 import config from "./config.js";
-import { handleWorkspaceHierarchy, handleCreateTask } from "./handlers/tools.js";
+import { handleWorkspaceHierarchy, handleCreateTask, handleCreateBulkTasks, handleCreateList, handleCreateFolder, handleCreateListInFolder, handleMoveTask, handleDuplicateTask, handleUpdateTask } from "./handlers/tools.js";
 import { handleSummarizeTasks, handleAnalyzeTaskPriorities } from "./handlers/prompts.js";
 import { getAllTasks } from "./utils/resolvers.js";
-console.log('Server starting up...');
-console.log('Config loaded:', {
+import { logError, logInfo, logDebug } from "./utils/logger.js";
+// Set up global error handlers
+process.on('uncaughtException', (error) => {
+    logError('server.uncaught', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    logError('server.unhandled_rejection', reason);
+    process.exit(1);
+});
+logInfo('server', { status: 'starting' });
+logInfo('config', {
     clickupApiKey: config.clickupApiKey ? '***' : 'missing',
     teamId: config.teamId || 'missing'
 });
-// Initialize ClickUp service
+/**
+ * Initialize ClickUp service singleton
+ * This must be done before any other ClickUp operations
+ */
 let clickup;
 try {
-    console.log('Initializing ClickUp service...');
+    logDebug('clickup', { status: 'initializing' });
     clickup = ClickUpService.initialize(config.clickupApiKey);
-    console.log('ClickUp service initialized successfully');
+    logInfo('clickup', { status: 'initialized' });
 }
 catch (error) {
-    console.error("Failed to initialize ClickUp service:", error);
+    logError('clickup.initialization', error);
     process.exit(1);
 }
-console.log('Creating MCP server...');
+/**
+ * Create and configure the MCP server instance
+ * Sets up capabilities, tools, and error handling
+ */
+logDebug('mcp', { status: 'creating' });
 const server = new Server({
     name: "clickup-mcp-server",
     version: "0.4.14",
-}, {
+    transport: new StdioServerTransport(),
     capabilities: {
-        resources: {
-            list: true,
-            read: true,
-        },
         tools: {
             workspace_hierarchy: {
                 description: "List complete hierarchy of the ClickUp workspace",
@@ -80,17 +101,17 @@ const server = new Server({
                 }
             },
             create_bulk_tasks: {
-                description: "Create multiple tasks in a ClickUp list",
+                description: "Create multiple tasks simultaneously in a list",
                 inputSchema: {
                     type: "object",
                     properties: {
                         listId: {
                             type: "string",
-                            description: "ID of the list to create the tasks in (optional if listName is provided)"
+                            description: "ID of the list to create tasks in (optional if listName is provided)"
                         },
                         listName: {
                             type: "string",
-                            description: "Name of the list to create the tasks in (optional if listId is provided)"
+                            description: "Name of the list to create tasks in (optional if listId is provided)"
                         },
                         tasks: {
                             type: "array",
@@ -112,18 +133,11 @@ const server = new Server({
                                     },
                                     priority: {
                                         type: "number",
-                                        description: "Priority level (1-4)"
+                                        description: "Priority of the task (1-4)"
                                     },
                                     dueDate: {
                                         type: "string",
-                                        description: "Due date (ISO string)"
-                                    },
-                                    assignees: {
-                                        type: "array",
-                                        items: {
-                                            type: "number"
-                                        },
-                                        description: "Array of user IDs to assign to the task"
+                                        description: "Due date of the task (ISO string)"
                                     }
                                 },
                                 required: ["name"]
@@ -134,17 +148,17 @@ const server = new Server({
                 }
             },
             create_list: {
-                description: "Create a new list in a ClickUp space",
+                description: "Create a new list in a space",
                 inputSchema: {
                     type: "object",
                     properties: {
                         spaceId: {
                             type: "string",
-                            description: "ID of the space to create the list in (optional if spaceName is provided)"
+                            description: "ID of the space (optional if spaceName is provided)"
                         },
                         spaceName: {
                             type: "string",
-                            description: "Name of the space to create the list in (optional if spaceId is provided)"
+                            description: "Name of the space (optional if spaceId is provided)"
                         },
                         name: {
                             type: "string",
@@ -152,40 +166,24 @@ const server = new Server({
                         },
                         content: {
                             type: "string",
-                            description: "Description or content of the list"
-                        },
-                        dueDate: {
-                            type: "string",
-                            description: "Due date for the list (ISO string)"
-                        },
-                        priority: {
-                            type: "number",
-                            description: "Priority of the list (1-4)"
-                        },
-                        assignee: {
-                            type: "number",
-                            description: "User ID to assign the list to"
-                        },
-                        status: {
-                            type: "string",
-                            description: "Status of the list"
+                            description: "List description"
                         }
                     },
                     required: ["name"]
                 }
             },
             create_folder: {
-                description: "Create a new folder in a ClickUp space",
+                description: "Create a new folder in a space",
                 inputSchema: {
                     type: "object",
                     properties: {
                         spaceId: {
                             type: "string",
-                            description: "ID of the space to create the folder in (optional if spaceName is provided)"
+                            description: "ID of the space (optional if spaceName is provided)"
                         },
                         spaceName: {
                             type: "string",
-                            description: "Name of the space to create the folder in (optional if spaceId is provided)"
+                            description: "Name of the space (optional if spaceId is provided)"
                         },
                         name: {
                             type: "string",
@@ -200,25 +198,25 @@ const server = new Server({
                 }
             },
             create_list_in_folder: {
-                description: "Create a new list in a ClickUp folder",
+                description: "Create a new list within a folder",
                 inputSchema: {
                     type: "object",
                     properties: {
                         folderId: {
                             type: "string",
-                            description: "ID of the folder to create the list in (optional if folderName and spaceId/spaceName are provided)"
+                            description: "ID of the folder (optional if using folderName)"
                         },
                         folderName: {
                             type: "string",
-                            description: "Name of the folder to create the list in"
+                            description: "Name of the folder"
                         },
                         spaceId: {
                             type: "string",
-                            description: "ID of the space containing the folder (required if using folderName)"
+                            description: "ID of the space (required if using folderName)"
                         },
                         spaceName: {
                             type: "string",
-                            description: "Name of the space containing the folder (alternative to spaceId)"
+                            description: "Name of the space (alternative to spaceId)"
                         },
                         name: {
                             type: "string",
@@ -226,11 +224,7 @@ const server = new Server({
                         },
                         content: {
                             type: "string",
-                            description: "Description or content of the list"
-                        },
-                        status: {
-                            type: "string",
-                            description: "Status of the list"
+                            description: "List description"
                         }
                     },
                     required: ["name"]
@@ -247,18 +241,18 @@ const server = new Server({
                         },
                         listId: {
                             type: "string",
-                            description: "ID of the destination list (optional if listName is provided)"
+                            description: "ID of destination list (optional if listName is provided)"
                         },
                         listName: {
                             type: "string",
-                            description: "Name of the destination list (optional if listId is provided)"
+                            description: "Name of destination list (optional if listId is provided)"
                         }
                     },
                     required: ["taskId"]
                 }
             },
             duplicate_task: {
-                description: "Duplicate a task to a list",
+                description: "Create a copy of a task in a specified list",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -268,18 +262,18 @@ const server = new Server({
                         },
                         listId: {
                             type: "string",
-                            description: "ID of the destination list (optional if listName is provided)"
+                            description: "ID of destination list (optional if listName is provided)"
                         },
                         listName: {
                             type: "string",
-                            description: "Name of the destination list (optional if listId is provided)"
+                            description: "Name of destination list (optional if listId is provided)"
                         }
                     },
                     required: ["taskId"]
                 }
             },
             update_task: {
-                description: "Update an existing task in ClickUp",
+                description: "Update an existing task",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -289,55 +283,106 @@ const server = new Server({
                         },
                         name: {
                             type: "string",
-                            description: "New name of the task"
+                            description: "New task name"
                         },
                         description: {
                             type: "string",
-                            description: "New description of the task"
+                            description: "New description"
                         },
                         status: {
                             type: "string",
-                            description: "New status of the task"
+                            description: "New status"
                         },
                         priority: {
                             type: "number",
-                            description: "New priority of the task (1-4)"
+                            description: "New priority level (1-4)"
                         },
                         dueDate: {
                             type: "string",
-                            description: "New due date of the task (ISO string)"
+                            description: "New due date (ISO string)"
                         }
                     },
                     required: ["taskId"]
                 }
             }
-        },
-        prompts: {
-            summarize_tasks: {
-                description: "Summarize tasks in the workspace",
-                inputSchema: {
-                    type: "object",
-                    properties: {},
-                    required: []
-                }
-            },
-            analyze_priorities: {
-                description: "Analyze task priorities",
-                inputSchema: {
-                    type: "object",
-                    properties: {},
-                    required: []
-                }
-            }
-        },
+        }
     },
+    errorHandler: (error) => {
+        logError('mcp', error);
+    }
 });
-console.log('MCP server created');
 /**
- * Handler for listing available ClickUp tasks as resources.
+ * Register handlers for MCP tool requests
+ * Each tool is mapped to its corresponding handler function
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        logDebug('tool.request', { name: request.params.name });
+        switch (request.params.name) {
+            case "workspace_hierarchy": {
+                return await handleWorkspaceHierarchy(clickup, config.teamId);
+            }
+            case "create_task": {
+                const args = request.params.arguments;
+                return await handleCreateTask(clickup, config.teamId, args);
+            }
+            case "create_bulk_tasks": {
+                const args = request.params.arguments;
+                return await handleCreateBulkTasks(clickup, config.teamId, args);
+            }
+            case "create_list": {
+                const args = request.params.arguments;
+                return await handleCreateList(clickup, config.teamId, args);
+            }
+            case "create_folder": {
+                const args = request.params.arguments;
+                return await handleCreateFolder(clickup, config.teamId, args);
+            }
+            case "create_list_in_folder": {
+                const args = request.params.arguments;
+                return await handleCreateListInFolder(clickup, config.teamId, args);
+            }
+            case "move_task": {
+                const args = request.params.arguments;
+                return await handleMoveTask(clickup, config.teamId, args);
+            }
+            case "duplicate_task": {
+                const args = request.params.arguments;
+                return await handleDuplicateTask(clickup, config.teamId, args);
+            }
+            case "update_task": {
+                const args = request.params.arguments;
+                return await handleUpdateTask(clickup, config.teamId, args);
+            }
+            default:
+                throw new Error(`Unknown tool: ${request.params.name}`);
+        }
+    }
+    catch (error) {
+        logError(`tool.${request.params.name}`, error);
+        throw error;
+    }
+});
+/**
+ * Initialize and start the server
+ * Connects to the transport and begins listening for requests
+ */
+try {
+    logInfo('mcp', { status: 'connecting' });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logInfo('mcp', { status: 'connected' });
+}
+catch (error) {
+    logError('mcp.connection', error);
+    process.exit(1);
+}
+/**
+ * Handler for listing available ClickUp tasks as resources
+ * Returns a list of all tasks across all spaces with their metadata
  */
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    console.log('Handling ListResources request');
+    logDebug('resources', { action: 'listing' });
     try {
         const { tasks, spaces } = await getAllTasks(clickup, config.teamId);
         return {
@@ -351,17 +396,19 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
         };
     }
     catch (error) {
-        console.error('Error in ListResources:', error);
+        logError('resources.list', error);
         throw error;
     }
 });
 /**
- * Handler for reading the contents of a specific ClickUp task.
+ * Handler for reading individual ClickUp task contents
+ * Returns detailed information about a specific task
  */
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     try {
         const url = new URL(request.params.uri);
         const taskId = url.pathname.replace(/^\/task\//, '');
+        logDebug('resources.read', { taskId });
         const task = await clickup.getTask(taskId);
         return {
             contents: [{
@@ -373,259 +420,28 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         };
     }
     catch (error) {
-        console.error('Error reading resource:', error);
+        logError('resources.read', error);
         throw error;
     }
 });
 /**
- * Handler for listing available tools.
+ * Handler for listing available tools
+ * Returns metadata about all registered tools
  */
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    console.log('Handling ListTools request');
+    logDebug('tools', { action: 'listing' });
     const toolCapabilities = server.capabilities?.tools || {};
-    return {
-        tools: Object.entries(toolCapabilities).map(([name, tool]) => ({
-            name,
-            description: tool.description,
-            inputSchema: tool.inputSchema
-        }))
-    };
-});
-/**
- * Handler for executing tools.
- */
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    try {
-        switch (request.params.name) {
-            case "workspace_hierarchy": {
-                const output = await handleWorkspaceHierarchy(clickup, config.teamId);
-                return {
-                    content: [{
-                            type: "text",
-                            text: output
-                        }]
-                };
-            }
-            case "create_task": {
-                const args = request.params.arguments;
-                const task = await handleCreateTask(clickup, config.teamId, args);
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Created task ${task.id}: ${task.name}`
-                        }]
-                };
-            }
-            case "create_bulk_tasks": {
-                const args = request.params.arguments;
-                let listId = args.listId;
-                if (!listId && args.listName) {
-                    const result = await clickup.findListByNameGlobally(config.teamId, args.listName);
-                    if (!result) {
-                        throw new Error(`List with name "${args.listName}" not found`);
-                    }
-                    listId = result.list.id;
-                }
-                if (!listId) {
-                    throw new Error("Either listId or listName is required");
-                }
-                if (!args.tasks || !args.tasks.length) {
-                    throw new Error("At least one task is required");
-                }
-                const { listId: _, listName: __, tasks } = args;
-                const createdTasks = await clickup.createBulkTasks(listId, { tasks });
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Created ${createdTasks.length} tasks:\n${createdTasks.map(task => `- ${task.id}: ${task.name}`).join('\n')}`
-                        }]
-                };
-            }
-            case "create_list": {
-                const args = request.params.arguments;
-                if (!args.name) {
-                    throw new Error("name is required");
-                }
-                // If folder is specified, create list in folder
-                if (args.folderName || args.folderId) {
-                    let folderId = args.folderId;
-                    if (!folderId && args.folderName) {
-                        const result = await clickup.findFolderByNameGlobally(config.teamId, args.folderName);
-                        if (!result) {
-                            throw new Error(`Folder with name "${args.folderName}" not found`);
-                        }
-                        folderId = result.folder.id;
-                    }
-                    if (!folderId) {
-                        throw new Error("Either folderId or folderName must be provided");
-                    }
-                    const { spaceId: _, spaceName: __, folderName: ___, folderId: ____, ...listData } = args;
-                    const list = await clickup.createListInFolder(folderId, listData);
-                    return {
-                        content: [{
-                                type: "text",
-                                text: `Created list ${list.id}: ${list.name} in folder`
-                            }]
-                    };
-                }
-                // Otherwise, create list in space
-                let spaceId = args.spaceId;
-                if (!spaceId && args.spaceName) {
-                    const space = await clickup.findSpaceByName(config.teamId, args.spaceName);
-                    if (!space) {
-                        throw new Error(`Space with name "${args.spaceName}" not found`);
-                    }
-                    spaceId = space.id;
-                }
-                if (!spaceId) {
-                    throw new Error("Either spaceId or spaceName must be provided");
-                }
-                const { spaceId: _, spaceName: __, folderName: ___, folderId: ____, ...listData } = args;
-                const list = await clickup.createList(spaceId, listData);
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Created list ${list.id}: ${list.name}`
-                        }]
-                };
-            }
-            case "create_folder": {
-                const args = request.params.arguments;
-                if (!args.name) {
-                    throw new Error("name is required");
-                }
-                let spaceId = args.spaceId;
-                if (!spaceId && args.spaceName) {
-                    const space = await clickup.findSpaceByName(config.teamId, args.spaceName);
-                    if (!space) {
-                        throw new Error(`Space with name "${args.spaceName}" not found`);
-                    }
-                    spaceId = space.id;
-                }
-                if (!spaceId) {
-                    throw new Error("Either spaceId or spaceName must be provided");
-                }
-                const { spaceId: _, spaceName: __, ...folderData } = args;
-                const folder = await clickup.createFolder(spaceId, folderData);
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Created folder ${folder.id}: ${folder.name}`
-                        }]
-                };
-            }
-            case "create_list_in_folder": {
-                const args = request.params.arguments;
-                if (!args.name) {
-                    throw new Error("name is required");
-                }
-                let folderId = args.folderId;
-                if (!folderId && args.folderName) {
-                    const result = await clickup.findFolderByNameGlobally(config.teamId, args.folderName);
-                    if (!result) {
-                        throw new Error(`Folder with name "${args.folderName}" not found`);
-                    }
-                    folderId = result.folder.id;
-                }
-                if (!folderId) {
-                    throw new Error("Either folderId or folderName is required");
-                }
-                const listData = {
-                    name: args.name,
-                    content: args.content,
-                    status: args.status
-                };
-                try {
-                    const list = await clickup.createListInFolder(folderId, listData);
-                    return {
-                        content: [{
-                                type: "text",
-                                text: `Created list ${list.id}: ${list.name} in folder`
-                            }]
-                    };
-                }
-                catch (error) {
-                    throw new Error(`Failed to create list: ${error.message}`);
-                }
-            }
-            case "move_task": {
-                const args = request.params.arguments;
-                if (!args.taskId) {
-                    throw new Error("taskId is required");
-                }
-                let listId = args.listId;
-                if (!listId && args.listName) {
-                    const result = await clickup.findListByNameGlobally(config.teamId, args.listName);
-                    if (!result) {
-                        throw new Error(`List with name "${args.listName}" not found`);
-                    }
-                    listId = result.list.id;
-                }
-                if (!listId) {
-                    throw new Error("Either listId or listName is required");
-                }
-                const task = await clickup.moveTask(args.taskId, listId);
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Moved task ${task.id} to list ${listId}`
-                        }]
-                };
-            }
-            case "duplicate_task": {
-                const args = request.params.arguments;
-                if (!args.taskId) {
-                    throw new Error("taskId is required");
-                }
-                let listId = args.listId;
-                if (!listId && args.listName) {
-                    const result = await clickup.findListByNameGlobally(config.teamId, args.listName);
-                    if (!result) {
-                        throw new Error(`List with name "${args.listName}" not found`);
-                    }
-                    listId = result.list.id;
-                }
-                if (!listId) {
-                    throw new Error("Either listId or listName is required");
-                }
-                const task = await clickup.duplicateTask(args.taskId, listId);
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Duplicated task ${args.taskId} to new task ${task.id} in list ${listId}`
-                        }]
-                };
-            }
-            case "update_task": {
-                const args = request.params.arguments;
-                if (!args.taskId) {
-                    throw new Error("taskId is required");
-                }
-                const task = await clickup.updateTask(args.taskId, {
-                    name: args.name,
-                    description: args.description,
-                    status: args.status,
-                    priority: args.priority,
-                    due_date: args.due_date
-                });
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Updated task ${task.id}: ${task.name}`
-                        }]
-                };
-            }
-            default:
-                throw new Error("Unknown tool");
-        }
-    }
-    catch (error) {
-        console.error('Error executing tool:', error);
-        throw error;
-    }
+    const tools = Object.entries(toolCapabilities).map(([name, tool]) => ({
+        name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+    }));
+    logDebug('tools', { count: tools.length });
+    return { tools };
 });
 /**
- * Handler for listing available prompts.
+ * Handler for listing available prompts
+ * Returns metadata about all registered prompts
  */
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
     return {
@@ -642,7 +458,8 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
     };
 });
 /**
- * Handler for getting a specific prompt.
+ * Handler for executing specific prompts
+ * Maps prompt names to their corresponding handler functions
  */
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
     try {
@@ -670,42 +487,61 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
         }
     }
     catch (error) {
-        console.error('Error getting prompt:', error);
+        logError('prompt', error);
         throw error;
     }
 });
+// Server startup logic
 if (process.argv.includes('--stdio')) {
-    console.log('Starting server in stdio mode...');
+    logInfo('server', { status: 'stdio.starting' });
     // Set up stdio transport
     const transport = new StdioServerTransport();
     // Connect server with better error handling
     server.connect(transport)
         .then(() => {
-        console.log('Server connected successfully to stdio transport');
+        logInfo('server', { status: 'connected' });
+        // Send initial handshake message with more details
+        const capabilities = {
+            tools: server.capabilities?.tools || {},
+            prompts: server.capabilities?.prompts || {},
+            resources: {
+                list: true,
+                read: true
+            }
+        };
+        logInfo('mcp', { status: 'handshake.preparing' });
+        logInfo('mcp', {
+            status: 'handshake',
+            name: "clickup-mcp-server",
+            version: "0.4.17", // Match package.json version
+            hasTools: Object.keys(capabilities.tools).length > 0,
+            hasPrompts: Object.keys(capabilities.prompts).length > 0
+        });
+        logInfo('server', { status: 'ready' });
         // Keep the process alive
         process.stdin.resume();
         // Handle process termination
         process.on('SIGINT', () => {
-            console.log('Received SIGINT. Shutting down...');
+            logInfo('server', { status: 'shutdown.sigint' });
             transport.close();
             process.exit(0);
         });
         process.on('SIGTERM', () => {
-            console.log('Received SIGTERM. Shutting down...');
+            logInfo('server', { status: 'shutdown.sigterm' });
             transport.close();
             process.exit(0);
         });
     })
         .catch(error => {
-        console.error('Failed to connect server to transport:', error);
+        logError('server', error);
         process.exit(1);
     });
 }
 else {
-    console.log('Starting server in standard mode...');
+    logInfo('server', { status: 'standard.starting' });
     // Add your non-stdio server initialization here if needed
 }
 // Prevent unhandled promise rejections from crashing the server
 process.on('unhandledRejection', (error) => {
-    console.error('Unhandled promise rejection:', error);
+    logError('server.unhandled', error);
 });