MCP Todo.txt Integration

Instructions

Implementation Reference

• src/tools.ts:228-247 (handler)

  The main handler function for the 'add-metadata' tool. It loads tasks, validates the task ID using getTaskIndex, adds metadata as extensions to the task, saves the tasks, and returns success or error.

  async ({ taskId, metadata }) => {
      const tasks = await loadTasks();
      const idx = getTaskIndex(taskId, tasks);
      if (idx === null) {
          return {
              content: [
                  { type: "text", text: "Invalid task ID." },
              ],
              isError: true,
          };
      }
      Object.entries(metadata).forEach(([key, value]) => {
          tasks[idx].setExtension(key as string, value as string);
      });
      await saveTasks(tasks);
      return {
          content: [
              { type: "text", text: "Metadata added successfully." },
          ],
      };

• src/tools.ts:224-227 (schema)

  Input schema definition using Zod: taskId as number, metadata as a record of string keys to string values.

  {
      taskId: z.number(),
      metadata: z.record(z.string()),
  },

• src/tools.ts:221-249 (registration)

  Registration of the 'add-metadata' tool on the McpServer instance within the registerTools function.

  server.tool(
      "add-metadata",
      "Add custom metadata (key-value pairs) to a task by ID.",
      {
          taskId: z.number(),
          metadata: z.record(z.string()),
      },
      async ({ taskId, metadata }) => {
          const tasks = await loadTasks();
          const idx = getTaskIndex(taskId, tasks);
          if (idx === null) {
              return {
                  content: [
                      { type: "text", text: "Invalid task ID." },
                  ],
                  isError: true,
              };
          }
          Object.entries(metadata).forEach(([key, value]) => {
              tasks[idx].setExtension(key as string, value as string);
          });
          await saveTasks(tasks);
          return {
              content: [
                  { type: "text", text: "Metadata added successfully." },
              ],
          };
      }
  );

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

  Helper function used by the handler to convert 1-based taskId to 0-based array index and validate bounds.

  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-10 (helper)

  Helper function used by the handler to persist the updated tasks 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");