Microsoft Todo MCP Service

Instructions

Implementation Reference

• src/todo-index.ts:798-912 (registration)

  Registration of the 'create-task' MCP tool using server.tool(). Includes inline schema definition and handler implementation. The tool creates a new task in Microsoft To Do via Graph API.

  server.tool(
    "create-task",
    "Create a new task in a specific Microsoft Todo list. A task is the main todo item that can have a title, description, due date, and other properties.",
    {
      listId: z.string().describe("ID of the task list"),
      title: z.string().describe("Title of the task"),
      body: z.string().optional().describe("Description or body content of the task"),
      dueDateTime: z.string().optional().describe("Due date in ISO format (e.g., 2023-12-31T23:59:59Z)"),
      startDateTime: z.string().optional().describe("Start date in ISO format (e.g., 2023-12-31T23:59:59Z)"),
      importance: z.enum(["low", "normal", "high"]).optional().describe("Task importance"),
      isReminderOn: z.boolean().optional().describe("Whether to enable reminder for this task"),
      reminderDateTime: z.string().optional().describe("Reminder date and time in ISO format"),
      status: z.enum(["notStarted", "inProgress", "completed", "waitingOnOthers", "deferred"]).optional().describe("Status of the task"),
      categories: z.array(z.string()).optional().describe("Categories associated with the task")
    },
    async ({ listId, title, body, dueDateTime, startDateTime, importance, isReminderOn, reminderDateTime, status, categories }) => {
      try {
        const token = await getAccessToken();
        if (!token) {
          return {
            content: [
              {
                type: "text",
                text: "Failed to authenticate with Microsoft API",
              },
            ],
          };
        }
  
        // Construct the task body with all supported properties
        const taskBody: any = { title };
        
        // Add optional properties if provided
        if (body) {
          taskBody.body = {
            content: body,
            contentType: "text"
          };
        }
        
        if (dueDateTime) {
          taskBody.dueDateTime = {
            dateTime: dueDateTime,
            timeZone: "UTC",
          };
        }
        
        if (startDateTime) {
          taskBody.startDateTime = {
            dateTime: startDateTime,
            timeZone: "UTC",
          };
        }
        
        if (importance) {
          taskBody.importance = importance;
        }
        
        if (isReminderOn !== undefined) {
          taskBody.isReminderOn = isReminderOn;
        }
        
        if (reminderDateTime) {
          taskBody.reminderDateTime = {
            dateTime: reminderDateTime,
            timeZone: "UTC",
          };
        }
        
        if (status) {
          taskBody.status = status;
        }
        
        if (categories && categories.length > 0) {
          taskBody.categories = categories;
        }
  
        const response = await makeGraphRequest<Task>(
          `${MS_GRAPH_BASE}/me/todo/lists/${listId}/tasks`,
          token,
          "POST",
          taskBody
        );
        
        if (!response) {
          return {
            content: [
              {
                type: "text",
                text: `Failed to create task in list: ${listId}`,
              },
            ],
          };
        }
  
        return {
          content: [
            {
              type: "text",
              text: `Task created successfully!\nID: ${response.id}\nTitle: ${response.title}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error creating task: ${error}`,
            },
          ],
        };
      }
    }
  );

