@alanse/clickup-multi-mcp-server 1.0.0

package/build/tools/task/utilities.js

@@ -0,0 +1,310 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp MCP Task Utilities
+ *
+ * This module provides utility functions for task-related operations including
+ * data formatting, validation, and resolution of IDs from names.
+ */
+import { formatDueDate } from '../utils.js';
+import { clickUpServices } from '../../services/shared.js';
+import { findListIDByName } from '../../tools/list.js';
+// Use shared services instance for ID resolution
+const { workspace: workspaceService, task: taskService } = clickUpServices;
+//=============================================================================
+// DATA FORMATTING UTILITIES
+//=============================================================================
+/**
+ * Formats task data for response
+ */
+export function formatTaskData(task, additional = {}) {
+    return {
+        id: task.id,
+        custom_id: task.custom_id,
+        name: task.name,
+        text_content: task.text_content,
+        description: task.description,
+        url: task.url,
+        status: task.status?.status || "Unknown",
+        status_color: task.status?.color,
+        orderindex: task.orderindex,
+        date_created: task.date_created,
+        date_updated: task.date_updated,
+        date_closed: task.date_closed,
+        creator: task.creator,
+        assignees: task.assignees,
+        watchers: task.watchers,
+        checklists: task.checklists,
+        tags: task.tags,
+        parent: task.parent,
+        priority: task.priority,
+        due_date: task.due_date ? formatDueDate(Number(task.due_date)) : undefined,
+        start_date: task.start_date ? formatDueDate(Number(task.start_date)) : undefined,
+        time_estimate: task.time_estimate,
+        time_spent: task.time_spent,
+        custom_fields: task.custom_fields,
+        dependencies: task.dependencies,
+        linked_tasks: task.linked_tasks,
+        team_id: task.team_id,
+        list: {
+            id: task.list.id,
+            name: task.list.name,
+            access: task.list.access
+        },
+        folder: task.folder ? {
+            id: task.folder.id,
+            name: task.folder.name,
+            hidden: task.folder.hidden,
+            access: task.folder.access
+        } : null,
+        space: {
+            id: task.space.id,
+            name: task.space.name
+        },
+        ...additional
+    };
+}
+//=============================================================================
+// TASK ID DETECTION UTILITIES
+//=============================================================================
+/**
+ * Detects if a task ID is a custom task ID based on common patterns
+ * Custom task IDs typically:
+ * - Contain hyphens (e.g., "DEV-1234", "PROJ-456")
+ * - Have uppercase prefixes followed by numbers
+ * - Are not 9-character alphanumeric strings (regular ClickUp task IDs)
+ *
+ * @param taskId The task ID to check
+ * @returns true if the ID appears to be a custom task ID
+ */
+export function isCustomTaskId(taskId) {
+    if (!taskId || typeof taskId !== 'string') {
+        return false;
+    }
+    // Trim whitespace
+    taskId = taskId.trim();
+    // Regular ClickUp task IDs are typically 9 characters, alphanumeric
+    // Custom task IDs usually have different patterns
+    // Check if it's a standard 9-character ClickUp ID (letters and numbers only)
+    const standardIdPattern = /^[a-zA-Z0-9]{9}$/;
+    if (standardIdPattern.test(taskId)) {
+        return false;
+    }
+    // Check for common custom task ID patterns:
+    // 1. Contains hyphens (most common pattern: PREFIX-NUMBER)
+    if (taskId.includes('-')) {
+        // Additional validation: should have letters before hyphen and numbers after
+        const hyphenPattern = /^[A-Za-z]+[-][0-9]+$/;
+        return hyphenPattern.test(taskId);
+    }
+    // 2. Contains underscores (another common pattern: PREFIX_NUMBER)
+    if (taskId.includes('_')) {
+        const underscorePattern = /^[A-Za-z]+[_][0-9]+$/;
+        return underscorePattern.test(taskId);
+    }
+    // 3. Contains uppercase letters followed by numbers (without separators)
+    const customIdPattern = /^[A-Z]+\d+$/;
+    if (customIdPattern.test(taskId)) {
+        return true;
+    }
+    // 4. Mixed case with numbers but not 9 characters (less common)
+    const mixedCasePattern = /^[A-Za-z]+\d+$/;
+    if (mixedCasePattern.test(taskId) && taskId.length !== 9) {
+        return true;
+    }
+    // 5. Contains dots (some organizations use PROJECT.TASK format)
+    if (taskId.includes('.')) {
+        const dotPattern = /^[A-Za-z]+[.][0-9]+$/;
+        return dotPattern.test(taskId);
+    }
+    // If none of the patterns match, assume it's a regular task ID
+    return false;
+}
+/**
+ * Validates task identification parameters
+ *
+ * @param params - Task identification parameters
+ * @param options - Validation options
+ * @returns Validation result with error message if any
+ */
+export function validateTaskIdentification(params, options = {}) {
+    const { taskId, taskName, customTaskId, listName } = params;
+    const { requireTaskId = false, useGlobalLookup = true } = options;
+    // If taskId is required, it must be provided
+    if (requireTaskId && !taskId) {
+        return {
+            isValid: false,
+            errorMessage: 'Task ID is required for this operation'
+        };
+    }
+    // At least one identification method must be provided
+    if (!taskId && !taskName && !customTaskId) {
+        return {
+            isValid: false,
+            errorMessage: 'Either taskId, taskName, or customTaskId must be provided to identify the task'
+        };
+    }
+    // When using taskName without global lookup, listName is required
+    if (taskName && !taskId && !customTaskId && !useGlobalLookup && !listName) {
+        return {
+            isValid: false,
+            errorMessage: 'When identifying a task by name, you must also provide the listName parameter'
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Validates list identification parameters
+ * Ensures either listId or listName is provided
+ */
+export function validateListIdentification(listId, listName) {
+    if (!listId && !listName) {
+        throw new Error("Either listId or listName must be provided");
+    }
+}
+/**
+ * Validates task update data
+ * Ensures at least one update field is provided
+ */
+export function validateTaskUpdateData(updateData) {
+    // Validate custom_fields if provided
+    if (updateData.custom_fields) {
+        if (!Array.isArray(updateData.custom_fields)) {
+            throw new Error("custom_fields must be an array");
+        }
+        for (const field of updateData.custom_fields) {
+            if (!field.id || field.value === undefined) {
+                throw new Error("Each custom field must have both id and value properties");
+            }
+        }
+    }
+    // Ensure there's at least one field to update
+    if (Object.keys(updateData).length === 0) {
+        throw new Error("At least one field to update must be provided");
+    }
+}
+/**
+ * Validate bulk task array and task identification
+ * @param tasks Array of tasks to validate
+ * @param operation The bulk operation type ('create', 'update', 'move', 'delete')
+ */
+export function validateBulkTasks(tasks, operation = 'update') {
+    if (!Array.isArray(tasks) || tasks.length === 0) {
+        throw new Error("tasks must be a non-empty array");
+    }
+    tasks.forEach((task, index) => {
+        if (!task || typeof task !== 'object') {
+            throw new Error(`Task at index ${index} must be an object`);
+        }
+        // Skip task identification validation for create operations
+        if (operation === 'create') {
+            return;
+        }
+        // For bulk operations, require listName when using taskName
+        if (task.taskName && !task.listName) {
+            throw new Error(`Task at index ${index} using taskName must also provide listName`);
+        }
+        // At least one identifier is required for non-create operations
+        if (!task.taskId && !task.taskName && !task.customTaskId) {
+            throw new Error(`Task at index ${index} must provide either taskId, taskName + listName, or customTaskId`);
+        }
+    });
+}
+/**
+ * Parse options for bulk operations
+ */
+export function parseBulkOptions(rawOptions) {
+    if (typeof rawOptions === 'string') {
+        try {
+            return JSON.parse(rawOptions);
+        }
+        catch (error) {
+            return undefined;
+        }
+    }
+    return rawOptions;
+}
+/**
+ * Resolves a list ID from either direct ID or name
+ * Handles validation and throws appropriate errors
+ */
+export async function resolveListIdWithValidation(listId, listName) {
+    // Validate parameters
+    validateListIdentification(listId, listName);
+    // If listId is provided, use it directly
+    if (listId)
+        return listId;
+    // At this point we know we have listName (validation ensures this)
+    const listInfo = await findListIDByName(workspaceService, listName);
+    if (!listInfo) {
+        throw new Error(`List "${listName}" not found`);
+    }
+    return listInfo.id;
+}
+//=============================================================================
+// PATH EXTRACTION HELPER FUNCTIONS
+//=============================================================================
+/**
+ * Extract path from node to root
+ */
+export function extractPath(node) {
+    if (!node)
+        return '';
+    if (!node.parent)
+        return node.name;
+    return `${extractPath(node.parent)} > ${node.name}`;
+}
+/**
+ * Extract path from root to a specific node
+ */
+export function extractTreePath(root, targetId) {
+    if (!root)
+        return [];
+    // If this node is the target, return it in an array
+    if (root.id === targetId) {
+        return [root];
+    }
+    // Check children if they exist
+    if (root.children) {
+        for (const child of root.children) {
+            const path = extractTreePath(child, targetId);
+            if (path.length > 0) {
+                return [root, ...path];
+            }
+        }
+    }
+    // Not found in this branch
+    return [];
+}
+/**
+ * Get task ID from various identification methods
+ */
+export async function getTaskId(taskId, taskName, listName, customTaskId, requireId = false) {
+    // Validate task identification
+    const validationResult = validateTaskIdentification({ taskId, taskName, listName, customTaskId }, { requireTaskId: requireId, useGlobalLookup: true });
+    if (!validationResult.isValid) {
+        throw new Error(validationResult.errorMessage);
+    }
+    try {
+        const result = await taskService.findTasks({
+            taskId,
+            customTaskId,
+            taskName,
+            listName,
+            allowMultipleMatches: false,
+            useSmartDisambiguation: true,
+            includeFullDetails: false
+        });
+        if (!result || Array.isArray(result)) {
+            throw new Error(`Task not found with the provided identification`);
+        }
+        return result.id;
+    }
+    catch (error) {
+        if (error.message.includes('Multiple tasks found')) {
+            throw new Error(`Multiple tasks found with name "${taskName}". Please provide list name to disambiguate.`);
+        }
+        throw error;
+    }
+}

package/build/tools/task/workspace-operations.js

@@ -0,0 +1,258 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp MCP Workspace Task Operations
+ *
+ * This module defines tools for workspace-wide task operations, including
+ * filtering tasks across the entire workspace with tag-based filtering.
+ */
+/**
+ * Tool definition for getting workspace tasks
+ */
+export const getWorkspaceTasksTool = {
+    name: "get_workspace_tasks",
+    description: `Purpose: Retrieve tasks from across the entire workspace with powerful filtering options, including tag-based filtering.
+
+Valid Usage:
+1. Apply any combination of filters (tags, lists, folders, spaces, statuses, etc.)
+2. Use pagination to manage large result sets
+3. Include subtasks by setting subtasks=true
+
+Requirements:
+- At least one filter parameter is REQUIRED (tags, list_ids, folder_ids, space_ids, statuses, assignees, or date filters)
+- Pagination parameters (page, order_by, reverse) alone are not considered filters
+
+Notes:
+- Provides workspace-wide task access (unlike get_tasks which only searches in one list)
+- Returns complete task details including descriptions, assignees, custom fields, and all metadata
+- Tag filtering is especially useful for cross-list organization (e.g., "project-x", "blocker", "needs-review")
+- Combine multiple filters to narrow down your search scope
+- Use pagination for large result sets
+- Set subtasks=true to include subtask details in the response
+  IMPORTANT: subtasks=true enables subtasks to appear in results, but subtasks must still match your other filter criteria (tags, lists, etc.) to be returned. To see all subtasks of a specific task regardless of filters, use the get_task tool with subtasks=true instead.
+- Use the detail_level parameter to control the amount of data returned:
+  - "summary": Returns lightweight task data (name, status, list, tags)
+  - "detailed": Returns complete task data with all fields (DEFAULT if not specified)
+- Responses exceeding 50,000 tokens automatically switch to summary format to avoid hitting LLM token limits
+- **Enhanced List Filtering**: When list_ids are provided, the tool leverages ClickUp's Views API to include tasks that are *associated with* the specified lists, including tasks that have been added to multiple lists. This provides comprehensive coverage of all tasks related to your specified lists, not just tasks that were originally created in those lists.
+`,
+    parameters: {
+        type: 'object',
+        properties: {
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by tag names. Only tasks with ALL specified tags will be returned.'
+            },
+            list_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by list IDs. Narrows the search to specific lists.'
+            },
+            folder_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by folder IDs. Narrows the search to specific folders.'
+            },
+            space_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by space IDs. Narrows the search to specific spaces.'
+            },
+            statuses: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by status names (e.g., [\'To Do\', \'In Progress\']).'
+            },
+            assignees: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by assignee IDs.'
+            },
+            date_created_gt: {
+                type: 'number',
+                description: 'Filter for tasks created after this timestamp.'
+            },
+            date_created_lt: {
+                type: 'number',
+                description: 'Filter for tasks created before this timestamp.'
+            },
+            date_updated_gt: {
+                type: 'number',
+                description: 'Filter for tasks updated after this timestamp.'
+            },
+            date_updated_lt: {
+                type: 'number',
+                description: 'Filter for tasks updated before this timestamp.'
+            },
+            due_date_gt: {
+                type: 'number',
+                description: 'Filter for tasks with due date greater than this timestamp.'
+            },
+            due_date_lt: {
+                type: 'number',
+                description: 'Filter for tasks with due date less than this timestamp.'
+            },
+            include_closed: {
+                type: 'boolean',
+                description: 'Include closed tasks in the results.'
+            },
+            include_archived_lists: {
+                type: 'boolean',
+                description: 'Include tasks from archived lists.'
+            },
+            include_closed_lists: {
+                type: 'boolean',
+                description: 'Include tasks from closed lists.'
+            },
+            archived: {
+                type: 'boolean',
+                description: 'Include archived tasks in the results.'
+            },
+            order_by: {
+                type: 'string',
+                enum: ['id', 'created', 'updated', 'due_date'],
+                description: 'Sort field for ordering results.'
+            },
+            reverse: {
+                type: 'boolean',
+                description: 'Reverse sort order (descending).'
+            },
+            page: {
+                type: 'number',
+                description: 'Page number for pagination (0-based).'
+            },
+            detail_level: {
+                type: 'string',
+                enum: ['summary', 'detailed'],
+                description: 'Level of detail to return. Use summary for lightweight responses or detailed for full task data. If not specified, defaults to "detailed".'
+            },
+            subtasks: {
+                type: 'boolean',
+                description: 'Include subtasks in the response. Set to true to retrieve subtask details for all returned tasks. Note: subtasks must still match your other filter criteria to appear in results.'
+            },
+            include_subtasks: {
+                type: 'boolean',
+                description: 'Alternative parameter for including subtasks (legacy support).'
+            },
+            include_compact_time_entries: {
+                type: 'boolean',
+                description: 'Include compact time entry data in the response.'
+            },
+            custom_fields: {
+                type: 'object',
+                description: 'Filter by custom field values. Provide as key-value pairs where keys are custom field IDs.'
+            }
+        }
+    },
+    inputSchema: {
+        type: 'object',
+        properties: {
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by tag names. Only tasks with ALL specified tags will be returned.'
+            },
+            list_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by list IDs. Narrows the search to specific lists.'
+            },
+            folder_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by folder IDs. Narrows the search to specific folders.'
+            },
+            space_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by space IDs. Narrows the search to specific spaces.'
+            },
+            statuses: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by status names (e.g., [\'To Do\', \'In Progress\']).'
+            },
+            assignees: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Filter tasks by assignee IDs.'
+            },
+            date_created_gt: {
+                type: 'number',
+                description: 'Filter for tasks created after this timestamp.'
+            },
+            date_created_lt: {
+                type: 'number',
+                description: 'Filter for tasks created before this timestamp.'
+            },
+            date_updated_gt: {
+                type: 'number',
+                description: 'Filter for tasks updated after this timestamp.'
+            },
+            date_updated_lt: {
+                type: 'number',
+                description: 'Filter for tasks updated before this timestamp.'
+            },
+            due_date_gt: {
+                type: 'number',
+                description: 'Filter for tasks with due date greater than this timestamp.'
+            },
+            due_date_lt: {
+                type: 'number',
+                description: 'Filter for tasks with due date less than this timestamp.'
+            },
+            include_closed: {
+                type: 'boolean',
+                description: 'Include closed tasks in the results.'
+            },
+            include_archived_lists: {
+                type: 'boolean',
+                description: 'Include tasks from archived lists.'
+            },
+            include_closed_lists: {
+                type: 'boolean',
+                description: 'Include tasks from closed lists.'
+            },
+            archived: {
+                type: 'boolean',
+                description: 'Include archived tasks in the results.'
+            },
+            order_by: {
+                type: 'string',
+                enum: ['id', 'created', 'updated', 'due_date'],
+                description: 'Sort field for ordering results.'
+            },
+            reverse: {
+                type: 'boolean',
+                description: 'Reverse sort order (descending).'
+            },
+            page: {
+                type: 'number',
+                description: 'Page number for pagination (0-based).'
+            },
+            detail_level: {
+                type: 'string',
+                enum: ['summary', 'detailed'],
+                description: 'Level of detail to return. Use summary for lightweight responses or detailed for full task data. If not specified, defaults to "detailed".'
+            },
+            subtasks: {
+                type: 'boolean',
+                description: 'Include subtasks in the response. Set to true to retrieve subtask details for all returned tasks. Note: subtasks must still match your other filter criteria to appear in results.'
+            },
+            include_subtasks: {
+                type: 'boolean',
+                description: 'Alternative parameter for including subtasks (legacy support).'
+            },
+            include_compact_time_entries: {
+                type: 'boolean',
+                description: 'Include compact time entry data in the response.'
+            },
+            custom_fields: {
+                type: 'object',
+                description: 'Filter by custom field values. Provide as key-value pairs where keys are custom field IDs.'
+            }
+        }
+    }
+};

