create_folder

Instructions

Implementation Reference

• src/tools/folder.ts:156-212 (handler)

  Main handler function for the create_folder tool. Validates input parameters, resolves space ID using workspace service if spaceName provided, prepares folder data, calls folderService.createFolder, and returns formatted JSON response with the new folder details.

  export async function handleCreateFolder(parameters: any) {
    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: CreateFolderData = {
      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: any) {
      throw new Error(`Failed to create folder: ${error.message}`);
    }
  }

• src/tools/folder.ts:27-52 (schema)

  Tool schema definition including name, description, and inputSchema for parameter validation in MCP protocol.

  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"]
    }
  };

• src/server.ts:134-135 (registration)

  Registration of the create_folder tool handler in the CallToolRequestHandler switch statement.

  case "create_folder":
    return handleCreateFolder(params);

• src/server.ts:87-87 (registration)

  Registration of the createFolderTool definition in the ListToolsRequestHandler tool list.

  createFolderTool,

• src/services/clickup/folder.ts:64-77 (helper)

  Underlying service method called by the handler to perform the actual ClickUp API call for creating a folder.

  async createFolder(spaceId: string, folderData: CreateFolderData): Promise<ClickUpFolder> {
    try {
      this.logOperation('createFolder', { spaceId, ...folderData });
      
      const response = await this.client.post<ClickUpFolder>(
        `/space/${spaceId}/folder`,
        folderData
      );
      
      return response.data;
    } catch (error) {
      throw this.handleError(error, `Failed to create folder in space ${spaceId}`);
    }
  }