ms-todo-oauth

TotalClaw 作者 yalonghan@gmaill.com

强大的 CLI 技能，可通过 Microsoft Graph API 管理 Microsoft To Do 任务。支持完整的任务生命周期管理，包括列表、具有优先级的任务、截止日期、提醒、重复模式、视图、搜索和数据导出。包括全面的可靠性测试套件。这是带有 AI ASSISTANCE 的 ms-todo-sync 的基于 OAUTH2 的修订版。所有版权归原作者所有。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw install totalclaw:totalclaw~nathanatgit-ms-todo-oauth

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~nathanatgit-ms-todo-oauth/file -o nathanatgit-ms-todo-oauth.md

## 概述（中文）

强大的 CLI 技能，可通过 Microsoft Graph API 管理 Microsoft To Do 任务。
支持完整的任务生命周期管理，包括列表、具有优先级的任务、
截止日期、提醒、重复模式、视图、搜索和数据导出。
包括全面的可靠性测试套件。
这是带有 AI ASSISTANCE 的 ms-todo-sync 的基于 OAUTH2 的修订版。
所有版权归原作者所有。

## 原文

# ms-todo-oauth

A fully-tested Microsoft To Do command-line client for managing tasks and lists via Microsoft Graph API.

## ⚠️This is a oauth based script. It contains a generated Azure Client ID and Secret ID

IF YOU WORRIED ABOUT YOUR PRIVACY, CONSIDER REPLACING THEM TO YOUR OWN IN `scripts\ms-todo-oauth.py`.
Just search for values below:

`client_id="ca6ec244……`

`client_secret="TwQ8Q……`

## ✨ Features

- ✅ **Full Task Management**: Create, complete, delete, and search tasks
- 🗂️ **List Organization**: Create and manage multiple task lists
- ⏰ **Rich Task Options**: Priorities, due dates, reminders, descriptions, tags
- 🔄 **Recurring Tasks**: Daily, weekly, monthly patterns with custom intervals
- 📊 **Multiple Views**: Today, overdue, pending, statistics
- 🔍 **Powerful Search**: Find tasks across all lists
- 💾 **Data Export**: Export all tasks to JSON
- 🧪 **Fully Tested**: 29 comprehensive automated tests
- 🌐 **Unicode Support**: Full support for Chinese characters and emojis

## Prerequisites

