@taazkareem/clickup-mcp-server 0.4.74 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 # MCP Server
 A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.
 
-> 🚧 **Status Update:** -Added get_task_comments tool -Improved task name matching -Fixed workspace hierarchy display
+> 🚧 **Status Update:** -Added attach_task_file tool with support for local files, URLs, and base64 data, and create_task_comment tool
 
 <a href="https://glama.ai/mcp/servers/iwjvs2zy63">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/iwjvs2zy63/badge" alt="ClickUp Server MCP server" />
@@ -15,6 +15,7 @@ A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI appl
    - ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
    - Team ID from your ClickUp workspace URL
 2. Choose either hosted installation (sends webhooks) or NPX installation (downloads to local path and installs dependencies)
+3. Use natural language to manage your workspace!
 
 ## Smithery Installation (Quick Start)
 
@@ -52,17 +53,17 @@ Or use this npx command:
 ## Features
 
 - 🎯 **Task Management**
-  - Create, update, and delete individual tasks
+  - Create, retrieve, update, and delete tasks
   - Move and duplicate tasks between lists, spaces, and folders
-  - Create, update, move, and delete multiple tasks in bulk
+  - Single operation or bulk operation
   - View and modify task details and properties
   - Get task comments
   - Set due dates using natural language and relative time expressions
+  - Attach files to tasks using local file paths, URL, base64, or chunked uploads
 
 - 📂 **Workspace Organization**
   - Complete workspace hierarchy (spaces, folders, lists)
   - Tree structure with clear relationships
-  - Full CRUD operations for workspace components
   - Efficient path-based navigation
 
 - 🔄 **Integration Features**
