@taazkareem/clickup-mcp-server 0.4.60 → 0.4.63

package/build/server.js

@@ -0,0 +1,120 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createClickUpServices } from "./services/clickup/index.js";
+import config from "./config.js";
+import { workspaceHierarchyTool, handleGetWorkspaceHierarchy } from "./tools/workspace.js";
+import { createTaskTool, handleCreateTask, updateTaskTool, handleUpdateTask, moveTaskTool, handleMoveTask, duplicateTaskTool, handleDuplicateTask, getTaskTool, handleGetTask, getTasksTool, handleGetTasks, deleteTaskTool, handleDeleteTask, createBulkTasksTool, handleCreateBulkTasks, updateBulkTasksTool, handleUpdateBulkTasks, moveBulkTasksTool, handleMoveBulkTasks, deleteBulkTasksTool, handleDeleteBulkTasks } from "./tools/task.js";
+import { createListTool, handleCreateList, createListInFolderTool, handleCreateListInFolder, getListTool, handleGetList, updateListTool, handleUpdateList, deleteListTool, handleDeleteList } from "./tools/list.js";
+import { createFolderTool, handleCreateFolder, getFolderTool, handleGetFolder, updateFolderTool, handleUpdateFolder, deleteFolderTool, handleDeleteFolder } from "./tools/folder.js";
+// Initialize ClickUp services
+const services = createClickUpServices({
+    apiKey: config.clickupApiKey,
+    teamId: config.clickupTeamId
+});
+// Extract the workspace service for use in this module
+const { workspace } = services;
+/**
+ * MCP Server for ClickUp integration
+ */
+export const server = new Server({
+    name: "clickup-mcp-server",
+    version: "0.4.61",
+}, {
+    capabilities: {
+        tools: {},
+        prompts: {},
+    },
+});
+/**
+ * Configure the server routes and handlers
+ */
+export function configureServer() {
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                workspaceHierarchyTool,
+                createTaskTool,
+                getTaskTool,
+                getTasksTool,
+                updateTaskTool,
+                moveTaskTool,
+                duplicateTaskTool,
+                deleteTaskTool,
+                createBulkTasksTool,
+                updateBulkTasksTool,
+                moveBulkTasksTool,
+                deleteBulkTasksTool,
+                createListTool,
+                createListInFolderTool,
+                getListTool,
+                updateListTool,
+                deleteListTool,
+                createFolderTool,
+                getFolderTool,
+                updateFolderTool,
+                deleteFolderTool
+            ]
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: params } = req.params;
+        // Handle tool calls by routing to the appropriate handler
+        switch (name) {
+            case "get_workspace_hierarchy":
+                return handleGetWorkspaceHierarchy();
+            case "create_task":
+                return handleCreateTask(params);
+            case "update_task":
+                return handleUpdateTask(params);
+            case "move_task":
+                return handleMoveTask(params);
+            case "duplicate_task":
+                return handleDuplicateTask(params);
+            case "get_task":
+                return handleGetTask(params);
+            case "get_tasks":
+                return handleGetTasks(params);
+            case "delete_task":
+                return handleDeleteTask(params);
+            case "create_bulk_tasks":
+                return handleCreateBulkTasks(params);
+            case "update_bulk_tasks":
+                return handleUpdateBulkTasks(params);
+            case "move_bulk_tasks":
+                return handleMoveBulkTasks(params);
+            case "delete_bulk_tasks":
+                return handleDeleteBulkTasks(params);
+            case "create_list":
+                return handleCreateList(params);
+            case "create_list_in_folder":
+                return handleCreateListInFolder(params);
+            case "get_list":
+                return handleGetList(params);
+            case "update_list":
+                return handleUpdateList(params);
+            case "delete_list":
+                return handleDeleteList(params);
+            case "create_folder":
+                return handleCreateFolder(params);
+            case "get_folder":
+                return handleGetFolder(params);
+            case "update_folder":
+                return handleUpdateFolder(params);
+            case "delete_folder":
+                return handleDeleteFolder(params);
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    });
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return { prompts: [] };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async () => {
+        throw new Error("Prompt not found");
+    });
+    return server;
+}
+/**
+ * Export the clickup service for use in tool handlers
+ */
+export { workspace };

package/build/services/clickup/base.js

