@littlebearapps/outlook-assistant 3.4.1 → 3.5.1

package/.env.example

@@ -20,3 +20,11 @@ USE_TEST_MODE=false
 
 # Restrict sending to specific domains/addresses (comma-separated)
 # OUTLOOK_ALLOWED_RECIPIENTS=mycompany.com,partner@example.com
+
+# Optional: Enable immutable IDs (IDs persist through folder moves)
+# OUTLOOK_IMMUTABLE_IDS=true
+
+# Optional: Default authentication method (device-code or browser)
+# device-code: No auth server needed, works remotely/headless
+# browser: Traditional OAuth redirect via localhost:3333
+# OUTLOOK_AUTH_METHOD=device-code

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/outlook-assistant-logo-full.svg" height="200" alt="Outlook Assistant" />
+  <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/assets/outlook-assistant-logo-full.png" height="200" alt="Outlook Assistant" />
 </p>
 
 <h1 align="center">Outlook Assistant</h1>
@@ -11,13 +11,9 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/v/@littlebearapps/outlook-assistant" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/dm/@littlebearapps/outlook-assistant" alt="npm downloads" /></a>
-  <a href="https://github.com/littlebearapps/outlook-assistant/stargazers"><img src="https://img.shields.io/github/stars/littlebearapps/outlook-assistant" alt="GitHub stars" /></a>
-  <a href="https://github.com/littlebearapps/outlook-assistant/commits/main"><img src="https://img.shields.io/github/last-commit/littlebearapps/outlook-assistant" alt="Last commit" /></a>
   <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a>
-  <a href="https://github.com/littlebearapps/outlook-assistant/issues"><img src="https://img.shields.io/github/issues/littlebearapps/outlook-assistant" alt="Open issues" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js" /></a>
 </p>
 
 Outlook Assistant connects AI assistants to your Microsoft Outlook account through the [Model Context Protocol](https://modelcontextprotocol.io/). Ask your AI assistant to search your inbox, send emails, schedule meetings, manage contacts, and configure mailbox settings — without leaving the conversation. Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
@@ -37,7 +33,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 ### What you can do
 
 - 📨 **Search and read emails** — find messages by sender, subject, date, or keywords; read full threads with conversation grouping; batch flag, move, export, or categorise multiple emails at once
-- 🛡️ **Send emails with safety controls** — dry-run preview, session rate limiting, and recipient allowlist to prevent mistakes
+- 🛡️ **Send emails with safety controls** — dry-run preview, pre-send mail tips (out-of-office, mailbox full, delivery restrictions), session rate limiting, and recipient allowlist to prevent mistakes
 - 📅 **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations
 - 📦 **Export emails** — save to Markdown, EML, MBOX, JSON, or HTML for archiving, analysis, or migration; export search results or entire threads in one call
 - 🔍 **Investigate email headers** — check DKIM, SPF, and DMARC authentication; trace delivery chains; analyse spam scores — useful for phishing investigation and compliance
@@ -64,7 +60,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 | Module | Tools | What You Can Do |
 |--------|------:|-----------------|
-| **Email** | 6 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run), `update-email` (read status, flags), `attachments`, `export` |
+| **Email** | 7 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run + mail tips), `update-email` (read status, flags), `attachments`, `export`, `get-mail-tips` |
 | **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (decline/cancel/delete) |
 | **Contacts** | 2 | `manage-contact` (list/search/get/create/update/delete), `search-people` |
 | **Categories** | 3 | `manage-category` (CRUD), `apply-category`, `manage-focused-inbox` |
@@ -74,7 +70,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 | **Advanced** | 2 | `access-shared-mailbox`, `find-meeting-rooms` |
 | **Auth** | 1 | `auth` (status/authenticate/about) |
 
-**20 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.
+**21 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.
 
 ### Export Formats
 
@@ -115,6 +111,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 - **Email forensics** — full header analysis (DKIM, SPF, DMARC, delivery chain, spam scores) built in as a first-class feature — useful for phishing investigation, compliance, and security review.
 - **Delta sync** — incremental inbox monitoring returns only what changed since your last check, with tokens for continuous polling. Designed for agent workflows that need to watch a mailbox.
 - **Batch operations** — flag, move, export, or categorise multiple emails in a single call. Search-driven export lets you batch-export results without collecting IDs manually.
