outlook-cli 1.2.0

package/README.md

@@ -0,0 +1,994 @@
+# outlook-cli
+
+Production-ready CLI and MCP server for Microsoft Outlook through Microsoft Graph.
+
+**GitHub:** https://github.com/selvin-paul-raj/outlook-cli
+
+---
+
+## What This Package Gives You
+
+- Global CLI command: `outlook-cli`
+- One-time OAuth token storage — reused across runs and updates
+- Human-friendly commands with rich terminal output, plus machine-friendly `--json` mode
+- 19 MCP tools available to Claude and other AI assistants via the shared tool registry
+- Full email, calendar, folder, and rules management through Microsoft Graph API
+
+---
+
+## Install
+
+### Global (recommended)
+
+```bash
+npm i -g outlook-cli
+```
+
+```bash
+outlook-cli --help
+```
+
+### Local development
+
+```bash
+npm install
+npm run cli -- --help
+```
+
+**Requirements:** Node.js >= 18.0.0
+
+---
+
+## Azure App Setup (Required)
+
+Before using this package you need an Azure app registration:
+
+1. Go to [portal.azure.com](https://portal.azure.com) → Azure Active Directory → App registrations → New registration
+2. Set redirect URI to: `http://localhost:3333/auth/callback`
+3. Under API Permissions, add Microsoft Graph delegated permissions:
+   - `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`
+   - `Calendars.Read`, `Calendars.ReadWrite`
+   - `User.Read`
+   - `offline_access`
+4. Under Certificates & Secrets → New client secret — copy the **Value** (not the Secret ID)
+5. Copy your Application (client) ID from the Overview page
+
+---
+
+## Quick Start
+
+### 1. Set credentials
+
+**PowerShell (Windows):**
+```powershell
+$env:OUTLOOK_CLIENT_ID="your-client-id-here"
+$env:OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"
+```
+
+**Bash/zsh (Linux/Mac):**
+```bash
+export OUTLOOK_CLIENT_ID="your-client-id-here"
+export OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"
+```
+
+**Or use a `.env` file (copy from `.env.example`):**
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+### 2. Start the auth server (required for first-time login)
+
+```bash
+npm run auth-server
+# or
+outlook-cli auth server --start
+```
+
+This starts an OAuth callback server on port 3333. Keep it running during authentication.
+
+### 3. Authenticate once
+
+```bash
+outlook-cli auth login --open --start-server --wait
+```
+
+This opens your browser to the Microsoft login page. After you approve, tokens are saved to `~/.outlook-mcp-tokens.json` and reused for all future runs.
+
+### 4. Verify and explore
+
+```bash
+outlook-cli auth status        # confirm authenticated
+outlook-cli tools list         # see all available tools
+outlook-cli email list         # list recent inbox emails
+outlook-cli calendar list      # list upcoming events
+```
+
+---
+
+## Environment Variables
+
+### Required
+
+| Variable | Description |
+|---|---|
+| `OUTLOOK_CLIENT_ID` | Azure app Application (client) ID |
+| `OUTLOOK_CLIENT_SECRET` | Azure app client secret **value** (not the Secret ID) |
+
+### Optional
+
+| Variable | Default | Description |
+|---|---|---|
+| `OUTLOOK_REDIRECT_URI` | `http://localhost:3333/auth/callback` | OAuth redirect URL |
+| `OUTLOOK_SCOPES` | `offline_access Mail.Read Mail.ReadWrite Mail.Send User.Read Calendars.Read Calendars.ReadWrite` | Microsoft Graph permission scopes |
+| `OUTLOOK_TOKEN_STORE_PATH` | `~/.outlook-mcp-tokens.json` | Where tokens are saved on disk |
+| `OUTLOOK_TOKEN_ENDPOINT` | Microsoft consumer OAuth endpoint | Token exchange URL |
+| `OUTLOOK_AUTH_SERVER_URL` | `http://localhost:3333` | Auth server base URL |
+| `USE_TEST_MODE` | `false` | Use mock data instead of real API calls |
+
+**Legacy aliases** (backward-compatible): `MS_CLIENT_ID`, `MS_CLIENT_SECRET`, `MS_REDIRECT_URI`, `MS_SCOPES`, `MS_TOKEN_STORE_PATH`, `MS_TOKEN_ENDPOINT`, `MS_AUTH_SERVER_URL`
+
+---
+
+## Command Groups
+
+### `auth` — Authentication
+
+| Command | Description | Example |
+|---|---|---|
+| `auth status` | Show current authentication status | `outlook-cli auth status` |
+| `auth login` | Start authentication flow | `outlook-cli auth login --open --start-server --wait` |
+| `auth url` | Show the OAuth URL without opening browser | `outlook-cli auth url` |
+| `auth logout` | Clear stored tokens | `outlook-cli auth logout` |
+
+**Flags for `auth login`:**
+- `--open` — Automatically open the auth URL in your browser
+- `--start-server` — Start the OAuth callback server automatically
+- `--wait` — Wait for authentication to complete before returning
+
+**Examples:**
+```bash
+# Full login with browser open and wait
+outlook-cli auth login --open --start-server --wait
+
+# Just get the URL to open manually
+outlook-cli auth url
+
+# Check if you're logged in
+outlook-cli auth status
+
+# Force re-authentication
+outlook-cli auth login --open --force
+```
+
+---
+
+### `email` — Email Management
+
+| Command | Description | Example |
+|---|---|---|
+| `email list` | List recent emails | `outlook-cli email list --count 20` |
+| `email search` | Search emails by criteria | `outlook-cli email search --from boss@company.com` |
+| `email read` | Read full email content | `outlook-cli email read --id AAMkAGVm...` |
+| `email send` | Send a new email | `outlook-cli email send --to user@example.com --subject "Hi" --body "Hello"` |
+| `email mark-read` | Mark email as read or unread | `outlook-cli email mark-read --id AAMkAGVm...` |
+
+---
+
+#### `email list` — List Recent Emails
+
+Lists emails from a folder, sorted newest first.
+
+**Parameters:**
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--folder` | string | `inbox` | Folder to list from: `inbox`, `sent`, `drafts`, `deleted`, `junk`, `archive`, or any custom folder name |
+| `--count` | number | `10` | Number of emails to return (1–50) |
+
+**Examples:**
+```bash
+# Default: 10 most recent inbox emails
+outlook-cli email list
+
+# Last 25 inbox emails
+outlook-cli email list --count 25
+
+# 10 most recent sent emails
+outlook-cli email list --folder sent
+
+# 15 emails from a custom folder
+outlook-cli email list --folder "Project Alpha" --count 15
+
+# Output as JSON for scripting
+outlook-cli email list --count 5 --json
+```
+
+**Output shows:** Email ID, sender, subject, date, read/unread status, attachment indicator, body preview.
+
+---
+
+#### `email search` — Search Emails
+
+Searches emails using text and/or filter criteria. Supports multiple criteria simultaneously.
+
+**Parameters:**
+
+| Flag | Type | Description |
+|---|---|---|
+| `--query` | string | Full-text search across subject, body, and sender |
+| `--folder` | string | Folder to search (default: `inbox`) |
+| `--from` | string | Filter by sender email or name |
+| `--to` | string | Filter by recipient email |
+| `--subject` | string | Filter by subject text |
+| `--hasAttachments` | boolean | Only show emails with attachments |
+| `--unreadOnly` | boolean | Only show unread emails |
+| `--count` | number | Max results (1–50, default: 10) |
+
+**Examples:**
+```bash
+# Search by keyword
+outlook-cli email search --query "quarterly report"
+
+# Find unread emails from a specific sender
+outlook-cli email search --from manager@company.com --unreadOnly
+
+# Find emails with attachments about invoices
+outlook-cli email search --subject invoice --hasAttachments
+
+# Search sent folder for emails to a client
+outlook-cli email search --folder sent --to client@example.com
+
+# Complex search
+outlook-cli email search --from finance@company.com --subject "budget" --unreadOnly --count 20
+
+# JSON output
+outlook-cli email search --query "meeting notes" --json
+```
+
+---
+
+#### `email read` — Read Full Email
+
+Reads the complete content of one email by its ID.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--id` | string | yes | Email ID from `email list` or `email search` output |
+
+**Examples:**
+```bash
+# Read a specific email
+outlook-cli email read --id AAMkAGVmMDAwAT...
+
+# Read and output as JSON
+outlook-cli email read --id AAMkAGVmMDAwAT... --json
+```
+
+**Output shows:** From, To, CC, BCC, Subject, Date, Importance, Attachment status, full Body text (HTML auto-converted to plain text).
+
+**Tip:** Get email IDs from `email list` or `email search` output first.
+
+---
+
+#### `email send` — Send Email
+
+Composes and sends an email from the user's account.
+
+**Parameters:**
+
+| Flag | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `--to` | string | yes | — | Recipient(s), comma-separated for multiple |
+| `--subject` | string | yes | — | Email subject |
+| `--body` | string | yes | — | Email body (plain text or HTML) |
+| `--cc` | string | no | — | CC recipient(s), comma-separated |
+| `--bcc` | string | no | — | BCC recipient(s), comma-separated |
+| `--importance` | string | no | `normal` | Priority: `normal`, `high`, or `low` |
+| `--saveToSentItems` | boolean | no | `true` | Save copy to Sent folder |
+
+**Examples:**
+```bash
+# Simple email
+outlook-cli email send \
+  --to colleague@company.com \
+  --subject "Meeting notes" \
+  --body "Here are today's action items..."
+
+# Email to multiple recipients with CC and high priority
+outlook-cli email send \
+  --to "team@company.com,manager@company.com" \
+  --cc hr@company.com \
+  --subject "URGENT: System outage" \
+  --body "We are investigating..." \
+  --importance high
+
+# Email without saving to sent folder
+outlook-cli email send \
+  --to test@example.com \
+  --subject "Test" \
+  --body "Hello" \
+  --saveToSentItems false
+```
+
+**Notes:**
+- HTML body is detected automatically when the body contains `<html`.
+- Attachments are not supported — body text only.
+
+---
+
+#### `email mark-read` — Mark Email Read/Unread
+
+Changes the read status of an email.
+
+**Parameters:**
+
+| Flag | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `--id` | string | yes | — | Email ID |
+| `--isRead` | boolean | no | `true` | `true` = mark read, `false` = mark unread |
+
+**Examples:**
+```bash
+# Mark as read (default)
+outlook-cli email mark-read --id AAMkAGVmMDAwAT...
+
+# Mark as unread
+outlook-cli email mark-read --id AAMkAGVmMDAwAT... --isRead false
+```
+
+---
+
+### `calendar` — Calendar Management
+
+| Command | Description |
+|---|---|
+| `calendar list` | List upcoming events |
+| `calendar create` | Create a new event |
+| `calendar decline` | Decline an event invitation |
+| `calendar cancel` | Cancel an event you organized |
+| `calendar delete` | Delete an event |
+
+---
+
+#### `calendar list` — List Upcoming Events
+
+Lists upcoming calendar events starting from now, ordered by start time.
+
+**Parameters:**
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--count` | number | `10` | Number of events to return (1–50) |
+
+**Examples:**
+```bash
+# Next 10 events (default)
+outlook-cli calendar list
+
+# Next 30 events
+outlook-cli calendar list --count 30
+
+# JSON output
+outlook-cli calendar list --count 5 --json
+```
+
+**Output shows:** Event ID, subject, location, start time, end time, organizer, attendees list.
+
+**Tip:** Copy the Event ID from the output to use with `decline`, `cancel`, or `delete` commands.
+
+---
+
+#### `calendar create` — Create Calendar Event
+
+Creates a new event on the calendar. Optionally invites attendees.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--subject` | string | yes | Event title |
+| `--start` | string | yes | Start datetime: `YYYY-MM-DDTHH:MM:SS` |
+| `--end` | string | yes | End datetime: `YYYY-MM-DDTHH:MM:SS` |
+| `--attendees` | string | no | Comma-separated attendee email addresses |
+| `--body` | string | no | Event description/agenda |
+
+**Examples:**
+```bash
+# Simple personal event
+outlook-cli calendar create \
+  --subject "Focus time" \
+  --start "2026-04-10T09:00:00" \
+  --end "2026-04-10T11:00:00"
+
+# Team meeting with attendees and agenda
+outlook-cli calendar create \
+  --subject "Q2 Planning" \
+  --start "2026-04-15T14:00:00" \
+  --end "2026-04-15T15:30:00" \
+  --attendees "alice@company.com,bob@company.com" \
+  --body "Agenda: review Q1, plan Q2 roadmap, assign owners"
+
+# All-day event (use midnight to midnight)
+outlook-cli calendar create \
+  --subject "Company holiday" \
+  --start "2026-04-25T00:00:00" \
+  --end "2026-04-25T23:59:00"
+```
+
+**Notes:**
+- Datetime must be in `YYYY-MM-DDTHH:MM:SS` format without timezone offset.
+- The server uses Central European Standard Time by default.
+
+---
+
+#### `calendar decline` — Decline Event Invitation
+
+Declines a received event invitation, optionally with a message to the organizer.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--eventId` | string | yes | Event ID from `calendar list` |
+| `--comment` | string | no | Message to send to the organizer |
+
+**Examples:**
+```bash
+# Decline without a message
+outlook-cli calendar decline --eventId AAMkAGVmMDAwAT...
+
+# Decline with a reason
+outlook-cli calendar decline \
+  --eventId AAMkAGVmMDAwAT... \
+  --comment "Sorry, I have a conflict. Can we reschedule to next week?"
+```
+
+---
+
+#### `calendar cancel` — Cancel Your Event
+
+Cancels an event you organized and notifies all attendees.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--eventId` | string | yes | Event ID from `calendar list` |
+| `--comment` | string | no | Cancellation reason sent to attendees |
+
+**Examples:**
+```bash
+# Cancel without message
+outlook-cli calendar cancel --eventId AAMkAGVmMDAwAT...
+
+# Cancel with explanation
+outlook-cli calendar cancel \
+  --eventId AAMkAGVmMDAwAT... \
+  --comment "This meeting is no longer needed. Details will follow by email."
+```
+
+**Note:** Use `cancel` (not `delete`) when you want attendees to receive a cancellation notification.
+
+---
+
+#### `calendar delete` — Delete Event
+
+Permanently removes an event from the calendar without notifying attendees.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--eventId` | string | yes | Event ID from `calendar list` |
+
+**Examples:**
+```bash
+outlook-cli calendar delete --eventId AAMkAGVmMDAwAT...
+```
+
+**Tip:** Use `cancel` instead of `delete` for meetings with attendees so they receive proper notification.
+
+---
+
+### `folder` — Mail Folder Management
+
+| Command | Description |
+|---|---|
+| `folder list` | List all mail folders |
+| `folder create` | Create a new folder |
+| `folder move` | Move emails to another folder |
+
+---
+
+#### `folder list` — List Mail Folders
+
+Lists all mail folders in the account. Optionally shows item counts and subfolder hierarchy.
+
+**Parameters:**
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--includeItemCounts` | boolean | `false` | Show total and unread message counts |
+| `--includeChildren` | boolean | `false` | Show nested subfolders |
+
+**Examples:**
+```bash
+# Simple folder list
+outlook-cli folder list
+
+# With message counts
+outlook-cli folder list --includeItemCounts
+
+# Full hierarchy with counts
+outlook-cli folder list --includeItemCounts --includeChildren
+
+# JSON output for scripting
+outlook-cli folder list --includeItemCounts --json
+```
+
+**Tip:** Use this to discover custom folder names before using them in `email list`, `email search`, `folder move`, or `rule create`.
+
+---
+
+#### `folder create` — Create Mail Folder
+
+Creates a new mail folder at the root level or inside an existing folder.
+
+**Parameters:**
+
+| Flag | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `--name` | string | yes | — | Name for the new folder |
+| `--parentFolder` | string | no | root | Name of existing parent folder |
+
+**Examples:**
+```bash
+# Create top-level folder
+outlook-cli folder create --name "Project Alpha"
+
+# Create subfolder inside an existing folder
+outlook-cli folder create --name "2026 Invoices" --parentFolder "Finance"
+
+# Create a subfolder under inbox
+outlook-cli folder create --name "Action Required" --parentFolder inbox
+```
+
+---
+
+#### `folder move` — Move Emails
+
+Moves one or more emails from one folder to another.
+
+**Parameters:**
+
+| Flag | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `--emailIds` | string | yes | — | Comma-separated email ID(s) |
+| `--targetFolder` | string | yes | — | Destination folder name |
+| `--sourceFolder` | string | no | `inbox` | Source folder (for context) |
+
+**Examples:**
+```bash
+# Move one email to archive
+outlook-cli folder move \
+  --emailIds AAMkAGVmMDAwAT... \
+  --targetFolder archive
+
+# Move multiple emails to a custom folder
+outlook-cli folder move \
+  --emailIds "AAMkAGVm...,BBMkAHXn...,CCMkAIYo..." \
+  --targetFolder "Project Alpha"
+
+# Move from a non-inbox folder
+outlook-cli folder move \
+  --emailIds AAMkAGVmMDAwAT... \
+  --sourceFolder "Junk" \
+  --targetFolder inbox
+```
+
+**Output:** Reports success count, failure count, and error details for any failed moves (up to 3 error messages shown).
+
+---
+
+### `rule` — Inbox Rules
+
+| Command | Description |
+|---|---|
+| `rule list` | List all inbox rules |
+| `rule create` | Create a new inbox rule |
+| `rule sequence` | Change a rule's execution order |
+
+---
+
+#### `rule list` — List Inbox Rules
+
+Lists all inbox rules sorted by sequence (execution order — lower runs first).
+
+**Parameters:**
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--includeDetails` | boolean | `false` | Show full conditions and actions |
+
+**Examples:**
+```bash
+# Just rule names and enabled status
+outlook-cli rule list
+
+# Full detail — conditions and actions for each rule
+outlook-cli rule list --includeDetails
+
+# JSON for scripting
+outlook-cli rule list --includeDetails --json
+```
+
+**Output (with details) shows:**
+- Conditions: fromAddresses, subjectContains, bodyContains, hasAttachment, importance
+- Actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, delete
+
+---
+
+#### `rule create` — Create Inbox Rule
+
+Creates an inbox rule that automatically processes incoming emails. Needs a name, at least one condition, and at least one action.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--name` | string | yes | Rule name |
+| `--fromAddresses` | string | condition | Comma-separated sender emails to match |
+| `--containsSubject` | string | condition | Text that must appear in subject |
+| `--hasAttachments` | boolean | condition | Match only emails with attachments |
+| `--moveToFolder` | string | action | Folder name to move matching emails to |
+| `--markAsRead` | boolean | action | Auto-mark matching emails as read |
+| `--isEnabled` | boolean | — | Whether rule is active (default: `true`) |
+| `--sequence` | number | — | Execution order (lower = first); auto-assigned if omitted |
+
+At least one condition (`--fromAddresses`, `--containsSubject`, `--hasAttachments`) and at least one action (`--moveToFolder`, `--markAsRead`) are required.
+
+**Examples:**
+```bash
+# Auto-move emails from boss to Important folder
+outlook-cli rule create \
+  --name "Boss emails" \
+  --fromAddresses boss@company.com \
+  --moveToFolder Important
+
+# Auto-file newsletters and mark as read
+outlook-cli rule create \
+  --name "Newsletter handler" \
+  --fromAddresses "news@service.com,digest@news.com" \
+  --moveToFolder Newsletters \
+  --markAsRead \
+  --sequence 10
+
+# Rule based on subject text
+outlook-cli rule create \
+  --name "Invoice sorter" \
+  --containsSubject invoice \
+  --hasAttachments \
+  --moveToFolder Finance
+
+# Disabled rule (create but don't activate yet)
+outlook-cli rule create \
+  --name "Temp filter" \
+  --fromAddresses test@example.com \
+  --markAsRead \
+  --isEnabled false
+```
+
+**Notes:**
+- The `moveToFolder` target must already exist. Create it first with `folder create`.
+- If `--sequence` is not provided, the rule is placed after all existing rules.
+
+---
+
+#### `rule sequence` — Change Rule Execution Order
+
+Changes the sequence (execution order) of an existing rule. Lower sequence numbers run first.
+
+**Parameters:**
+
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--ruleName` | string | yes | Exact name of the rule to reorder |
+| `--sequence` | number | yes | New sequence number |
+
+**Examples:**
+```bash
+# Make boss email rule run first
+outlook-cli rule sequence --ruleName "Boss emails" --sequence 1
+
+# Push newsletter rule later in the order
+outlook-cli rule sequence --ruleName "Newsletter handler" --sequence 500
+```
+
+---
+
+### `tools` — Tool Inspection
+
+| Command | Description | Example |
+|---|---|---|
+| `tools list` | List all available MCP tools | `outlook-cli tools list` |
+| `tools schema` | Show schema for a specific tool | `outlook-cli tools schema list-emails` |
+
+**Examples:**
+```bash
+# See all tools
+outlook-cli tools list
+
+# Inspect a tool's parameters
+outlook-cli tools schema send-email
+outlook-cli tools schema create-event
+```
+
+---
+
+### `call` — Generic Tool Invocation
+
+Invoke any MCP tool directly by name with JSON arguments.
+
+```bash
+outlook-cli call <tool-name> --args-json '<json>'
+```
+
+**Examples:**
+```bash
+# List emails via generic call
+outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}'
+
+# Send email via generic call
+outlook-cli call send-email --args-json '{"to":"user@example.com","subject":"Hi","body":"Hello"}'
+
+# With JSON output
+outlook-cli call list-events --args-json '{"count":10}' --json
+```
+
+---
+
+### `doctor` — Diagnostics
+
+Runs a series of diagnostic checks and reports what's working and what needs fixing.
+
+```bash
+outlook-cli doctor
+```
+
+Checks: Node.js version, environment variables, token file presence, token validity, server connectivity.
+
+---
+
+### `update` — Update the CLI
+
+```bash
+# Check for updates
+outlook-cli update
+
+# Run the update automatically
+outlook-cli update --run
+```
+
+Or update via npm directly:
+```bash
+npm i -g outlook-cli@latest
+```
+
+---
+
+## Output Flags (All Commands)
+
+| Flag | Description |
+|---|---|
+| `--json` | Output raw JSON instead of human-readable text |
+| `--plain` | No colors or formatting |
+| `--no-color` | Disable color only |
+| `--no-animate` | Disable spinner animations |
+
+**Examples:**
+```bash
+outlook-cli auth status --json
+outlook-cli email list --count 10 --json
+outlook-cli calendar list --plain
+```
+
+---
+
+## Complete MCP Tool Catalog
+
+All 19 tools are available through the shared MCP tool registry — used by Claude and other AI assistants, and also callable via `outlook-cli call <tool-name>`.
+
+### Authentication Tools
+
+| Tool | What it does | Required | Optional |
+|---|---|---|---|
+| `about` | Returns server name, version, description | none | none |
+| `authenticate` | Starts OAuth flow, returns auth URL | none | `force` (boolean) |
+| `check-auth-status` | Returns current auth status | none | none |
+
+### Calendar Tools
+
+| Tool | What it does | Required | Optional |
+|---|---|---|---|
+| `list-events` | List upcoming calendar events | none | `count` (1–50) |
+| `create-event` | Create a new event | `subject`, `start`, `end` | `attendees` (array), `body` |
+| `decline-event` | Decline an event invitation | `eventId` | `comment` |
+| `cancel-event` | Cancel an event and notify attendees | `eventId` | `comment` |
+| `delete-event` | Delete an event silently | `eventId` | none |
+
+### Email Tools
+
+| Tool | What it does | Required | Optional |
+|---|---|---|---|
+| `list-emails` | List recent emails from a folder | none | `folder`, `count` |
+| `search-emails` | Search with text and filter criteria | none | `query`, `folder`, `from`, `to`, `subject`, `hasAttachments`, `unreadOnly`, `count` |
+| `read-email` | Read full content of one email | `id` | none |
+| `send-email` | Send a new email | `to`, `subject`, `body` | `cc`, `bcc`, `importance`, `saveToSentItems` |
+| `mark-as-read` | Mark email read or unread | `id` | `isRead` (boolean, default `true`) |
+
+### Folder Tools
+
+| Tool | What it does | Required | Optional |
+|---|---|---|---|
+| `list-folders` | List all mail folders | none | `includeItemCounts`, `includeChildren` |
+| `create-folder` | Create a new folder | `name` | `parentFolder` |
+| `move-emails` | Move emails to another folder | `emailIds` (comma-separated), `targetFolder` | `sourceFolder` |
+
+### Rules Tools
+
+| Tool | What it does | Required | Optional |
+|---|---|---|---|
+| `list-rules` | List inbox rules by execution order | none | `includeDetails` |
+| `create-rule` | Create inbox rule (1 condition + 1 action minimum) | `name` + condition + action | `isEnabled`, `sequence` |
+| `edit-rule-sequence` | Change rule execution order | `ruleName`, `sequence` | none |
+
+---
+
+## MCP Server Mode (for Claude and AI Assistants)
+
+Run as a standard MCP stdio server for use with Claude Desktop or other MCP clients:
+
+```bash
+npm run mcp-server
+# or
+node index.js
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config file (`claude-config-sample.json` is included as a reference):
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "node",
+      "args": ["/path/to/outlook-mcp/index.js"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "your-client-id",
+        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "outlook-cli",
+      "args": ["mcp-server"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "your-client-id",
+        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+### AI Assistant Skill
+
+A complete skill reference for AI assistants (Claude and others) is in [skill/outlook-mcp.md](skill/outlook-mcp.md). This document covers every tool, every parameter, common workflows, and examples — useful for RAG systems or as a system prompt addition.
+
+---
+
+## Token Behavior
+
+- Tokens are stored at `~/.outlook-mcp-tokens.json` (Windows: `%USERPROFILE%\.outlook-mcp-tokens.json`)
+- Tokens survive package updates and reinstalls — no need to re-authenticate after upgrading
+- Access tokens auto-refresh when expired (using the refresh token)
+- Force re-authentication anytime with `outlook-cli auth login --force` or `authenticate { force: true }`
+
+---
+
+## Test Mode
+
+```bash
+USE_TEST_MODE=true outlook-cli email list
+```
+
+With `USE_TEST_MODE=true`, all API calls use mock data — no real Microsoft account needed. Useful for development and CI testing.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `AADSTS7000215` error | You're using the Secret ID instead of the secret **Value** in Azure |
+| Auth server won't start | Run `npx kill-port 3333` then try again |
+| "Not authenticated" after token exists | Token expired with no refresh token — run `auth login` again |
+| `create-rule` fails on folder | Folder doesn't exist — run `folder create` first |
+| `move-emails` partial failure | Some email IDs were invalid — verify IDs with `email list` |
+| Missing dependencies | Run `npm install` |
+
+---
+
+## AI Assistant Skill
+
+The `skills/outlook-automation/` folder contains a structured skill for Claude Code, OpenAI Codex, and VS Code.
+
+### Install the skill
+
+```bash
+# Claude Code — personal
+uv run python tools/install_skill.py --personal
+
+# Claude Code — project/team
+uv run python tools/install_skill.py --project
+
+# OpenAI Codex
+uv run python tools/install_skill.py --codex
+
+# Verify
+uv run python tools/install_skill.py --verify --personal
+```
+
+> **Note:** OpenAI Codex skills require the experimental feature flag. Add to `~/.codex/config.toml`:
+> ```toml
+> [features]
+> skills = true
+> ```
+
+### Skill structure
+
+| File | Contents |
+|---|---|
+| [skills/outlook-automation/SKILL.md](skills/outlook-automation/SKILL.md) | Main skill entry — overview, behavioral rules, quick examples, install instructions |
+| [skills/outlook-automation/reference/cli.md](skills/outlook-automation/reference/cli.md) | Complete CLI command reference — every command, flag, and example |
+| [skills/outlook-automation/reference/json-schema.md](skills/outlook-automation/reference/json-schema.md) | JSON schemas for all 19 MCP tools |
+| [skills/outlook-automation/reference/security.md](skills/outlook-automation/reference/security.md) | OAuth flow, token lifecycle, permission scopes, AI safety rules |
+| [skills/outlook-automation/reference/troubleshooting.md](skills/outlook-automation/reference/troubleshooting.md) | Common errors, diagnostic checklist, step-by-step fixes |
+
+---
+
+## Documentation
+
+| File | Contents |
+|---|---|
+| [docs/REFERENCE.md](docs/REFERENCE.md) | Full parameter-by-parameter API reference |
+| [CLI.md](CLI.md) | CLI quick reference card |
+| [QUICKSTART.md](QUICKSTART.md) | Setup walkthrough for new users |
+| [docs/PROJECT-STRUCTURE.md](docs/PROJECT-STRUCTURE.md) | Codebase architecture and module overview |
+| [docs/PUBLISHING.md](docs/PUBLISHING.md) | Publishing checklist for maintainers |
+| [claude-config-sample.json](claude-config-sample.json) | Sample Claude Desktop MCP config |
+
+---
+
+## Scripts Reference
+
+| Script | Command | Description |
+|---|---|---|
+| `npm start` | `node cli.js` | Run the CLI |
+| `npm run mcp-server` | `node index.js` | Run as MCP stdio server |
+| `npm run cli` | `node cli.js` | CLI alias |
+| `npm run auth-server` | `node outlook-auth-server.js` | Start OAuth callback server on port 3333 |
+| `npm run doctor` | `node cli.js doctor` | Run diagnostics |
+| `npm run inspect` | MCP Inspector | Test MCP server interactively |
+| `npm test` | Jest | Run unit tests |