package/build/tools/tool-enhancer.js

@@ -0,0 +1,37 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Tool Enhancer Utilities
+ *
+ * This module provides utilities to enhance existing tool definitions with workspace support.
+ */
+import { workspaceParameter } from './workspace-helper.js';
+/**
+ * Enhance a tool definition with workspace parameter
+ * @param tool - Original tool definition
+ * @returns Enhanced tool with workspace parameter
+ */
+export function enhanceToolWithWorkspace(tool) {
+    // Clone the tool to avoid modifying the original
+    const enhanced = {
+        ...tool,
+        inputSchema: {
+            type: 'object',
+            ...(tool.inputSchema || {}),
+            properties: {
+                ...(tool.inputSchema?.properties || {}),
+                ...workspaceParameter
+            }
+        }
+    };
+    return enhanced;
+}
+/**
+ * Enhance multiple tools with workspace parameter
+ * @param tools - Array of tool definitions
+ * @returns Array of enhanced tools
+ */
+export function enhanceToolsWithWorkspace(tools) {
+    return tools.map(enhanceToolWithWorkspace);
+}

package/build/tools/utils.js

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+// Re-export date utilities
+export { getRelativeTimestamp, parseDueDate, formatDueDate, formatRelativeTime } from '../utils/date-utils.js';
+// Re-export resolver utilities
+export { resolveListId } from '../utils/resolver-utils.js';