@@ -0,0 +1,253 @@
+/**
+ * Base ClickUp Service Class
+ *
+ * This class provides core functionality for all ClickUp service modules:
+ * - Axios client configuration
+ * - Rate limiting and request throttling
+ * - Error handling
+ * - Common request methods
+ */
+import axios from 'axios';
+/**
+ * Error types for better error handling
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["RATE_LIMIT"] = "rate_limit_exceeded";
+    ErrorCode["NOT_FOUND"] = "resource_not_found";
+    ErrorCode["UNAUTHORIZED"] = "unauthorized";
+    ErrorCode["VALIDATION"] = "validation_error";
+    ErrorCode["SERVER_ERROR"] = "server_error";
+    ErrorCode["NETWORK_ERROR"] = "network_error";
+    ErrorCode["WORKSPACE_ERROR"] = "workspace_error";
+    ErrorCode["INVALID_PARAMETER"] = "invalid_parameter";
+    ErrorCode["UNKNOWN"] = "unknown_error";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Custom error class for ClickUp API errors
+ */
+export class ClickUpServiceError extends Error {
+    constructor(message, code = ErrorCode.UNKNOWN, data, status, context) {
+        super(message);
+        this.name = 'ClickUpServiceError';
+        this.code = code;
+        this.data = data;
+        this.status = status;
+        this.context = context;
+    }
+}
+/**
+ * Base ClickUp service class that handles common functionality
+ */
+export class BaseClickUpService {
+    /**
+     * Creates an instance of BaseClickUpService.
+     * @param apiKey - ClickUp API key for authentication
+     * @param teamId - ClickUp team ID for targeting the correct workspace
+     * @param baseUrl - Optional custom base URL for the ClickUp API
+     */
+    constructor(apiKey, teamId, baseUrl = 'https://api.clickup.com/api/v2') {
+        this.defaultRequestSpacing = 600; // Default milliseconds between requests
+        this.rateLimit = 100; // Maximum requests per minute (Free Forever plan)
+        this.timeout = 65000; // 65 seconds (safely under the 1-minute window)
+        this.requestQueue = [];
+        this.processingQueue = false;
+        this.lastRateLimitReset = 0;
+        this.apiKey = apiKey;
+        this.teamId = teamId;
+        this.requestSpacing = this.defaultRequestSpacing;
+        // Configure the Axios client with default settings
+        this.client = axios.create({
+            baseURL: baseUrl,
+            headers: {
+                'Authorization': apiKey,
+                'Content-Type': 'application/json'
+            },
+            timeout: this.timeout
+        });
+        // Add response interceptor for error handling
+        this.client.interceptors.response.use(response => response, error => this.handleAxiosError(error));
+    }
+    /**
+     * Handle errors from Axios requests
+     * @private
+     * @param error Error from Axios
+     * @returns Never - always throws an error
+     */
+    handleAxiosError(error) {
+        let message = 'Unknown error occurred';
+        let code = ErrorCode.UNKNOWN;
+        let details = null;
+        let status = undefined;
+        if (error.response) {
+            // Server responded with an error status code
+            status = error.response.status;
+            details = error.response.data;
+            switch (status) {
+                case 401:
+                    message = 'Unauthorized: Invalid API key';
+                    code = ErrorCode.UNAUTHORIZED;
+                    break;
+                case 403:
+                    message = 'Forbidden: Insufficient permissions';
+                    code = ErrorCode.UNAUTHORIZED;
+                    break;
+                case 404:
+                    message = 'Resource not found';
+                    code = ErrorCode.NOT_FOUND;
+                    break;
+                case 429:
+                    message = 'Rate limit exceeded';
+                    code = ErrorCode.RATE_LIMIT;
+                    break;
+                case 400:
+                    message = 'Invalid request: ' + (error.response.data?.err || 'Validation error');
+                    code = ErrorCode.VALIDATION;
+                    break;
+                case 500:
+                case 502:
+                case 503:
+                case 504:
+                    message = 'ClickUp server error';
+                    code = ErrorCode.SERVER_ERROR;
+                    break;
+                default:
+                    message = `ClickUp API error (${status}): ${error.response.data?.err || 'Unknown error'}`;
+            }
+        }
+        else if (error.request) {
+            // Request was made but no response received
+            message = 'Network error: No response received from ClickUp';
+            code = ErrorCode.NETWORK_ERROR;
+            details = { request: error.request };
+        }
+        else {
+            // Error setting up the request
+            message = `Request setup error: ${error.message}`;
+            details = { message: error.message };
+        }
+        throw new ClickUpServiceError(message, code, details, status);
+    }
+    /**
+     * Process the request queue, respecting rate limits by spacing out requests
+     * @private
+     */
+    async processQueue() {
+        if (this.processingQueue || this.requestQueue.length === 0) {
+            return;
+        }
+        this.processingQueue = true;
+        try {
+            while (this.requestQueue.length > 0) {
+                const request = this.requestQueue.shift();
+                if (request) {
+                    try {
+                        await request();
+                    }
+                    catch (error) {
+                        console.error('Request failed:', error);
+                        // Continue processing queue even if one request fails
+                    }
+                    // Space out requests to stay within rate limit
+                    if (this.requestQueue.length > 0) {
+                        await new Promise(resolve => setTimeout(resolve, this.requestSpacing));
+                    }
+                }
+            }
+        }
+        finally {
+            this.processingQueue = false;
+        }
+    }
+    /**
+     * Handle rate limit headers from ClickUp API
+     * @private
+     * @param headers Response headers from ClickUp
+     */
+    handleRateLimitHeaders(headers) {
+        const limit = parseInt(headers['x-ratelimit-limit'], 10);
+        const remaining = parseInt(headers['x-ratelimit-remaining'], 10);
+        const reset = parseInt(headers['x-ratelimit-reset'], 10);
+        if (!isNaN(reset)) {
+            this.lastRateLimitReset = reset;
+        }
+        // If we're running low on remaining requests, increase spacing
+        if (!isNaN(remaining) && remaining < 10) {
+            const timeUntilReset = (this.lastRateLimitReset * 1000) - Date.now();
+            if (timeUntilReset > 0) {
+                this.requestSpacing = Math.max(this.defaultRequestSpacing, Math.floor(timeUntilReset / remaining));
+            }
+        }
+        else {
+            this.requestSpacing = this.defaultRequestSpacing; // Reset to default spacing
+        }
+    }
+    /**
+     * Makes an API request with rate limiting.
+     * @protected
+     * @param fn - Function that executes the API request
+     * @returns Promise that resolves with the result of the API request
+     */
+    async makeRequest(fn) {
+        return new Promise((resolve, reject) => {
+            this.requestQueue.push(async () => {
+                try {
+                    const result = await fn();
+                    // Handle rate limit headers if present
+                    if (result && typeof result === 'object' && 'headers' in result) {
+                        this.handleRateLimitHeaders(result.headers);
+                    }
+                    resolve(result);
+                }
+                catch (error) {
+                    if (axios.isAxiosError(error) && error.response?.status === 429) {
+                        const retryAfter = parseInt(error.response.headers['retry-after'] || '60', 10);
+                        const resetTime = parseInt(error.response.headers['x-ratelimit-reset'] || '0', 10);
+                        // Use the more precise reset time if available
+                        const waitTime = resetTime > 0 ?
+                            (resetTime * 1000) - Date.now() :
+                            retryAfter * 1000;
+                        await new Promise(resolve => setTimeout(resolve, waitTime));
+                        try {
+                            // Retry the request once after waiting
+                            const result = await fn();
+                            resolve(result);
+                        }
+                        catch (retryError) {
+                            reject(retryError);
+                        }
+                    }
+                    else {
+                        reject(error);
+                    }
+                }
+            });
+            this.processQueue().catch(reject);
+        });
+    }
+    /**
+     * Gets the ClickUp team ID associated with this service instance
+     * @returns The team ID
+     */
+    getTeamId() {
+        return this.teamId;
+    }
+    /**
+     * Helper method to log API operations
+     * @protected
+     * @param operation - Name of the operation being performed
+     * @param details - Details about the operation
+     */
+    logOperation(operation, details) {
+        // This could be enhanced to use a proper logging framework
+        console.log(`[ClickUpService] ${operation}:`, details);
+    }
+    /**
+     * Protected helper method to check if cache is available
+     * @param cacheService Optional cache service instance
+     * @returns True if caching is available and enabled
+     */
+    isCacheEnabled(cacheService) {
+        return !!cacheService && typeof cacheService.isEnabled === 'function' && cacheService.isEnabled();
+    }
+}

