@alanse/clickup-multi-mcp-server 1.0.0

package/build/tools/workspace.js

@@ -0,0 +1,73 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp MCP Workspace Tools
+ *
+ * This module defines workspace-related tools like retrieving workspace hierarchy.
+ * It handles the workspace tool definitions and the implementation of their handlers.
+ */
+import { Logger } from '../logger.js';
+import { sponsorService } from '../utils/sponsor-service.js';
+import { getServicesForWorkspace, workspaceParameter } from './workspace-helper.js';
+// Create a logger for workspace tools
+const logger = new Logger('WorkspaceTool');
+/**
+ * Tool definition for retrieving the complete workspace hierarchy
+ */
+export const workspaceHierarchyTool = {
+    name: 'get_workspace_hierarchy',
+    description: `Gets complete workspace hierarchy (spaces, folders, lists) for a specific workspace. Returns tree structure with names and IDs for navigation.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            ...workspaceParameter
+        }
+    }
+};
+/**
+ * Handler for the get_workspace_hierarchy tool
+ */
+export async function handleGetWorkspaceHierarchy(params = {}) {
+    try {
+        // Get services for the specified workspace
+        const services = getServicesForWorkspace(params);
+        const { workspace: workspaceService } = services;
+        // Get workspace hierarchy from the workspace service
+        const hierarchy = await workspaceService.getWorkspaceHierarchy();
+        // Generate tree representation
+        const treeOutput = formatTreeOutput(hierarchy);
+        // Use sponsor service to create the response with optional sponsor message
+        return sponsorService.createResponse({ hierarchy: treeOutput }, true);
+    }
+    catch (error) {
+        return sponsorService.createErrorResponse(`Error getting workspace hierarchy: ${error.message}`);
+    }
+}
+/**
+ * Format the hierarchy as a tree string
+ */
+function formatTreeOutput(hierarchy) {
+    // Helper function to format a node and its children as a tree
+    const formatNodeAsTree = (node, level = 0, isLast = true, parentPrefix = '') => {
+        const lines = [];
+        // Calculate the current line's prefix
+        const currentPrefix = level === 0 ? '' : parentPrefix + (isLast ? '└── ' : '├── ');
+        // Format current node with descriptive ID type
+        const idType = 'type' in node ? `${node.type.charAt(0).toUpperCase() + node.type.slice(1)} ID` : 'Workspace ID';
+        lines.push(`${currentPrefix}${node.name} (${idType}: ${node.id})`);
+        // Calculate the prefix for children
+        const childPrefix = level === 0 ? '' : parentPrefix + (isLast ? '    ' : '│   ');
+        // Process children
+        const children = node.children || [];
+        children.forEach((child, index) => {
+            const childLines = formatNodeAsTree(child, level + 1, index === children.length - 1, childPrefix);
+            lines.push(...childLines);
+        });
+        return lines;
+    };
+    // Generate tree representation
+    const treeLines = formatNodeAsTree(hierarchy.root);
+    // Return plain text instead of adding code block markers
+    return treeLines.join('\n');
+}

package/build/utils/color-processor.js

@@ -0,0 +1,183 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Color Processor Utility
+ *
+ * Processes natural language color commands and converts them to HEX color values.
+ * Also generates appropriate foreground (text) colors for optimal contrast.
+ */
+// Basic color mapping with common color names to their HEX values
+const COLOR_MAP = {
+    // Primary colors
+    red: '#FF0000',
+    green: '#00FF00',
+    blue: '#0000FF',
+    // Secondary colors
+    yellow: '#FFFF00',
+    purple: '#800080',
+    orange: '#FFA500',
+    pink: '#FFC0CB',
+    brown: '#A52A2A',
+    // Neutrals
+    black: '#000000',
+    white: '#FFFFFF',
+    gray: '#808080',
+    grey: '#808080',
+    // Extended colors
+    navy: '#000080',
+    teal: '#008080',
+    olive: '#808000',
+    maroon: '#800000',
+    aqua: '#00FFFF',
+    cyan: '#00FFFF',
+    magenta: '#FF00FF',
+    fuchsia: '#FF00FF',
+    lime: '#00FF00',
+    indigo: '#4B0082',
+    violet: '#EE82EE',
+    gold: '#FFD700',
+    silver: '#C0C0C0',
+    beige: '#F5F5DC',
+    tan: '#D2B48C',
+    coral: '#FF7F50',
+    crimson: '#DC143C',
+    khaki: '#F0E68C',
+    lavender: '#E6E6FA',
+    plum: '#DDA0DD',
+    salmon: '#FA8072',
+    turquoise: '#40E0D0',
+};
+// Extended color variations
+const COLOR_VARIATIONS = {
+    red: {
+        light: '#FF6666',
+        dark: '#8B0000',
+        bright: '#FF0000',
+        deep: '#8B0000',
+    },
+    blue: {
+        light: '#ADD8E6',
+        dark: '#00008B',
+        sky: '#87CEEB',
+        navy: '#000080',
+        royal: '#4169E1',
+        deep: '#00008B',
+    },
+    green: {
+        light: '#90EE90',
+        dark: '#006400',
+        forest: '#228B22',
+        lime: '#32CD32',
+        mint: '#98FB98',
+        olive: '#808000',
+    },
+    yellow: {
+        light: '#FFFFE0',
+        dark: '#BDB76B',
+        pale: '#FFF9C4',
+        gold: '#FFD700',
+        lemon: '#FFFACD',
+    },
+    // Add more variations for other colors as needed
+};
+/**
+ * Extracts a color name from natural language text
+ * @param text - Natural language text that contains a color reference
+ * @returns The extracted color name or null if no color is found
+ */
+function extractColorFromText(text) {
+    if (!text)
+        return null;
+    // Convert to lowercase for case-insensitive matching
+    const lowercaseText = text.toLowerCase();
+    // First check for color variations (e.g., "dark blue", "light green")
+    for (const [baseColor, variations] of Object.entries(COLOR_VARIATIONS)) {
+        for (const [variation, _] of Object.entries(variations)) {
+            const colorPhrase = `${variation} ${baseColor}`;
+            if (lowercaseText.includes(colorPhrase)) {
+                return colorPhrase;
+            }
+        }
+    }
+    // Then check for base colors
+    for (const color of Object.keys(COLOR_MAP)) {
+        // Use word boundary to make sure we're matching whole words
+        const regex = new RegExp(`\\b${color}\\b`, 'i');
+        if (regex.test(lowercaseText)) {
+            return color;
+        }
+    }
+    return null;
+}
+/**
+ * Converts a color name to its HEX value
+ * @param colorName - Name of the color to convert (e.g., "blue", "dark red")
+ * @returns HEX color code or null if color name is not recognized
+ */
+function colorNameToHex(colorName) {
+    if (!colorName)
+        return null;
+    const lowercaseColor = colorName.toLowerCase();
+    // Check if it's a color variation (e.g., "dark blue")
+    const parts = lowercaseColor.split(' ');
+    if (parts.length === 2) {
+        const variation = parts[0];
+        const baseColor = parts[1];
+        if (COLOR_VARIATIONS[baseColor] && COLOR_VARIATIONS[baseColor][variation]) {
+            return COLOR_VARIATIONS[baseColor][variation];
+        }
+    }
+    // Check if it's a base color
+    return COLOR_MAP[lowercaseColor] || null;
+}
+/**
+ * Calculates the relative luminance of a color for WCAG contrast calculations
+ * @param hex - HEX color code
+ * @returns Relative luminance value
+ */
+function calculateLuminance(hex) {
+    // Remove # if present
+    const color = hex.startsWith('#') ? hex.slice(1) : hex;
+    // Convert HEX to RGB
+    const r = parseInt(color.substr(0, 2), 16) / 255;
+    const g = parseInt(color.substr(2, 2), 16) / 255;
+    const b = parseInt(color.substr(4, 2), 16) / 255;
+    // Calculate luminance using the formula from WCAG 2.0
+    const R = r <= 0.03928 ? r / 12.92 : Math.pow((r + 0.055) / 1.055, 2.4);
+    const G = g <= 0.03928 ? g / 12.92 : Math.pow((g + 0.055) / 1.055, 2.4);
+    const B = b <= 0.03928 ? b / 12.92 : Math.pow((b + 0.055) / 1.055, 2.4);
+    return 0.2126 * R + 0.7152 * G + 0.0722 * B;
+}
+/**
+ * Generates a contrasting foreground color for optimal readability
+ * @param backgroundColor - HEX code of the background color
+ * @returns HEX code of the foreground color (either black or white)
+ */
+function generateContrastingForeground(backgroundColor) {
+    const luminance = calculateLuminance(backgroundColor);
+    // Use white text on dark backgrounds and black text on light backgrounds
+    // The threshold 0.5 is based on WCAG guidelines for contrast
+    return luminance > 0.5 ? '#000000' : '#FFFFFF';
+}
+/**
+ * Processes a natural language command to extract a color and convert it to HEX values
+ * @param command - Natural language command (e.g., "Create a blue tag")
+ * @returns Object containing background and foreground HEX colors, or null if color not recognized
+ */
+export function processColorCommand(command) {
+    // Extract color name from command
+    const colorName = extractColorFromText(command);
+    if (!colorName)
+        return null;
+    // Convert color name to HEX background color
+    const backgroundColor = colorNameToHex(colorName);
+    if (!backgroundColor)
+        return null;
+    // Generate appropriate foreground color
+    const foregroundColor = generateContrastingForeground(backgroundColor);
+    return {
+        background: backgroundColor,
+        foreground: foregroundColor
+    };
+}

package/build/utils/concurrency-utils.js

@@ -0,0 +1,248 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * 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'));
+}