1. **Python >= 3.9** must be installed
2. **Working directory**: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file)
3. **Network access**: Requires internet access to Microsoft Graph API endpoints
4. **Microsoft Account**: Personal Microsoft account (Hotmail, Outlook.com) or work/school account
5. **Authentication**: First-time use requires OAuth2 login via browser. See [Authentication](#authentication) section
   - **Token cache**: `~/.mstodo_token_cache.json` (persists across sessions, auto-refreshed)

## Installation & Setup

### First-Time Setup

Before using this skill for the first time, dependencies must be installed:

```bash
# Navigate to skill directory
cd <path-to-ms-todo-oauth>

# Create a venv in the project (creates '.venv' folder)
python3 -m venv .venv
# Activate the venv choose based on platforms:
#- Bash/Zsh: 
source .venv/bin/activate
# - Fish: 
source .venv/bin/activate.fish
#  - Windows (PowerShell):
.venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install -r requirements.txt

# Alternative (global python env, not recommended):
# pip install -r requirements.txt
```

**Dependencies:**

- `msal` (Microsoft Authentication Library) - Official Microsoft OAuth library
- `requests` - HTTP client for API calls
- Specified in `requirements.txt`

### Environment Verification

After installation, verify the setup:

```bash

# If using native venv (activate as above):
python3 scripts/ms-todo-oauth.py --help

# Expected: Command help text should be displayed
```

**Troubleshooting:**

- If `Python not found`, install Python 3.9 or higher from https://python.org


### Testing (Optional but Recommended)

Verify all functionality works correctly:

```bash
# Run comprehensive automated test suite (29 tests)
python3 test_ms_todo_oauth.py

# Expected: All tests pass (100% pass rate)
```

See [Testing](#testing) section for details.

### Security Notes

- Uses official Microsoft Graph API via Microsoft's `msal` library
- All code is plain Python (.py files), readable and auditable
- Tokens stored locally in `~/.mstodo_token_cache.json`
- All API calls go directly to Microsoft endpoints (graph.microsoft.com)
- OAuth2 standard authentication flow
- No third-party services involved

## Command Reference

All commands follow this pattern:

```
python3 scripts/ms-todo-oauth.py [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]
```

### Global Options

| Option            | Description                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `-v, --verbose` | Show detailed information (IDs, dates, notes).**Must be placed BEFORE the subcommand.**                                       |
| `--debug`       | Enable debug mode to display API requests and responses. Useful for troubleshooting.**Must be placed BEFORE the subcommand.** |
| `--reauth`      | Force re-authentication by clearing the token cache and starting fresh login                                                        |

> ⚠️ **Common mistake**: Global options MUST come before the subcommand.
>
> - ✅ `python3 scripts/ms-todo-oauth.py -v lists`
> - ✅ `python3 scripts/ms-todo-oauth.py --debug add "Task"`
> - ❌ `python3 scripts/ms-todo-oauth.py lists -v`

---

### Authentication

Authentication uses OAuth2 authorization code flow, designed for both interactive and automated environments.

#### `login get` — Get OAuth2 authorization URL

```bash
python3 scripts/ms-todo-oauth.py login get
```

**Output example:**

```
======================================================================
🔐 OAuth2 Authorization Required
======================================================================

Please visit the following URL to authorize the application:

  https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?...

After authorization, you will be redirected to a callback URL.
Copy the 'code' parameter from the callback URL and run:

  ms-todo-oauth.py login verify <authorization_code>

======================================================================
```

**What to do:**

1. Open the provided URL in your browser
2. Sign in with your Microsoft account
3. Grant permissions when prompted
4. You'll be redirected to a URL like: `http://localhost:8000/callback?code=M.R3_BAY.abc123...`
5. Copy the entire code after `code=` (usually a long string starting with `M.R3_BAY.`)

**Agent behavior**: Present the URL to the user and explain they need to:

1. Visit the URL
2. Complete the login
3. Copy the authorization code from the callback URL
4. Provide it to you

#### `login verify` — Complete login with authorization code

```bash
python3 scripts/ms-todo-oauth.py login verify <authorization_code>
```

**Example:**

```bash
python3 scripts/ms-todo-oauth.py login verify "M.R3_BAY.abc123def456..."
```

**Output on success:**

```
✓ Authentication successful!
✓ Login information saved, you will be logged in automatically next time.
```

**Output on failure:**

```
❌ Token acquisition failed
Error: invalid_grant
Description: AADSTS54005: OAuth2 Authorization code was already redeemed...
```

**Exit code**: 0 on success, 1 on failure.

**Important notes:**

- Each authorization code can only be used ONCE
- If verification fails, you need to run `login get` again to get a new code
- Once successfully logged in, the token is cached and you won't need to login again unless:
  - You run `logout`
  - You run `--reauth`
  - The token expires and cannot be auto-refreshed

#### `logout` — Clear saved login

```bash
python3 scripts/ms-todo-oauth.py logout
```

Output: `✓ Login information cleared`

Only use when the user explicitly asks to switch accounts or clear login data. Under normal circumstances, the token is cached and login is automatic.

---

### List Management

#### `lists` — List all task lists

```bash
python3 scripts/ms-todo-oauth.py lists
python3 scripts/ms-todo-oauth.py -v lists  # with IDs and creation dates
```

**Output example:**

```
📋 Task Lists (3 total):

1. 任务
   ID: AQMkADAwATYwMAItYTQwZC04OThhLTAwAi0wMAoALgAAA0QJKpxW32BIsIlHaM...
   Created: 2024-12-15T08:30:00Z
2. Work
3. Shopping
```

#### `create-list` — Create a new list

```bash
python3 scripts/ms-todo-oauth.py create-list "<name>"
```

| Argument | Required | Description                                     |
| -------- | -------- | ----------------------------------------------- |
| `name` | Yes      | Name of the new list (supports Unicode/Chinese) |

**Example:**

```bash
python3 scripts/ms-todo-oauth.py create-list "项目 A"
```

Output: `✓ List creat