• src/todo-index.ts:813-911 (handler)

  The core handler logic for executing the 'create-task' tool. Handles authentication, builds the task payload from inputs, calls makeGraphRequest to POST to Graph API, and returns success/error messages.

  async ({ listId, title, body, dueDateTime, startDateTime, importance, isReminderOn, reminderDateTime, status, categories }) => {
    try {
      const token = await getAccessToken();
      if (!token) {
        return {
          content: [
            {
              type: "text",
              text: "Failed to authenticate with Microsoft API",
            },
          ],
        };
      }
  
      // Construct the task body with all supported properties
      const taskBody: any = { title };
      
      // Add optional properties if provided
      if (body) {
        taskBody.body = {
          content: body,
          contentType: "text"
        };
      }
      
      if (dueDateTime) {
        taskBody.dueDateTime = {
          dateTime: dueDateTime,
          timeZone: "UTC",
        };
      }
      
      if (startDateTime) {
        taskBody.startDateTime = {
          dateTime: startDateTime,
          timeZone: "UTC",
        };
      }
      
      if (importance) {
        taskBody.importance = importance;
      }
      
      if (isReminderOn !== undefined) {
        taskBody.isReminderOn = isReminderOn;
      }
      
      if (reminderDateTime) {
        taskBody.reminderDateTime = {
          dateTime: reminderDateTime,
          timeZone: "UTC",
        };
      }
      
      if (status) {
        taskBody.status = status;
      }
      
      if (categories && categories.length > 0) {
        taskBody.categories = categories;
      }
  
      const response = await makeGraphRequest<Task>(
        `${MS_GRAPH_BASE}/me/todo/lists/${listId}/tasks`,
        token,
        "POST",
        taskBody
      );
      
      if (!response) {
        return {
          content: [
            {
              type: "text",
              text: `Failed to create task in list: ${listId}`,
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: "text",
            text: `Task created successfully!\nID: ${response.id}\nTitle: ${response.title}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error creating task: ${error}`,
          },
        ],
      };
    }
  }

• src/todo-index.ts:802-812 (schema)

  Input validation schema for the 'create-task' tool using Zod. Defines required listId and title, and optional fields for body, dates, importance, status, etc.

    listId: z.string().describe("ID of the task list"),
    title: z.string().describe("Title of the task"),
    body: z.string().optional().describe("Description or body content of the task"),
    dueDateTime: z.string().optional().describe("Due date in ISO format (e.g., 2023-12-31T23:59:59Z)"),
    startDateTime: z.string().optional().describe("Start date in ISO format (e.g., 2023-12-31T23:59:59Z)"),
    importance: z.enum(["low", "normal", "high"]).optional().describe("Task importance"),
    isReminderOn: z.boolean().optional().describe("Whether to enable reminder for this task"),
    reminderDateTime: z.string().optional().describe("Reminder date and time in ISO format"),
    status: z.enum(["notStarted", "inProgress", "completed", "waitingOnOthers", "deferred"]).optional().describe("Status of the task"),
    categories: z.array(z.string()).optional().describe("Categories associated with the task")
  },

• src/todo-index.ts:75-138 (helper)

  Supporting helper function 'makeGraphRequest' used by the create-task handler to perform authenticated HTTP requests to the Microsoft Graph API, handling errors like personal account limitations.

  async function makeGraphRequest<T>(url: string, token: string, method = "GET", body?: any): Promise<T | null> {
    const headers = {
      "User-Agent": USER_AGENT,
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    };
  
    try {
      const options: RequestInit = { 
        method, 
        headers 
      };
  
      if (body && (method === "POST" || method === "PATCH")) {
        options.body = JSON.stringify(body);
      }
  
      console.error(`Making request to: ${url}`);
      console.error(`Request options: ${JSON.stringify({
        method,
        headers: {
          ...headers,
          Authorization: 'Bearer [REDACTED]'
        }
      })}`);
  
      const response = await fetch(url, options);
      
      if (!response.ok) {
        const errorText = await response.text();
        console.error(`HTTP error! status: ${response.status}, body: ${errorText}`);
        
        // Check for the specific MailboxNotEnabledForRESTAPI error
        if (errorText.includes('MailboxNotEnabledForRESTAPI')) {
          console.error(`
  =================================================================
  ERROR: MailboxNotEnabledForRESTAPI
  
  The Microsoft To Do API is not available for personal Microsoft accounts 
  (outlook.com, hotmail.com, live.com, etc.) through the Graph API.
  
  This is a limitation of the Microsoft Graph API, not an authentication issue.
  Microsoft only allows To Do API access for Microsoft 365 business accounts.
  
  You can still use Microsoft To Do through the web interface or mobile apps,
  but API access is restricted for personal accounts.
  =================================================================
          `);
          
          throw new Error("Microsoft To Do API is not available for personal Microsoft accounts. See console for details.");
        }
        
        throw new Error(`HTTP error! status: ${response.status}, body: ${errorText}`);
      }
      
      const data = await response.json();
      console.error(`Response received: ${JSON.stringify(data).substring(0, 200)}...`);
      return data as T;
    } catch (error) {
      console.error("Error making Graph API request:", error);
      return null;
    }
  }