create_list_in_folder

Instructions

Implementation Reference

• src/tools/list.ts:274-349 (handler)

  The primary handler function for the 'create_list_in_folder' tool. It validates inputs, resolves folder IDs using workspace service if names are provided, prepares list data, calls the list service to create the list in the folder, and returns a formatted response with the new list details.

  export async function handleCreateListInFolder(parameters: any) {
    const { name, folderId, folderName, spaceId, spaceName, content, status } = parameters;
    
    // Validate required fields
    if (!name) {
      throw new Error("List name is required");
    }
    
    let targetFolderId = folderId;
    
    // If no folderId but folderName is provided, 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("When using folderName to identify a folder, you must also provide either spaceId or spaceName to locate the correct folder. This is because folder names might not be unique across different spaces.");
      }
      
      // Find the folder in the workspace hierarchy
      const hierarchy = await workspaceService.getWorkspaceHierarchy();
      const folderInfo = workspaceService.findIDByNameInHierarchy(hierarchy, folderName, 'folder');
      if (!folderInfo) {
        throw new Error(`Folder "${folderName}" not found in space`);
      }
      targetFolderId = folderInfo.id;
    }
    
    if (!targetFolderId) {
      throw new Error("Either folderId or folderName must be provided");
    }
  
    // Prepare list data
    const listData: CreateListData = {
      name
    };
  
    // Add optional fields if provided
    if (content) listData.content = content;
    if (status) listData.status = status;
  
    try {
      // Create the list in the folder
      const newList = await listService.createListInFolder(targetFolderId, listData);
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify(
            {
              id: newList.id,
              name: newList.name,
              content: newList.content,
              space: {
                id: newList.space.id,
                name: newList.space.name
              },
              message: `List "${newList.name}" created successfully in folder`
            },
            null,
            2
          )
        }]
      };
    } catch (error: any) {
      throw new Error(`Failed to create list in folder: ${error.message}`);
    }
  }

• src/tools/list.ts:74-111 (schema)

  The tool definition object defining the 'create_list_in_folder' tool, including its name, description, and detailed inputSchema for parameter validation.

  export const createListInFolderTool = {
    name: "create_list_in_folder",
    description: "Create a new list within a ClickUp folder. You MUST provide either: 1) folderId alone, or 2) folderName WITH either spaceName or spaceId. Folder names may not be unique across spaces, which is why space information is required when using folderName.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Name of the list"
        },
        folderId: {
          type: "string",
          description: "ID of the folder to create the list in. If you have this, you don't need folderName or space information."
        },
        folderName: {
          type: "string",
          description: "Name of the folder to create the list in. When using this, you MUST also provide either spaceName or spaceId."
        },
        spaceId: {
          type: "string",
          description: "ID of the space containing the folder. Required when using folderName instead of folderId."
        },
        spaceName: {
          type: "string", 
          description: "Name of the space containing the folder. Required when using folderName instead of folderId."
        },
        content: {
          type: "string",
          description: "Description or content of the list"
        },
        status: {
          type: "string",
          description: "Status of the list (uses folder default if not specified)"
        }
      },
      required: ["name"]
    }
  };

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

  Registration of the createListInFolderTool in the list of available tools returned by the ListToolsRequestSchema handler (line 83 specifically includes createListInFolderTool).

  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:125-127 (registration)

  Dispatch/registration of the handler for 'create_list_in_folder' in the CallToolRequestSchema switch statement.

    return handleCreateList(params);
  case "create_list_in_folder":
    return handleCreateListInFolder(params);

• src/services/clickup/list.ts:75-89 (helper)

  The underlying service method called by the handler to perform the actual ClickUp API call for creating a list in a folder.

  async createListInFolder(folderId: string, listData: CreateListData): Promise<ClickUpList> {
    this.logOperation('createListInFolder', { folderId, ...listData });
    
    try {
      return await this.makeRequest(async () => {
        const response = await this.client.post<ClickUpList>(
          `/folder/${folderId}/list`,
          listData
        );
        return response.data;
      });
    } catch (error) {
      throw this.handleError(error, `Failed to create list in folder ${folderId}`);
    }
  }