@taazkareem/clickup-mcp-server 0.6.0 → 0.6.2

package/build/services/clickup/tag.js

@@ -0,0 +1,190 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp Tag Service
+ *
+ * Provides access to ClickUp API endpoints for tag management:
+ * - Space tags (get, create, update, delete)
+ * - Task tags (add, remove)
+ */
+import { BaseClickUpService } from './base.js';
+/**
+ * ClickUp Tag Service class for managing tags
+ */
+export class ClickUpTagService extends BaseClickUpService {
+    /**
+     * Get all tags in a space
+     * @param spaceId - ID of the space to get tags from
+     * @returns Promise with tags array
+     */
+    async getSpaceTags(spaceId) {
+        try {
+            this.logger.debug(`Getting tags for space: ${spaceId}`);
+            const response = await this.client.get(`/space/${spaceId}/tag`);
+            return {
+                success: true,
+                data: response.data.tags
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to get tags for space: ${spaceId}`, error);
+            return {
+                success: false,
+                error: {
+                    message: error.message || 'Failed to get space tags',
+                    code: error.code,
+                    details: error.data
+                }
+            };
+        }
+    }
+    /**
+     * Create a new tag in a space
+     * @param spaceId - ID of the space
+     * @param tagData - Tag data (name, background color, foreground color)
+     * @returns Promise with created tag
+     */
+    async createSpaceTag(spaceId, tagData) {
+        try {
+            this.logger.debug(`Creating tag "${tagData.tag_name}" in space: ${spaceId}`);
+            // Send tag data wrapped in a 'tag' object
+            const response = await this.client.post(`/space/${spaceId}/tag`, {
+                tag: {
+                    name: tagData.tag_name,
+                    tag_bg: tagData.tag_bg,
+                    tag_fg: tagData.tag_fg
+                }
+            });
+            return {
+                success: true,
+                data: response.data.tag
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to create tag in space: ${spaceId}`, error);
+            return {
+                success: false,
+                error: {
+                    message: error.message || 'Failed to create space tag',
+                    code: error.code,
+                    details: error.data
+                }
+            };
+        }
+    }
+    /**
+     * Update an existing tag in a space
+     * @param spaceId - ID of the space
+     * @param tagName - Current name of the tag to update
+     * @param updateData - Tag data to update (name, colors)
+     * @returns Promise with updated tag
+     */
+    async updateSpaceTag(spaceId, tagName, updateData) {
+        try {
+            this.logger.debug(`Updating tag "${tagName}" in space: ${spaceId}`);
+            // Encode the tag name in the URL
+            const encodedTagName = encodeURIComponent(tagName);
+            const response = await this.client.put(`/space/${spaceId}/tag/${encodedTagName}`, updateData);
+            return {
+                success: true,
+                data: response.data.tag
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to update tag "${tagName}" in space: ${spaceId}`, error);
+            return {
+                success: false,
+                error: {
+                    message: error.message || 'Failed to update space tag',
+                    code: error.code,
+                    details: error.data
+                }
+            };
+        }
+    }
+    /**
+     * Delete a tag from a space
+     * @param spaceId - ID of the space
+     * @param tagName - Name of the tag to delete
+     * @returns Promise with success status
+     */
+    async deleteSpaceTag(spaceId, tagName) {
+        try {
+            this.logger.debug(`Deleting tag "${tagName}" from space: ${spaceId}`);
+            // Encode the tag name in the URL
+            const encodedTagName = encodeURIComponent(tagName);
+            await this.client.delete(`/space/${spaceId}/tag/${encodedTagName}`);
+            return {
+                success: true
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to delete tag "${tagName}" from space: ${spaceId}`, error);
+            return {
+                success: false,
+                error: {
+                    message: error.message || 'Failed to delete space tag',
+                    code: error.code,
+                    details: error.data
+                }
+            };
+        }
+    }
+    /**
+     * Add a tag to a task
+     * @param taskId - ID of the task
+     * @param tagName - Name of the tag to add
+     * @returns Promise with success status
+     */
+    async addTagToTask(taskId, tagName) {
+        try {
+            this.logger.debug(`Adding tag "${tagName}" to task: ${taskId}`);
+            // Encode the tag name in the URL
+            const encodedTagName = encodeURIComponent(tagName);
+            await this.client.post(`/task/${taskId}/tag/${encodedTagName}`, {});
+            return {
+                success: true
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to add tag "${tagName}" to task: ${taskId}`, error);
+            return {
+                success: false,
+                error: {
+                    message: error.message || 'Failed to add tag to task',
+                    code: error.code,
+                    details: error.data
+                }
+            };
+        }
+    }
+    /**
+     * Remove a tag from a task
+     * @param taskId - ID of the task
+     * @param tagName - Name of the tag to remove
+     * @returns Promise with success status
+     */
+    async removeTagFromTask(taskId, tagName) {
+        try {
+            this.logger.debug(`Removing tag "${tagName}" from task: ${taskId}`);
+            // Encode the tag name in the URL
+            const encodedTagName = encodeURIComponent(tagName);
+            await this.client.delete(`/task/${taskId}/tag/${encodedTagName}`);
+            return {
+                success: true
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to remove tag "${tagName}" from task: ${taskId}`, error);
+            return {
+                success: false,
+                error: {
+                    message: error.message || 'Failed to remove tag from task',
+                    code: error.code,
+                    details: error.data
+                }
+            };
+        }
+    }
+}

