@taazkareem/clickup-mcp-server 0.4.72 → 0.4.74

package/build/tools/utils.js

@@ -5,7 +5,5 @@
  */
 // 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/tools/workspace.js

@@ -5,6 +5,7 @@
  * It handles the workspace tool definitions and the implementation of their handlers.
  */
 import { Logger } from '../logger.js';
+import { sponsorService } from '../utils/sponsor-service.js';
 // Create a logger for workspace tools
 const logger = new Logger('WorkspaceTool');
 // Use the workspace service imported from the server
@@ -15,7 +16,18 @@ let workspaceService;
  */
 export const workspaceHierarchyTool = {
     name: 'get_workspace_hierarchy',
-    description: 'Get the complete workspace hierarchy including spaces, folders, and lists.',
+    description: `Purpose: Retrieve the complete workspace hierarchy including spaces, folders, and lists.
+
+Valid Usage:
+1. Call without parameters to get the full hierarchy
+
+Requirements:
+- No parameters required
+
+Notes:
+- Returns a tree structure showing all spaces, folders, and lists
+- Each item includes its name and ID
+- Use this to navigate the workspace and understand its organization`,
     inputSchema: {
         type: 'object',
         properties: {}
@@ -42,18 +54,14 @@ export async function handleGetWorkspaceHierarchy() {
     try {
         // Get workspace hierarchy from the workspace service
         const hierarchy = await workspaceService.getWorkspaceHierarchy();
-        const response = formatHierarchyResponse(hierarchy);
-        return response;
+        // Generate tree representation
+        const treeOutput = formatTreeOutput(hierarchy);
+        return sponsorService.createResponse({
+            hierarchy: treeOutput
+        }, true);
     }
     catch (error) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error getting workspace hierarchy: ${error.message}`
-                }
-            ]
-        };
+        return sponsorService.createErrorResponse(`Error getting workspace hierarchy: ${error.message}`);
     }
 }
 /**
@@ -61,27 +69,7 @@ export async function handleGetWorkspaceHierarchy() {
  */
 function formatHierarchyResponse(hierarchy) {
     try {
-        // 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);
-        const treeOutput = treeLines.join('\n');
+        const treeOutput = formatTreeOutput(hierarchy);
         return {
             content: [
                 {
@@ -102,3 +90,29 @@ function formatHierarchyResponse(hierarchy) {
         };
     }
 }
+/**
+ * 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 treeLines.join('\n');
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Sponsor Service Module
+ *
+ * Provides configuration and utilities for sponsorship functionality
+ */
+import { Logger } from '../logger.js';
+import config from '../config.js';
+// Create logger instance for this module
+const logger = new Logger('SponsorService');
+/**
+ * SponsorService - Provides sponsorship configuration and message handling
+ */
+export class SponsorService {
+    constructor() {
+        this.isEnabled = config.enableSponsorMessage;
+        this.sponsorUrl = config.sponsorUrl;
+        logger.info('SponsorService initialized', { enabled: this.isEnabled });
+    }
+    /**
+     * Get sponsor information (for documentation/reference purposes)
+     */
+    getSponsorInfo() {
+        return {
+            isEnabled: this.isEnabled,
+            url: this.sponsorUrl
+        };
+    }
+    /**
+     * Creates a response with optional sponsorship message
+     */
+    createResponse(data, includeSponsorMessage = false) {
+        const content = [];
+        if (this.isEnabled && includeSponsorMessage) {
+            content.push({
+                type: "text",
+                text: `❤️ Support this project by sponsoring the developer at ${this.sponsorUrl}\n\n`
+            });
+        }
+        content.push({
+            type: "text",
+            text: JSON.stringify(data, null, 2)
+        });
+        return { content };
+    }
+    /**
+     * Creates an error response
+     */
+    createErrorResponse(error, context) {
+        return this.createResponse({
+            error: typeof error === 'string' ? error : error.message,
+            ...context
+        });
+    }
+    /**
+     * Creates a bulk operation response with sponsorship message
+     */
+    createBulkResponse(result) {
+        return this.createResponse({
+            success: true,
+            total: result.totals.total,
+            successful: result.totals.success,
+            failed: result.totals.failure,
+            failures: result.failed.map((failure) => ({
+                id: failure.item?.id || failure.item,
+                error: failure.error.message
+            }))
+        }, true); // Always include sponsor message for bulk operations
+    }
+}
+// Export a singleton instance
+export const sponsorService = new SponsorService();

package/build/utils/sponsor-utils.js

@@ -4,36 +4,44 @@
  * 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() {
+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: config.sponsorUrl
+        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) {
+export function enhanceResponseWithSponsor(taskResponse, source = 'unknown') {
     // Skip if sponsor message is disabled
     if (!config.enableSponsorMessage) {
         return taskResponse;
     }
-    const sponsorInfo = getSponsorMessage();
+    const sponsorInfo = getSponsorMessage(source);
     if (!sponsorInfo) {
         return taskResponse;
     }
+    // Track the impression
+    trackImpression(source);
     // Create a new response with sponsor information
     const enhancedResponse = {
         ...taskResponse,

package/package.json

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