package/build/services/clickup/bulk.js

@@ -0,0 +1,116 @@
+export class BulkProcessor {
+    async processBulk(items, processor, options) {
+        const opts = {
+            batchSize: options?.batchSize ?? 10,
+            concurrency: options?.concurrency ?? 3,
+            continueOnError: options?.continueOnError ?? false,
+            retryCount: options?.retryCount ?? 3,
+            retryDelay: options?.retryDelay ?? 1000,
+            exponentialBackoff: options?.exponentialBackoff ?? true,
+            onProgress: options?.onProgress ?? (() => { })
+        };
+        const result = {
+            success: true,
+            successfulItems: [],
+            failedItems: [],
+            totalItems: items.length,
+            successCount: 0,
+            failureCount: 0
+        };
+        if (items.length === 0)
+            return result;
+        try {
+            const totalBatches = Math.ceil(items.length / opts.batchSize);
+            let processedItems = 0;
+            for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
+                const startIdx = batchIndex * opts.batchSize;
+                const endIdx = Math.min(startIdx + opts.batchSize, items.length);
+                const batch = items.slice(startIdx, endIdx);
+                const batchResults = await this.processBatch(batch, processor, startIdx, opts);
+                result.successfulItems.push(...batchResults.successfulItems);
+                result.failedItems.push(...batchResults.failedItems);
+                result.successCount += batchResults.successCount;
+                result.failureCount += batchResults.failureCount;
+                if (batchResults.failureCount > 0 && !opts.continueOnError) {
+                    result.success = false;
+                    return result;
+                }
+                processedItems += batch.length;
+                opts.onProgress(processedItems, items.length, result.successCount, result.failureCount);
+            }
+            result.success = result.failedItems.length === 0;
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            console.error('Failed to process bulk operation:', err.message || String(error));
+            result.success = false;
+            return result;
+        }
+    }
+    async processBatch(batch, processor, startIndex, opts) {
+        const result = {
+            success: true,
+            successfulItems: [],
+            failedItems: [],
+            totalItems: batch.length,
+            successCount: 0,
+            failureCount: 0
+        };
+        try {
+            for (let i = 0; i < batch.length; i += opts.concurrency) {
+                const concurrentBatch = batch.slice(i, Math.min(i + opts.concurrency, batch.length));
+                const promises = concurrentBatch.map((item, idx) => {
+                    const index = startIndex + i + idx;
+                    return this.processWithRetry(() => processor(item, index), index, item, opts);
+                });
+                const results = await Promise.allSettled(promises);
+                results.forEach((promiseResult, idx) => {
+                    const index = startIndex + i + idx;
+                    if (promiseResult.status === 'fulfilled') {
+                        result.successfulItems.push(promiseResult.value);
+                        result.successCount++;
+                    }
+                    else {
+                        const error = promiseResult.reason;
+                        result.failedItems.push({ item: batch[i + idx], index, error });
+                        result.failureCount++;
+                        if (!opts.continueOnError) {
+                            result.success = false;
+                            throw new Error(`Bulk operation failed at index ${index}: ${error.message || String(error)}`);
+                        }
+                    }
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            console.error(`Bulk operation failed: ${err.message || String(error)}`, error);
+            result.success = false;
+            return result;
+        }
+    }
+    async processWithRetry(operation, index, item, options) {
+        let attempts = 1;
+        let lastError = new Error('Unknown error');
+        while (attempts <= options.retryCount) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                const err = error;
+                console.warn(`Operation failed for item at index ${index}, attempt ${attempts}/${options.retryCount}: ${err.message || String(error)}`);
+                lastError = err;
+                if (attempts >= options.retryCount)
+                    break;
+                const delay = options.exponentialBackoff
+                    ? options.retryDelay * Math.pow(2, attempts) + Math.random() * 1000
+                    : options.retryDelay * Math.pow(1.5, attempts - 1);
+                await new Promise(resolve => setTimeout(resolve, delay));
+                attempts++;
+            }
+        }
+        throw new Error(`Operation failed after ${attempts} attempts for item at index ${index}: ${lastError?.message || 'Unknown error'}`);
+    }
+}

