@taazkareem/clickup-mcp-server 0.6.0 → 0.6.2

package/build/tools/utils.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Utility functions for ClickUp MCP tools
  *
  * Re-exports specialized utilities from dedicated modules.

package/build/tools/workspace.js

@@ -1,4 +1,7 @@
 /**
+ * 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.

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
+ */
+export 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
+ */
+export 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)
+ */
+export 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

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Concurrency Utilities
  *
  * This module provides utilities for handling concurrent operations,

package/build/utils/date-utils.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Date Utility Functions
  *
  * This module provides utilities for handling dates, timestamps, and due date parsing.

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

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Resolver Utility Functions
  *
  * This module provides utilities for resolving entity IDs from names or other identifiers.

package/build/utils/sponsor-analytics.js

@@ -0,0 +1,100 @@
+/**
+ * Sponsor Analytics Module
+ *
+ * This module provides analytics tracking for sponsor messages, including:
+ * - Impression tracking
+ * - URL tracking
+ * - Analytics aggregation
+ */
+import { Logger } from '../logger.js';
+import config from '../config.js';
+// Create logger instance for this module
+const logger = new Logger('SponsorAnalytics');
+// Initialize analytics storage
+const analytics = {
+    impressions: {
+        total: 0,
+        byEndpoint: {},
+        byDate: {}
+    },
+    urlClicks: {
+        total: 0,
+        byUrl: {}
+    }
+};
+/**
+ * Track a sponsor message impression
+ * @param endpoint The endpoint/operation where the message was shown
+ */
+export function trackImpression(endpoint) {
+    if (!config.enableSponsorMessage)
+        return;
+    const today = new Date().toISOString().split('T')[0];
+    // Update total impressions
+    analytics.impressions.total++;
+    // Update impressions by endpoint
+    analytics.impressions.byEndpoint[endpoint] =
+        (analytics.impressions.byEndpoint[endpoint] || 0) + 1;
+    // Update impressions by date
+    analytics.impressions.byDate[today] =
+        (analytics.impressions.byDate[today] || 0) + 1;
+    logger.debug('Sponsor message impression tracked', {
+        endpoint,
+        total: analytics.impressions.total,
+        endpointTotal: analytics.impressions.byEndpoint[endpoint],
+        dateTotal: analytics.impressions.byDate[today]
+    });
+}
+/**
+ * Generate a tracking URL for the sponsor link
+ * @param originalUrl The original sponsor URL
+ * @param source The source/endpoint that generated the URL
+ * @returns Tracking URL
+ */
+export function generateTrackingUrl(originalUrl, source) {
+    // Add UTM parameters for tracking
+    const url = new URL(originalUrl);
+    // If it's a GitHub profile URL, modify it to be a sponsor URL
+    if (url.pathname === '/taazkareem') {
+        url.pathname = '/sponsors/taazkareem';
+    }
+    // Add minimal tracking parameters
+    url.searchParams.set('ref', source);
+    return url.toString();
+}
+/**
+ * Track a sponsor URL click (called when tracking URL is generated)
+ * @param url The tracking URL that was generated
+ */
+export function trackUrlGenerated(url) {
+    if (!config.enableSponsorMessage)
+        return;
+    // Update total clicks
+    analytics.urlClicks.total++;
+    // Update clicks by URL
+    analytics.urlClicks.byUrl[url] =
+        (analytics.urlClicks.byUrl[url] || 0) + 1;
+    logger.debug('Sponsor URL tracking link generated', {
+        url,
+        total: analytics.urlClicks.total,
+        urlTotal: analytics.urlClicks.byUrl[url]
+    });
+}
+/**
+ * Get current analytics data
+ * @returns Copy of current analytics data
+ */
+export function getAnalytics() {
+    return JSON.parse(JSON.stringify(analytics));
+}
+/**
+ * Reset analytics data
+ */
+export function resetAnalytics() {
+    analytics.impressions.total = 0;
+    analytics.impressions.byEndpoint = {};
+    analytics.impressions.byDate = {};
+    analytics.urlClicks.total = 0;
+    analytics.urlClicks.byUrl = {};
+    logger.info('Sponsor analytics data reset');
+}

