listTasks

Retrieve and filter tasks by status or priority to manage workloads efficiently using the Task API Server.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`status`	No	Filter tasks by status (optional)
`priority`	No	Filter tasks by priority level (optional)

Implementation Reference

src/index.ts:290-368 (handler)

Handler function for listTasks tool: fetches tasks from external API with optional status and priority filters, handles various response formats, formats tasks, and returns formatted list or error.

async ({ status, priority }: { status?: string, priority?: string }) => {
  try {
    const params: any = {};
    if (status) params.status = status;
    if (priority) params.priority = priority;

    const tasksResponse = await makeApiRequest("POST", "/tasks/list", { status, priority });
    
    // More flexible validation for tasks data structure
    let tasks: any[] = [];
    
    // Handle various response formats that might come from the API
    if (tasksResponse) {
      if (Array.isArray(tasksResponse.tasks)) {
        // Standard format: { tasks: [...] }
        tasks = tasksResponse.tasks;
        logDebug("Found tasks array in standard format");
      } else if (Array.isArray(tasksResponse)) {
        // Direct array format: [...]
        tasks = tasksResponse;
        logDebug("Found tasks in direct array format");
      } else if (typeof tasksResponse === 'object' && tasksResponse !== null) {
        // Try to extract tasks from any available property
        const possibleTasksProperties = Object.entries(tasksResponse)
          .filter(([_, value]) => Array.isArray(value))
          .map(([key, value]) => ({ key, value }));
          
        if (possibleTasksProperties.length > 0) {
          // Use the first array property as tasks
          const tasksProp = possibleTasksProperties[0];
          tasks = tasksProp.value as any[];
          logDebug(`Found tasks array in property: ${tasksProp.key}`);
        } else {
          logError(`No tasks array found in response`, tasksResponse);
        }
      }
    }
    
    // If we still couldn't find tasks, log error and return empty array
    if (tasks.length === 0) {
      logError(`Invalid or empty tasks data structure`, tasksResponse);
    }
    
    // Format response in a way that's useful for AI to parse
    const formattedTasks = tasks.map(task => ({
      id: task.id,
      task: task.task || "No description",
      category: task.category,
      priority: task.priority || "medium",
      status: task.status || "not_started",
      createTime: task.create_time || task.created_at || task.createTime || new Date().toISOString()
    }));
    
    // Log the formatted response for debugging
    logDebug(`listTasks formatted response`, formattedTasks);

    return {
      content: [
        {
          type: "text",
          text: `Found ${tasks.length} tasks${status ? ` with status '${status}'` : ''}${priority ? ` and priority '${priority}'` : ''}.`
        },
        {
          type: "text",
          text: JSON.stringify(formattedTasks, null, 2)
        }
      ]
    };
  } catch (error: any) {
    return {
      content: [
        {
          type: "text",
          text: `Error listing tasks: ${error.message}`
        }
      ]
    };
  }
}

src/index.ts:284-289 (schema)

Input schema for listTasks tool, defining optional status and priority parameters using Zod.

{ 
  status: z.enum(["not_started", "started", "done"]).optional()
    .describe("Filter tasks by status (optional)"),
  priority: z.enum(["low", "medium", "high"]).optional()
    .describe("Filter tasks by priority level (optional)")
},

src/index.ts:282-369 (registration)

Registration of the listTasks tool on the MCP server, including name, input schema, and handler function.

