todoist-mcp

Instructions

Implementation Reference

• src/utils/handlers.ts:201-353 (handler)

  Core batch API handler logic for 'update_tasks': processes batch of items supporting task_id or task_name lookup, validates path params, performs POST /tasks/{id} via todoistApi with update fields, returns per-item results and summary.
  const handler = async (args: z.infer<typeof batchSchema>): Promise<any> => { const { items } = args; // For modes other than create, check if name lookup is needed let allItems: any[] = []; const needsNameLookup = options.mode !== 'create' && options.nameField && options.findByName && items.some(item => item[options.nameField!] && !item[options.idField!]); if (needsNameLookup) { // Determine the base path for fetching all items // Example: /tasks from /tasks/{id} const lookupPath = options.basePath || (options.path ? options.path.split('/{')[0] : ''); allItems = await todoistApi.get(lookupPath, {}); } const results = await Promise.all( items.map(async item => { if (options.validateItem) { const validation = options.validateItem(item); if (!validation.valid) { return { success: false, error: validation.error || 'Validation failed', item, }; } } try { let finalPath = ''; const apiParams = { ...item }; // For modes where need id if (options.mode !== 'create' && options.idField) { let itemId = item[options.idField]; let matchedName = null; let matchedContent = null; // If no ID but name is provided, search by name if (!itemId && item[options.nameField!] && options.findByName) { const searchName = item[options.nameField!]; const matchedItem = options.findByName(searchName, allItems); if (!matchedItem) { return { success: false, error: `Item not found with name: ${searchName}`, item, }; } itemId = matchedItem.id; matchedName = searchName; matchedContent = matchedItem.content; } if (!itemId) { return { success: false, error: `Either ${options.idField} or ${options.nameField} must be provided`, item, }; } // Apply security validation to itemId before using in path const safeItemId = validatePathParameter(itemId, options.idField || 'id'); if (options.basePath && options.pathSuffix) { finalPath = `${options.basePath}${options.pathSuffix.replace('{id}', safeItemId)}`; } else if (options.path) { finalPath = options.path.replace('{id}', safeItemId); } delete apiParams[options.idField]; if (options.nameField) { delete apiParams[options.nameField]; } let result; switch (options.method) { case 'GET': result = await todoistApi.get(finalPath, apiParams); break; case 'POST': result = await todoistApi.post(finalPath, apiParams); break; case 'DELETE': result = await todoistApi.delete(finalPath); break; } const response: any = { success: true, id: itemId, result, }; if (matchedName) { response.found_by_name = matchedName; response.matched_content = matchedContent; } return response; } // Create mode else { finalPath = options.path || options.basePath || ''; let result; switch (options.method) { case 'GET': result = await todoistApi.get(finalPath, apiParams); break; case 'POST': result = await todoistApi.post(finalPath, apiParams); break; case 'DELETE': result = await todoistApi.delete(finalPath); break; } return { success: true, created_item: result, }; } } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error), item, }; } }) ); const successCount = results.filter(r => r.success).length; return { success: successCount === items.length, summary: { total: items.length, succeeded: successCount, failed: items.length - successCount, }, results, }; };
• src/tools/tasks.ts:121-136 (registration)

  Registers the 'update_tasks' tool via createBatchApiHandler: sets name, description, itemSchema (task_id/name + create_fields), method POST, path '/tasks/{id}', mode 'update', findByName helper.
  createBatchApiHandler({ name: 'update_tasks', description: 'Update tasks in Todoist', itemSchema: { task_id: z.string().optional(), task_name: z.string().optional(), ...create_fields, }, method: 'POST', path: '/tasks/{id}', mode: 'update', idField: 'task_id', nameField: 'task_name', findByName: (name, items) => items.find(item => item.content.toLowerCase().includes(name.toLowerCase())), });
• src/tools/tasks.ts:10-63 (schema)

  Common Zod schema (create_fields) for task updates: content, description, labels, priority, due_string/date/datetime/lang, assignee_id, duration/unit, deadline_*.
  /// Common fields for create and update tasks const create_fields = { content: z .string() .describe('Task title (brief). May contain markdown-formatted text and hyperlinks'), description: z .string() .optional() .describe('Description (detailed). May contain markdown-formatted text and hyperlinks'), labels: z.array(z.string()).optional(), priority: z.number().int().min(1).max(4).optional().describe('From 1 (urgent) to 4 (normal)'), due_string: z .string() .optional() .describe( 'Human defined task due date (ex.: "next Monday", "Tomorrow"). Value is set using local (not UTC) time, if not in english provided, due_lang should be set to the language of the string' ), due_date: z .string() .optional() .describe( 'Due date in YYYY-MM-DD format relative to user timezone (when you plan to work on task)' ), due_datetime: z.string().optional().describe('Specific date and time in RFC3339 format in UTC'), due_lang: z .string() .optional() .describe('2-letter code specifying language in case due_string is not written in english'), assignee_id: z .string() .optional() .describe('The responsible user ID (only applies to shared tasks)'), duration: z .number() .int() .positive() .optional() .describe( 'A positive (greater than zero) integer for the amount of duration_unit the task will take' ), duration_unit: z .enum(['minute', 'day']) .optional() .describe( 'The unit of time that the duration field represents. Must be either minute or day' ), deadline_date: z .string() .optional() .describe( 'Deadline date in YYYY-MM-DD format relative to user timezone (fixed date when task must be completed, for tasks with external consequences)' ), deadline_lang: z.string().optional().describe('2-letter code specifying language of deadline'), };
• src/tools/tasks.ts:123-128 (schema)

  Specific itemSchema for update_tasks: task_id (opt), task_name (opt), spreads create_fields.
  description: 'Update tasks in Todoist', itemSchema: { task_id: z.string().optional(), task_name: z.string().optional(), ...create_fields, },
• src/tools/tasks.ts:134-135 (helper)

  findByName helper: finds task by partial content match (case-insensitive).
  findByName: (name, items) => items.find(item => item.content.toLowerCase().includes(name.toLowerCase())),