list_todos

Instructions

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_todos"
  }
}

Implementation Reference

• src/handlers/toolHandlers.ts:161-200 (handler)

  The handleListTodos method processes the 'list_todos' tool invocation: validates input using ListTodosSchema, delegates to TodoService.listTodos, and formats a paginated response with summary statistics.

  async handleListTodos(request: CallToolRequest): Promise<CallToolResult> {
    try {
      const sanitizedArgs = sanitizeInput(request.params.arguments);
      const validatedRequest = validateData(ListTodosSchema, sanitizedArgs);
      
      const result = this.todoService.listTodos({
        ...validatedRequest,
        status: validatedRequest.status || "all",
        limit: validatedRequest.limit || 50,
        offset: validatedRequest.offset || 0,
      });
  
      return {
        content: [
          {
            type: "text",
            text:
              `📋 Encontrados ${result.todos.length} de ${result.total} todo(s)\n` +
              `📄 Página: ${Math.floor(result.offset / result.limit) + 1}\n` +
              `${
                result.hasMore
                  ? "➡️ Há mais resultados disponíveis"
                  : "✅ Todos os resultados exibidos"
              }\n\n` +
              JSON.stringify(result.todos, null, 2),
          },
        ],
      };
    } catch (error) {
      const errorResponse = createErrorResponse(error, "listar todos");
      return {
        content: [
          {
            type: "text",
            text: `❌ ${errorResponse.error}\n${errorResponse.details || ""}`,
          },
        ],
      };
    }
  }

• src/schemas/todo.schemas.ts:39-45 (schema)

  Zod schema defining input validation for list_todos tool parameters including status filter, priority, tags, limit, and offset.

  export const ListTodosSchema = z.object({
    status: z.enum(['all', 'completed', 'pending']).default('all'),
    priority: z.enum(['low', 'medium', 'high']).optional(),
    tags: z.array(z.string()).optional(),
    limit: z.number().int().min(1).max(100).default(50),
    offset: z.number().int().min(0).default(0)
  });

• src/config/toolDefinitions.ts:92-129 (registration)

  MCP tool definition entry for 'list_todos' including name, description, and JSON inputSchema used for tool registration.

  {
    name: "list_todos",
    description: "List todos with filtering and pagination",
    inputSchema: {
      type: "object",
      properties: {
        status: {
          type: "string",
          enum: ["all", "completed", "pending"],
          description: "Filter by completion status",
          default: "all",
        },
        priority: {
          type: "string",
          enum: ["low", "medium", "high"],
          description: "Filter by priority",
        },
        tags: {
          type: "array",
          items: { type: "string" },
          description: "Filter by tags (OR logic)",
        },
        limit: {
          type: "number",
          minimum: 1,
          maximum: 100,
          description: "Maximum number of results",
          default: 50,
        },
        offset: {
          type: "number",
          minimum: 0,
          description: "Number of results to skip",
          default: 0,
        },
      },
    },
  },

• src/services/todo.services.ts:108-144 (helper)

  TodoService.listTodos implements the core filtering, pagination, and response formatting logic for listing todos based on input parameters.

  listTodos(request: ListTodosRequest): TodoListResponse {
    // Validar entrada
    const validatedRequest = validateData(ListTodosSchema, request);
    
    const filters: TodoFilters = {};
    
    if (validatedRequest.status !== undefined) {
      filters.status = validatedRequest.status;
    }
    
    if (validatedRequest.priority !== undefined) {
      filters.priority = validatedRequest.priority;
    }
    
    if (validatedRequest.tags !== undefined) {
      filters.tags = validatedRequest.tags;
    }
  
    const allFilteredTodos = this.getAllTodos(filters);
    const startIndex = validatedRequest.offset ?? 0;
    const limit = validatedRequest.limit ?? 50;
    const offset = validatedRequest.offset ?? 0;
    const endIndex = startIndex + limit;
    const paginatedTodos = allFilteredTodos.slice(startIndex, endIndex);
  
    const response: TodoListResponse = {
      todos: paginatedTodos,
      total: allFilteredTodos.length,
      limit: limit,
      offset: offset,
      hasMore: endIndex < allFilteredTodos.length
    };
  
    return validateData(TodoSchema.array(), paginatedTodos).length > 0 
      ? response 
      : { ...response, todos: [] };
  }