+- **Pre-send intelligence** — check recipients for out-of-office, full mailbox, delivery restrictions, and moderation status before sending — no other Outlook MCP server offers this.
 - **Compound automation** — rules, categories, folders, and Focused Inbox work together. Set up complete inbox management through your AI assistant in one conversation.
 
 ## Safety & Token Efficiency
@@ -124,11 +121,12 @@ Outlook Assistant is designed with safety-first principles for AI-driven email a
 **Destructive action safeguards** — Every tool carries [MCP annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so AI clients can auto-approve safe reads and prompt for confirmation on destructive operations like sending email or deleting events.
 
 **Send-email protections** — The `send-email` tool includes:
+- **Pre-send mail tips** (`checkRecipients: true`) — check recipients for out-of-office, mailbox full, delivery restrictions before sending
 - **Dry-run mode** (`dryRun: true`) — preview composed emails without sending
 - **Session rate limiting** — configurable via `OUTLOOK_MAX_EMAILS_PER_SESSION` (default: unlimited)
 - **Recipient allowlist** — restrict sending to approved addresses/domains via `OUTLOOK_ALLOWED_RECIPIENTS`
 
-**Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 20 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.
+**Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 21 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.
 
 > **Important**: These safeguards are defence-in-depth measures that reduce risk, but they are not a guarantee against unintended actions. AI-driven access to your email is inherently sensitive — always review tool calls before approving, particularly for sends and deletes. No automated guardrail is foolproof, and you remain responsible for actions taken through your mailbox.
 
@@ -154,6 +152,7 @@ You need a Microsoft Azure app registration to authenticate. See the **[Azure Se
 2. Set redirect URI to `http://localhost:3333/auth/callback`
 3. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
 4. Create a client secret and copy the **Value** (not the Secret ID)
+5. Enable **"Allow public client flows"** in Authentication > Advanced settings (for device code flow)
 
 ### 3. Configure Your MCP Client
 
@@ -191,6 +190,10 @@ Then set environment variables in your `.env` or shell.
 <details>
 <summary><strong>Cursor</strong> (<code>.cursor/mcp.json</code>)</summary>
 
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Outlook%20Assistant&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsaXR0bGViZWFyYXBwcy9vdXRsb29rLWFzc2lzdGFudCJdLCJlbnYiOnsiT1VUTE9PS19DTElFTlRfSUQiOiIiLCJPVVRMT09LX0NMSUVOVF9TRUNSRVQiOiIifX0=)
+
+Or add manually to `.cursor/mcp.json`:
+
 ```json
 {
   "mcpServers": {
@@ -338,7 +341,21 @@ If installed from source, use `node` instead of `npx`:
 
 ## Authentication Flow
 
-### Step 1: Start the Auth Server
+### Device Code Flow (Default — Recommended)
+
+No auth server needed. Works everywhere, including remote/headless environments.
+
+1. Ask your AI assistant to authenticate (calls `auth` tool with `action=authenticate`)
+2. Visit the URL shown (`microsoft.com/devicelogin`) on **any** browser, **any** device
+3. Enter the code, sign in with your Microsoft account, and grant permissions
+4. Tell your AI assistant to complete authentication (calls `auth` with `action=device-code-complete`)
+5. Tokens are saved to `~/.outlook-assistant-tokens.json` and **refresh automatically**
+
+> **Prerequisite**: Enable "Allow public client flows" in Azure Portal > your app > Authentication > Advanced settings.
+
+### Browser Redirect Flow (Alternative)
+
+For localhost development or if you prefer the traditional OAuth flow:
 
 ```bash
 npm run auth-server
@@ -346,24 +363,22 @@ npm run auth-server
 
 This starts a local server on port 3333 to handle the OAuth callback.
 
-> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables (or `MS_CLIENT_ID`/`MS_CLIENT_SECRET`). When running the auth server separately, ensure your `.env` file is in the project root or export the variables in your shell. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.
-
-### Step 2: Authenticate
-
-1. In your AI assistant, use the `auth` tool with `action=authenticate`
+1. In your AI assistant, use the `auth` tool with `action=authenticate, method=browser`
 2. Open the provided URL in your browser
-3. Sign in with your Microsoft account and grant permissions
-4. Tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+3. Sign in and grant permissions — tokens are saved automatically
+
+> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.
 
 ## Directory Structure
 
 ```
 outlook-assistant/
-├── index.js                 # Main entry point (20 tools)
+├── index.js                 # Main entry point (21 tools)
 ├── config.js                # Configuration settings
 ├── outlook-auth-server.js   # OAuth server (port 3333)
 ├── auth/                    # Authentication module (1 tool)
-├── email/                   # Email module (6 tools)
+├── email/                   # Email module (7 tools)
+│   ├── mail-tips.js         # Pre-send recipient validation
 │   ├── headers.js           # Email header retrieval
 │   ├── mime.js              # Raw MIME/EML content
 │   ├── conversations.js     # Thread listing/export
@@ -377,7 +392,7 @@ outlook-assistant/
 ├── rules/                   # Rules module (1 tool)
 ├── advanced/                # Advanced module (2 tools)
 └── utils/
-    ├── graph-api.js         # Microsoft Graph API client
+    ├── graph-api.js         # Microsoft Graph API client (includes $batch)
     ├── safety.js            # Rate limiting, recipient allowlist, dry-run
     ├── odata-helpers.js     # OData query building
     ├── field-presets.js     # Token-efficient field selections
@@ -406,7 +421,11 @@ You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Port
 
 ### Authentication URL doesn't work
 
-Start the auth server first: `npm run auth-server`
+If using browser flow: start the auth server first with `npm run auth-server`. If using device code flow: visit `microsoft.com/devicelogin` instead.
+
+### Device code "invalid_client"
+
+Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings.
 
 ### Empty API responses
 
@@ -444,9 +463,9 @@ USE_TEST_MODE=true npm start
 |-------|-------------|
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
-| [How-To Guides](docs/how-to/index.md) | 27 practical guides for email, calendar, contacts, and settings |
+| [How-To Guides](docs/how-to/index.md) | 28 practical guides for email, calendar, contacts, and settings |
 | [Troubleshooting & FAQ](docs/how-to/getting-started/verify-your-connection.md#common-connection-problems) | Common problems, re-authentication, and frequently asked questions |
-| [Tools Reference](docs/quickrefs/tools-reference.md) | All 20 tools with parameters |
+| [Tools Reference](docs/quickrefs/tools-reference.md) | All 21 tools with parameters |
 | [AI Agent Guide](docs/how-to/ai-agents/using-outlook-assistant-in-agents.md) | Tool selection and workflow patterns for AI agents |
 
 Full documentation: [docs/](docs/README.md)

package/auth/device-code.js

@@ -0,0 +1,139 @@
+/**
+ * Device Code Flow for Microsoft OAuth2
+ *
+ * Enables authentication without browser redirect — ideal for
+ * headless/remote environments (SSH, VPS, containers).
+ *
+ * The user gets a short code, visits https://microsoft.com/devicelogin
+ * on any device, and enters it. No auth server or port forwarding needed.
+ */
+const https = require('https');
+const querystring = require('querystring');
+const config = require('../config');
+
+/**
+ * POST helper for OAuth2 endpoints
+ * @param {string} url - Full URL to POST to
+ * @param {string} postData - URL-encoded form data
+ * @returns {Promise<{statusCode: number, body: object}>}
+ */
+function postRequest(url, postData) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(postData),
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            resolve({ statusCode: res.statusCode, body: JSON.parse(data) });
+          } catch (_e) {
+            reject(new Error(`Failed to parse response: ${data}`));
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Initiates the device code flow by requesting a device code from Azure.
+ * @param {string} clientId - Azure app client ID
+ * @param {string[]} scopes - OAuth2 scopes to request
+ * @returns {Promise<{userCode: string, verificationUri: string, deviceCode: string, expiresIn: number, interval: number, message: string}>}
+ */
+async function initiateDeviceCodeFlow(clientId, scopes) {
+  const postData = querystring.stringify({
+    client_id: clientId,
+    scope: scopes.join(' '),
+  });
+
+  const endpoint = config.AUTH_CONFIG.deviceCodeEndpoint;
+  const { statusCode, body } = await postRequest(endpoint, postData);
+
+  if (statusCode < 200 || statusCode >= 300) {
+    throw new Error(
+      body.error_description ||
+        `Device code request failed with status ${statusCode}`
+    );
+  }
+
+  return {
+    userCode: body.user_code,
+    verificationUri: body.verification_uri,
+    deviceCode: body.device_code,
+    expiresIn: body.expires_in,
+    interval: body.interval || 5,
+    message: body.message,
+  };
+}
+
+/**
+ * Polls the token endpoint until the user completes authentication.
+ * @param {string} clientId - Azure app client ID
+ * @param {string} deviceCode - Device code from initiateDeviceCodeFlow
+ * @param {number} interval - Polling interval in seconds
+ * @param {number} expiresIn - Seconds until the device code expires
+ * @returns {Promise<{access_token: string, refresh_token: string, expires_in: number, scope: string, token_type: string}>}
+ */
+async function pollForToken(clientId, deviceCode, interval, expiresIn) {
+  const endpoint = config.AUTH_CONFIG.tokenEndpoint;
+  const deadline = Date.now() + expiresIn * 1000;
+  let pollInterval = interval;
+
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+
+    const postData = querystring.stringify({
+      client_id: clientId,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      device_code: deviceCode,
+    });
+
+    const { statusCode, body } = await postRequest(endpoint, postData);
+
+    if (statusCode >= 200 && statusCode < 300) {
+      return body;
+    }
+
+    switch (body.error) {
+      case 'authorization_pending':
+        // User hasn't completed auth yet — keep polling
+        break;
+      case 'slow_down':
+        // Server asked us to slow down — increase interval by 5s
+        pollInterval += 5;
+        break;
+      case 'authorization_declined':
+        throw new Error('Authentication was declined by the user.');
+      case 'expired_token':
+        throw new Error(
+          'Device code expired. Please restart the authentication process.'
+        );
+      default:
+        throw new Error(
+          body.error_description ||
+            `Token polling failed: ${body.error || `status ${statusCode}`}`
+        );
+    }
+  }
+
+  throw new Error(
+    'Device code expired. Please restart the authentication process.'
+  );
+}
+
+module.exports = {
+  initiateDeviceCodeFlow,
+  pollForToken,
+};

package/auth/index.js

@@ -2,22 +2,32 @@
  * Authentication module for Outlook Assistant server
  */
 const tokenManager = require('./token-manager');
+const TokenStorage = require('./token-storage');
+const config = require('../config');
 const { authTools } = require('./tools');
 
+// Singleton TokenStorage instance with auto-refresh support
+const tokenStorage = new TokenStorage({
+  clientId: config.AUTH_CONFIG.clientId,
+  clientSecret: config.AUTH_CONFIG.clientSecret,
+  tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+  scopes: config.AUTH_CONFIG.scopes,
+  tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+});
+
 /**
- * Ensures the user is authenticated and returns an access token
+ * Ensures the user is authenticated and returns an access token.
+ * Automatically refreshes expired tokens via tokenStorage.
  * @param {boolean} forceNew - Whether to force a new authentication
  * @returns {Promise<string>} - Access token
  * @throws {Error} - If authentication fails
  */
 async function ensureAuthenticated(forceNew = false) {
   if (forceNew) {
-    // Force re-authentication
     throw new Error('Authentication required');
   }
 
-  // Check for existing token
-  const accessToken = tokenManager.getAccessToken();
+  const accessToken = await tokenStorage.getValidAccessToken();
   if (!accessToken) {
     throw new Error('Authentication required');
   }
@@ -26,7 +36,8 @@ async function ensureAuthenticated(forceNew = false) {
 }
 
 module.exports = {
-  tokenManager,
+  tokenManager, // deprecated: use tokenStorage
+  tokenStorage,
   authTools,
   ensureAuthenticated,
 };

package/auth/tools.js

@@ -3,6 +3,7 @@
  */
 const config = require('../config');
 const tokenManager = require('./token-manager');
+const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
 
 /**
  * About tool handler
@@ -46,18 +47,14 @@ async function handleAbout() {
 }
 
 /**
- * Authentication tool handler
+ * Authentication tool handler — supports browser redirect and device code flow.
  * @param {object} args - Tool arguments
  * @returns {object} - MCP response
  */
 async function handleAuthenticate(args) {
-  const _force = args && args.force === true;
-
   // For test mode, create a test token
   if (config.USE_TEST_MODE) {
-    // Create a test token with a 1-hour expiry
     tokenManager.createTestTokens();
-
     return {
       content: [
         {
@@ -68,43 +65,205 @@ async function handleAuthenticate(args) {
     };
   }
 
-  // For real authentication, generate an auth URL and instruct the user to visit it
+  const method = args?.method || config.AUTH_CONFIG.defaultAuthMethod;
+
+  if (method === 'device-code') {
+    return handleDeviceCodeAuth();
+  }
+
+  // Browser redirect flow (existing behaviour)
   const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${config.AUTH_CONFIG.clientId}`;
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.\n\nNote: The auth server must be running on port 3333. If working remotely, consider using method=device-code instead.`,
+      },
+    ],
+  };
+}
+
+// Module-level state for pending device code flow
+let pendingDeviceCode = null;
+
+/**
+ * Device code flow step 1 — request a code for the user to enter.
+ * Returns the code + URL immediately. Call device-code-complete to finish.
+ * @returns {object} - MCP response
+ */
+async function handleDeviceCodeAuth() {
+  const clientId = config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Error: OUTLOOK_CLIENT_ID is not configured.',
+        },
+      ],
+    };
+  }
+
+  console.error('[AUTH] Starting device code flow...');
+  const response = await initiateDeviceCodeFlow(
+    clientId,
+    config.AUTH_CONFIG.scopes
+  );
+
+  // Store for the completion step
+  pendingDeviceCode = {
+    deviceCode: response.deviceCode,
+    interval: response.interval,
+    expiresIn: response.expiresIn,
+    expiresAt: Date.now() + response.expiresIn * 1000,
+  };
+
+  console.error(
+    `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
+  );
 
   return {
     content: [
       {
         type: 'text',
-        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.`,
+        text: [
+          `## Device Code Authentication\n`,
+          `Visit: **${response.verificationUri}**`,
+          `Enter code: **${response.userCode}**\n`,
+          `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
+          `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`,
+        ].join('\n'),
       },
     ],
   };
 }
 
 /**
- * Check authentication status tool handler
+ * Device code flow step 2 — poll until the user completes authentication.
+ * @returns {object} - MCP response
+ */
+async function handleDeviceCodeComplete() {
+  if (!pendingDeviceCode) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'No pending device code flow. Call authenticate with method=device-code first.',
+        },
+      ],
+    };
+  }
+
+  if (Date.now() > pendingDeviceCode.expiresAt) {
+    pendingDeviceCode = null;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Device code has expired. Please start a new authentication with action=authenticate.',
+        },
+      ],
+    };
+  }
+
+  const clientId = config.AUTH_CONFIG.clientId;
+
+  try {
+    console.error('[AUTH] Polling for device code completion...');
+    const tokenResponse = await pollForToken(
+      clientId,
+      pendingDeviceCode.deviceCode,
+      pendingDeviceCode.interval,
+      Math.ceil((pendingDeviceCode.expiresAt - Date.now()) / 1000)
+    );
+
+    pendingDeviceCode = null;
+
+    // Save tokens using TokenStorage
+    const TokenStorage = require('./token-storage');
+    const tokenStorage = new TokenStorage({
+      clientId: config.AUTH_CONFIG.clientId,
+      clientSecret: config.AUTH_CONFIG.clientSecret,
+      tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+      scopes: config.AUTH_CONFIG.scopes,
+      tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+    });
+
+    tokenStorage.tokens = {
+      access_token: tokenResponse.access_token,
+      refresh_token: tokenResponse.refresh_token,
+      expires_in: tokenResponse.expires_in,
+      expires_at: Date.now() + tokenResponse.expires_in * 1000,
+      scope: tokenResponse.scope,
+      token_type: tokenResponse.token_type,
+    };
+    await tokenStorage._saveTokensToFile();
+
+    console.error('[AUTH] Device code flow completed successfully.');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Authentication successful! Tokens saved. You can now use Outlook tools.',
+        },
+      ],
+    };
+  } catch (error) {
+    pendingDeviceCode = null;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Authentication failed: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Check authentication status — attempts token refresh if expired.
  * @returns {object} - MCP response
  */
 async function handleCheckAuthStatus() {
   console.error('[CHECK-AUTH-STATUS] Starting authentication status check');
 
-  const tokens = tokenManager.loadTokenCache();
+  // Use TokenStorage for accurate status (includes refresh attempt)
+  const TokenStorage = require('./token-storage');
+  const tokenStorage = new TokenStorage({
+    clientId: config.AUTH_CONFIG.clientId,
+    clientSecret: config.AUTH_CONFIG.clientSecret,
+    tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+    scopes: config.AUTH_CONFIG.scopes,
+    tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+  });
 
-  console.error(`[CHECK-AUTH-STATUS] Tokens loaded: ${tokens ? 'YES' : 'NO'}`);
+  const accessToken = await tokenStorage.getValidAccessToken();
 
-  if (!tokens || !tokens.access_token) {
-    console.error('[CHECK-AUTH-STATUS] No valid access token found');
+  if (!accessToken) {
+    console.error('[CHECK-AUTH-STATUS] No valid access token');
     return {
       content: [{ type: 'text', text: 'Not authenticated' }],
     };
   }
 
-  console.error('[CHECK-AUTH-STATUS] Access token present');
-  console.error(`[CHECK-AUTH-STATUS] Token expires at: ${tokens.expires_at}`);
-  console.error(`[CHECK-AUTH-STATUS] Current time: ${Date.now()}`);
+  const expiresAt = tokenStorage.getExpiryTime();
+  const expiresIn = expiresAt
+    ? Math.round((expiresAt - Date.now()) / 60000)
+    : 'unknown';
+
+  console.error(
+    `[CHECK-AUTH-STATUS] Authenticated, token expires in ~${expiresIn} min`
+  );
 
   return {
-    content: [{ type: 'text', text: 'Authenticated and ready' }],
+    content: [
+      {
+        type: 'text',
+        text: `Authenticated and ready (token expires in ~${expiresIn} minutes)`,
+      },
+    ],
   };
 }
 
@@ -113,7 +272,7 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state, action=authenticate starts OAuth flow, action=about shows server info.',
+      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state and refreshes tokens if needed, action=authenticate starts OAuth flow (device-code by default — no auth server needed), action=device-code-complete finishes device code auth after user enters code, action=about shows server info.',
     annotations: {
       title: 'Authentication',
       readOnlyHint: false,
@@ -125,9 +284,15 @@ const authTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['status', 'authenticate', 'about'],
+          enum: ['status', 'authenticate', 'device-code-complete', 'about'],
           description: 'Action to perform (default: status)',
         },
+        method: {
+          type: 'string',
+          enum: ['device-code', 'browser'],
+          description:
+            'Auth method for action=authenticate. device-code (default): no auth server needed, works remotely. browser: traditional OAuth redirect via port 3333.',
+        },
         force: {
           type: 'boolean',
           description:
@@ -141,6 +306,8 @@ const authTools = [
       switch (action) {
         case 'authenticate':
           return handleAuthenticate(args);
+        case 'device-code-complete':
+          return handleDeviceCodeComplete();
         case 'about':
           return handleAbout();
         case 'status':
@@ -155,5 +322,7 @@ module.exports = {
   authTools,
   handleAbout,
   handleAuthenticate,
+  handleDeviceCodeAuth,
+  handleDeviceCodeComplete,
   handleCheckAuthStatus,
 };