@taazkareem/clickup-mcp-server 0.4.70 → 0.4.71

package/build/tools/utils.js

@@ -1,150 +1,11 @@
 /**
  * Utility functions for ClickUp MCP tools
- */
-/**
- * Get a timestamp for a relative time
- *
- * @param hours Hours from now
- * @param days Days from now
- * @param weeks Weeks from now
- * @param months Months from now
- * @returns Timestamp in milliseconds
- */
-export function getRelativeTimestamp(hours = 0, days = 0, weeks = 0, months = 0) {
-    const now = new Date();
-    if (hours)
-        now.setHours(now.getHours() + hours);
-    if (days)
-        now.setDate(now.getDate() + days);
-    if (weeks)
-        now.setDate(now.getDate() + (weeks * 7));
-    if (months)
-        now.setMonth(now.getMonth() + months);
-    return now.getTime();
-}
-/**
- * Parse a due date string into a timestamp
- * Supports ISO 8601 format or natural language like "tomorrow"
  *
- * @param dateString Date string to parse
- * @returns Timestamp in milliseconds or undefined if parsing fails
- */
-export function parseDueDate(dateString) {
-    if (!dateString)
-        return undefined;
-    try {
-        // Handle natural language dates
-        const lowerDate = dateString.toLowerCase();
-        const now = new Date();
-        if (lowerDate === 'today') {
-            const today = new Date();
-            today.setHours(23, 59, 59, 999);
-            return today.getTime();
-        }
-        // Handle relative dates with specific times
-        const relativeTimeRegex = /(?:(\d+)\s*(days?|weeks?|months?)\s*from\s*now|tomorrow|next\s+(?:week|month))\s*(?:at\s+(\d+)(?::(\d+))?\s*(am|pm)?)?/i;
-        const match = lowerDate.match(relativeTimeRegex);
-        if (match) {
-            const date = new Date();
-            const [_, amount, unit, hours, minutes, meridian] = match;
-            // Calculate the future date
-            if (amount && unit) {
-                const value = parseInt(amount);
-                if (unit.startsWith('day')) {
-                    date.setDate(date.getDate() + value);
-                }
-                else if (unit.startsWith('week')) {
-                    date.setDate(date.getDate() + (value * 7));
-                }
-                else if (unit.startsWith('month')) {
-                    date.setMonth(date.getMonth() + value);
-                }
-            }
-            else if (lowerDate.startsWith('tomorrow')) {
-                date.setDate(date.getDate() + 1);
-            }
-            else if (lowerDate.includes('next week')) {
-                date.setDate(date.getDate() + 7);
-            }
-            else if (lowerDate.includes('next month')) {
-                date.setMonth(date.getMonth() + 1);
-            }
-            // Set the time if specified
-            if (hours) {
-                let parsedHours = parseInt(hours);
-                const parsedMinutes = minutes ? parseInt(minutes) : 0;
-                // Convert to 24-hour format if meridian is specified
-                if (meridian?.toLowerCase() === 'pm' && parsedHours < 12)
-                    parsedHours += 12;
-                if (meridian?.toLowerCase() === 'am' && parsedHours === 12)
-                    parsedHours = 0;
-                date.setHours(parsedHours, parsedMinutes, 0, 0);
-            }
-            else {
-                // Default to end of day if no time specified
-                date.setHours(23, 59, 59, 999);
-            }
-            return date.getTime();
-        }
-        // Handle hours from now
-        const hoursRegex = /(\d+)\s*hours?\s*from\s*now/i;
-        const daysRegex = /(\d+)\s*days?\s*from\s*now/i;
-        const weeksRegex = /(\d+)\s*weeks?\s*from\s*now/i;
-        const monthsRegex = /(\d+)\s*months?\s*from\s*now/i;
-        if (hoursRegex.test(lowerDate)) {
-            const hours = parseInt(lowerDate.match(hoursRegex)[1]);
-            return getRelativeTimestamp(hours);
-        }
-        if (daysRegex.test(lowerDate)) {
-            const days = parseInt(lowerDate.match(daysRegex)[1]);
-            return getRelativeTimestamp(0, days);
-        }
-        if (weeksRegex.test(lowerDate)) {
-            const weeks = parseInt(lowerDate.match(weeksRegex)[1]);
-            return getRelativeTimestamp(0, 0, weeks);
-        }
-        if (monthsRegex.test(lowerDate)) {
-            const months = parseInt(lowerDate.match(monthsRegex)[1]);
-            return getRelativeTimestamp(0, 0, 0, months);
-        }
-        // Try to parse as a date string
-        const date = new Date(dateString);
-        if (!isNaN(date.getTime())) {
-            return date.getTime();
-        }
-        // If all parsing fails, return undefined
-        return undefined;
-    }
-    catch (error) {
-        console.warn(`Failed to parse due date: ${dateString}`, error);
-        return undefined;
-    }
-}
-/**
- * Format a due date timestamp into a human-readable string
- *
- * @param timestamp Unix timestamp in milliseconds
- * @returns Formatted date string or undefined if timestamp is invalid
- */
-export function formatDueDate(timestamp) {
-    if (!timestamp)
-        return undefined;
-    try {
-        const date = new Date(timestamp);
-        if (isNaN(date.getTime()))
-            return undefined;
-        // Format: "March 10, 2025 at 10:56 PM"
-        return date.toLocaleString('en-US', {
-            year: 'numeric',
-            month: 'long',
-            day: 'numeric',
-            hour: 'numeric',
-            minute: '2-digit',
-            hour12: true
-        }).replace(' at', ',');
-    }
-    catch (error) {
-        console.warn(`Failed to format due date: ${timestamp}`, error);
-        return undefined;
-    }
-}
+ * Re-exports specialized utilities from dedicated modules.
+ */
+// Re-export date utilities
+export { getRelativeTimestamp, parseDueDate, formatDueDate } from '../utils/date-utils.js';
+// Re-export sponsor utilities
+export { getSponsorMessage, enhanceResponseWithSponsor } from '../utils/sponsor-utils.js';
+// Re-export resolver utilities
+export { resolveListId, resolveTaskId } from '../utils/resolver-utils.js';