package/build/utils/sponsor-service.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Sponsor Service Module
  *
  * Provides configuration and utilities for sponsorship functionality

package/build/utils/sponsor-utils.js

@@ -0,0 +1,57 @@
+/**
+ * Sponsor Utility Functions
+ *
+ * This module provides utilities for adding sponsor information to responses.
+ */
+import config from '../config.js';
+import { trackImpression, generateTrackingUrl, trackUrlGenerated } from './sponsor-analytics.js';
+/**
+ * Generate a sponsor message to be included in task responses
+ *
+ * @param source The source/endpoint requesting the sponsor message
+ * @returns Object containing sponsor message and URL, or null if sponsor messages are disabled
+ */
+export function getSponsorMessage(source = 'unknown') {
+    // Skip if sponsor message is disabled
+    if (!config.enableSponsorMessage) {
+        return null;
+    }
+    // Generate tracking URL
+    const trackingUrl = generateTrackingUrl(config.sponsorUrl, source);
+    trackUrlGenerated(trackingUrl);
+    return {
+        message: "❤️ Support this project: If you find this integration valuable, please consider sponsoring the developer.",
+        url: trackingUrl
+    };
+}
+/**
+ * Enhances a task response with sponsor information if enabled
+ *
+ * @param taskResponse The original task response to enhance
+ * @param source The source/endpoint of the response
+ * @returns Enhanced task response with sponsor information
+ */
+export function enhanceResponseWithSponsor(taskResponse, source = 'unknown') {
+    // Skip if sponsor message is disabled
+    if (!config.enableSponsorMessage) {
+        return taskResponse;
+    }
+    const sponsorInfo = getSponsorMessage(source);
+    if (!sponsorInfo) {
+        return taskResponse;
+    }
+    // Track the impression
+    trackImpression(source);
+    // Create a new response with sponsor information
+    const enhancedResponse = {
+        ...taskResponse,
+        content: [
+            ...(taskResponse.content || []),
+            {
+                type: "text",
+                text: `\n\n${sponsorInfo.message}\n${sponsorInfo.url}`
+            }
+        ]
+    };
+    return enhancedResponse;
+}

package/build/utils/token-utils.js

@@ -0,0 +1,49 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Token Utilities
+ *
+ * Functions for estimating token counts for LLM processing
+ */
+/**
+ * Simple heuristic to estimate token count from text
+ * Based on the approximate ratio of 4 characters per token for English text
+ *
+ * @param text Text to estimate tokens for
+ * @returns Estimated token count
+ */
+export function estimateTokensFromText(text) {
+    if (!text)
+        return 0;
+    // Characters per token varies by language, but ~4 chars per token
+    // is a reasonable approximation for English text
+    const CHARS_PER_TOKEN = 4;
+    // Add some overhead for non-text elements and special tokens
+    const OVERHEAD_FACTOR = 1.1;
+    return Math.ceil((text.length / CHARS_PER_TOKEN) * OVERHEAD_FACTOR);
+}
+/**
+ * Estimate tokens for a JSON object
+ *
+ * @param obj Object to estimate tokens for
+ * @returns Estimated token count
+ */
+export function estimateTokensFromObject(obj) {
+    // Convert to JSON string
+    const jsonString = JSON.stringify(obj);
+    // Use text estimation on the JSON string
+    // JSON has more special chars than plain text, so we adjust overhead
+    return Math.ceil(estimateTokensFromText(jsonString) * 1.2);
+}
+/**
+ * Check if an object would exceed the token limit when serialized to JSON
+ *
+ * @param obj Object to check
+ * @param tokenLimit Token limit to check against
+ * @returns Whether the object would exceed the token limit
+ */
+export function wouldExceedTokenLimit(obj, tokenLimit) {
+    const estimatedTokens = estimateTokensFromObject(obj);
+    return estimatedTokens > tokenLimit;
+}

package/package.json

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