todoist-mcp

Instructions

Implementation Reference

• src/tools/labels.ts:64-78 (registration)

  Registers the delete_labels MCP tool with batch API handler factory, defining schema, path, method, and name lookup logic.

  createBatchApiHandler({
      name: 'delete_labels',
      description: 'Delete a personal label in Todoist',
      itemSchema: {
          id: z.string().optional().describe('ID of the label to delete (preferred over name)'),
          name: z.string().optional().describe('Name of the label to delete'),
      },
      method: 'DELETE',
      path: '/labels/{id}',
      idField: 'id',
      nameField: 'name',
      mode: 'delete',
      findByName: (name, items) =>
          items.find(item => item.name.toLowerCase().includes(name.toLowerCase())),
  });

• src/tools/labels.ts:67-70 (schema)

  Zod schema for input items: array of objects with optional 'id' or 'name' for the label to delete.

  itemSchema: {
      id: z.string().optional().describe('ID of the label to delete (preferred over name)'),
      name: z.string().optional().describe('Name of the label to delete'),
  },

• src/utils/handlers.ts:286-296 (handler)

  Executes the DELETE request to Todoist API at constructed path (e.g., /labels/{id}) within the batch handler for delete_labels.

  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;
  }

• src/utils/handlers.ts:213-219 (helper)

  Fetches list of all labels (/labels) if name lookup needed (derives path from tool's path '/labels/{id}') for delete_labels.

  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, {});
  }

• src/utils/handlers.ts:246-261 (helper)

  Name-to-ID resolution logic using tool-provided findByName on fetched labels list for delete_labels.

  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;
  }