@taazkareem/clickup-mcp-server 0.4.60 → 0.4.63

package/build/services/clickup/workspace.js

@@ -0,0 +1,314 @@
+/**
+ * ClickUp Workspace Service Module
+ *
+ * Handles workspace hierarchy and space-related operations
+ */
+import { BaseClickUpService, ClickUpServiceError, ErrorCode } from './base.js';
+/**
+ * Service for workspace-related operations
+ */
+export class WorkspaceService extends BaseClickUpService {
+    /**
+     * Creates an instance of WorkspaceService
+     * @param apiKey - ClickUp API key
+     * @param teamId - ClickUp team ID
+     * @param baseUrl - Optional custom API URL
+     */
+    constructor(apiKey, teamId, baseUrl) {
+        super(apiKey, teamId, baseUrl);
+        // Store the workspace hierarchy in memory
+        this.workspaceHierarchy = null;
+    }
+    /**
+     * Helper method to handle errors consistently
+     * @param error - Error caught from a try/catch
+     * @param message - Optional message to add to the error
+     * @returns - A standardized ClickUpServiceError
+     */
+    handleError(error, message) {
+        // Log the error for debugging
+        console.error('WorkspaceService error:', error);
+        // If the error is already a ClickUpServiceError, return it
+        if (error instanceof ClickUpServiceError) {
+            return error;
+        }
+        // Otherwise, create a new ClickUpServiceError
+        const errorMessage = message || 'An error occurred in WorkspaceService';
+        return new ClickUpServiceError(errorMessage, ErrorCode.WORKSPACE_ERROR, error);
+    }
+    /**
+     * Get all spaces for the team
+     * @returns - Promise resolving to array of spaces
+     */
+    async getSpaces() {
+        try {
+            const response = await this.makeRequest(async () => {
+                const result = await this.client.get(`/team/${this.teamId}/space`);
+                return result.data;
+            });
+            return response.spaces || [];
+        }
+        catch (error) {
+            throw this.handleError(error, 'Failed to get spaces');
+        }
+    }
+    /**
+     * Get a specific space by ID
+     * @param spaceId - The ID of the space to retrieve
+     * @returns - Promise resolving to the space object
+     */
+    async getSpace(spaceId) {
+        try {
+            // Validate spaceId
+            if (!spaceId) {
+                throw new ClickUpServiceError('Space ID is required', ErrorCode.INVALID_PARAMETER);
+            }
+            return await this.makeRequest(async () => {
+                const result = await this.client.get(`/space/${spaceId}`);
+                return result.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get space with ID ${spaceId}`);
+        }
+    }
+    /**
+     * Find a space by name
+     * @param spaceName - The name of the space to find
+     * @returns - Promise resolving to the space or null if not found
+     */
+    async findSpaceByName(spaceName) {
+        try {
+            // Validate spaceName
+            if (!spaceName) {
+                throw new ClickUpServiceError('Space name is required', ErrorCode.INVALID_PARAMETER);
+            }
+            // Get all spaces and find the one with the matching name
+            const spaces = await this.getSpaces();
+            const space = spaces.find(s => s.name === spaceName);
+            return space || null;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to find space with name ${spaceName}`);
+        }
+    }
+    /**
+     * Get the complete workspace hierarchy including spaces, folders, and lists
+     * @param forceRefresh - Whether to force a refresh of the hierarchy
+     * @returns - Promise resolving to the workspace tree
+     */
+    async getWorkspaceHierarchy(forceRefresh = false) {
+        try {
+            // If we have a cached result and not forcing refresh, return it
+            if (this.workspaceHierarchy && !forceRefresh) {
+                return this.workspaceHierarchy;
+            }
+            // Start building the workspace tree
+            const workspaceTree = {
+                root: {
+                    id: this.teamId,
+                    name: 'Workspace',
+                    children: []
+                }
+            };
+            // Get all spaces
+            const spaces = await this.getSpaces();
+            // Process each space
+            for (const space of spaces) {
+                const spaceNode = {
+                    id: space.id,
+                    name: space.name,
+                    type: 'space',
+                    children: []
+                };
+                // Get folders for the space
+                const folders = await this.getFoldersInSpace(space.id);
+                for (const folder of folders) {
+                    const folderNode = {
+                        id: folder.id,
+                        name: folder.name,
+                        type: 'folder',
+                        parentId: space.id,
+                        children: []
+                    };
+                    // Get lists in the folder
+                    const listsInFolder = await this.getListsInFolder(folder.id);
+                    for (const list of listsInFolder) {
+                        folderNode.children?.push({
+                            id: list.id,
+                            name: list.name,
+                            type: 'list',
+                            parentId: folder.id
+                        });
+                    }
+                    spaceNode.children?.push(folderNode);
+                }
+                // Get lists directly in the space (not in any folder)
+                const listsInSpace = await this.getListsInSpace(space.id);
+                for (const list of listsInSpace) {
+                    spaceNode.children?.push({
+                        id: list.id,
+                        name: list.name,
+                        type: 'list',
+                        parentId: space.id
+                    });
+                }
+                workspaceTree.root.children.push(spaceNode);
+            }
+            // Store the hierarchy for later use
+            this.workspaceHierarchy = workspaceTree;
+            return workspaceTree;
+        }
+        catch (error) {
+            throw this.handleError(error, 'Failed to get workspace hierarchy');
+        }
+    }
+    /**
+     * Invalidate the workspace hierarchy cache
+     */
+    invalidateWorkspaceCache() {
+        this.workspaceHierarchy = null;
+    }
+    /**
+     * Find a node in the workspace tree by name and type
+     * @param node - The node to start searching from
+     * @param name - The name to search for
+     * @param type - The type of node to search for
+     * @returns - The node and its path if found, null otherwise
+     */
+    findNodeInTree(node, name, type) {
+        // If this is the node we're looking for, return it
+        if ('type' in node && node.type === type && node.name === name) {
+            return { node, path: node.name };
+        }
+        // Otherwise, search its children recursively
+        for (const child of (node.children || [])) {
+            const result = this.findNodeInTree(child, name, type);
+            if (result) {
+                // Prepend this node's name to the path
+                const currentNodeName = 'name' in node ? node.name : 'Workspace';
+                result.path = `${currentNodeName} > ${result.path}`;
+                return result;
+            }
+        }
+        // Not found in this subtree
+        return null;
+    }
+    /**
+     * Find an ID by name and type in the workspace hierarchy
+     * @param hierarchy - The workspace hierarchy
+     * @param name - The name to search for
+     * @param type - The type of node to search for
+     * @returns - The ID and path if found, null otherwise
+     */
+    findIDByNameInHierarchy(hierarchy, name, type) {
+        const result = this.findNodeInTree(hierarchy.root, name, type);
+        if (result) {
+            return { id: result.node.id, path: result.path };
+        }
+        return null;
+    }
+    /**
+     * Find a space ID by name
+     * @param spaceName - The name of the space to find
+     * @returns - Promise resolving to the space ID or null if not found
+     */
+    async findSpaceIDByName(spaceName) {
+        const space = await this.findSpaceByName(spaceName);
+        return space ? space.id : null;
+    }
+    /**
+     * Get lists from the API (using the appropriate endpoint based on context)
+     * @param spaceId - The ID of the space
+     * @returns - Promise resolving to array of lists
+     */
+    async getLists(spaceId) {
+        try {
+            const response = await this.makeRequest(async () => {
+                const result = await this.client.get(`/space/${spaceId}/list`);
+                return result.data;
+            });
+            return response.lists || [];
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get lists for space ${spaceId}`);
+        }
+    }
+    /**
+     * Get folders from the API
+     * @param spaceId - The ID of the space
+     * @returns - Promise resolving to array of folders
+     */
+    async getFolders(spaceId) {
+        try {
+            const response = await this.makeRequest(async () => {
+                const result = await this.client.get(`/space/${spaceId}/folder`);
+                return result.data;
+            });
+            return response.folders || [];
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get folders for space ${spaceId}`);
+        }
+    }
+    /**
+     * Get a specific folder by ID
+     * @param folderId - The ID of the folder to retrieve
+     * @returns - Promise resolving to the folder
+     */
+    async getFolder(folderId) {
+        try {
+            return await this.makeRequest(async () => {
+                const result = await this.client.get(`/folder/${folderId}`);
+                return result.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get folder with ID ${folderId}`);
+        }
+    }
+    /**
+     * Get lists in a space (not in any folder)
+     * @param spaceId - The ID of the space
+     * @returns - Promise resolving to array of lists
+     */
+    async getListsInSpace(spaceId) {
+        try {
+            const lists = await this.getLists(spaceId);
+            return lists.filter((list) => !list.folder); // Filter lists not in a folder
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get lists in space ${spaceId}`);
+        }
+    }
+    /**
+     * Get folders in a space
+     * @param spaceId - The ID of the space
+     * @returns - Promise resolving to array of folders
+     */
+    async getFoldersInSpace(spaceId) {
+        try {
+            return await this.getFolders(spaceId);
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get folders in space ${spaceId}`);
+        }
+    }
+    /**
+     * Get lists in a folder
+     * @param folderId - The ID of the folder
+     * @returns - Promise resolving to array of lists
+     */
+    async getListsInFolder(folderId) {
+        try {
+            const response = await this.makeRequest(async () => {
+                const result = await this.client.get(`/folder/${folderId}/list`);
+                return result.data;
+            });
+            return response.lists || [];
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get lists in folder ${folderId}`);
+        }
+    }
+}