package/build/services/clickup/task.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * ClickUp Task Service
  *
  * Handles all operations related to tasks in ClickUp, including:
@@ -10,6 +13,7 @@
  */
 import { BaseClickUpService, ErrorCode, ClickUpServiceError } from './base.js';
 import { ListService } from './list.js';
+import { estimateTokensFromObject, wouldExceedTokenLimit } from '../../utils/token-utils.js';
 export class TaskService extends BaseClickUpService {
     constructor(apiKey, teamId, baseUrl, workspaceService) {
         super(apiKey, teamId, baseUrl);
@@ -59,6 +63,27 @@ export class TaskService extends BaseClickUpService {
         if (filters.assignees && filters.assignees.length > 0) {
             filters.assignees.forEach(assignee => params.append('assignees[]', assignee));
         }
+        // Team tasks endpoint specific parameters
+        if (filters.tags && filters.tags.length > 0) {
+            filters.tags.forEach(tag => params.append('tags[]', tag));
+        }
+        if (filters.list_ids && filters.list_ids.length > 0) {
+            filters.list_ids.forEach(id => params.append('list_ids[]', id));
+        }
+        if (filters.folder_ids && filters.folder_ids.length > 0) {
+            filters.folder_ids.forEach(id => params.append('folder_ids[]', id));
+        }
+        if (filters.space_ids && filters.space_ids.length > 0) {
+            filters.space_ids.forEach(id => params.append('space_ids[]', id));
+        }
+        if (filters.archived !== undefined)
+            params.append('archived', String(filters.archived));
+        if (filters.include_closed_lists !== undefined)
+            params.append('include_closed_lists', String(filters.include_closed_lists));
+        if (filters.include_archived_lists !== undefined)
+            params.append('include_archived_lists', String(filters.include_archived_lists));
+        if (filters.include_compact_time_entries !== undefined)
+            params.append('include_compact_time_entries', String(filters.include_compact_time_entries));
         // Date filters
         if (filters.due_date_gt)
             params.append('due_date_gt', String(filters.due_date_gt));
@@ -560,4 +585,117 @@ export class TaskService extends BaseClickUpService {
             throw this.handleError(error, `Failed to upload attachment from URL to task ${taskId}`);
         }
     }
+    /**
+     * Format task data for summary view
+     * @param task The task to format
+     * @returns TaskSummary object
+     */
+    formatTaskSummary(task) {
+        return {
+            id: task.id,
+            name: task.name,
+            status: task.status.status,
+            list: {
+                id: task.list.id,
+                name: task.list.name
+            },
+            due_date: task.due_date,
+            url: task.url,
+            priority: this.extractPriorityValue(task),
+            tags: task.tags.map(tag => ({
+                name: tag.name,
+                tag_bg: tag.tag_bg,
+                tag_fg: tag.tag_fg
+            }))
+        };
+    }
+    /**
+     * Estimates token count for a task in JSON format
+     * @param task ClickUp task
+     * @returns Estimated token count
+     */
+    estimateTaskTokens(task) {
+        return estimateTokensFromObject(task);
+    }
+    /**
+     * Get filtered tasks across the entire team/workspace using tags and other filters
+     * @param filters Task filters to apply including tags, list/folder/space filtering
+     * @returns Either a DetailedTaskResponse or WorkspaceTasksResponse depending on detail_level
+     */
+    async getWorkspaceTasks(filters = {}) {
+        try {
+            this.logOperation('getWorkspaceTasks', { filters });
+            const params = this.buildTaskFilterParams(filters);
+            const response = await this.client.get(`/team/${this.teamId}/task`, {
+                params
+            });
+            const tasks = response.data.tasks;
+            const totalCount = tasks.length; // Note: This is just the current page count
+            const hasMore = totalCount === 100; // ClickUp returns max 100 tasks per page
+            const nextPage = (filters.page || 0) + 1;
+            // If the estimated token count exceeds 50,000 or detail_level is 'summary',
+            // return summary format for efficiency and to avoid hitting token limits
+            const TOKEN_LIMIT = 50000;
+            // Estimate tokens for the full response
+            let tokensExceedLimit = false;
+            if (filters.detail_level !== 'summary' && tasks.length > 0) {
+                // We only need to check token count if detailed was requested
+                // For summary requests, we always return summary format
+                // First check with a sample task - if one task exceeds the limit, we definitely need summary
+                const sampleTask = tasks[0];
+                // Check if all tasks would exceed the token limit
+                const estimatedTokensPerTask = this.estimateTaskTokens(sampleTask);
+                const estimatedTotalTokens = estimatedTokensPerTask * tasks.length;
+                // Add 10% overhead for the response wrapper
+                tokensExceedLimit = estimatedTotalTokens * 1.1 > TOKEN_LIMIT;
+                // Double-check with more precise estimation if we're close to the limit
+                if (!tokensExceedLimit && estimatedTotalTokens * 1.1 > TOKEN_LIMIT * 0.8) {
+                    // More precise check - build a representative sample and extrapolate
+                    tokensExceedLimit = wouldExceedTokenLimit({ tasks, total_count: totalCount, has_more: hasMore, next_page: nextPage }, TOKEN_LIMIT);
+                }
+            }
+            // Determine if we should return summary or detailed based on request and token limit
+            const shouldUseSummary = filters.detail_level === 'summary' || tokensExceedLimit;
+            this.logOperation('getWorkspaceTasks', {
+                totalTasks: tasks.length,
+                estimatedTokens: tasks.reduce((count, task) => count + this.estimateTaskTokens(task), 0),
+                usingDetailedFormat: !shouldUseSummary,
+                requestedFormat: filters.detail_level || 'auto'
+            });
+            if (shouldUseSummary) {
+                return {
+                    summaries: tasks.map(task => this.formatTaskSummary(task)),
+                    total_count: totalCount,
+                    has_more: hasMore,
+                    next_page: nextPage
+                };
+            }
+            return {
+                tasks,
+                total_count: totalCount,
+                has_more: hasMore,
+                next_page: nextPage
+            };
+        }
+        catch (error) {
+            this.logOperation('getWorkspaceTasks', { error: error.message, status: error.response?.status });
+            throw this.handleError(error, 'Failed to get workspace tasks');
+        }
+    }
+    /**
+     * Get task summaries for lightweight retrieval
+     * @param filters Task filters to apply
+     * @returns WorkspaceTasksResponse with task summaries
+     */
+    async getTaskSummaries(filters = {}) {
+        return this.getWorkspaceTasks({ ...filters, detail_level: 'summary' });
+    }
+    /**
+     * Get detailed task data
+     * @param filters Task filters to apply
+     * @returns DetailedTaskResponse with full task data
+     */
+    async getTaskDetails(filters = {}) {
+        return this.getWorkspaceTasks({ ...filters, detail_level: 'detailed' });
+    }
 }

package/build/services/clickup/types.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Common type definitions for ClickUp API entities
  */
 // Helper function to validate and convert priority values

package/build/services/clickup/workspace.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * ClickUp Workspace Service Module
  *
  * Handles workspace hierarchy and space-related operations

package/build/services/shared.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Shared Services Module
  *
  * This module maintains singleton instances of services that should be shared

package/build/tools/bulk-tasks.js

@@ -0,0 +1,36 @@
+/**
+ * Alternative implementation for bulk tasks creation
+ */
+import { handleCreateBulkTasks } from './task.js';
+/**
+ * Alternative tool definition for bulk task creation to work around MCP validation issues
+ */
+export const createTasksBulkTool = {
+    name: "create_tasks_bulk",
+    description: "Create multiple tasks in a list efficiently. You MUST provide:\n1. An array of tasks with required properties\n2. Either listId or listName to specify the target list",
+    inputSchema: {
+        type: "object",
+        properties: {
+            listId: {
+                type: "string",
+                description: "ID of list for new tasks (preferred). Use this instead of listName if you have it."
+            },
+            listName: {
+                type: "string",
+                description: "Name of list for new tasks. Only use if you don't have listId."
+            },
+            tasks: {
+                // Define minimally to avoid validation issues
+                description: "Array of tasks to create. Each task must have at least a name."
+            }
+        },
+        required: ["tasks"]
+    }
+};
+/**
+ * Handler for create_tasks_bulk tool
+ */
+export async function handleCreateTasksBulk(parameters) {
+    // Use the same implementation as handleCreateBulkTasks
+    return handleCreateBulkTasks(parameters);
+}

package/build/tools/debug.js

@@ -0,0 +1,76 @@
+/**
+ * Debug Tools
+ *
+ * This module provides tools for debugging and monitoring the ClickUp MCP server.
+ */
+// In-memory log storage
+const DEBUG_LOGS = [];
+/**
+ * Log a message to the in-memory debug logs
+ */
+export function logDebug(message, level = 'info') {
+    const timestamp = new Date().toISOString();
+    DEBUG_LOGS.push({ timestamp, message, level });
+    // Optional: Also print to console for development
+    if (level === 'error') {
+        console.error(`[${timestamp}] ERROR: ${message}`);
+    }
+    else if (level === 'warn') {
+        console.warn(`[${timestamp}] WARN: ${message}`);
+    }
+    else {
+        console.log(`[${timestamp}] INFO: ${message}`);
+    }
+}
+/**
+ * Tool definition for checking debug logs
+ */
+export const checkDebugLogsTool = {
+    name: 'check_debug_logs',
+    description: 'Check the server debug logs collected since the server started.',
+    inputSchema: {
+        type: 'object',
+        properties: {}
+    }
+};
+/**
+ * Tool definition for clearing debug logs
+ */
+export const clearDebugLogsTool = {
+    name: 'clear_debug_logs',
+    description: 'Clear all server debug logs.',
+    inputSchema: {
+        type: 'object',
+        properties: {}
+    }
+};
+/**
+ * Handler for the check_debug_logs tool
+ */
+export function handleCheckDebugLogs() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: DEBUG_LOGS.length > 0
+                    ? DEBUG_LOGS.map(log => `[${log.timestamp}] [${log.level.toUpperCase()}] ${log.message}`).join('\n')
+                    : "No debug logs available."
+            }
+        ]
+    };
+}
+/**
+ * Handler for the clear_debug_logs tool
+ */
+export function handleClearDebugLogs() {
+    const count = DEBUG_LOGS.length;
+    DEBUG_LOGS.length = 0;
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Cleared ${count} debug log entries.`
+            }
+        ]
+    };
+}

package/build/tools/folder.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * ClickUp MCP Folder Tools
  *
  * This module defines folder-related tools for creating, retrieving,

package/build/tools/index.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * Tools Index
  *
  * This file exports all tool definitions and handlers for the ClickUp MCP server.
@@ -9,3 +12,4 @@ export * from './workspace.js';
 export * from './task/index.js';
 export * from './list.js';
 export * from './folder.js';
+export * from './tag.js';

package/build/tools/list.js

@@ -1,4 +1,7 @@
 /**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
  * ClickUp MCP List Tools
  *
  * This module defines list-related tools including creating, updating,

package/build/tools/logs.js

@@ -0,0 +1,55 @@
+/**
+ * Simple Logs Tool
+ *
+ * Provides a basic tool for reading server logs.
+ */
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+// Define the log file path - using __dirname to get absolute path
+const LOG_FILE = join(dirname(__dirname), 'server.log');
+// Tool definition
+export const checkLogsTool = {
+    name: "check_logs",
+    description: "Check server logs with optional filtering by log level",
+    parameters: {
+        type: "object",
+        properties: {
+            level: {
+                type: "string",
+                enum: ["TRACE", "DEBUG", "INFO", "WARN", "ERROR"],
+                description: "Filter logs by level"
+            },
+            limit: {
+                type: "number",
+                description: "Maximum number of log entries to return (default: 50)"
+            }
+        }
+    }
+};
+// Simple handler implementation using async/await with promises
+export async function handleCheckLogs(params) {
+    try {
+        // Read log file using promises
+        const content = await fs.readFile(LOG_FILE, 'utf-8');
+        // Split into lines and filter out empty lines
+        let lines = content.split('\n').filter(Boolean);
+        // Apply level filtering if specified
+        if (params?.level) {
+            lines = lines.filter(line => line.includes(`${params.level}:`));
+        }
+        // Apply limit (default to 50)
+        const limit = params?.limit || 50;
+        const result = lines.slice(-limit);
+        // Return results
+        return {
+            logs: result.length > 0 ? result : ['No matching logs found.']
+        };
+    }
+    catch (error) {
+        // Simple error handling
+        if (error.code === 'ENOENT') {
+            return { logs: ['Log file not found.'] };
+        }
+        return { logs: [`Error reading logs: ${error.message}`] };
+    }
+}