@taazkareem/clickup-mcp-server 0.4.40 → 0.4.41

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

@@ -1,41 +1,47 @@
-class Logger {
-    logLevel = 'info';
-    setLogLevel(level) {
-        this.logLevel = level;
-    }
-    shouldLog(level) {
-        const levels = {
-            debug: 0,
-            info: 1,
-            warn: 2,
-            error: 3
-        };
-        return levels[level] >= levels[this.logLevel];
-    }
-    formatMessage(level, message, ...args) {
-        const timestamp = new Date().toISOString();
-        const formattedArgs = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg, null, 2) : arg).join(' ');
-        return `[${timestamp}] ${level.toUpperCase()}: ${message} ${formattedArgs}`.trim();
-    }
-    debug(message, ...args) {
-        if (this.shouldLog('debug')) {
-            console.debug(this.formatMessage('debug', message, ...args));
-        }
-    }
-    info(message, ...args) {
-        if (this.shouldLog('info')) {
-            console.info(this.formatMessage('info', message, ...args));
-        }
-    }
-    warn(message, ...args) {
-        if (this.shouldLog('warn')) {
-            console.warn(this.formatMessage('warn', message, ...args));
-        }
-    }
-    error(message, ...args) {
-        if (this.shouldLog('error')) {
-            console.error(this.formatMessage('error', message, ...args));
-        }
+/**
+ * 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 });
     }
 }
-export const logger = new Logger();
+/**
+ * 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,9 +1,9 @@
 {
   "name": "@taazkareem/clickup-mcp-server",
-  "version": "0.4.40",
+  "version": "0.4.41",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
-  "main": "build/index.js",
+  "main": "./build/index.js",
   "bin": {
     "clickup-mcp-server": "build/index.js"
   },
@@ -35,16 +35,18 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/taazkareem/clickup-mcp-server.git"
+    "url": "git+https://github.com/taazkareem/clickup-mcp-server.git"
   },
   "bugs": {
     "url": "https://github.com/taazkareem/clickup-mcp-server/issues"
   },
   "homepage": "https://github.com/taazkareem/clickup-mcp-server#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.4.1",
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@modelcontextprotocol/server-github": "^2025.1.23",
     "axios": "^1.6.7",
-    "dotenv": "^16.4.1"
+    "dotenv": "^16.4.1",
+    "zod": "^3.24.2"
   },
   "devDependencies": {
     "@types/node": "^20.11.16",