get_folder

Instructions

Implementation Reference

• src/tools/folder.ts:218-279 (handler)

  Handler function that executes the get_folder tool: resolves folderId from name if needed, fetches folder details via folderService.getFolder, and returns formatted JSON response.

  export async function handleGetFolder(parameters: any) {
    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: any) => ({
                id: list.id,
                name: list.name
              })),
              space: {
                id: folder.space.id,
                name: folder.space.name
              }
            },
            null,
            2
          )
        }]
      };
    } catch (error: any) {
      throw new Error(`Failed to retrieve folder: ${error.message}`);
    }
  }

• src/tools/folder.ts:57-82 (schema)

  Tool definition including name, description, and inputSchema for validating get_folder parameters.

  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: []
    }
  };

• src/server.ts:67-93 (registration)

  Registration of getFolderTool in the list of available tools returned by ListToolsRequest.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        workspaceHierarchyTool,
        createTaskTool,
        getTaskTool,
        getTasksTool,
        updateTaskTool,
        moveTaskTool,
        duplicateTaskTool,
        deleteTaskTool,
        createBulkTasksTool,
        updateBulkTasksTool,
        moveBulkTasksTool,
        deleteBulkTasksTool,
        createListTool,
        createListInFolderTool,
        getListTool,
        updateListTool,
        deleteListTool,
        createFolderTool,
        getFolderTool,
        updateFolderTool,
        deleteFolderTool
      ]
    };
  });

• src/server.ts:136-137 (registration)

  Registration in CallToolRequest switch statement that routes 'get_folder' calls to handleGetFolder.

  case "get_folder":
    return handleGetFolder(params);

• src/services/clickup/folder.ts:84-96 (helper)

  FolderService.getFolder helper method called by the handler to fetch folder data from ClickUp API.

  async getFolder(folderId: string): Promise<ClickUpFolder> {
    try {
      this.logOperation('getFolder', { folderId });
      
      const response = await this.client.get<ClickUpFolder>(
        `/folder/${folderId}`
      );
      
      return response.data;
    } catch (error) {
      throw this.handleError(error, `Failed to get folder ${folderId}`);
    }
  }