Microsoft To Do MCP Service Module

This specialized Model Context Protocol (MCP) module bridges an AI assistant with the Microsoft To Do service for comprehensive task management.

Deployment Prerequisites

1. Required Dependencies

• Node.js (version 16 or newer)
• npm package manager
• A valid Microsoft account credential set
• An active Azure Application Registration (refer to the authorization setup section)

2. Installation Procedure

Tool deployment necessitates two distinct phases: 1. Installing the core package distribution. 2. Executing the necessary authorization configuration (which requires repository cloning).

Phase A: Install Package Globally

Execute the following command to integrate the module into your system:

npm install -g @jhirono/todomcp

Phase B: Configure Authentication Assets

Cloning the repository is mandatory to finalize the security setup, even after a global package installation:

git clone https://github.com/jhirono/todoMCP.git
cd todoMCP
npm install

3. Azure Application Registration Steps

Follow these steps within the Azure Portal:

1. Navigate to 'App registrations' and initiate a new application registration.
2. Assign a descriptive identifier to your application (e.g., "To Do Interface Agent").
3. Select the appropriate 'Supported account types' setting based on operational scope:
   • Single Tenant: For internal use within your specific organization's directory.
   • Multi-Tenant: For access across various Azure AD organizations.
   • Personal + Organizational: To support both Azure AD and standard consumer Microsoft accounts.
4. Configure the Reply URL to: http://localhost:3000/callback.
5. In the 'Certificates & secrets' section, generate a new client secret key.
6. Navigate to 'API permissions' and delegate the following scopes under Microsoft Graph:
   • Tasks.Read
   • Tasks.ReadWrite
   • User.Read
7. Confirm access by clicking 'Grant admin consent' for the added permissions.

4. Configuration File Generation

Create a file named .env in the root installation directory containing these parameters:

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
TENANT_ID=your_tenant_setting
REDIRECT_URI=http://localhost:3000/callback

Tenant ID Parameter Meanings: * organizations: Default for multi-tenant organizational access. * consumers: Exclusively for personal Microsoft accounts. * common: Supports both work/school and personal accounts. * specific-id: Use a UUID for single-tenant setups.

Operational Workflow

To enable AI interaction with your To Do data, execute the following sequence from the cloned repository directory:

1. Token Acquisition: bash npm run auth (This initiates a browser-based OAuth flow, resulting in a saved tokens.json file.)

2. Configuration File Generation: bash npm run create-config (This produces the mcp.json configuration file incorporating the acquired authentication tokens.)

3. Global System Integration: Move the generated configuration to the designated global storage location for MCP servers: bash # Example for macOS/Linux: cp mcp.json ~/.cursor/mcp-servers.json

4. Activation in Assistant: The Microsoft To Do functionality is now accessible. Use natural language prompts within the AI assistant (e.g., "Show pending to-dos" or "Check authentication status").

AI Configuration File Locations (Cursor Desktop): * macOS: ~/Library/Application Support/Claude/claude_desktop_config.json * Windows: %APPDATA%\Claude\claude_desktop_config.json * Linux: ~/.config/Claude/claude_desktop_config.json

Toolset Manifest

This module exposes the following functional endpoints:

• auth-status: Verifies current token validity.
• get-task-lists: Retrieves all existing task containers.
• create-task-list: Initializes a new task container.
• update-task-list: Modifies an existing container's properties.
• delete-task-list: Removes a specified container.
• get-tasks: Fetches items within a designated list.
• create-task: Adds a new actionable item.
• update-task: Modifies an existing actionable item's details.
• delete-task: Removes a specified actionable item.
• get-checklist-items: Views sub-items attached to a task.
• create-checklist-item: Adds a sub-item to a task.
• update-checklist-item: Edits a sub-item's status or name.
• delete-checklist-item: Removes a sub-item.

Constraints & Known Issues

• Service functionality is contingent upon valid OAuth tokens and required Graph API permissions.
• Microsoft Graph service may impose rate limiting based on usage patterns.

Troubleshooting Authentication

• Error: "MailboxNotEnabledForRESTAPI": Suggests the use of a personal Microsoft account where Graph API access for To Do is restricted.

• Token Failures: Verify that CLIENT_ID, CLIENT_SECRET, and TENANT_ID within .env are accurately specified.

• Permission Errors: Confirm that the necessary delegated permissions were consented to by an administrator in the Azure portal.

Account Type Guidance

• Work/School Accounts: Optimal performance is generally achieved using TENANT_ID=organizations or a tenant-specific ID.

• Personal Accounts: Access is limited. If personal accounts must be used, try setting TENANT_ID=consumers or TENANT_ID=common.

Token Expiration Verification

Use the auth-status utility or manually inspect the token file:

cat tokens.json | grep expiresAt

To convert the Unix epoch timestamp to a human-readable format (assuming UTC time conversion):

date -r $(echo "$(cat tokens.json | grep expiresAt | cut -d ":" -f2 | cut -d "," -f1) / 1000" | bc)