get_list

Instructions

Implementation Reference

• src/tools/list.ts:355-400 (handler)

  Handler function that resolves the list ID if only name is provided, fetches the list details using listService.getList, and returns formatted JSON response with list info including URL.

  export async function handleGetList(parameters: any) {
    const { listId, listName } = parameters;
    
    let targetListId = listId;
    
    // If no listId provided but listName is, look up the list ID
    if (!targetListId && listName) {
      const listResult = await findListIDByName(workspaceService, listName);
      if (!listResult) {
        throw new Error(`List "${listName}" not found`);
      }
      targetListId = listResult.id;
    }
    
    if (!targetListId) {
      throw new Error("Either listId or listName must be provided");
    }
  
    try {
      // Get the list
      const list = await listService.getList(targetListId);
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify(
            {
              id: list.id,
              name: list.name,
              content: list.content,
              space: {
                id: list.space.id,
                name: list.space.name
              },
              status: list.status,
              url: `https://app.clickup.com/${config.clickupTeamId}/v/l/${list.id}`
            },
            null,
            2
          )
        }]
      };
    } catch (error: any) {
      throw new Error(`Failed to retrieve list: ${error.message}`);
    }
  }

• src/tools/list.ts:116-133 (schema)

  Tool definition including the name, description, and inputSchema for validating parameters: listId or listName.

  export const getListTool = {
    name: "get_list",
    description: "Retrieve details about a specific ClickUp list. You MUST provide either listId or listName. Using listId is more reliable as list names might not be unique.",
    inputSchema: {
      type: "object",
      properties: {
        listId: {
          type: "string",
          description: "ID of the list to retrieve. Use this instead of listName if you have the ID."
        },
        listName: {
          type: "string",
          description: "Name of the list to retrieve. May be ambiguous if multiple lists have the same name."
        }
      },
      required: []
    }
  };

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

  Registration of the get_list tool (as getListTool) in the list of available tools returned by the ListToolsRequest handler.

  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:128-129 (registration)

  Switch case in CallToolRequest handler that routes 'get_list' calls to the handleGetList function.

  case "get_list":
    return handleGetList(params);

• src/tools/list.ts:195-201 (helper)

  Helper function to resolve a list name to its ID by searching the workspace hierarchy, used when only listName is provided.

  export async function findListIDByName(workspaceService: any, listName: string): Promise<{ id: string; name: string } | null> {
    // Use workspace service to find the list in the hierarchy
    const hierarchy = await workspaceService.getWorkspaceHierarchy();
    const listInfo = workspaceService.findIDByNameInHierarchy(hierarchy, listName, 'list');
    if (!listInfo) return null;
    return { id: listInfo.id, name: listName };
  }