Todoist MCP Server

Instructions

Implementation Reference

• src/tools/task-queries.ts:210-222 (handler)

  The async handler function that executes the 'search_tasks_using_and' tool logic by calling the core searchTasksUsingAnd function and returning formatted JSON response.

  handler: async (args: { search_terms: string[] }) => {
    console.error('Executing search_tasks_using_and...');
    const result = await searchTasksUsingAnd(args.search_terms);
    console.error('search_tasks_using_and completed successfully');
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  },

• src/tools/task-queries.ts:191-209 (schema)

  Input schema and metadata definition for the 'search_tasks_using_and' tool, specifying the name, description, and required search_terms array.

  schema: {
    name: 'search_tasks_using_and',
    description:
      'Search for tasks in Todoist using AND logic - all search terms must be present. Search query examples: meeting (basic text search), *report* (wildcard search), "buy groceries" (quoted, exact phrase search). Returns structured JSON data with task details including id, content, description, completion status, labels, priority, due date, and comment count.',
    inputSchema: {
      type: 'object',
      properties: {
        search_terms: {
          type: 'array',
          items: {
            type: 'string',
          },
          description:
            'Array of search terms. All terms must be present in matching tasks. Examples: ["meeting", "team"], ["weekly", "report", "friday"]',
        },
      },
      required: ['search_terms'],
    },
  },

• src/services/tasks/task-search.ts:51-100 (helper)

  Core helper function implementing the AND search logic using Todoist API filter with 'search:term1 & search:term2' syntax, mapping responses and caching task names.

  export async function searchTasksUsingAnd(
    searchTerms: string[]
  ): Promise<TasksResponse> {
    if (searchTerms.length === 0) {
      throw new Error('At least one search term is required');
    }
  
    // Validate that all search terms are non-empty after trimming
    const trimmedTerms = searchTerms.map((term) => term.trim());
    if (trimmedTerms.some((term) => term === '')) {
      throw new Error('All search terms must be non-empty');
    }
  
    const todoistClient = getTodoistClient();
  
    try {
      // Build the filter string by joining terms with " & " operator
      const filterString = trimmedTerms
        .map((term) => `search:${term}`)
        .join(' & ');
  
      const response = await todoistClient.get<TodoistTask[]>(
        `/tasks?filter=${encodeURIComponent(filterString)}`
      );
  
      const tasks = response.data.map((task) => ({
        id: parseInt(task.id),
        content: task.content,
        description: task.description,
        is_completed: task.is_completed,
        labels: task.labels,
        priority: task.priority,
        due_date: task.due?.date || null,
        url: task.url,
        comment_count: task.comment_count,
      }));
  
      // Store task names in cache
      tasks.forEach((task) => {
        setTaskName(task.id.toString(), task.content);
      });
  
      return {
        tasks,
        total_count: tasks.length,
      };
    } catch (error) {
      throw new Error(`Failed to and search tasks: ${getErrorMessage(error)}`);
    }
  }

• src/handlers/tool-request-handler.ts:61-61 (registration)

  Registration of the tool's handler in the toolsWithArgs registry for execution dispatching.

  search_tasks_using_and: searchTasksUsingAndTool.handler,

• src/index.ts:101-101 (registration)

  Registration of the tool's schema in the list of available tools for the MCP server.

  searchTasksUsingAndTool.schema,