Todoist MCP Server

Instructions

Implementation Reference

• src/tools/task-operations.ts:125-236 (handler)

  Primary handler implementation for the 'update_task' tool. Validates input, constructs parameters, invokes the updateTask service, and returns MCP-formatted response or error.

  export const updateTaskTool: Tool = {
    schema: {
      name: 'update_task',
      description:
        'Update a Todoist task with new title, description, labels, priority, or due string. All fields are optional - only provided fields will be updated.',
      inputSchema: {
        type: 'object',
        properties: {
          task_id: {
            type: 'string',
            description: 'The ID of the task to update (required)',
          },
          title: {
            type: 'string',
            description: 'New title for the task',
          },
          description: {
            type: 'string',
            description: 'New description for the task',
          },
          labels: {
            type: 'array',
            items: {
              type: 'string',
            },
            description: 'Array of label names to assign to the task',
          },
          priority: {
            type: 'number',
            description: 'Priority level (1-4, where 1 is highest priority)',
          },
          due_string: {
            type: 'string',
            description:
              'Human defined task due date (ex.: "next Monday", "Tomorrow"). Value is set using local (not UTC) time. Using "no date" or "no due date" removes the date.',
          },
        },
        required: ['task_id'],
      },
    },
    handler: async (args: {
      task_id: string;
      title?: string;
      description?: string;
      labels?: string[];
      priority?: number;
      due_string?: string;
    }): Promise<{
      content: Array<{
        type: 'text';
        text: string;
      }>;
    }> => {
      console.error('Executing update_task...');
      const { task_id, title, description, labels, priority, due_string } = args;
  
      if (!task_id) {
        throw new Error('task_id is required');
      }
  
      try {
        // Build service parameters with only provided fields
        const serviceParams: any = {
          taskId: task_id,
        };
  
        if (title !== undefined) {
          serviceParams.title = title;
        }
  
        if (description !== undefined) {
          serviceParams.description = description;
        }
  
        if (labels !== undefined) {
          serviceParams.labels = labels;
        }
  
        if (priority !== undefined) {
          serviceParams.priority = priority;
        }
  
        if (due_string !== undefined) {
          serviceParams.dueString = due_string;
        }
  
        const result = await updateTask(serviceParams);
        console.error('update_task completed successfully');
  
        return {
          content: [
            {
              type: 'text',
              text: result,
            },
          ],
        };
      } catch (error) {
        console.error('update_task error:', error);
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${
                error instanceof Error ? error.message : 'Unknown error'
              }`,
            },
          ],
        };
      }
    },
  };

• src/services/tasks/task-update.ts:27-34 (schema)

  Type definition for UpdateTaskParams used by the updateTask service and tool handler for input validation.

  export interface UpdateTaskParams {
    taskId: string;
    title?: string;
    description?: string;
    labels?: string[];
    priority?: number;
    dueString?: string;
  }

• src/handlers/tool-request-handler.ts:50-64 (registration)

  Registers 'update_task' handler in the toolsWithArgs registry for dispatching tool calls in handleToolRequest.

  const toolsWithArgs: Record<string, (args: any) => Promise<ToolResponse>> = {
    get_task_comments: getTaskCommentsTool.handler,
    create_project_label: createProjectLabelTool.handler,
    create_task_comment: createTaskCommentTool.handler,
    update_task: updateTaskTool.handler,
    create_task: createTaskTool.handler,
    move_task: moveTaskTool.handler,
    get_tasks_with_label: getTasksWithLabelTool.handler,
    complete_task: completeTaskTool.handler,
    uncomplete_task: uncompleteTaskTool.handler,
    search_tasks: searchTasksTool.handler,
    search_tasks_using_and: searchTasksUsingAndTool.handler,
    search_tasks_using_or: searchTasksUsingOrTool.handler,
    complete_becky_task: completeBeckyTaskTool.handler,
  };

• src/index.ts:79-117 (registration)

  Registers updateTaskTool.schema in the list of available tools for ListToolsRequestHandler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        getTaskCommentsTool.schema,
        listPersonalInboxTasksTool.schema,
        listBrianInboxPerBeckyTasksTool.schema,
        listBeckyInboxPerBrianTasksTool.schema,
        listNextActionsTool.schema,
        getBrianOnlyProjectsTool.schema,
        getBrianSharedProjectsTool.schema,
        getBeckySharedProjectsTool.schema,
        getInboxProjectsTool.schema,
        createProjectLabelTool.schema,
        createTaskCommentTool.schema,
        updateTaskTool.schema,
        createTaskTool.schema,
        moveTaskTool.schema,
        getContextLabelsTool.schema,
        getTasksWithLabelTool.schema,
        completeTaskTool.schema,
        uncompleteTaskTool.schema,
        searchTasksTool.schema,
        searchTasksUsingAndTool.schema,
        searchTasksUsingOrTool.schema,
        getChoresDueTodayTool.schema,
        getTasksDueTomorrowTool.schema,
        getTasksDueThisWeekTool.schema,
        getTicklerTasksTool.schema,
        listGtdProjectsTool.schema,
        getWaitingTasksTool.schema,
        getRecentMediaTool.schema,
        getAreasOfFocusTool.schema,
        getShoppingListTool.schema,
        completeBeckyTaskTool.schema,
        listBrianTimeSensitiveTasksTool.schema,
        listBeckyTimeSensitiveTasksTool.schema,
      ],
    };
  });

• src/services/tasks/task-update.ts:190-209 (helper)

  Core service function that performs the Todoist API update on the task, handles rename comments, and throws errors.

  export async function updateTask(params: UpdateTaskParams): Promise<string> {
    const client = getTodoistClient();
  
    try {
      const oldTitle = params.title
        ? await retrieveOldTaskTitle(params.taskId)
        : undefined;
  
      const updatePayload = buildUpdatePayload(params);
      await performTaskUpdate(client, params.taskId, updatePayload);
  
      if (params.title && oldTitle) {
        await handleTaskRename(params.taskId, oldTitle, params.title);
      }
  
      return 'Task updated successfully';
    } catch (error) {
      throw new Error(`Failed to update task: ${getErrorMessage(error)}`);
    }
  }