package/build/tools/workspace-helper.js

@@ -0,0 +1,44 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Workspace Helper Utilities
+ *
+ * This module provides helper functions for workspace-aware tool operations.
+ */
+import { getClickUpServices } from '../services/shared.js';
+import { getAvailableWorkspaces } from '../config.js';
+/**
+ * Common workspace parameter schema for all tools
+ */
+export const workspaceParameter = {
+    workspace: {
+        type: 'string',
+        description: 'Workspace identifier (optional, uses default if not specified)',
+        optional: true
+    }
+};
+/**
+ * Get services for a specific workspace from tool parameters
+ * @param params - Tool parameters that may contain workspace property
+ * @returns ClickUp services instance for the specified or default workspace
+ */
+export function getServicesForWorkspace(params) {
+    try {
+        return getClickUpServices(params.workspace);
+    }
+    catch (error) {
+        // Enhance error message with available workspaces
+        const available = getAvailableWorkspaces().join(', ');
+        throw new Error(`${error.message}\nAvailable workspaces: ${available}`);
+    }
+}
+/**
+ * Extract workspace ID from parameters and remove it before passing to service methods
+ * @param params - Tool parameters
+ * @returns Tuple of [workspace ID or undefined, params without workspace]
+ */
+export function extractWorkspace(params) {
+    const { workspace, ...rest } = params;
+    return [workspace, rest];
+}