package/build/services/clickup/folder.js

@@ -0,0 +1,133 @@
+/**
+ * ClickUp Folder Service
+ *
+ * Handles all operations related to folders in ClickUp, including:
+ * - Creating folders
+ * - Retrieving folders
+ * - Updating folders
+ * - Deleting folders
+ * - Finding folders by name
+ */
+import { BaseClickUpService, ErrorCode, ClickUpServiceError } from './base.js';
+export class FolderService extends BaseClickUpService {
+    /**
+     * Creates an instance of FolderService
+     * @param apiKey - ClickUp API key
+     * @param teamId - ClickUp team ID
+     * @param baseUrl - Optional custom API URL
+     * @param workspaceService - Optional workspace service for lookups
+     */
+    constructor(apiKey, teamId, baseUrl, workspaceService) {
+        super(apiKey, teamId, baseUrl);
+        this.workspaceService = null;
+        this.workspaceService = workspaceService || null;
+    }
+    /**
+     * Helper method to handle errors consistently
+     * @param error The error that occurred
+     * @param message Optional custom error message
+     * @returns A ClickUpServiceError
+     */
+    handleError(error, message) {
+        if (error instanceof ClickUpServiceError) {
+            return error;
+        }
+        return new ClickUpServiceError(message || `Folder service error: ${error.message}`, ErrorCode.UNKNOWN, error);
+    }
+    /**
+     * Create a new folder in a space
+     * @param spaceId The ID of the space to create the folder in
+     * @param folderData The data for the new folder
+     * @returns The created folder
+     */
+    async createFolder(spaceId, folderData) {
+        try {
+            this.logOperation('createFolder', { spaceId, ...folderData });
+            const response = await this.client.post(`/space/${spaceId}/folder`, folderData);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to create folder in space ${spaceId}`);
+        }
+    }
+    /**
+     * Get a folder by its ID
+     * @param folderId The ID of the folder to retrieve
+     * @returns The folder details
+     */
+    async getFolder(folderId) {
+        try {
+            this.logOperation('getFolder', { folderId });
+            const response = await this.client.get(`/folder/${folderId}`);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get folder ${folderId}`);
+        }
+    }
+    /**
+     * Update an existing folder
+     * @param folderId The ID of the folder to update
+     * @param updateData The data to update on the folder
+     * @returns The updated folder
+     */
+    async updateFolder(folderId, updateData) {
+        try {
+            this.logOperation('updateFolder', { folderId, ...updateData });
+            const response = await this.client.put(`/folder/${folderId}`, updateData);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to update folder ${folderId}`);
+        }
+    }
+    /**
+     * Delete a folder
+     * @param folderId The ID of the folder to delete
+     * @returns Success indicator
+     */
+    async deleteFolder(folderId) {
+        try {
+            this.logOperation('deleteFolder', { folderId });
+            await this.client.delete(`/folder/${folderId}`);
+            return {
+                success: true
+            };
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to delete folder ${folderId}`);
+        }
+    }
+    /**
+     * Get all folders in a space
+     * @param spaceId The ID of the space to get folders from
+     * @returns Array of folders in the space
+     */
+    async getFoldersInSpace(spaceId) {
+        this.logOperation('getFoldersInSpace', { spaceId });
+        try {
+            const response = await this.client.get(`/space/${spaceId}/folder`);
+            return response.data.folders;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get folders in space ${spaceId}`);
+        }
+    }
+    /**
+     * Find a folder by its name in a space
+     * @param spaceId The ID of the space to search in
+     * @param folderName The name of the folder to find
+     * @returns The folder if found, otherwise null
+     */
+    async findFolderByName(spaceId, folderName) {
+        this.logOperation('findFolderByName', { spaceId, folderName });
+        try {
+            const folders = await this.getFoldersInSpace(spaceId);
+            const matchingFolder = folders.find(folder => folder.name.toLowerCase() === folderName.toLowerCase());
+            return matchingFolder || null;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to find folder by name in space ${spaceId}`);
+        }
+    }
+}

