Todoist MCP Server

Instructions

Implementation Reference

• src/handlers/subtask-handlers.ts:206-249 (handler)

  Main handler function that implements the todoist_subtask_promote tool logic: finds the subtask by ID or name, verifies it has a parent, deletes it, and recreates it as a top-level task in the same or specified project/section, preserving all other properties.

  export async function handlePromoteSubtask(
    todoistClient: TodoistApi,
    args: PromoteSubtaskArgs
  ): Promise<TodoistTask> {
    try {
      // Find subtask
      const subtask = await findTask(todoistClient, {
        task_id: args.subtask_id,
        task_name: args.subtask_name,
      });
  
      // Check if it's actually a subtask
      if (!subtask.parentId) {
        throw new ValidationError(`Task "${subtask.content}" is not a subtask`);
      }
  
      // Delete the subtask and recreate it as a main task
      // This is a workaround since updateTask may not support parentId changes
      await todoistClient.deleteTask(subtask.id);
  
      const taskData: TaskCreationData = {
        content: subtask.content,
        projectId: args.project_id || subtask.projectId,
      };
  
      // Preserve other task properties
      if (subtask.description) taskData.description = subtask.description;
      if (subtask.due?.string) taskData.dueString = subtask.due.string;
      if (subtask.priority) taskData.priority = subtask.priority;
      if (subtask.labels) taskData.labels = subtask.labels;
      if (subtask.deadline?.date)
        taskData.deadline = { date: subtask.deadline.date };
      if (args.section_id) taskData.sectionId = args.section_id;
  
      const promotedTask = (await todoistClient.addTask(taskData)) as TodoistTask;
  
      // Clear cache
      taskCache.clear();
  
      return promotedTask;
    } catch (error) {
      throw ErrorHandler.handleAPIError("promoteSubtask", error);
    }
  }

• src/tools/subtask-tools.ts:138-164 (schema)

  Tool schema definition including input schema for validating arguments to the todoist_subtask_promote tool.

  export const PROMOTE_SUBTASK_TOOL: Tool = {
    name: "todoist_subtask_promote",
    description: "Promote a subtask to a main task (remove parent relationship)",
    inputSchema: {
      type: "object",
      properties: {
        subtask_id: {
          type: "string",
          description:
            "ID of the subtask to promote (provide this OR subtask_name)",
        },
        subtask_name: {
          type: "string",
          description:
            "Name/content of the subtask to promote (provide this OR subtask_id)",
        },
        project_id: {
          type: "string",
          description: "ID of the project to move the task to (optional)",
        },
        section_id: {
          type: "string",
          description: "ID of the section to move the task to (optional)",
        },
      },
    },
  };

• src/index.ts:334-340 (registration)

  Server request handler registration for the todoist_subtask_promote tool, dispatching to the handlePromoteSubtask function.

  case "todoist_subtask_promote":
    if (!isPromoteSubtaskArgs(args)) {
      throw new Error("Invalid arguments for todoist_subtask_promote");
    }
    const promotedTask = await handlePromoteSubtask(apiClient, args);
    result = `Promoted subtask "${promotedTask.content}" (ID: ${promotedTask.id}) to main task`;
    break;

• src/tools/subtask-tools.ts:192-198 (registration)

  Registration of the todoist_subtask_promote tool (as PROMOTE_SUBTASK_TOOL) in the SUBTASK_TOOLS array, which is included in ALL_TOOLS.

  export const SUBTASK_TOOLS = [
    CREATE_SUBTASK_TOOL,
    BULK_CREATE_SUBTASKS_TOOL,
    CONVERT_TO_SUBTASK_TOOL,
    PROMOTE_SUBTASK_TOOL,
    GET_TASK_HIERARCHY_TOOL,
  ];

• src/type-guards.ts:322-335 (schema)

  Type guard function for validating input arguments to the todoist_subtask_promote tool.

  export function isPromoteSubtaskArgs(
    args: unknown
  ): args is PromoteSubtaskArgs {
    if (typeof args !== "object" || args === null) return false;
  
    const obj = args as Record<string, unknown>;
    return (
      (obj.subtask_id === undefined || typeof obj.subtask_id === "string") &&
      (obj.subtask_name === undefined || typeof obj.subtask_name === "string") &&
      (obj.subtask_id !== undefined || obj.subtask_name !== undefined) &&
      (obj.project_id === undefined || typeof obj.project_id === "string") &&
      (obj.section_id === undefined || typeof obj.section_id === "string")
    );
  }