MCP Todo.txt Integration

Instructions

Implementation Reference

• src/tools.ts:63-81 (handler)

  Handler that loads the task list, converts 1-based ID to index, marks the task as completed with today's date if found, saves the list, or returns error if not found.

  async ({ taskId }) => {
      const tasks = await loadTasks();
      const idx = getTaskIndex(taskId, tasks);
      if (idx === null) {
          return {
              content: [
                  { type: "text", text: "Task not found." },
              ],
              isError: true,
          };
      }
      tasks[idx].setCompleted(new Date().toISOString().split("T")[0]);
      await saveTasks(tasks);
      return {
          content: [
              { type: "text", text: "Task marked as completed." },
          ],
      };
  }

• src/tools.ts:62-62 (schema)

  Input schema defining taskId as a required number (1-based index).

  { taskId: z.number() },

• src/tools.ts:59-82 (registration)

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

  server.tool(
      "complete-task",
      "Mark a task as completed by its 1-based ID.",
      { taskId: z.number() },
      async ({ taskId }) => {
          const tasks = await loadTasks();
          const idx = getTaskIndex(taskId, tasks);
          if (idx === null) {
              return {
                  content: [
                      { type: "text", text: "Task not found." },
                  ],
                  isError: true,
              };
          }
          tasks[idx].setCompleted(new Date().toISOString().split("T")[0]);
          await saveTasks(tasks);
          return {
              content: [
                  { type: "text", text: "Task marked as completed." },
              ],
          };
      }
  );

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

  Helper function to convert 1-based task ID 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;
  }

• src/tools.ts:8-11 (helper)

  Helper function to persist the tasks list to the TODO file.

  async function saveTasks(tasks: Item[]) {
      const content = tasks.map((task) => task.toString()).join("\n");
      await fs.writeFile(TODO_FILE_PATH, content, "utf-8");
  }