@taazkareem/clickup-mcp-server 0.4.16 → 0.4.18

package/build/services/clickup.js

@@ -1,7 +1,25 @@
+/**
+ * ClickUp API Service Module
+ * Provides a singleton service for interacting with the ClickUp API.
+ * Handles all API operations including tasks, lists, spaces, and folders management.
+ * Implements caching and connection pooling through axios instance.
+ * @module services/clickup
+ */
 import axios from 'axios';
+/**
+ * ClickUp Service Class
+ * Singleton service that manages all interactions with the ClickUp API.
+ * Provides methods for CRUD operations on tasks, lists, spaces, and folders.
+ * Implements helper methods for searching and managing ClickUp resources.
+ */
 export class ClickUpService {
     client;
     static instance;
+    /**
+     * Private constructor to enforce singleton pattern
+     * Creates an axios instance with base configuration for ClickUp API
+     * @param apiKey - ClickUp API key for authentication
+     */
     constructor(apiKey) {
         this.client = axios.create({
             baseURL: 'https://api.clickup.com/api/v2',
@@ -11,105 +29,231 @@ export class ClickUpService {
             }
         });
     }
+    /**
+     * Initializes the ClickUpService singleton
+     * Creates a new instance if one doesn't exist
+     * @param apiKey - ClickUp API key for authentication
+     * @returns The singleton ClickUpService instance
+     * @throws Error if API key is invalid
+     */
     static initialize(apiKey) {
         if (!ClickUpService.instance) {
             ClickUpService.instance = new ClickUpService(apiKey);
         }
         return ClickUpService.instance;
     }
+    /**
+     * Gets the existing ClickUpService instance
+     * @returns The singleton ClickUpService instance
+     * @throws Error if service hasn't been initialized
+     */
     static getInstance() {
         if (!ClickUpService.instance) {
             throw new Error('ClickUpService not initialized. Call initialize() first.');
         }
         return ClickUpService.instance;
     }
-    // Tasks
+    // Task Operations
+    /**
+     * Retrieves all tasks from a specific list
+     * Also returns available statuses in the list
+     * @param listId - ID of the list to fetch tasks from
+     * @returns Promise resolving to tasks array and unique statuses
+     */
     async getTasks(listId) {
         const response = await this.client.get(`/list/${listId}/task`);
         const tasks = response.data.tasks;
         const statuses = [...new Set(tasks.map((task) => task.status.status))];
         return { tasks, statuses };
     }
+    /**
+     * Retrieves a specific task by ID
+     * @param taskId - ID of the task to fetch
+     * @returns Promise resolving to task details
+     */
     async getTask(taskId) {
         const response = await this.client.get(`/task/${taskId}`);
         return response.data;
     }
+    /**
+     * Creates a new task in a specified list
+     * @param listId - ID of the list to create task in
+     * @param data - Task creation data
+     * @returns Promise resolving to created task
+     */
     async createTask(listId, data) {
         const response = await this.client.post(`/list/${listId}/task`, data);
         return response.data;
     }
+    /**
+     * Creates multiple tasks in a list simultaneously
+     * @param listId - ID of the list to create tasks in
+     * @param data - Bulk task creation data
+     * @returns Promise resolving to array of created tasks
+     */
     async createBulkTasks(listId, data) {
         const tasks = await Promise.all(data.tasks.map(taskData => this.createTask(listId, taskData)));
         return tasks;
     }
+    /**
+     * Updates an existing task
+     * @param taskId - ID of the task to update
+     * @param data - Task update data
+     * @returns Promise resolving to updated task
+     */
     async updateTask(taskId, data) {
         const response = await this.client.put(`/task/${taskId}`, data);
         return response.data;
     }
+    /**
+     * Deletes a task
+     * @param taskId - ID of the task to delete
+     */
     async deleteTask(taskId) {
         await this.client.delete(`/task/${taskId}`);
     }
-    // Lists
+    // List Operations
+    /**
+     * Retrieves all lists in a space
+     * @param spaceId - ID of the space to fetch lists from
+     * @returns Promise resolving to array of lists
+     */
     async getLists(spaceId) {
         const response = await this.client.get(`/space/${spaceId}/list`);
         return response.data.lists;
     }
+    /**
+     * Retrieves all lists across all spaces in a team
+     * @param teamId - ID of the team to fetch lists from
+     * @returns Promise resolving to array of lists
+     */
     async getAllLists(teamId) {
         const response = await this.client.get(`/team/${teamId}/list`);
         return response.data.lists;
     }
+    /**
+     * Retrieves a specific list by ID
+     * @param listId - ID of the list to fetch
+     * @returns Promise resolving to list details
+     */
     async getList(listId) {
         const response = await this.client.get(`/list/${listId}`);
         return response.data;
     }
-    // Spaces
+    // Space Operations
+    /**
+     * Retrieves all spaces in a team
+     * @param teamId - ID of the team to fetch spaces from
+     * @returns Promise resolving to array of spaces
+     */
     async getSpaces(teamId) {
         const response = await this.client.get(`/team/${teamId}/space`);
         return response.data.spaces;
     }
+    /**
+     * Retrieves a specific space by ID
+     * @param spaceId - ID of the space to fetch
+     * @returns Promise resolving to space details
+     */
     async getSpace(spaceId) {
         const response = await this.client.get(`/space/${spaceId}`);
         return response.data;
     }
+    /**
+     * Finds a space by name (case-insensitive)
+     * @param teamId - ID of the team to search in
+     * @param spaceName - Name of the space to find
+     * @returns Promise resolving to space if found, null otherwise
+     */
     async findSpaceByName(teamId, spaceName) {
         const spaces = await this.getSpaces(teamId);
         return spaces.find(space => space.name.toLowerCase() === spaceName.toLowerCase()) || null;
     }
+    /**
+     * Creates a new list in a space
+     * @param spaceId - ID of the space to create list in
+     * @param data - List creation data
+     * @returns Promise resolving to created list
+     */
     async createList(spaceId, data) {
         const response = await this.client.post(`/space/${spaceId}/list`, data);
         return response.data;
     }
-    // Folders
+    // Folder Operations
+    /**
+     * Retrieves all folders in a space
+     * @param spaceId - ID of the space to fetch folders from
+     * @returns Promise resolving to array of folders
+     */
     async getFolders(spaceId) {
         const response = await this.client.get(`/space/${spaceId}/folder`);
         return response.data.folders;
     }
+    /**
+     * Retrieves a specific folder by ID
+     * @param folderId - ID of the folder to fetch
+     * @returns Promise resolving to folder details
+     */
     async getFolder(folderId) {
         const response = await this.client.get(`/folder/${folderId}`);
         return response.data;
     }
+    /**
+     * Creates a new folder in a space
+     * @param spaceId - ID of the space to create folder in
+     * @param data - Folder creation data
+     * @returns Promise resolving to created folder
+     */
     async createFolder(spaceId, data) {
         const response = await this.client.post(`/space/${spaceId}/folder`, data);
         return response.data;
     }
+    /**
+     * Deletes a folder
+     * @param folderId - ID of the folder to delete
+     */
     async deleteFolder(folderId) {
         await this.client.delete(`/folder/${folderId}`);
     }
+    /**
+     * Creates a new list within a folder
+     * @param folderId - ID of the folder to create list in
+     * @param data - List creation data
+     * @returns Promise resolving to created list
+     */
     async createListInFolder(folderId, data) {
         const response = await this.client.post(`/folder/${folderId}/list`, data);
         return response.data;
     }
+    /**
+     * Finds a folder by name within a space (case-insensitive)
+     * @param spaceId - ID of the space to search in
+     * @param folderName - Name of the folder to find
+     * @returns Promise resolving to folder if found, null otherwise
+     */
     async findFolderByName(spaceId, folderName) {
         const folders = await this.getFolders(spaceId);
         return folders.find(folder => folder.name.toLowerCase() === folderName.toLowerCase()) || null;
     }
-    // Additional helper methods
+    // Helper Methods
+    /**
+     * Moves a task to a different list
+     * @param taskId - ID of the task to move
+     * @param listId - ID of the destination list
+     * @returns Promise resolving to updated task
+     */
     async moveTask(taskId, listId) {
         const response = await this.client.post(`/task/${taskId}`, {
             list: listId
         });
         return response.data;
     }
+    /**
+     * Finds a list by name across all spaces and folders (case-insensitive)
+     * @param teamId - ID of the team to search in
+     * @param listName - Name of the list to find
+     * @returns Promise resolving to list details with context if found, null otherwise
+     */
     async findListByNameGlobally(teamId, listName) {
         const spaces = await this.getSpaces(teamId);
         for (const space of spaces) {
@@ -136,6 +280,12 @@ export class ClickUpService {
         }
         return null;
     }
+    /**
+     * Finds a folder by name across all spaces (case-insensitive)
+     * @param teamId - ID of the team to search in
+     * @param folderName - Name of the folder to find
+     * @returns Promise resolving to folder details with context if found, null otherwise
+     */
     async findFolderByNameGlobally(teamId, folderName) {
         const spaces = await this.getSpaces(teamId);
         for (const space of spaces) {
@@ -147,15 +297,31 @@ export class ClickUpService {
         }
         return null;
     }
+    /**
+     * Creates a duplicate of a task in a specified list
+     * @param taskId - ID of the task to duplicate
+     * @param listId - ID of the destination list
+     * @returns Promise resolving to duplicated task
+     */
     async duplicateTask(taskId, listId) {
         const response = await this.client.post(`/task/${taskId}/duplicate`, {
             list: listId
         });
         return response.data;
     }
+    /**
+     * Deletes a list
+     * @param listId - ID of the list to delete
+     */
     async deleteList(listId) {
         await this.client.delete(`/list/${listId}`);
     }
+    /**
+     * Updates an existing list
+     * @param listId - ID of the list to update
+     * @param data - List update data
+     * @returns Promise resolving to updated list
+     */
     async updateList(listId, data) {
         const response = await this.client.put(`/list/${listId}`, data);
         return response.data;

package/build/types/clickup.js

@@ -1 +1,8 @@
+/**
+ * Type definitions for ClickUp API entities and operations.
+ * Defines interfaces for tasks, lists, spaces, folders and their associated
+ * creation/update data structures. These types match the ClickUp API's
+ * expected request/response formats.
+ * @module types/clickup
+ */
 export {};

package/build/utils/logger.js

@@ -0,0 +1,47 @@
+/**
+ * Logger module for MCP server that provides structured logging capabilities.
+ * All logs are formatted as JSON-RPC 2.0 messages and written to stderr.
+ * @module logger
+ */
+/**
+ * Creates a JSON-RPC 2.0 formatted log message
+ * @param method - The logging method/category (e.g., 'server.error', 'mcp.info')
+ * @param params - Additional data to include in the log message
+ */
+export function logMessage(method, params) {
+    const jsonRpcMessage = {
+        jsonrpc: "2.0",
+        method,
+        params,
+        id: Date.now() // Using timestamp as a unique ID
+    };
+    console.error(JSON.stringify(jsonRpcMessage)); // Use stderr for logging
+}
+/**
+ * Logs an error with optional stack trace
+ * @param context - The context where the error occurred (e.g., 'server', 'mcp')
+ * @param error - The error object or error message
+ */
+export function logError(context, error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logMessage(`${context}.error`, { error: errorMessage });
+    if (error instanceof Error && error.stack) {
+        logMessage(`${context}.stack`, { stack: error.stack });
+    }
+}
+/**
+ * Logs debug information
+ * @param context - The context of the debug message
+ * @param data - Debug data to log
+ */
+export function logDebug(context, data) {
+    logMessage(`${context}.debug`, { data });
+}
+/**
+ * Logs informational messages
+ * @param context - The context of the info message
+ * @param data - Information to log
+ */
+export function logInfo(context, data) {
+    logMessage(`${context}.info`, { data });
+}

package/build/utils/resolvers.js

@@ -1,3 +1,18 @@
+/**
+ * Resolver module for ClickUp entity resolution.
+ * Provides utilities to resolve IDs from names and fetch entities from the ClickUp API.
+ * @module resolvers
+ */
+import { logMessage } from '../utils/logger.js';
+/**
+ * Resolves a ClickUp list ID from either a direct ID or list name
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to search within
+ * @param listId - Optional direct list ID
+ * @param listName - Optional list name to search for
+ * @returns Promise resolving to the list ID
+ * @throws Error if neither listId nor listName is provided, or if list is not found
+ */
 export async function resolveListId(clickup, teamId, listId, listName) {
     if (listId)
         return listId;
@@ -10,6 +25,15 @@ export async function resolveListId(clickup, teamId, listId, listName) {
     }
     return result.list.id;
 }
+/**
+ * Resolves a ClickUp space ID from either a direct ID or space name
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to search within
+ * @param spaceId - Optional direct space ID
+ * @param spaceName - Optional space name to search for
+ * @returns Promise resolving to the space ID
+ * @throws Error if neither spaceId nor spaceName is provided, or if space is not found
+ */
 export async function resolveSpaceId(clickup, teamId, spaceId, spaceName) {
     if (spaceId)
         return spaceId;
@@ -22,6 +46,15 @@ export async function resolveSpaceId(clickup, teamId, spaceId, spaceName) {
     }
     return space.id;
 }
+/**
+ * Resolves a ClickUp folder ID from either a direct ID or folder name
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to search within
+ * @param folderId - Optional direct folder ID
+ * @param folderName - Optional folder name to search for
+ * @returns Promise resolving to the folder ID
+ * @throws Error if neither folderId nor folderName is provided, or if folder is not found
+ */
 export async function resolveFolderId(clickup, teamId, folderId, folderName) {
     if (folderId)
         return folderId;
@@ -34,6 +67,12 @@ export async function resolveFolderId(clickup, teamId, folderId, folderName) {
     }
     return result.folder.id;
 }
+/**
+ * Retrieves all tasks across all spaces in a team
+ * @param clickup - ClickUp service instance
+ * @param teamId - Team ID to fetch tasks for
+ * @returns Promise resolving to an object containing all tasks and spaces
+ */
 export async function getAllTasks(clickup, teamId) {
     const spaces = await clickup.getSpaces(teamId);
     const spacePromises = spaces.map(async (space) => {
@@ -46,3 +85,14 @@ export async function getAllTasks(clickup, teamId) {
     const allTasks = tasksPerSpace.flat();
     return { tasks: allTasks, spaces };
 }
+/**
+ * Generic error handler that formats and logs errors before re-throwing
+ * @param context - Context where the error occurred
+ * @param error - The error to handle
+ * @throws The original error after logging
+ */
+export function handleError(context, error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logMessage(`Error in ${context}`, { error: errorMessage });
+    throw error;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taazkareem/clickup-mcp-server",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
   "main": "./build/index.js",