feat: add find-tasks-by-filter tool with order field support

[josegtmonteiro]

Summary

• Adds find-tasks-by-filter tool for executing raw Todoist filter queries
• Enables project hierarchy queries (##Work returns tasks from parent + all sub-projects)
• Adds order field to task output schema for global task positioning
• Implements client-side sorting by multiple criteria including order

Motivation

The existing find-tasks tool requires specific parameters (projectId, sectionId, etc.) but doesn't support:

1. Project hierarchy queries: Getting tasks from a parent project AND all its sub-projects in one call
2. Complex filter syntax: Using Todoist's native filter language with logical operators
3. Global ordering: Sorting tasks by their order field across multiple projects

Changes

New Tool: find-tasks-by-filter

Parameters:

• filter (required): Raw Todoist filter query string
• limit, cursor: Standard pagination
• sortBy: Client-side sorting (priority, due_date, project, created, order, default)
• sortOrder: Sort direction (asc/desc) with sensible defaults per field
• responsibleUser, responsibleUserFiltering: User assignment filters (defaults to all to preserve filter behavior)
• labels, labelsOperator: Label filters

Key features:

• Project hierarchy support: ##Work aggregates tasks from Work + all sub-projects
• Complex queries: (today | overdue) & p1 for high-priority due/overdue tasks
• Client-side sorting: Since REST API doesn't support sorting in filter queries
• Debugging support: Returns appliedFilter showing final executed query

Core Enhancement: order field

• Added order (from task.childOrder) to mapTask() function
• Added order to TaskSchema output
• Enables global task ordering across projects when using sortBy: order

Use case: Users can set order values (1, 3, 4, 5) across different sub-projects and sort globally

Test plan

• All existing tests pass (388 tests)
• New tests added (25 tests for find-tasks-by-filter)
• TypeScript type-check passes
• Build succeeds
• Biome linting passes
• Schema validation passes (Gemini API compatible)
• Manual testing:
  • ✅ Project hierarchy filter (##Work)
  • ✅ Complex filters with operators
  • ✅ Sorting by order field
  • ✅ Label and user filters
  • ✅ Pagination

Example usage

// Project hierarchy
await findTasksByFilter.execute({
  filter: '##Work',
  sortBy: 'order',
  limit: 50
}, client)

// Complex query with sorting
await findTasksByFilter.execute({
  filter: '(today | overdue) & p1',
  sortBy: 'priority',
  limit: 20
}, client)

// With labels
await findTasksByFilter.execute({
  filter: '##Work',
  labels: ['urgent'],
  sortBy: 'due_date'
}, client)

PR Checklist

• Added tests for new features
• Updated docs (src/mcp-server.ts tool instructions)
• New tool added to getMcpServer AND exported in src/index.ts
• Tool added to tool-annotations test
• All 388 tests pass
• Build and type-check pass

Design rationale

Follows repository's workflow-centric philosophy:

• User intent: Matches how users think about filtering ("get all Work tasks")
• Rich responses: Returns structured data + text summaries with helpful hints
• Context-aware: Provides debugging info via appliedFilter field
• Batch-friendly: Supports sorting across multiple projects/sections

🤖 Generated with Claude Code

[scottlovegrove]

@josegtmonteiro You may wish to rebase your branch and resolve the conflicts.

[goncalossilva]

Why don't we improve find-tasks and instead of having searchText with a custom behavior (it prepends search: to search on task content) we rename it to filter and allow invocations using our powerful filtering syntax?

It should cover this use case without adding complexity or additional tools.