@@ -83,6 +84,8 @@ Or use this npx command:
 | [get_tasks](docs/api-reference.md#task-management) | Get tasks from list | `listId`/`listName` |
 | [get_task](docs/api-reference.md#task-management) | Get task details | `taskId`/`taskName` |
 | [get_task_comments](docs/api-reference.md#task-management) | Get comments on a task | `taskId`/`taskName` |
+| [create_task_comment](docs/api-reference.md#task-management) | Add a comment to a task | `commentText`, (`taskId`/(`taskName`+`listName`)) |
+| [attach_task_file](docs/api-reference.md#task-management) | Attach file to a task | `taskId`/`taskName`, (`file_data` or `file_url`) |
 | [delete_task](docs/api-reference.md#task-management) | Remove task | `taskId`/`taskName` |
 | [delete_bulk_tasks](docs/api-reference.md#task-management) | Remove multiple tasks | `tasks[]` with IDs or names |
 | [move_task](docs/api-reference.md#task-management) | Move task | `taskId`/`taskName`, `listId`/`listName` |
@@ -126,6 +129,10 @@ If you find this project useful, please consider supporting:
 
 [![Sponsor TaazKareem](https://img.shields.io/badge/Sponsor-TaazKareem-orange?logo=github)](https://github.com/sponsors/TaazKareem)
 
+## Acknowledgements
+
+Special thanks to [ClickUp](https://clickup.com) for their excellent API and services that make this integration possible.
+
 ## Contributing
 
 Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

package/build/index.js

@@ -19,12 +19,6 @@
  * - Smart name-based lookups that eliminate the need for IDs
  * - Support for priorities, statuses, and due dates
  *
- * AI-Enhanced Capabilities:
- * - Task summarization and status grouping for project overviews
- * - Priority analysis and optimization for workload balancing
- * - Detailed task description generation with structured content
- * - Task relationship identification for dependency management
- *
  * Technical Features:
  * - Full markdown support for rich text content
  * - Secure credential handling through configuration

package/build/server.js

@@ -1,7 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { workspaceHierarchyTool, handleGetWorkspaceHierarchy } from "./tools/workspace.js";
-import { createTaskTool, updateTaskTool, moveTaskTool, duplicateTaskTool, getTaskTool, getTasksTool, deleteTaskTool, getTaskCommentsTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, handleCreateTask, handleUpdateTask, handleMoveTask, handleDuplicateTask, handleGetTasks, handleDeleteTask, handleGetTaskComments, handleCreateBulkTasks, handleUpdateBulkTasks, handleMoveBulkTasks, handleDeleteBulkTasks, handleGetTask } from "./tools/task/index.js";
+import { createTaskTool, updateTaskTool, moveTaskTool, duplicateTaskTool, getTaskTool, getTasksTool, deleteTaskTool, getTaskCommentsTool, createTaskCommentTool, createBulkTasksTool, updateBulkTasksTool, moveBulkTasksTool, deleteBulkTasksTool, attachTaskFileTool, handleCreateTask, handleUpdateTask, handleMoveTask, handleDuplicateTask, handleGetTasks, handleDeleteTask, handleGetTaskComments, handleCreateTaskComment, handleCreateBulkTasks, handleUpdateBulkTasks, handleMoveBulkTasks, handleDeleteBulkTasks, handleGetTask, handleAttachTaskFile } from "./tools/task/index.js";
 import { createListTool, handleCreateList, createListInFolderTool, handleCreateListInFolder, getListTool, handleGetList, updateListTool, handleUpdateList, deleteListTool, handleDeleteList } from "./tools/list.js";
 import { createFolderTool, handleCreateFolder, getFolderTool, handleGetFolder, updateFolderTool, handleUpdateFolder, deleteFolderTool, handleDeleteFolder } from "./tools/folder.js";
 import { Logger } from "./logger.js";
@@ -15,7 +15,7 @@ const { workspace } = clickUpServices;
  */
 export const server = new Server({
     name: "clickup-mcp-server",
-    version: "0.4.72",
+    version: "0.5.0",
 }, {
     capabilities: {
         tools: {},
@@ -41,6 +41,8 @@ export function configureServer() {
                 duplicateTaskTool,
                 deleteTaskTool,
                 getTaskCommentsTool,
+                createTaskCommentTool,
+                attachTaskFileTool,
                 createBulkTasksTool,
                 updateBulkTasksTool,
                 moveBulkTasksTool,
@@ -59,7 +61,7 @@ export function configureServer() {
     });
     // Register CallTool handler with proper logging
     logger.info("Registering tool handlers", {
-        toolCount: 22,
+        toolCount: 23,
         categories: ["workspace", "task", "list", "folder"]
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -89,6 +91,10 @@ export function configureServer() {
                     return handleDeleteTask(params);
                 case "get_task_comments":
                     return handleGetTaskComments(params);
+                case "create_task_comment":
+                    return handleCreateTaskComment(params);
+                case "attach_task_file":
+                    return handleAttachTaskFile(params);
                 case "create_bulk_tasks":
                     return handleCreateBulkTasks(params);
                 case "update_bulk_tasks":

package/build/services/clickup/task.js

@@ -204,6 +204,32 @@ export class TaskService extends BaseClickUpService {
             throw this.handleError(error, `Failed to get task ${taskId}`);
         }
     }
+    /**
+     * Get a specific task by its custom ID
+     * @param customTaskId The custom ID of the task (e.g., "DEV-1234")
+     * @param listId Optional list ID to search within for better performance
+     * @returns The task details
+     */
+    async getTaskByCustomId(customTaskId, listId) {
+        this.logOperation('getTaskByCustomId', { customTaskId, listId });
+        try {
+            return await this.makeRequest(async () => {
+                // Build query with custom_task_ids=true
+                const params = new URLSearchParams({ custom_task_ids: 'true' });
+                // Use the ClickUp API endpoint for retrieving tasks by ID
+                // With custom_task_ids=true parameter, it will treat the ID as a custom ID
+                const response = await this.client.get(`/task/${customTaskId}?${params.toString()}`);
+                return response.data;
+            });
+        }
+        catch (error) {
+            // Enhance error message for custom ID lookups
+            if (error?.response?.status === 404) {
+                throw this.handleError(error, `Task with custom ID ${customTaskId} not found`);
+            }
+            throw this.handleError(error, `Failed to get task with custom ID ${customTaskId}`);
+        }
+    }
     /**
      * Update an existing task
      * @param taskId ID of the task to update
@@ -347,6 +373,67 @@ export class TaskService extends BaseClickUpService {
             throw this.handleError(error, 'Failed to get task comments');
         }
     }
+    /**
+     * Create a comment on a task
+     *
+     * @param taskId ID of the task to comment on
+     * @param commentText Text content of the comment
+     * @param notifyAll Whether to notify all assignees
+     * @param assignee Optional user ID to assign the comment to
+     * @returns The created comment
+     */
+    async createTaskComment(taskId, commentText, notifyAll = false, assignee) {
+        this.logOperation('createTaskComment', { taskId, commentText, notifyAll, assignee });
+        try {
+            const payload = {
+                comment_text: commentText,
+                notify_all: notifyAll
+            };
+            if (assignee) {
+                payload.assignee = assignee;
+            }
+            // Make the request directly without using makeRequest for better error handling
+            const response = await this.client.post(`/task/${taskId}/comment`, payload);
+            // Handle different response formats from ClickUp API
+            if (response.data) {
+                if (response.data.comment) {
+                    // Standard format: { comment: ClickUpComment }
+                    return response.data.comment;
+                }
+                else if (response.data.id && (response.data.comment_text || response.data.comment)) {
+                    // Direct format: the comment object itself
+                    return response.data;
+                }
+                else {
+                    // Fallback: construct a minimal valid comment object
+                    return {
+                        id: response.data.id || `custom-${Date.now()}`,
+                        comment: response.data.comment || commentText,
+                        comment_text: response.data.comment_text || commentText,
+                        user: response.data.user || { id: 0, username: 'Unknown', email: '', color: '' },
+                        date: response.data.date || new Date().toISOString(),
+                        resolved: false
+                    };
+                }
+            }
+            throw new Error('Invalid response from ClickUp API');
+        }
+        catch (error) {
+            // Check if comment might have been created despite error
+            if (error.response?.status === 200 || error.response?.status === 201) {
+                // Try to construct a comment object from what we know
+                return {
+                    id: `fallback-${Date.now()}`,
+                    comment: commentText,
+                    comment_text: commentText,
+                    user: { id: 0, username: 'Unknown', email: '', color: '' },
+                    date: new Date().toISOString(),
+                    resolved: false
+                };
+            }
+            throw this.handleError(error, 'Failed to create task comment');
+        }
+    }
     /**
      * Validate that a list exists
      *
@@ -368,4 +455,84 @@ export class TaskService extends BaseClickUpService {
             throw new ClickUpServiceError(`Failed to validate list existence: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.UNKNOWN, { listId });
         }
     }
+    /**
+     * Upload a file attachment to a ClickUp task
+     * @param taskId The ID of the task to attach the file to
+     * @param fileData The file data as a Buffer
+     * @param fileName The name of the file
+     * @returns Promise resolving to the attachment response from ClickUp
+     */
+    async uploadTaskAttachment(taskId, fileData, fileName) {
+        this.logOperation('uploadTaskAttachment', { taskId, fileName, fileSize: fileData.length });
+        try {
+            return await this.makeRequest(async () => {
+                // Create FormData for multipart/form-data upload
+                const FormData = (await import('form-data')).default;
+                const formData = new FormData();
+                // Add the file to the form data
+                formData.append('attachment', fileData, {
+                    filename: fileName,
+                    contentType: 'application/octet-stream' // Let ClickUp determine the content type
+                });
+                // Use the raw axios client for this request since we need to handle FormData
+                const response = await this.client.post(`/task/${taskId}/attachment`, formData, {
+                    headers: {
+                        ...formData.getHeaders(),
+                        'Authorization': this.apiKey
+                    }
+                });
+                return response.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to upload attachment to task ${taskId}`);
+        }
+    }
+    /**
+     * Upload a file attachment to a ClickUp task from a URL
+     * @param taskId The ID of the task to attach the file to
+     * @param fileUrl The URL of the file to download and attach
+     * @param fileName Optional file name (if not provided, it will be extracted from the URL)
+     * @param authHeader Optional authorization header for the URL
+     * @returns Promise resolving to the attachment response from ClickUp
+     */
+    async uploadTaskAttachmentFromUrl(taskId, fileUrl, fileName, authHeader) {
+        this.logOperation('uploadTaskAttachmentFromUrl', { taskId, fileUrl, fileName });
+        try {
+            return await this.makeRequest(async () => {
+                // Import required modules
+                const axios = (await import('axios')).default;
+                const FormData = (await import('form-data')).default;
+                // Download the file from the URL
+                const headers = {};
+                if (authHeader) {
+                    headers['Authorization'] = authHeader;
+                }
+                const response = await axios.get(fileUrl, {
+                    responseType: 'arraybuffer',
+                    headers
+                });
+                // Extract filename from URL if not provided
+                const actualFileName = fileName || fileUrl.split('/').pop() || 'downloaded-file';
+                // Create FormData for multipart/form-data upload
+                const formData = new FormData();
+                // Add the file to the form data
+                formData.append('attachment', Buffer.from(response.data), {
+                    filename: actualFileName,
+                    contentType: 'application/octet-stream'
+                });
+                // Upload the file to ClickUp
+                const uploadResponse = await this.client.post(`/task/${taskId}/attachment`, formData, {
+                    headers: {
+                        ...formData.getHeaders(),
+                        'Authorization': this.apiKey
+                    }
+                });
+                return uploadResponse.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to upload attachment from URL to task ${taskId}`);
+        }
+    }
 }

package/build/tools/task/attachments.js

@@ -0,0 +1,354 @@
+/**
+ * ClickUp MCP Task Attachment Tool
+ *
+ * This module implements a tool for attaching files to ClickUp tasks
+ * with automatic method selection based on file source and size.
+ */
+import { taskService } from '../../services/shared.js';
+import { validateTaskIdentification, resolveTaskIdWithValidation } from './utilities.js';
+import { sponsorService } from '../../utils/sponsor-service.js';
+// Session storage for chunked uploads (in-memory for demonstration)
+// In production, this should use a more persistent store
+const chunkSessions = new Map();
+// Clean up expired sessions periodically
+setInterval(() => {
+    const now = Date.now();
+    const expired = 24 * 60 * 60 * 1000; // 24 hours
+    for (const [token, session] of chunkSessions.entries()) {
+        if (now - session.timestamp > expired) {
+            chunkSessions.delete(token);
+            console.log(`Cleaned up expired upload session: ${token}`);
+        }
+    }
+}, 3600 * 1000); // Check every hour
+/**
+ * Single unified tool for attaching files to ClickUp tasks
+ */
+export const attachTaskFileTool = {
+    name: "attach_task_file",
+    description: `Purpose: Attaches a file to a ClickUp task.
+
+Valid Usage:
+1. Upload from base64: Provide file_data + file_name
+2. Upload from URL or local file: Provide file_url + optional file_name
+   - For web URLs: Use http:// or https:// URLs
+   - For local files: Use absolute file paths (starting with / or drive letter)
+3. For large files, advanced options are available via chunk_* parameters
+
+Requirements:
+- EITHER taskId OR (taskName + listName) is REQUIRED
+- EITHER file_data OR file_url is REQUIRED
+
+Notes:
+- The system automatically selects the best upload method based on file size and source
+- Base64 method has a 10MB size limit due to encoding overhead (file_data parameter)
+- URL method works for files hosted online (file_url parameter with http/https)
+- Local file method works with absolute paths only (file_url parameter with / or drive letter)
+- For large files, the system may use chunked uploading automatically`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "ID of the task to attach the file to. Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
+            },
+            taskName: {
+                type: "string",
+                description: "Name of the task to attach the file to. When using this parameter, you MUST also provide listName."
+            },
+            listName: {
+                type: "string",
+                description: "Name of the list containing the task. REQUIRED when using taskName."
+            },
+            file_name: {
+                type: "string",
+                description: "Name of the file to be attached (include the extension). Required when using file_data."
+            },
+            file_data: {
+                type: "string",
+                description: "Base64-encoded content of the file (without the data URL prefix)."
+            },
+            file_url: {
+                type: "string",
+                description: "DUAL PURPOSE PARAMETER: Either (1) a web URL starting with http/https to download a file from, OR (2) an absolute local file path starting with / or drive letter. DO NOT use relative paths."
+            },
+            auth_header: {
+                type: "string",
+                description: "Optional authorization header to use when downloading from a web URL (ignored for local files)."
+            },
+            // Advanced parameters for chunked uploads - usually not needed as chunking is automatic
+            chunk_index: {
+                type: "number",
+                description: "Optional: For advanced usage with large file chunking. The 0-based index of this chunk."
+            },
+            chunk_session: {
+                type: "string",
+                description: "Optional: For advanced usage with large file chunking. Session identifier from a previous chunk upload."
+            },
+            chunk_total: {
+                type: "number",
+                description: "Optional: For advanced usage with large file chunking. Total number of chunks expected."
+            },
+            chunk_is_last: {
+                type: "boolean",
+                description: "Optional: For advanced usage with large file chunking. Whether this is the final chunk."
+            }
+        },
+        required: [] // Will validate based on context in the handler
+    }
+};
+/**
+ * Handler function for the attachTaskFileTool
+ */
+async function attachTaskFileHandler(params) {
+    // Extract common parameters
+    const { taskId, taskName, listName, file_name, file_data, file_url, auth_header, chunk_total, chunk_size, chunk_index, session_id } = params;
+    // Validate task identification
+    validateTaskIdentification(params);
+    // Validate file source - either file_data or file_url must be provided
+    if (!file_data && !file_url && !session_id) {
+        throw new Error("Either file_data, file_url, or session_id must be provided");
+    }
+    // Resolve task ID
+    const resolvedTaskId = await resolveTaskIdWithValidation(taskId, taskName, listName);
+    try {
+        // CASE 1: Chunked upload continuation
+        if (session_id) {
+            return await handleChunkUpload(resolvedTaskId, session_id, chunk_index, file_data, chunk_total === chunk_index + 1);
+        }
+        // CASE 2: URL-based upload or local file path
+        if (file_url) {
+            // Check if it's a local file path
+            console.log(`Checking if path is local: ${file_url}`);
+            if (file_url.startsWith('/') || /^[A-Za-z]:\\/.test(file_url)) {
+                console.log(`Detected as local path, proceeding to handle: ${file_url}`);
+                return await handleLocalFileUpload(resolvedTaskId, file_url, file_name);
+            }
+            else if (file_url.startsWith('http://') || file_url.startsWith('https://')) {
+                console.log(`Detected as URL, proceeding with URL upload: ${file_url}`);
+                return await handleUrlUpload(resolvedTaskId, file_url, file_name, auth_header);
+            }
+            else {
+                throw new Error(`Invalid file_url format: "${file_url}". The file_url parameter must be either an absolute file path (starting with / or drive letter) or a web URL (starting with http:// or https://)`);
+            }
+        }
+        // CASE 3: Base64 upload (with automatic chunking for large files)
+        if (file_data) {
+            if (!file_name) {
+                throw new Error("file_name is required when using file_data");
+            }
+            // Check if we need to use chunking (file > 10MB)
+            const fileBuffer = Buffer.from(file_data, 'base64');
+            const fileSize = fileBuffer.length;
+            if (fileSize > 10 * 1024 * 1024) {
+                // For large files, start chunked upload process
+                return await startChunkedUpload(resolvedTaskId, file_name, fileBuffer);
+            }
+            else {
+                // For small files, upload directly
+                return await handleDirectUpload(resolvedTaskId, file_name, fileBuffer);
+            }
+        }
+        throw new Error("Invalid parameters: Unable to determine upload method");
+    }
+    catch (error) {
+        console.error(`Error attaching file to task:`, error);
+        throw error;
+    }
+}
+/**
+ * Handle direct upload for small files
+ */
+async function handleDirectUpload(taskId, fileName, fileBuffer) {
+    try {
+        // Call service method
+        const result = await taskService.uploadTaskAttachment(taskId, fileBuffer, fileName);
+        return {
+            success: true,
+            message: `File "${fileName}" successfully attached to task ${taskId}`,
+            attachment: result
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to upload file: ${error.message}`);
+    }
+}
+/**
+ * Handle URL-based upload
+ */
+async function handleUrlUpload(taskId, fileUrl, fileName, authHeader) {
+    try {
+        // Extract filename from URL if not provided
+        const extractedFileName = fileName || new URL(fileUrl).pathname.split('/').pop() || 'downloaded-file';
+        // Call service method
+        const result = await taskService.uploadTaskAttachmentFromUrl(taskId, fileUrl, extractedFileName, authHeader);
+        return {
+            success: true,
+            message: `File from "${fileUrl}" successfully attached to task ${taskId}`,
+            attachment: result
+        };
+    }
+    catch (error) {
+        if (error.message === 'Invalid URL') {
+            throw new Error(`Failed to upload file from URL: Invalid URL format. The file_url parameter must be a valid web URL starting with http:// or https://`);
+        }
+        throw new Error(`Failed to upload file from URL: ${error.message}`);
+    }
+}
+/**
+ * Start a chunked upload process for large files
+ */
+async function startChunkedUpload(taskId, fileName, fileBuffer) {
+    // Generate a session token
+    const sessionToken = `chunk_session_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+    // Store the file in chunks (for demonstration - in production would store chunk info only)
+    // Split the file into chunks for storage
+    const chunkSize = 5 * 1024 * 1024; // 5MB chunks
+    const chunksMap = new Map();
+    for (let i = 0; i < fileBuffer.length; i += chunkSize) {
+        const chunk = fileBuffer.slice(i, i + chunkSize);
+        chunksMap.set(Math.floor(i / chunkSize), chunk);
+    }
+    // Create a new session
+    chunkSessions.set(sessionToken, {
+        taskId,
+        fileName,
+        fileSize: fileBuffer.length,
+        chunks: chunksMap,
+        timestamp: Date.now()
+    });
+    // Return initial chunk
+    return {
+        success: true,
+        message: `Large file detected. Chunked upload initialized for "${fileName}" (${fileBuffer.length} bytes)`,
+        chunk_session: sessionToken,
+        chunks_total: chunksMap.size,
+        chunk_uploaded: 1,
+        attachment: null,
+        details: {
+            taskId,
+            fileName,
+            fileSize: fileBuffer.length,
+            chunkCount: chunksMap.size,
+            progress: Math.round((1 / chunksMap.size) * 100)
+        }
+    };
+}
+/**
+ * Handle chunk upload as part of a multi-chunk process
+ */
+async function handleChunkUpload(taskId, sessionToken, chunkIndex, chunkData, isLastChunk) {
+    // Verify session exists
+    const session = chunkSessions.get(sessionToken);
+    if (!session) {
+        throw new Error("Upload session not found or expired");
+    }
+    // If this is the last chunk or all chunks are uploaded, finalize the upload
+    if (isLastChunk || (session.chunks.size === 1 && chunkIndex === undefined)) {
+        // Combine all chunks
+        const fileData = Buffer.allocUnsafe(session.fileSize);
+        let offset = 0;
+        // Sort chunks by index
+        const sortedChunks = Array.from(session.chunks.entries())
+            .sort((a, b) => a[0] - b[0]);
+        for (const [index, chunk] of sortedChunks) {
+            chunk.copy(fileData, offset);
+            offset += chunk.length;
+        }
+        try {
+            // Call service method
+            const result = await taskService.uploadTaskAttachment(session.taskId, fileData, session.fileName);
+            // Clean up the session
+            chunkSessions.delete(sessionToken);
+            return {
+                success: true,
+                message: `File "${session.fileName}" successfully attached to task ${session.taskId}`,
+                attachment: result
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to upload file: ${error.message}`);
+        }
+    }
+    // Otherwise handle the current chunk
+    if (chunkIndex === undefined || chunkData === undefined) {
+        throw new Error("chunk_index and chunk_data are required for chunk uploads");
+    }
+    // Store the chunk
+    // (In a real implementation, we'd append to a temp file or storage)
+    session.chunks.delete(chunkIndex); // Remove the chunk if it exists
+    session.chunks.set(chunkIndex, Buffer.from(chunkData, 'base64'));
+    return {
+        success: true,
+        message: `Chunk ${chunkIndex + 1}/${session.chunks.size} received`,
+        chunk_session: sessionToken,
+        chunks_remaining: session.chunks.size - chunkIndex - 1,
+        details: {
+            taskId: session.taskId,
+            fileName: session.fileName,
+            chunksReceived: chunkIndex + 1,
+            progress: Math.round(((chunkIndex + 1) / session.chunks.size) * 100)
+        }
+    };
+}
+/**
+ * Handle local file path upload
+ */
+async function handleLocalFileUpload(taskId, filePath, fileName) {
+    try {
+        // Import fs and path modules
+        const fs = await import('fs');
+        const path = await import('path');
+        console.log(`Processing absolute file path: ${filePath}`);
+        // Normalize the path to prevent directory traversal attacks
+        const normalizedPath = path.normalize(filePath);
+        // Check if file exists
+        if (!fs.existsSync(normalizedPath)) {
+            throw new Error(`Local file not found: ${normalizedPath}`);
+        }
+        // Validate file stats
+        const stats = fs.statSync(normalizedPath);
+        if (!stats.isFile()) {
+            throw new Error(`Path is not a file: ${normalizedPath}`);
+        }
+        // Get file name if not provided
+        const extractedFileName = fileName || path.basename(normalizedPath);
+        // Read file
+        const fileBuffer = fs.readFileSync(normalizedPath);
+        const fileSize = fileBuffer.length;
+        console.log(`Successfully read file: ${extractedFileName} (${fileSize} bytes)`);
+        // Choose upload method based on file size
+        if (fileSize > 10 * 1024 * 1024) {
+            // For large files, start chunked upload process
+            return await startChunkedUpload(taskId, extractedFileName, fileBuffer);
+        }
+        else {
+            // For small files, upload directly
+            return await handleDirectUpload(taskId, extractedFileName, fileBuffer);
+        }
+    }
+    catch (error) {
+        if (error.message.includes('ENOENT')) {
+            throw new Error(`Failed to upload local file: Local file not found: ${filePath}. Make sure the file exists and the path is absolute.`);
+        }
+        else if (error.message.includes('EACCES')) {
+            throw new Error(`Failed to upload local file: Permission denied accessing: ${filePath}. Check file permissions.`);
+        }
+        throw new Error(`Failed to upload local file: ${error.message}`);
+    }
+}
+/**
+ * Creates a wrapped handler function with standard error handling and response formatting
+ */
+function createHandlerWrapper(handler, formatResponse = (result) => result) {
+    return async (parameters) => {
+        try {
+            const result = await handler(parameters);
+            return sponsorService.createResponse(formatResponse(result), true);
+        }
+        catch (error) {
+            return sponsorService.createErrorResponse(error, parameters);
+        }
+    };
+}
+export const handleAttachTaskFile = createHandlerWrapper(attachTaskFileHandler);

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

@@ -47,7 +47,7 @@ const bulkOptionsSchema = {
 const taskIdentifierSchema = {
     taskId: {
         type: "string",
-        description: "Task ID (preferred). Use instead of taskName if available."
+        description: "Task ID (preferred). Works with both regular task IDs (9 characters) and custom IDs with uppercase prefixes (like 'DEV-1234')."
     },
     taskName: {
         type: "string",
@@ -56,6 +56,10 @@ const taskIdentifierSchema = {
     listName: {
         type: "string",
         description: "REQUIRED with taskName: List containing the task."
+    },
+    customTaskId: {
+        type: "string",
+        description: "Custom task ID (e.g., 'DEV-1234'). Only use if you want to explicitly force custom ID lookup. In most cases, use taskId which auto-detects ID format."
     }
 };
 //=============================================================================