package/build/utils/concurrency-utils.js

@@ -0,0 +1,245 @@
+/**
+ * Concurrency Utilities
+ *
+ * This module provides utilities for handling concurrent operations,
+ * batch processing, rate limiting, and retry logic.
+ */
+import { Logger } from '../logger.js';
+// Create logger instance for this module
+const logger = new Logger('ConcurrencyUtils');
+/**
+ * Process a collection of items in batches with configurable concurrency
+ *
+ * This utility handles:
+ * - Breaking items into manageable batches
+ * - Processing multiple items concurrently
+ * - Retrying failed operations with backoff
+ * - Tracking progress and aggregating results
+ * - Graceful error handling
+ *
+ * @param items Array of items to process
+ * @param processor Function that processes a single item
+ * @param options Configuration options for batch processing
+ * @returns Results of the processing with success and failure information
+ */
+export async function processBatch(items, processor, options) {
+    // Apply default options
+    const opts = {
+        batchSize: options?.batchSize ?? 10,
+        concurrency: options?.concurrency ?? 3,
+        continueOnError: options?.continueOnError ?? true,
+        retryCount: options?.retryCount ?? 3,
+        retryDelay: options?.retryDelay ?? 1000,
+        exponentialBackoff: options?.exponentialBackoff ?? true,
+        progressCallback: options?.progressCallback ?? (() => { })
+    };
+    // Initialize results
+    const result = {
+        successful: [],
+        failed: [],
+        totals: {
+            success: 0,
+            failure: 0,
+            total: items.length
+        }
+    };
+    // Handle empty input array
+    if (items.length === 0) {
+        logger.info('processBatch called with empty items array');
+        return result;
+    }
+    try {
+        const totalBatches = Math.ceil(items.length / opts.batchSize);
+        let processedItems = 0;
+        logger.info(`Starting batch processing of ${items.length} items`, {
+            totalBatches,
+            batchSize: opts.batchSize,
+            concurrency: opts.concurrency
+        });
+        // Process items in batches
+        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);
+            logger.debug(`Processing batch ${batchIndex + 1}/${totalBatches}`, {
+                batchSize: batch.length,
+                startIdx,
+                endIdx
+            });
+            // Process the current batch
+            const batchResults = await processSingleBatch(batch, processor, startIdx, opts);
+            // Aggregate results
+            result.successful.push(...batchResults.successful);
+            result.failed.push(...batchResults.failed);
+            result.totals.success += batchResults.totals.success;
+            result.totals.failure += batchResults.totals.failure;
+            // Stop processing if an error occurred and continueOnError is false
+            if (batchResults.totals.failure > 0 && !opts.continueOnError) {
+                logger.warn(`Stopping batch processing due to failure and continueOnError=false`, {
+                    failedItems: batchResults.totals.failure
+                });
+                break;
+            }
+            // Update progress
+            processedItems += batch.length;
+            opts.progressCallback(processedItems, items.length, result.totals.success, result.totals.failure);
+        }
+        logger.info(`Batch processing completed`, {
+            totalItems: items.length,
+            successful: result.totals.success,
+            failed: result.totals.failure
+        });
+        return result;
+    }
+    catch (error) {
+        logger.error(`Unexpected error in batch processing`, {
+            error: error.message || String(error)
+        });
+        // Add any unprocessed items as failures
+        const processedCount = result.totals.success + result.totals.failure;
+        if (processedCount < items.length) {
+            const remainingItems = items.slice(processedCount);
+            for (let i = 0; i < remainingItems.length; i++) {
+                const index = processedCount + i;
+                result.failed.push({
+                    item: remainingItems[i],
+                    error: new Error('Batch processing failed: ' + (error.message || 'Unknown error')),
+                    index
+                });
+                result.totals.failure++;
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Process a single batch of items with concurrency
+ *
+ * @param batch The batch of items to process
+ * @param processor The function to process each item
+ * @param startIndex The starting index of the batch in the original array
+ * @param opts Processing options
+ * @returns Results for this batch
+ */
+async function processSingleBatch(batch, processor, startIndex, opts) {
+    const result = {
+        successful: [],
+        failed: [],
+        totals: {
+            success: 0,
+            failure: 0,
+            total: batch.length
+        }
+    };
+    try {
+        // Process items in concurrent chunks
+        for (let i = 0; i < batch.length; i += opts.concurrency) {
+            const concurrentBatch = batch.slice(i, Math.min(i + opts.concurrency, batch.length));
+            // Create a promise for each item in the concurrent batch
+            const promises = concurrentBatch.map((item, idx) => {
+                const index = startIndex + i + idx;
+                return processWithRetry(() => processor(item, index), item, index, opts);
+            });
+            // Wait for all promises to settle (either resolve or reject)
+            const results = await Promise.allSettled(promises);
+            // Process the results
+            results.forEach((promiseResult, idx) => {
+                const index = startIndex + i + idx;
+                if (promiseResult.status === 'fulfilled') {
+                    // Operation succeeded
+                    result.successful.push(promiseResult.value);
+                    result.totals.success++;
+                }
+                else {
+                    // Operation failed
+                    const error = promiseResult.reason;
+                    result.failed.push({
+                        item: batch[i + idx],
+                        error,
+                        index
+                    });
+                    result.totals.failure++;
+                    // If continueOnError is false, stop processing
+                    if (!opts.continueOnError) {
+                        throw new Error(`Operation failed at index ${index}: ${error.message || String(error)}`);
+                    }
+                }
+            });
+        }
+        return result;
+    }
+    catch (error) {
+        logger.error(`Error in batch processing`, {
+            batchSize: batch.length,
+            startIndex,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        // If we've hit an error that stopped the whole batch (continueOnError=false),
+        // we need to record any unprocessed items as failures
+        const processedCount = result.totals.success + result.totals.failure;
+        if (processedCount < batch.length) {
+            const remainingItems = batch.slice(processedCount);
+            for (let i = 0; i < remainingItems.length; i++) {
+                const index = startIndex + processedCount + i;
+                result.failed.push({
+                    item: remainingItems[i],
+                    error: new Error('Batch processing aborted: ' +
+                        (error instanceof Error ? error.message : String(error))),
+                    index
+                });
+                result.totals.failure++;
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Process a single item with retry logic
+ *
+ * @param operation The operation to perform
+ * @param item The item being processed (for context)
+ * @param index The index of the item (for logging)
+ * @param options Processing options
+ * @returns The result of the operation if successful
+ * @throws Error if all retry attempts fail
+ */
+async function processWithRetry(operation, item, index, options) {
+    let attempts = 0;
+    let lastError = null;
+    while (attempts <= options.retryCount) {
+        try {
+            // Attempt the operation
+            attempts++;
+            return await operation();
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            lastError = err;
+            logger.warn(`Operation failed for item at index ${index}`, {
+                attempt: attempts,
+                maxAttempts: options.retryCount + 1,
+                error: err.message
+            });
+            // If this was our last attempt, don't delay, just throw
+            if (attempts > options.retryCount) {
+                break;
+            }
+            // Calculate delay for next retry
+            let delay = options.retryDelay;
+            if (options.exponentialBackoff) {
+                // Use exponential backoff with jitter
+                delay = options.retryDelay * Math.pow(2, attempts - 1) + Math.random() * 1000;
+            }
+            logger.debug(`Retrying operation after delay`, {
+                index,
+                attempt: attempts,
+                delayMs: delay
+            });
+            // Wait before next attempt
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    // If we get here, all retry attempts failed
+    throw new Error(`Operation failed after ${attempts} attempts for item at index ${index}: ` +
+        (lastError?.message || 'Unknown error'));
+}

package/build/utils/date-utils.js

@@ -0,0 +1,152 @@
+/**
+ * Date Utility Functions
+ *
+ * This module provides utilities for handling dates, timestamps, and due date parsing.
+ */
+/**
+ * Get a timestamp for a relative time
+ *
+ * @param hours Hours from now
+ * @param days Days from now
+ * @param weeks Weeks from now
+ * @param months Months from now
+ * @returns Timestamp in milliseconds
+ */
+export function getRelativeTimestamp(hours = 0, days = 0, weeks = 0, months = 0) {
+    const now = new Date();
+    if (hours)
+        now.setHours(now.getHours() + hours);
+    if (days)
+        now.setDate(now.getDate() + days);
+    if (weeks)
+        now.setDate(now.getDate() + (weeks * 7));
+    if (months)
+        now.setMonth(now.getMonth() + months);
+    return now.getTime();
+}
+/**
+ * Parse a due date string into a timestamp
+ * Supports ISO 8601 format or natural language like "tomorrow"
+ *
+ * @param dateString Date string to parse
+ * @returns Timestamp in milliseconds or undefined if parsing fails
+ */
+export function parseDueDate(dateString) {
+    if (!dateString)
+        return undefined;
+    try {
+        // Handle natural language dates
+        const lowerDate = dateString.toLowerCase();
+        const now = new Date();
+        if (lowerDate === 'today') {
+            const today = new Date();
+            today.setHours(23, 59, 59, 999);
+            return today.getTime();
+        }
+        // Handle relative dates with specific times
+        const relativeTimeRegex = /(?:(\d+)\s*(days?|weeks?|months?)\s*from\s*now|tomorrow|next\s+(?:week|month))\s*(?:at\s+(\d+)(?::(\d+))?\s*(am|pm)?)?/i;
+        const match = lowerDate.match(relativeTimeRegex);
+        if (match) {
+            const date = new Date();
+            const [_, amount, unit, hours, minutes, meridian] = match;
+            // Calculate the future date
+            if (amount && unit) {
+                const value = parseInt(amount);
+                if (unit.startsWith('day')) {
+                    date.setDate(date.getDate() + value);
+                }
+                else if (unit.startsWith('week')) {
+                    date.setDate(date.getDate() + (value * 7));
+                }
+                else if (unit.startsWith('month')) {
+                    date.setMonth(date.getMonth() + value);
+                }
+            }
+            else if (lowerDate.startsWith('tomorrow')) {
+                date.setDate(date.getDate() + 1);
+            }
+            else if (lowerDate.includes('next week')) {
+                date.setDate(date.getDate() + 7);
+            }
+            else if (lowerDate.includes('next month')) {
+                date.setMonth(date.getMonth() + 1);
+            }
+            // Set the time if specified
+            if (hours) {
+                let parsedHours = parseInt(hours);
+                const parsedMinutes = minutes ? parseInt(minutes) : 0;
+                // Convert to 24-hour format if meridian is specified
+                if (meridian?.toLowerCase() === 'pm' && parsedHours < 12)
+                    parsedHours += 12;
+                if (meridian?.toLowerCase() === 'am' && parsedHours === 12)
+                    parsedHours = 0;
+                date.setHours(parsedHours, parsedMinutes, 0, 0);
+            }
+            else {
+                // Default to end of day if no time specified
+                date.setHours(23, 59, 59, 999);
+            }
+            return date.getTime();
+        }
+        // Handle hours from now
+        const hoursRegex = /(\d+)\s*hours?\s*from\s*now/i;
+        const daysRegex = /(\d+)\s*days?\s*from\s*now/i;
+        const weeksRegex = /(\d+)\s*weeks?\s*from\s*now/i;
+        const monthsRegex = /(\d+)\s*months?\s*from\s*now/i;
+        if (hoursRegex.test(lowerDate)) {
+            const hours = parseInt(lowerDate.match(hoursRegex)[1]);
+            return getRelativeTimestamp(hours);
+        }
+        if (daysRegex.test(lowerDate)) {
+            const days = parseInt(lowerDate.match(daysRegex)[1]);
+            return getRelativeTimestamp(0, days);
+        }
+        if (weeksRegex.test(lowerDate)) {
+            const weeks = parseInt(lowerDate.match(weeksRegex)[1]);
+            return getRelativeTimestamp(0, 0, weeks);
+        }
+        if (monthsRegex.test(lowerDate)) {
+            const months = parseInt(lowerDate.match(monthsRegex)[1]);
+            return getRelativeTimestamp(0, 0, 0, months);
+        }
+        // Try to parse as a date string
+        const date = new Date(dateString);
+        if (!isNaN(date.getTime())) {
+            return date.getTime();
+        }
+        // If all parsing fails, return undefined
+        return undefined;
+    }
+    catch (error) {
+        console.warn(`Failed to parse due date: ${dateString}`, error);
+        return undefined;
+    }
+}
+/**
+ * Format a due date timestamp into a human-readable string
+ *
+ * @param timestamp Unix timestamp in milliseconds
+ * @returns Formatted date string or undefined if timestamp is invalid
+ */
+export function formatDueDate(timestamp) {
+    if (!timestamp)
+        return undefined;
+    try {
+        const date = new Date(timestamp);
+        if (isNaN(date.getTime()))
+            return undefined;
+        // Format: "March 10, 2025 at 10:56 PM"
+        return date.toLocaleString('en-US', {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: '2-digit',
+            hour12: true
+        }).replace(' at', ',');
+    }
+    catch (error) {
+        console.warn(`Failed to format due date: ${timestamp}`, error);
+        return undefined;
+    }
+}

package/build/utils/params-utils.js

@@ -0,0 +1,39 @@
+/**
+ * Parameter Processing Utilities
+ *
+ * Utilities for processing MCP tool parameters, especially handling
+ * JSON string conversion for array and object parameters.
+ */
+import { Logger } from '../logger.js';
+// Create a logger instance
+const logger = new Logger('ParamsUtils');
+/**
+ * Process parameters that might contain JSON strings
+ * Handles cases where the MCP protocol sends stringified JSON for array or object parameters
+ *
+ * @param params The raw parameters received from the MCP tool call
+ * @returns Processed parameters with JSON strings parsed to objects/arrays
+ */
+export function processParams(params) {
+    if (!params)
+        return {};
+    const result = { ...params };
+    // Process special parameters that could be JSON strings
+    const jsonFields = ['tasks', 'options'];
+    for (const field of jsonFields) {
+        if (typeof result[field] === 'string') {
+            try {
+                if ((result[field].startsWith('[') && result[field].endsWith(']')) ||
+                    (result[field].startsWith('{') && result[field].endsWith('}'))) {
+                    result[field] = JSON.parse(result[field]);
+                    logger.debug(`Parsed JSON parameter: ${field}`);
+                }
+            }
+            catch (error) {
+                logger.error(`Failed to parse JSON for ${field}`, { error });
+                // Keep original string if parse fails
+            }
+        }
+    }
+    return result;
+}

package/build/utils/resolver-utils.js

@@ -0,0 +1,66 @@
+/**
+ * Resolver Utility Functions
+ *
+ * This module provides utilities for resolving entity IDs from names or other identifiers.
+ */
+import { clickUpServices } from '../services/shared.js';
+import { findListIDByName } from '../tools/list.js';
+/**
+ * Resolve a list ID from either a direct ID or list name
+ *
+ * @param listId Optional direct list ID
+ * @param listName Optional list name to resolve
+ * @param workspaceService Workspace service to use for lookup
+ * @returns Resolved list ID
+ * @throws Error if neither listId nor listName is provided, or if list name can't be resolved
+ */
+export async function resolveListId(listId, listName, workspaceService = clickUpServices.workspace) {
+    // If list ID is directly provided, use it
+    if (listId) {
+        return listId;
+    }
+    // If list name is provided, find the corresponding ID
+    if (listName) {
+        const listInfo = await findListIDByName(workspaceService, listName);
+        if (!listInfo) {
+            throw new Error(`List "${listName}" not found`);
+        }
+        return listInfo.id;
+    }
+    // If neither is provided, throw an error
+    throw new Error("Either listId or listName must be provided");
+}
+/**
+ * Resolve a task ID from either a direct ID or task name + list info
+ *
+ * @param taskId Optional direct task ID
+ * @param taskName Optional task name to resolve
+ * @param listId Optional list ID for task lookup
+ * @param listName Optional list name for task lookup
+ * @param taskService Task service to use for lookup
+ * @returns Resolved task ID
+ * @throws Error if parameters are insufficient or task can't be found
+ */
+export async function resolveTaskId(taskId, taskName, listId, listName, taskService = clickUpServices.task) {
+    // If task ID is directly provided, use it
+    if (taskId) {
+        return taskId;
+    }
+    // If task name is provided, we need list info to find it
+    if (taskName) {
+        // We need either listId or listName to find a task by name
+        if (!listId && !listName) {
+            throw new Error(`List name or ID is required when using task name for task "${taskName}"`);
+        }
+        // Get list ID
+        const targetListId = await resolveListId(listId, listName);
+        // Find the task in the list
+        const foundTask = await taskService.findTaskByName(targetListId, taskName);
+        if (!foundTask) {
+            throw new Error(`Task "${taskName}" not found in list`);
+        }
+        return foundTask.id;
+    }
+    // If neither is provided, throw an error
+    throw new Error("Either taskId or taskName must be provided");
+}