claude-ms-todo/mcp-extension/README.md

# Microsoft To Do — Claude Desktop extension (.mcpb)

A one-click Claude Desktop extension that connects Claude to **Microsoft To Do**.
It wraps the same core Graph client as the [`ms-todo` skill](../.claude/skills/ms-todo)
(`MSTodoClient`) and exposes it as MCP tools over stdio. Each user signs in as
**themselves** (delegated, browser auth-code + PKCE); their refresh token is
cached privately on their own machine.

The built artifact is **`ms-todo.mcpb`**.

---

## For end users — install in Claude Desktop

1. Get `ms-todo.mcpb` from your admin.
2. Open **Claude Desktop → Settings → Extensions**.
3. Drag `ms-todo.mcpb` in (or click **Install extension** and select it).
4. Optionally set your **Time zone** in the extension's settings (used for due /
   start / reminder dates; default UTC). Leave **Read-only mode** off for full
   access.
5. In a chat, say: **"Sign in to Microsoft To Do."** Claude runs the `todo_login`
   tool, your browser opens to the Microsoft sign-in page, you approve, and you're
   connected. (You only do this once.)
6. Try it: *"What's on my To Do list?"*, *"Add 'call dentist' due Friday to Tasks."*

> If Claude Desktop warns that the extension is **not verified/signed**, that's
> expected for an internally distributed extension — install it anyway (or have
> your admin sign it, see below).

### What it can do (tools)

`todo_login`, `todo_logout`, `todo_test`, `todo_list_lists`, `todo_list_tasks`,
`todo_get_task`, `todo_create_task`, `todo_update_task`, `todo_complete_task`,
`todo_delete_task`, `todo_create_list`, `todo_update_list`, `todo_delete_list`,
`todo_list_checklist`, `todo_add_checklist_item`, `todo_check_checklist_item`,
`todo_delete_checklist_item`.

---

## For the admin — one-time Entra setup (org-wide)

The extension ships with a **baked-in** public-client app id and tenant id (in
`manifest.json` → `server.mcp_config.env`). There is **no client secret** — these
identifiers are not secrets. For smooth org-wide use, in
[entra.microsoft.com](https://entra.microsoft.com) on that app registration:

1. **Authentication → Mobile and desktop applications** — ensure redirect URIs
   `http://localhost` **and** `http://127.0.0.1` are present (the extension uses a
   loopback redirect during sign-in). *Already configured for the current app.*
2. **API permissions** — delegated `Tasks.ReadWrite`, `offline_access`,
   `User.Read`. Click **Grant admin consent for <tenant>** so individual
   users are **not** prompted to consent (and so it works even if user consent is
   disabled in your tenant).
3. The tenant id is baked single-tenant, so only your org's accounts can sign in.
   To support guests/other tenants, change the app to multi-tenant and set
   `TODO_TENANT_ID` to `organizations` (then rebuild).

To change the baked id/tenant, edit `manifest.json` and rebuild (below).

---

## Rebuilding the .mcpb

Requires Node 18+. From this directory:

```bash
npm run pack
```

That runs three steps: `sync` (copy the canonical `graph.mjs` from the skill into
`server/lib/`), `npm ci --omit=dev` (install runtime deps to bundle), and
`mcpb pack` (zip into `ms-todo.mcpb`). Or run them manually:

```bash
node scripts/sync-core.mjs
npm ci --omit=dev
npx -y @anthropic-ai/mcpb pack . ms-todo.mcpb
```

Useful checks:

```bash
npx -y @anthropic-ai/mcpb validate manifest.json
npx -y @anthropic-ai/mcpb info ms-todo.mcpb
```

### Signing — currently disabled

Unsigned extensions install with a "not verified" warning, which is fine for
internal distribution (just click through it).

> ⚠️ **Do not sign with `mcpb sign` right now.** As of `@anthropic-ai/mcpb` 2.1.2
> (and 2.0.x/2.1.x), `sign` corrupts the bundle: it writes an invalid ZIP EOCD
> comment length, so Claude Desktop fails to open it ("Invalid comment length …
> extra bytes at the end of the file") and `mcpb verify` reports it as unsigned.
> Ship the **unsigned** bundle until this is fixed upstream.

When signing works again (or with a CA-trusted cert deployed to your fleet), the
command is:

```bash
npx -y @anthropic-ai/mcpb sign ms-todo.mcpb --cert cert.pem --key key.pem
```

---

## How it differs from the Claude Code skill

| | `ms-todo` skill | this `.mcpb` extension |
|---|---|---|
| Host | Claude Code (CLI/IDE) on your machine | Claude Desktop |
| Surface | `node todo.mjs …` commands | MCP tools (`todo_*`) |
| Sign-in | `node todo.mjs login` | `todo_login` tool ("sign in to Microsoft To Do") |
| Core client | `scripts/lib/graph.mjs` | the **same** file, synced into `server/lib/` |

The Graph + auth logic lives in one place; this bundle is just a thin MCP wrapper
plus a manifest. Token cache defaults to `~/.ms-todo/token-cache.json` per user.