feat: Add support for filtering by label (#71)

# Pull Request

## Short description

A suggestion from @amix was that we should be able to filter task
acquisition by labels. This adds support to the three main task tools
such that labels can be provided, and it can be set whether a task
should have any of the labels or all of them.

## PR Checklist

Feel free to leave unchecked or remove the lines that are not
applicable.

-   [ ] Added tests for bugs / new features
-   [ ] Updated docs (README, etc.)
- [ ] New tools added to `getMcpServer` AND exported in `src/index.ts`.

<!--
_Note:_ versioning is handled by
[release-please](https://github.com/googleapis/release-please) action,
based on the PR title.
-->

Author: scottlovegrove

src/tools/__tests__/__snapshots__/find-completed-tasks.test.ts.snap

@@ -26,3 +26,39 @@ Next:
 - Use find-tasks-by-date for active tasks or get-overview for current productivity.
 - Recurring tasks will automatically create new instances."
 `;
+
+exports[`find-completed-tasks tool label filtering should combine other filters with label filters 1`] = `
+"Completed tasks (by due date): 1 (limit 25).
+Filter: due date: 2025-08-01 to 2025-08-31; project: test-project-id; section: test-section-id; labels: @important.
+Preview:
+    Important completed task • P1 • id=8485093748
+Next:
+- Use find-tasks-by-date for active tasks or get-overview for current productivity."
+`;
+
+exports[`find-completed-tasks tool label filtering should filter completed tasks by labels: multiple labels with AND operator 1`] = `
+"Completed tasks (by due date): 1 (limit 50).
+Filter: due date: 2025-08-01 to 2025-08-31; labels: @work & @urgent.
+Preview:
+    Completed task with label • P1 • id=8485093748
+Next:
+- Use find-tasks-by-date for active tasks or get-overview for current productivity."
+`;
+
+exports[`find-completed-tasks tool label filtering should filter completed tasks by labels: multiple labels with OR operator 1`] = `
+"Completed tasks (by completed date): 1 (limit 25).
+Filter: completed date: 2025-08-10 to 2025-08-20; labels: @personal | @shopping.
+Preview:
+    Completed task with label • P1 • id=8485093748
+Next:
+- Use find-tasks-by-date for active tasks or get-overview for current productivity."
+`;
+
+exports[`find-completed-tasks tool label filtering should filter completed tasks by labels: single label with OR operator 1`] = `
+"Completed tasks (by completed date): 1 (limit 50).
+Filter: completed date: 2025-08-01 to 2025-08-31; labels: @work.
+Preview:
+    Completed task with label • P1 • id=8485093748
+Next:
+- Use find-tasks-by-date for active tasks or get-overview for current productivity."
+`;

src/tools/__tests__/__snapshots__/find-tasks-by-date.test.ts.snap

@@ -6,6 +6,17 @@ Filter: today + 6 more days.
 No results. Expand date range with larger 'daysCount'; Check 'overdue' for past-due items."
 `;
 
+exports[`find-tasks-by-date tool label filtering should combine date filters with label filters 1`] = `
+"Tasks for 2025-08-15: 1 (limit 25).
+Filter: 2025-08-15; labels: @important.
+Preview:
+    Important task for specific date • due 2025-08-15 • P1 • id=8485093748
+Next:
+- Use update-tasks to modify priorities or due dates
+- Use complete-tasks to mark finished tasks
+- Focus on overdue items first to get back on track"
+`;
+
 exports[`find-tasks-by-date tool listing overdue tasks should handle overdue tasks ignoring daysCount 1`] = `
 "Overdue tasks: 0 (limit 50).
 Filter: overdue tasks only.

src/tools/__tests__/__snapshots__/find-tasks.test.ts.snap

@@ -37,7 +37,8 @@ Preview:
     Regular future task • due 2025-08-25 • P1 • id=8485093748
 Next:
 - Use update-tasks to modify priorities or due dates
-- Use complete-tasks to mark finished tasks"
+- Use complete-tasks to mark finished tasks
+- Focus on overdue items first to get back on track"
 `;
 
 exports[`find-tasks tool next steps logic should provide helpful suggestions for empty search results 1`] = `

src/tools/__tests__/find-completed-tasks.test.ts

@@ -45,7 +45,14 @@ describe(`${FIND_COMPLETED_TASKS} tool`, () => {
             })
 
             const result = await findCompletedTasks.execute(
-                { getBy: 'completion', limit: 50, since: '2025-08-10', until: '2025-08-15' },
+                {
+                    getBy: 'completion',
+                    limit: 50,
+                    since: '2025-08-10',
+                    until: '2025-08-15',
+                    labels: [],
+                    labelsOperator: 'or' as const,
+                },
                 mockTodoistApi,
             )
 
@@ -72,6 +79,8 @@ describe(`${FIND_COMPLETED_TASKS} tool`, () => {
                     until: '2025-08-31',
                     projectId: 'specific-project-id',
                     cursor: 'current-cursor',
+                    labels: [],
+                    labelsOperator: 'or' as const,
                 },
                 mockTodoistApi,
             )
@@ -121,6 +130,8 @@ describe(`${FIND_COMPLETED_TASKS} tool`, () => {
                     limit: 50,
                     since: '2025-08-10',
                     until: '2025-08-20',
+                    labels: [],
+                    labelsOperator: 'or' as const,
                 },
                 mockTodoistApi,
             )
@@ -136,6 +147,141 @@ describe(`${FIND_COMPLETED_TASKS} tool`, () => {
         })
     })
 
+    describe('label filtering', () => {
+        it.each([
+            {
+                name: 'single label with OR operator',
+                params: {
+                    getBy: 'completion' as const,
+                    since: '2025-08-01',
+                    until: '2025-08-31',
+                    limit: 50,
+                    labels: ['work'],
+                },
+                expectedMethod: 'getCompletedTasksByCompletionDate',
+                expectedFilter: '(@work)',
+            },
+            {
+                name: 'multiple labels with AND operator',
+                params: {
+                    getBy: 'due' as const,
+                    since: '2025-08-01',
+                    until: '2025-08-31',
+                    limit: 50,
+                    labels: ['work', 'urgent'],
+                    labelsOperator: 'and' as const,
+                },
+                expectedMethod: 'getCompletedTasksByDueDate',
+                expectedFilter: '(@work  &  @urgent)',
+            },
+            {
+                name: 'multiple labels with OR operator',
+                params: {
+                    getBy: 'completion' as const,
+                    since: '2025-08-10',
+                    until: '2025-08-20',
+                    limit: 25,
+                    labels: ['personal', 'shopping'],
+                },
+                expectedMethod: 'getCompletedTasksByCompletionDate',
+                expectedFilter: '(@personal  |  @shopping)',
+            },
+        ])(
+            'should filter completed tasks by labels: $name',
+            async ({ params, expectedMethod, expectedFilter }) => {
+                const mockCompletedTasks = [
+                    createMockTask({
+                        id: '8485093748',
+                        content: 'Completed task with label',
+                        labels: params.labels,
+                        completedAt: '2024-01-01T00:00:00Z',
+                    }),
+                ]
+
+                const mockResponse = { items: mockCompletedTasks, nextCursor: null }
+                const mockMethod = mockTodoistApi[
+                    expectedMethod as keyof typeof mockTodoistApi
+                ] as jest.MockedFunction<
+                    (...args: never[]) => Promise<{ items: unknown[]; nextCursor: string | null }>
+                >
+                mockMethod.mockResolvedValue(mockResponse)
+
+                const result = await findCompletedTasks.execute(params, mockTodoistApi)
+
+                expect(mockMethod).toHaveBeenCalledWith({
+                    since: params.since,
+                    until: params.until,
+                    limit: params.limit,
+                    filterQuery: expectedFilter,
+                    filterLang: 'en',
+                })
+
+                const textContent = extractTextContent(result)
+                expect(textContent).toMatchSnapshot()
+            },
+        )
+
+        it('should handle empty labels array', async () => {
+            const params = {
+                getBy: 'completion' as const,
+                since: '2025-08-01',
+                until: '2025-08-31',
+                limit: 50,
+                labels: [],
+                labelsOperator: 'or' as const,
+            }
+
+            const mockResponse = { items: [], nextCursor: null }
+            mockTodoistApi.getCompletedTasksByCompletionDate.mockResolvedValue(mockResponse)
+
+            await findCompletedTasks.execute(params, mockTodoistApi)
+
+            expect(mockTodoistApi.getCompletedTasksByCompletionDate).toHaveBeenCalledWith({
+                since: params.since,
+                until: params.until,
+                limit: params.limit,
+            })
+        })
+
+        it('should combine other filters with label filters', async () => {
+            const params = {
+                getBy: 'due' as const,
+                since: '2025-08-01',
+                until: '2025-08-31',
+                limit: 25,
+                projectId: 'test-project-id',
+                sectionId: 'test-section-id',
+                labels: ['important'],
+                labelsOperator: 'or' as const,
+            }
+
+            const mockTasks = [
+                createMockTask({
+                    content: 'Important completed task',
+                    labels: ['important'],
+                    completedAt: '2024-01-01T00:00:00Z',
+                }),
+            ]
+            const mockResponse = { items: mockTasks, nextCursor: null }
+            mockTodoistApi.getCompletedTasksByDueDate.mockResolvedValue(mockResponse)
+
+            const result = await findCompletedTasks.execute(params, mockTodoistApi)
+
+            expect(mockTodoistApi.getCompletedTasksByDueDate).toHaveBeenCalledWith({
+                since: params.since,
+                until: params.until,
+                limit: params.limit,
+                projectId: params.projectId,
+                sectionId: params.sectionId,
+                filterQuery: '(@important)',
+                filterLang: 'en',
+            })
+
+            const textContent = extractTextContent(result)
+            expect(textContent).toMatchSnapshot()
+        })
+    })
+
     describe('error handling', () => {
         it('should propagate completion date API errors', async () => {
             const apiError = new Error('API Error: Invalid date range')
@@ -144,7 +290,14 @@ describe(`${FIND_COMPLETED_TASKS} tool`, () => {
             await expect(
                 findCompletedTasks.execute(
                     // invalid date range
-                    { getBy: 'completion', limit: 50, since: '2025-08-31', until: '2025-08-01' },
+                    {
+                        getBy: 'completion',
+                        limit: 50,
+                        since: '2025-08-31',
+                        until: '2025-08-01',
+                        labels: [],
+                        labelsOperator: 'or' as const,
+                    },
                     mockTodoistApi,
                 ),
             ).rejects.toThrow('API Error: Invalid date range')
@@ -162,6 +315,8 @@ describe(`${FIND_COMPLETED_TASKS} tool`, () => {
                         since: '2025-08-01',
                         until: '2025-08-31',
                         projectId: 'non-existent-project',
+                        labels: [],
+                        labelsOperator: 'or' as const,
                     },
                     mockTodoistApi,
                 ),