Todoist MCP Server

Instructions

Implementation Reference

• src/handlers/subtask-handlers.ts:254-352 (handler)

  Core handler function that implements todoist_task_hierarchy_get: locates the target task (by ID or name), fetches all tasks, traverses to topmost parent, builds recursive TaskNode tree filtering by include_completed, computes completion stats.

  export async function handleGetTaskHierarchy(
    todoistClient: TodoistApi,
    args: GetTaskHierarchyArgs
  ): Promise<TaskHierarchy> {
    try {
      // Find the requested task
      const requestedTask = await findTask(todoistClient, {
        task_id: args.task_id,
        task_name: args.task_name,
      });
  
      // Get all tasks for hierarchy building
      const response = (await todoistClient.getTasks()) as TasksResponse;
      const allTasks = extractArrayFromResponse(response) as TodoistTask[];
  
      // Find the topmost parent by traversing upward
      let topmostParent = requestedTask;
      const visitedIds = new Set<string>(); // Prevent infinite loops
  
      while (topmostParent.parentId && !visitedIds.has(topmostParent.id)) {
        visitedIds.add(topmostParent.id);
        const parent = allTasks.find((t: unknown) => {
          const todoTask = t as TodoistTask;
          return todoTask.id === topmostParent.parentId;
        });
  
        if (parent) {
          topmostParent = parent as TodoistTask;
        } else {
          // Parent not found, stop traversal
          break;
        }
      }
  
      // Build task tree recursively from the topmost parent
      async function buildTaskTree(
        task: TodoistTask,
        depth: number = 0,
        originalTaskId: string = ""
      ): Promise<ExtendedTaskNode> {
        // Find direct children
        const children = allTasks.filter((t: unknown) => {
          const todoTask = t as TodoistTask;
          return (
            todoTask.parentId === task.id &&
            (args.include_completed || !todoTask.isCompleted)
          );
        });
  
        // Recursively build child nodes
        const childNodes = await Promise.all(
          children.map((child) =>
            buildTaskTree(child as TodoistTask, depth + 1, originalTaskId)
          )
        );
  
        // Calculate completion percentage
        const totalSubtasks = childNodes.reduce(
          (sum, node) => sum + node.totalTasks,
          childNodes.length
        );
        const completedSubtasks = childNodes.reduce(
          (sum, node) => sum + node.completedTasks,
          childNodes.filter((n) => n.task.isCompleted).length
        );
  
        const completionPercentage =
          totalSubtasks > 0
            ? Math.round((completedSubtasks / totalSubtasks) * 100)
            : task.isCompleted
              ? 100
              : 0;
  
        return {
          task,
          children: childNodes,
          depth,
          completionPercentage,
          totalTasks: 1 + totalSubtasks,
          completedTasks: (task.isCompleted ? 1 : 0) + completedSubtasks,
          isOriginalTask: task.id === originalTaskId, // Mark the originally requested task
        };
      }
  
      const rootNode = await buildTaskTree(topmostParent, 0, requestedTask.id);
  
      return {
        root: rootNode,
        totalTasks: rootNode.totalTasks,
        completedTasks: rootNode.completedTasks,
        overallCompletion: Math.round(
          (rootNode.completedTasks / rootNode.totalTasks) * 100
        ),
        originalTaskId: requestedTask.id, // Include the originally requested task ID
      };
    } catch (error) {
      throw ErrorHandler.handleAPIError("getTaskHierarchy", error);
    }
  }

• src/tools/subtask-tools.ts:166-190 (schema)

  Tool schema definition including name, description, and inputSchema for validating arguments: task_id or task_name required, optional include_completed.

  export const GET_TASK_HIERARCHY_TOOL: Tool = {
    name: "todoist_task_hierarchy_get",
    description: "Get a task with all its subtasks in a hierarchical structure",
    inputSchema: {
      type: "object",
      properties: {
        task_id: {
          type: "string",
          description:
            "ID of the task to get hierarchy for (provide this OR task_name)",
        },
        task_name: {
          type: "string",
          description:
            "Name/content of the task to get hierarchy for (provide this OR task_id)",
        },
        include_completed: {
          type: "boolean",
          description:
            "Include completed tasks in the hierarchy (default: false)",
          default: false,
        },
      },
    },
  };

• src/index.ts:342-348 (registration)

  Main server request handler switch case that routes calls to 'todoist_task_hierarchy_get', validates args, invokes the handler, and formats the hierarchy output for response.

  case "todoist_task_hierarchy_get":
    if (!isGetTaskHierarchyArgs(args)) {
      throw new Error("Invalid arguments for todoist_task_hierarchy_get");
    }
    const hierarchy = await handleGetTaskHierarchy(apiClient, args);
    result = formatTaskHierarchy(hierarchy);
    break;

• src/tools/index.ts:62-69 (registration)

  Aggregates all tool definitions including SUBTASK_TOOLS (containing todoist_task_hierarchy_get) into ALL_TOOLS array served via ListToolsRequest.

  export const ALL_TOOLS = [
    ...TASK_TOOLS,
    ...PROJECT_TOOLS,
    ...COMMENT_TOOLS,
    ...LABEL_TOOLS,
    ...SUBTASK_TOOLS,
    ...TEST_TOOLS,
  ];

• src/handlers/subtask-handlers.ts:52-95 (helper)

  Helper function used by the handler to resolve task by ID (direct fetch) or name (cached search across all tasks).

  async function findTask(
    todoistClient: TodoistApi,
    args: { task_id?: string; task_name?: string }
  ): Promise<TodoistTask> {
    if (!args.task_id && !args.task_name) {
      throw new ValidationError("Either task_id or task_name is required");
    }
  
    try {
      let task: TodoistTask | undefined;
  
      if (args.task_id) {
        const response = await todoistClient.getTask(args.task_id);
        task = response as TodoistTask;
      } else if (args.task_name) {
        const cachedTasks = taskCache.get("todoist_tasks");
        let tasks: TodoistTask[];
  
        if (cachedTasks) {
          tasks = cachedTasks;
        } else {
          const response = (await todoistClient.getTasks()) as TasksResponse;
          tasks = extractArrayFromResponse(response);
          taskCache.set("todoist_tasks", tasks);
        }
  
        const searchTerm = args.task_name.toLowerCase();
        task = tasks.find((t) => t.content.toLowerCase().includes(searchTerm));
      }
  
      if (!task) {
        throw new TaskNotFoundError(
          `Task not found: ${args.task_id || args.task_name}`
        );
      }
  
      return task;
    } catch (error) {
      if (error instanceof TaskNotFoundError) {
        throw error;
      }
      throw ErrorHandler.handleAPIError("findTask", error);
    }
  }