todoist-mcp

Instructions

Implementation Reference

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

  Core batch handler logic for delete_tasks: processes array of items, looks up task IDs by name if needed by fetching all tasks, validates path parameters, constructs /tasks/{id} path, executes todoistApi.delete(finalPath) for each matching task, and returns batched results with success 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:170-184 (registration)

  Registers the delete_tasks tool, defining its name, description, input schema (task_id or task_name), HTTP method DELETE on /tasks/{id}, delete mode, ID/name fields, and custom findByName function for task lookup by partial content match.

  createBatchApiHandler({
      name: 'delete_tasks',
      description: 'Delete tasks from Todoist',
      itemSchema: {
          task_id: z.string().optional(),
          task_name: z.string().optional(),
      },
      method: 'DELETE',
      path: '/tasks/{id}',
      mode: 'delete',
      idField: 'task_id',
      nameField: 'task_name',
      findByName: (name, items) =>
          items.find(item => item.content.toLowerCase().includes(name.toLowerCase())),
  });

• src/tools/tasks.ts:173-176 (schema)

  Input schema definition for delete_tasks items, allowing optional task_id or task_name for identification.

  itemSchema: {
      task_id: z.string().optional(),
      task_name: z.string().optional(),
  },