todoist-mcp

Instructions

Implementation Reference

• src/utils/handlers.ts:311-332 (handler)

  Core handler logic for the 'create' mode in createBatchApiHandler: constructs the API path and performs POST request to Todoist /tasks endpoint with task parameters to create new tasks.

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

• src/tools/tasks.ts:85-100 (schema)

  Schema definition and configuration for the create_tasks tool: Zod itemSchema for batch items, using common create_fields, with additional project/section/parent options.

  createBatchApiHandler({
      name: 'create_tasks',
      description: 'Create new tasks in Todoist',
      itemSchema: {
          ...create_fields,
          project_id: z
              .string()
              .optional()
              .describe("Task project ID. If not set, task is put to user's Inbox"),
          section_id: z.string().optional(),
          parent_id: z.string().optional(),
      },
      method: 'POST',
      path: '/tasks',
      mode: 'create',
  });

• src/tools/tasks.ts:85-100 (registration)

  Registration of the create_tasks MCP tool via createBatchApiHandler, which internally calls createHandler to register with server.tool.

  createBatchApiHandler({
      name: 'create_tasks',
      description: 'Create new tasks in Todoist',
      itemSchema: {
          ...create_fields,
          project_id: z
              .string()
              .optional()
              .describe("Task project ID. If not set, task is put to user's Inbox"),
          section_id: z.string().optional(),
          parent_id: z.string().optional(),
      },
      method: 'POST',
      path: '/tasks',
      mode: 'create',
  });

• src/tools/tasks.ts:10-63 (schema)

  Shared Zod schema (create_fields) for task creation parameters, referenced in create_tasks itemSchema.

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