package/build/services/shared.js

@@ -0,0 +1,15 @@
+/**
+ * Shared Services Module
+ *
+ * This module maintains singleton instances of services that should be shared
+ * across the application to ensure consistent state.
+ */
+import { createClickUpServices } from './clickup/index.js';
+import config from '../config.js';
+// Create a single instance of ClickUp services to be shared
+export const clickUpServices = createClickUpServices({
+    apiKey: config.clickupApiKey,
+    teamId: config.clickupTeamId
+});
+// Export individual services for convenience
+export const { list: listService, task: taskService, folder: folderService, workspace: workspaceService } = clickUpServices;

package/build/tools/folder.js

@@ -0,0 +1,356 @@
+/**
+ * ClickUp MCP Folder Tools
+ *
+ * This module defines folder-related tools for creating, retrieving,
+ * updating, and deleting folders in the ClickUp workspace hierarchy.
+ */
+import { createClickUpServices } from '../services/clickup/index.js';
+import config from '../config.js';
+// Initialize ClickUp services using the factory function
+const services = createClickUpServices({
+    apiKey: config.clickupApiKey,
+    teamId: config.clickupTeamId
+});
+// Extract the services we need for folder operations
+const { folder: folderService, workspace: workspaceService } = services;
+/**
+ * Tool definition for creating a folder
+ */
+export const createFolderTool = {
+    name: "create_folder",
+    description: "Create a new folder in a ClickUp space for organizing related lists. You MUST provide:\n1. A folder name\n2. Either spaceId (preferred) or spaceName\n\nAfter creating a folder, you can add lists to it using create_list_in_folder.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "Name of the folder"
+            },
+            spaceId: {
+                type: "string",
+                description: "ID of the space to create the folder in (preferred). Use this instead of spaceName if you have it."
+            },
+            spaceName: {
+                type: "string",
+                description: "Name of the space to create the folder in. Only use if you don't have spaceId."
+            },
+            override_statuses: {
+                type: "boolean",
+                description: "Whether to override space statuses with folder-specific statuses"
+            }
+        },
+        required: ["name"]
+    }
+};
+/**
+ * Tool definition for getting folder details
+ */
+export const getFolderTool = {
+    name: "get_folder",
+    description: "Retrieve details about a specific folder including name, status, and metadata. Valid parameter combinations:\n1. Use folderId alone (preferred)\n2. Use folderName + (spaceId or spaceName)\n\nHelps you understand folder structure before creating or updating lists.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            folderId: {
+                type: "string",
+                description: "ID of folder to retrieve (preferred). Use this instead of folderName if you have it."
+            },
+            folderName: {
+                type: "string",
+                description: "Name of folder to retrieve. When using this, you MUST also provide spaceId or spaceName."
+            },
+            spaceId: {
+                type: "string",
+                description: "ID of space containing the folder (required with folderName). Use this instead of spaceName if you have it."
+            },
+            spaceName: {
+                type: "string",
+                description: "Name of space containing the folder (required with folderName). Only use if you don't have spaceId."
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for updating a folder
+ */
+export const updateFolderTool = {
+    name: "update_folder",
+    description: "Modify an existing folder's properties. Valid parameter combinations:\n1. Use folderId alone (preferred)\n2. Use folderName + (spaceId or spaceName)\n\nAt least one update field (name or override_statuses) must be provided.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            folderId: {
+                type: "string",
+                description: "ID of folder to update (preferred). Use this instead of folderName if you have it."
+            },
+            folderName: {
+                type: "string",
+                description: "Name of folder to update. When using this, you MUST also provide spaceId or spaceName."
+            },
+            spaceId: {
+                type: "string",
+                description: "ID of space containing the folder (required with folderName). Use this instead of spaceName if you have it."
+            },
+            spaceName: {
+                type: "string",
+                description: "Name of space containing the folder (required with folderName). Only use if you don't have spaceId."
+            },
+            name: {
+                type: "string",
+                description: "New name for the folder"
+            },
+            override_statuses: {
+                type: "boolean",
+                description: "Whether to override space statuses with folder-specific statuses"
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Tool definition for deleting a folder
+ */
+export const deleteFolderTool = {
+    name: "delete_folder",
+    description: "⚠️ PERMANENTLY DELETE a folder and all its contents. This action cannot be undone. Valid parameter combinations:\n1. Use folderId alone (preferred and safest)\n2. Use folderName + (spaceId or spaceName)\n\nWARNING: This will also delete all lists and tasks within the folder.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            folderId: {
+                type: "string",
+                description: "ID of folder to delete (preferred). Use this instead of folderName for safety."
+            },
+            folderName: {
+                type: "string",
+                description: "Name of folder to delete. When using this, you MUST also provide spaceId or spaceName."
+            },
+            spaceId: {
+                type: "string",
+                description: "ID of space containing the folder (required with folderName). Use this instead of spaceName if you have it."
+            },
+            spaceName: {
+                type: "string",
+                description: "Name of space containing the folder (required with folderName). Only use if you don't have spaceId."
+            }
+        },
+        required: []
+    }
+};
+/**
+ * Handler for the create_folder tool
+ * Creates a new folder in a space
+ */
+export async function handleCreateFolder(parameters) {
+    const { name, spaceId, spaceName, override_statuses } = parameters;
+    // Validate required fields
+    if (!name) {
+        throw new Error("Folder name is required");
+    }
+    let targetSpaceId = spaceId;
+    // If no spaceId but spaceName is provided, look up the space ID
+    if (!targetSpaceId && spaceName) {
+        const spaceIdResult = await workspaceService.findSpaceByName(spaceName);
+        if (!spaceIdResult) {
+            throw new Error(`Space "${spaceName}" not found`);
+        }
+        targetSpaceId = spaceIdResult.id;
+    }
+    if (!targetSpaceId) {
+        throw new Error("Either spaceId or spaceName must be provided");
+    }
+    // Prepare folder data
+    const folderData = {
+        name
+    };
+    // Add optional fields if provided
+    if (override_statuses !== undefined)
+        folderData.override_statuses = override_statuses;
+    try {
+        // Create the folder
+        const newFolder = await folderService.createFolder(targetSpaceId, folderData);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        id: newFolder.id,
+                        name: newFolder.name,
+                        space: {
+                            id: newFolder.space.id,
+                            name: newFolder.space.name
+                        },
+                        message: `Folder "${newFolder.name}" created successfully`
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to create folder: ${error.message}`);
+    }
+}
+/**
+ * Handler for the get_folder tool
+ * Retrieves details about a specific folder
+ */
+export async function handleGetFolder(parameters) {
+    const { folderId, folderName, spaceId, spaceName } = parameters;
+    let targetFolderId = folderId;
+    // If no folderId provided but folderName is, look up the folder ID
+    if (!targetFolderId && folderName) {
+        let targetSpaceId = spaceId;
+        // If no spaceId provided but spaceName is, look up the space ID first
+        if (!targetSpaceId && spaceName) {
+            const spaceIdResult = await workspaceService.findSpaceByName(spaceName);
+            if (!spaceIdResult) {
+                throw new Error(`Space "${spaceName}" not found`);
+            }
+            targetSpaceId = spaceIdResult.id;
+        }
+        if (!targetSpaceId) {
+            throw new Error("Either spaceId or spaceName must be provided when using folderName");
+        }
+        const folderResult = await folderService.findFolderByName(targetSpaceId, folderName);
+        if (!folderResult) {
+            throw new Error(`Folder "${folderName}" not found in space`);
+        }
+        targetFolderId = folderResult.id;
+    }
+    if (!targetFolderId) {
+        throw new Error("Either folderId or folderName must be provided");
+    }
+    try {
+        // Get the folder
+        const folder = await folderService.getFolder(targetFolderId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        id: folder.id,
+                        name: folder.name,
+                        lists: folder.lists.map((list) => ({
+                            id: list.id,
+                            name: list.name
+                        })),
+                        space: {
+                            id: folder.space.id,
+                            name: folder.space.name
+                        }
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to retrieve folder: ${error.message}`);
+    }
+}
+/**
+ * Handler for the update_folder tool
+ * Updates an existing folder's properties
+ */
+export async function handleUpdateFolder(parameters) {
+    const { folderId, folderName, name, override_statuses, spaceId, spaceName } = parameters;
+    let targetFolderId = folderId;
+    // If no folderId provided but folderName is, look up the folder ID
+    if (!targetFolderId && folderName) {
+        let targetSpaceId = spaceId;
+        // If no spaceId provided but spaceName is, look up the space ID first
+        if (!targetSpaceId && spaceName) {
+            const spaceIdResult = await workspaceService.findSpaceByName(spaceName);
+            if (!spaceIdResult) {
+                throw new Error(`Space "${spaceName}" not found`);
+            }
+            targetSpaceId = spaceIdResult.id;
+        }
+        if (!targetSpaceId) {
+            throw new Error("Either spaceId or spaceName must be provided when using folderName");
+        }
+        const folderResult = await folderService.findFolderByName(targetSpaceId, folderName);
+        if (!folderResult) {
+            throw new Error(`Folder "${folderName}" not found in space`);
+        }
+        targetFolderId = folderResult.id;
+    }
+    if (!targetFolderId) {
+        throw new Error("Either folderId or folderName must be provided");
+    }
+    // Ensure at least one update field is provided
+    if (!name && override_statuses === undefined) {
+        throw new Error("At least one of name or override_statuses must be provided for update");
+    }
+    // Prepare update data
+    const updateData = {};
+    if (name)
+        updateData.name = name;
+    if (override_statuses !== undefined)
+        updateData.override_statuses = override_statuses;
+    try {
+        // Update the folder
+        const updatedFolder = await folderService.updateFolder(targetFolderId, updateData);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        id: updatedFolder.id,
+                        name: updatedFolder.name,
+                        space: {
+                            id: updatedFolder.space.id,
+                            name: updatedFolder.space.name
+                        },
+                        message: `Folder "${updatedFolder.name}" updated successfully`
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to update folder: ${error.message}`);
+    }
+}
+/**
+ * Handler for the delete_folder tool
+ * Permanently removes a folder from the workspace
+ */
+export async function handleDeleteFolder(parameters) {
+    const { folderId, folderName, spaceId, spaceName } = parameters;
+    let targetFolderId = folderId;
+    // If no folderId provided but folderName is, look up the folder ID
+    if (!targetFolderId && folderName) {
+        let targetSpaceId = spaceId;
+        // If no spaceId provided but spaceName is, look up the space ID first
+        if (!targetSpaceId && spaceName) {
+            const spaceIdResult = await workspaceService.findSpaceByName(spaceName);
+            if (!spaceIdResult) {
+                throw new Error(`Space "${spaceName}" not found`);
+            }
+            targetSpaceId = spaceIdResult.id;
+        }
+        if (!targetSpaceId) {
+            throw new Error("Either spaceId or spaceName must be provided when using folderName");
+        }
+        const folderResult = await folderService.findFolderByName(targetSpaceId, folderName);
+        if (!folderResult) {
+            throw new Error(`Folder "${folderName}" not found in space`);
+        }
+        targetFolderId = folderResult.id;
+    }
+    if (!targetFolderId) {
+        throw new Error("Either folderId or folderName must be provided");
+    }
+    try {
+        // Get folder details before deletion for confirmation message
+        const folder = await folderService.getFolder(targetFolderId);
+        const folderName = folder.name;
+        // Delete the folder
+        await folderService.deleteFolder(targetFolderId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        message: `Folder "${folderName}" deleted successfully`
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to delete folder: ${error.message}`);
+    }
+}

package/build/tools/index.js

@@ -0,0 +1,11 @@
+/**
+ * Tools Index
+ *
+ * This file exports all tool definitions and handlers for the ClickUp MCP server.
+ * Each tool category (workspace, task, list, folder) is organized into its own module
+ * for better maintainability.
+ */
+export * from './workspace.js';
+export * from './task.js';
+export * from './list.js';
+export * from './folder.js';