todoist-mcp

Instructions

Implementation Reference

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

  The core batch handler function that implements the execution logic for the 'get_tasks' tool. It handles input items, performs name-based lookup if task_id not provided by fetching all tasks, validates path parameters, executes todoistApi.get('/tasks/{id}'), and returns batched results with success/error status.

  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:106-111 (schema)

  Input schema for the 'get_tasks' tool: accepts task_id (preferred) or task_name for identification in batch operations.

      task_id: z.string().optional().describe('ID of the task to retrieve (preferred)'),
      task_name: z
          .string()
          .optional()
          .describe('Name of the task to retrieve (if ID not provided)'),
  },

• src/tools/tasks.ts:102-119 (registration)

  Registers the 'get_tasks' MCP tool using createBatchApiHandler, configuring it for batch retrieval of Todoist tasks by ID or partial name match, with GET method on /tasks/{id} endpoint.

  createBatchApiHandler({
      name: 'get_tasks',
      description: 'Get tasks from Todoist',
      itemSchema: {
          task_id: z.string().optional().describe('ID of the task to retrieve (preferred)'),
          task_name: z
              .string()
              .optional()
              .describe('Name of the task to retrieve (if ID not provided)'),
      },
      method: 'GET',
      path: '/tasks/{id}',
      mode: 'read',
      idField: 'task_id',
      nameField: 'task_name',
      findByName: (name, items) =>
          items.find(item => item.content.toLowerCase().includes(name.toLowerCase())),
  });

• src/tools/tasks.ts:117-119 (helper)

  Custom findByName helper function specific to tasks: finds task by partial case-insensitive match on content.

      findByName: (name, items) =>
          items.find(item => item.content.toLowerCase().includes(name.toLowerCase())),
  });