server.tool(
  "listTasks", 
  { 
    status: z.enum(["not_started", "started", "done"]).optional()
      .describe("Filter tasks by status (optional)"),
    priority: z.enum(["low", "medium", "high"]).optional()
      .describe("Filter tasks by priority level (optional)")
  }, 
  async ({ status, priority }: { status?: string, priority?: string }) => {
    try {
      const params: any = {};
      if (status) params.status = status;
      if (priority) params.priority = priority;

      const tasksResponse = await makeApiRequest("POST", "/tasks/list", { status, priority });
      
      // More flexible validation for tasks data structure
      let tasks: any[] = [];
      
      // Handle various response formats that might come from the API
      if (tasksResponse) {
        if (Array.isArray(tasksResponse.tasks)) {
          // Standard format: { tasks: [...] }
          tasks = tasksResponse.tasks;
          logDebug("Found tasks array in standard format");
        } else if (Array.isArray(tasksResponse)) {
          // Direct array format: [...]
          tasks = tasksResponse;
          logDebug("Found tasks in direct array format");
        } else if (typeof tasksResponse === 'object' && tasksResponse !== null) {
          // Try to extract tasks from any available property
          const possibleTasksProperties = Object.entries(tasksResponse)
            .filter(([_, value]) => Array.isArray(value))
            .map(([key, value]) => ({ key, value }));
            
          if (possibleTasksProperties.length > 0) {
            // Use the first array property as tasks
            const tasksProp = possibleTasksProperties[0];
            tasks = tasksProp.value as any[];
            logDebug(`Found tasks array in property: ${tasksProp.key}`);
          } else {
            logError(`No tasks array found in response`, tasksResponse);
          }
        }
      }
      
      // If we still couldn't find tasks, log error and return empty array
      if (tasks.length === 0) {
        logError(`Invalid or empty tasks data structure`, tasksResponse);
      }
      
      // Format response in a way that's useful for AI to parse
      const formattedTasks = tasks.map(task => ({
        id: task.id,
        task: task.task || "No description",
        category: task.category,
        priority: task.priority || "medium",
        status: task.status || "not_started",
        createTime: task.create_time || task.created_at || task.createTime || new Date().toISOString()
      }));
      
      // Log the formatted response for debugging
      logDebug(`listTasks formatted response`, formattedTasks);

      return {
        content: [
          {
            type: "text",
            text: `Found ${tasks.length} tasks${status ? ` with status '${status}'` : ''}${priority ? ` and priority '${priority}'` : ''}.`
          },
          {
            type: "text",
            text: JSON.stringify(formattedTasks, null, 2)
          }
        ]
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error listing tasks: ${error.message}`
          }
        ]
      };
    }
  }
);

src/http-server.ts:306-384 (handler)

Handler function for listTasks tool (duplicate implementation in HTTP server version): fetches tasks from external API with optional filters, handles response formats, formats and returns task list.

async ({ status, priority }: { status?: string, priority?: string }) => {
  try {
    const params: any = {};
    if (status) params.status = status;
    if (priority) params.priority = priority;

    const tasksResponse = await makeApiRequest("POST", "/tasks/list", { status, priority });
    
    // More flexible validation for tasks data structure
    let tasks: any[] = [];
    
    // Handle various response formats that might come from the API
    if (tasksResponse) {
      if (Array.isArray(tasksResponse.tasks)) {
        // Standard format: { tasks: [...] }
        tasks = tasksResponse.tasks;
        logDebug("Found tasks array in standard format");
      } else if (Array.isArray(tasksResponse)) {
        // Direct array format: [...]
        tasks = tasksResponse;
        logDebug("Found tasks in direct array format");
      } else if (typeof tasksResponse === 'object' && tasksResponse !== null) {
        // Try to extract tasks from any available property
        const possibleTasksProperties = Object.entries(tasksResponse)
          .filter(([_, value]) => Array.isArray(value))
          .map(([key, value]) => ({ key, value }));
          
        if (possibleTasksProperties.length > 0) {
          // Use the first array property as tasks
          const tasksProp = possibleTasksProperties[0];
          tasks = tasksProp.value as any[];
          logDebug(`Found tasks array in property: ${tasksProp.key}`);
        } else {
          logError(`No tasks array found in response`, tasksResponse);
        }
      }
    }
    
    // If we still couldn't find tasks, log error and return empty array
    if (tasks.length === 0) {
      logError(`Invalid or empty tasks data structure`, tasksResponse);
    }
    
    // Format response in a way that's useful for AI to parse
    const formattedTasks = tasks.map(task => ({
      id: task.id,
      task: task.task || "No description",
      category: task.category,
      priority: task.priority || "medium",
      status: task.status || "not_started",
      createTime: task.create_time || task.created_at || task.createTime || new Date().toISOString()
    }));
    
    // Log the formatted response for debugging
    logDebug(`listTasks formatted response`, formattedTasks);

    return {
      content: [
        {
          type: "text",
          text: `Found ${tasks.length} tasks${status ? ` with status '${status}'` : ''}${priority ? ` and priority '${priority}'` : ''}.`
        },
        {
          type: "text",
          text: JSON.stringify(formattedTasks, null, 2)
        }
      ]
    };
  } catch (error: any) {
    return {
      content: [
        {
          type: "text",
          text: `Error listing tasks: ${error.message}`
        }
      ]
    };
  }
}

src/http-server.ts:300-305 (schema)

Input schema for listTasks tool (HTTP server version), defining optional status and priority filters using Zod.

{ 
  status: z.enum(["not_started", "started", "done"]).optional()
    .describe("Filter tasks by status (optional)"),
  priority: z.enum(["low", "medium", "high"]).optional()
    .describe("Filter tasks by priority level (optional)")
},

Task API Server

listTasks

Input Schema

Implementation Reference

Other Tools

Latest Blog Posts

MCP directory API