package/build/services/clickup/index.js

@@ -0,0 +1,43 @@
+/**
+ * ClickUp Service Entry Point
+ *
+ * This file re-exports all service modules for the ClickUp API integration.
+ * It also provides a convenient factory method to create instances of all services.
+ */
+// Export base service components
+export { BaseClickUpService, ClickUpServiceError, ErrorCode } from './base.js';
+// Export type definitions
+export * from './types.js';
+// Export service modules
+export { WorkspaceService } from './workspace.js';
+export { TaskService } from './task.js';
+export { ListService } from './list.js';
+export { FolderService } from './folder.js';
+export { InitializationService } from './initialization.js';
+// Import service classes for the factory function
+import { WorkspaceService } from './workspace.js';
+import { TaskService } from './task.js';
+import { ListService } from './list.js';
+import { FolderService } from './folder.js';
+import { InitializationService } from './initialization.js';
+/**
+ * Factory function to create instances of all ClickUp services
+ * @param config Configuration for the services
+ * @returns Object containing all service instances
+ */
+export function createClickUpServices(config) {
+    const { apiKey, teamId, baseUrl } = config;
+    // Create the workspace service
+    const workspaceService = new WorkspaceService(apiKey, teamId, baseUrl);
+    return {
+        workspace: workspaceService,
+        task: new TaskService(apiKey, teamId, baseUrl, workspaceService),
+        list: new ListService(apiKey, teamId, baseUrl, workspaceService),
+        folder: new FolderService(apiKey, teamId, baseUrl, workspaceService),
+        initialization: new InitializationService({
+            apiKey,
+            teamId,
+            baseUrl
+        })
+    };
+}