MCP Todo.txt Integration

Instructions

Implementation Reference

• src/tools.ts:381-412 (handler)

  Executes the update-task tool: loads tasks, validates task ID, updates description, priority, replaces contexts and projects, sets extensions, saves, and returns success or error.

  async ({ taskId, updates }) => {
      const tasks = await loadTasks();
      const idx = getTaskIndex(taskId, tasks);
      if (idx === null) {
          return {
              content: [
                  { type: "text", text: "Invalid task ID." },
              ],
              isError: true,
          };
      }
      const task = tasks[idx];
      if (updates.description) task.setBody(updates.description);
      if (updates.priority) task.setPriority(updates.priority);
      if (updates.contexts) {
          task.contexts().forEach((context: string) => task.removeContext(context));
          updates.contexts.forEach((context: string) => task.addContext(context));
      }
      if (updates.projects) {
          task.projects().forEach((project: string) => task.removeProject(project));
          updates.projects.forEach((project: string) => task.addProject(project));
      }
      if (updates.extensions) {
          Object.entries(updates.extensions).forEach(([key, value]) => task.setExtension(key as string, value as string));
      }
      await saveTasks(tasks);
      return {
          content: [
              { type: "text", text: "Task updated successfully." },
          ],
      };
  }

• src/tools.ts:371-380 (schema)

  Zod input schema defining parameters for update-task: required taskId (number), optional updates object with description, priority, contexts array, projects array, extensions record.

  {
      taskId: z.number(),
      updates: z.object({
          description: z.string().optional(),
          priority: z.string().optional(),
          contexts: z.array(z.string()).optional(),
          projects: z.array(z.string()).optional(),
          extensions: z.record(z.string(), z.string()).optional(),
      }),
  },

• src/tools.ts:368-413 (registration)

  Registers the 'update-task' tool on the MCP server with name, description, input schema, and handler function.

  server.tool(
      "update-task",
      "Update a task's fields (description, priority, contexts, projects, metadata) by ID.",
      {
          taskId: z.number(),
          updates: z.object({
              description: z.string().optional(),
              priority: z.string().optional(),
              contexts: z.array(z.string()).optional(),
              projects: z.array(z.string()).optional(),
              extensions: z.record(z.string(), z.string()).optional(),
          }),
      },
      async ({ taskId, updates }) => {
          const tasks = await loadTasks();
          const idx = getTaskIndex(taskId, tasks);
          if (idx === null) {
              return {
                  content: [
                      { type: "text", text: "Invalid task ID." },
                  ],
                  isError: true,
              };
          }
          const task = tasks[idx];
          if (updates.description) task.setBody(updates.description);
          if (updates.priority) task.setPriority(updates.priority);
          if (updates.contexts) {
              task.contexts().forEach((context: string) => task.removeContext(context));
              updates.contexts.forEach((context: string) => task.addContext(context));
          }
          if (updates.projects) {
              task.projects().forEach((project: string) => task.removeProject(project));
              updates.projects.forEach((project: string) => task.addProject(project));
          }
          if (updates.extensions) {
              Object.entries(updates.extensions).forEach(([key, value]) => task.setExtension(key as string, value as string));
          }
          await saveTasks(tasks);
          return {
              content: [
                  { type: "text", text: "Task updated successfully." },
              ],
          };
      }
  );

• src/tools.ts:14-18 (helper)

  Helper utility used by update-task (and others) to map 1-based taskId to 0-based array index, returns null if invalid.

  function getTaskIndex(taskId: number, tasks: Item[]): number | null {
      const idx = taskId - 1;
      if (idx < 0 || idx >= tasks.length) return null;
      return idx;
  }