@littlebearapps/outlook-assistant 3.12.1 → 3.13.0

package/README.md

@@ -17,7 +17,7 @@
   <a href="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant"><img src="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant/badges/score.svg" alt="Glama score" /></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.
+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, GitHub Copilot, Cursor, Windsurf, and any MCP-compatible client.
 
 **Works with personal Outlook.com and work/school Microsoft 365 accounts.**
 
@@ -135,7 +135,6 @@ Outlook Assistant is designed with safety-first principles for AI-driven email a
 > ```json
 > "env": {
 >   "OUTLOOK_CLIENT_ID": "…",
->   "OUTLOOK_CLIENT_SECRET": "…",
 >   "OUTLOOK_MAX_EMAILS_PER_SESSION": "10",
 >   "OUTLOOK_ALLOWED_RECIPIENTS": "your-domain.com,trusted@example.com"
 > }
@@ -166,7 +165,7 @@ npx @littlebearapps/outlook-assistant
 To check which version you have, or to see the available options:
 
 ```bash
-outlook-assistant --version     # prints e.g. 3.12.1
+outlook-assistant --version     # prints e.g. 3.13.0
 outlook-assistant --help        # usage, options and key environment variables
 ```
 
@@ -180,14 +179,23 @@ You need a Microsoft Azure app registration to authenticate. See the **[Azure Se
 
 1. Create a new app registration at [portal.azure.com](https://portal.azure.com/)
 2. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
-3. Create a client secret and copy the **Value** (not the Secret ID)
+3. _(Browser flow only)_ Create a client secret and copy the **Value** (not the Secret ID). The default device-code sign-in doesn't need one
 4. Under Authentication > **Add a platform** > **Mobile and desktop applications** — check `nativeclient` URI
 5. Enable **"Allow public client flows"** in Authentication > Advanced settings
 6. _(Optional)_ Set redirect URI to `http://localhost:3333/auth/callback` — only needed for browser auth flow
 
 ### 3. Configure Your MCP Client
 
-Add to your MCP client config:
+**Plugin install (Claude Code).** The plugin bundles the server pinned to an exact version and asks for your settings when you enable it:
+
+```bash
+claude plugin marketplace add littlebearapps/outlook-assistant
+claude plugin install outlook-assistant@littlebearapps
+```
+
+The same plugin folder ([`plugins/outlook-assistant`](plugins/outlook-assistant/)) also follows the [Agent Plugins](https://agent-plugins.org/) format used by GitHub Copilot and Cursor.
+
+**Manual config.** Add to your MCP client config. Only `OUTLOOK_CLIENT_ID` is needed for the default device-code sign-in; add `OUTLOOK_CLIENT_SECRET` only if you use the [browser flow](#browser-redirect-flow-alternative). You can also leave the client ID out and give it to your assistant when you first connect (`auth action=authenticate clientId=…`), which saves it to `~/.outlook-assistant-config.json`. An `OUTLOOK_CLIENT_ID` in the environment always takes precedence.
 
 <details>
 <summary><strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>)</summary>
@@ -199,8 +207,7 @@ Add to your MCP client config:
       "command": "npx",
       "args": ["@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }
@@ -214,17 +221,46 @@ Add to your MCP client config:
 ```bash
 claude mcp add outlook \
   -e OUTLOOK_CLIENT_ID=your-application-client-id \
-  -e OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE \
   -- npx -y @littlebearapps/outlook-assistant
 ```
 
 The MCP server reads its settings from the environment your client passes it; it doesn't load a `.env` file.
 </details>
 
+<details>
+<summary><strong>VS Code / GitHub Copilot</strong> (<code>.vscode/mcp.json</code>)</summary>
+
+VS Code prompts for the client ID the first time the server starts and stores it securely:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "outlook-client-id",
+      "description": "Azure application (client) ID"
+    }
+  ],
+  "servers": {
+    "outlook": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "${input:outlook-client-id}"
+      }
+    }
+  }
+}
+```
+
+Use it from Copilot Chat in **Agent** mode. To use it in every workspace, add the same entry to your user `mcp.json` (Command Palette → **MCP: Open User Configuration**).
+</details>
+
 <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=)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Outlook%20Assistant&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsaXR0bGViZWFyYXBwcy9vdXRsb29rLWFzc2lzdGFudCJdLCJlbnYiOnsiT1VUTE9PS19DTElFTlRfSUQiOiIifX0=)
 
 Or add manually to `.cursor/mcp.json`:
 
@@ -235,8 +271,7 @@ Or add manually to `.cursor/mcp.json`:
       "command": "npx",
       "args": ["@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }
@@ -254,8 +289,7 @@ Or add manually to `.cursor/mcp.json`:
       "command": "npx",
       "args": ["@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }
@@ -339,6 +373,8 @@ a server that would ignore it.
 
 ### Create a Client Secret
 
+Only needed for the [browser redirect flow](#browser-redirect-flow-alternative). Skip this if you sign in with the default device code.
+
 1. Go to **Certificates & secrets** > **New client secret**
 2. Enter a description and select expiration
 3. Click **Add**
@@ -378,7 +414,7 @@ USE_TEST_MODE=false
 
 ### MCP Client Configuration
 
-See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, Cursor, and Windsurf configs.
+See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, VS Code / GitHub Copilot, Cursor, and Windsurf configs.
 
 If installed from source, use `node` instead of `npx`:
 
@@ -389,8 +425,7 @@ If installed from source, use `node` instead of `npx`:
       "command": "node",
       "args": ["/path/to/outlook-assistant/index.js"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }

package/auth/client-config.js

@@ -0,0 +1,142 @@
+/**
+ * Runtime-supplied Azure Application (client) ID.
+ *
+ * Plugin marketplaces (GitHub Copilot, Cursor — Agent Plugins 1.0) ship a
+ * static `mcp.json` with no way to prompt for settings, so users there can't
+ * set OUTLOOK_CLIENT_ID. Device-code sign-in only needs the client ID (never
+ * the secret), so the `auth` tool accepts it at runtime and it's persisted to
+ * `~/.outlook-assistant-config.json`.
+ *
+ * Precedence: OUTLOOK_CLIENT_ID env → MS_CLIENT_ID env (legacy) → saved file.
+ *
+ * Deliberately does NOT require ../config (config.js requires this module).
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONFIG_FILE_NAME = '.outlook-assistant-config.json';
+
+// Azure Application (client) IDs are GUIDs.
+const CLIENT_ID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Path of the persisted config file. Resolved per call (not at load) so a
+ * changed HOME — e.g. in tests — is honoured.
+ * @returns {string}
+ */
+function getConfigPath() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  return path.join(homeDir, CONFIG_FILE_NAME);
+}
+
+/**
+ * @param {unknown} id
+ * @returns {boolean} - true when `id` (trimmed) is a GUID
+ */
+function isValidClientId(id) {
+  return typeof id === 'string' && CLIENT_ID_RE.test(id.trim());
+}
+
+/**
+ * Read the whole config file. Never throws.
+ * @returns {object} - Parsed object, or {} when missing/unreadable/not an object
+ */
+function readConfigFile() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(getConfigPath(), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The saved client ID, or '' when there is none or it isn't a valid GUID.
+ * Never throws.
+ * @returns {string}
+ */
+function loadSavedClientId() {
+  const { clientId } = readConfigFile();
+  return isValidClientId(clientId) ? clientId.trim() : '';
+}
+
+/**
+ * Validate and persist a client ID (mode 0600, temp file + rename), keeping
+ * any other keys already in the file.
+ * @param {string} id
+ * @returns {string} - The normalised (trimmed) ID that was saved
+ * @throws {Error} - When `id` isn't a GUID or the write fails
+ */
+function saveClientId(id) {
+  if (!isValidClientId(id)) {
+    throw new Error(
+      'Invalid client ID: expected the Application (client) ID GUID from your Azure app registration.'
+    );
+  }
+  const clientId = id.trim();
+  const filePath = getConfigPath();
+  const data = { ...readConfigFile(), clientId };
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`, {
+      mode: 0o600,
+      flag: 'wx',
+    });
+    fs.renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      // Temp file was never created or is already gone
+    }
+    throw error;
+  }
+  return clientId;
+}
+
+/**
+ * Which environment variable supplies the client ID, if any.
+ * @returns {{name: string, value: string}|null}
+ */
+function getEnvClientId() {
+  // Trimmed, and blank counts as unset: plugin managers pass "" (or stray
+  // whitespace) for an unset option, which must not hide a saved ID.
+  for (const name of ['OUTLOOK_CLIENT_ID', 'MS_CLIENT_ID']) {
+    const value = (process.env[name] || '').trim();
+    if (value) return { name, value };
+  }
+  return null;
+}
+
+/**
+ * Effective client ID: env (OUTLOOK_CLIENT_ID, then legacy MS_CLIENT_ID),
+ * then the saved file, then ''.
+ * @returns {string}
+ */
+function resolveClientId() {
+  const env = getEnvClientId();
+  return env ? env.value : loadSavedClientId();
+}
+
+/**
+ * @returns {'env'|'saved'|'none'} - Where the effective client ID comes from
+ */
+function getClientIdSource() {
+  if (getEnvClientId()) return 'env';
+  return loadSavedClientId() ? 'saved' : 'none';
+}
+
+module.exports = {
+  CONFIG_FILE_NAME,
+  getConfigPath,
+  isValidClientId,
+  loadSavedClientId,
+  saveClientId,
+  getEnvClientId,
+  resolveClientId,
+  getClientIdSource,
+};

package/auth/index.js

@@ -6,9 +6,11 @@ const TokenStorage = require('./token-storage');
 const config = require('../config');
 const { authTools, setToolCount } = require('./tools');
 
-// Singleton TokenStorage instance with auto-refresh support
+// Singleton TokenStorage instance with auto-refresh support. No clientId is
+// passed: TokenStorage resolves it on each use (env → saved config file), so
+// an ID saved at runtime via `auth action=authenticate clientId=…` applies
+// without a restart.
 const tokenStorage = new TokenStorage({
-  clientId: config.AUTH_CONFIG.clientId,
   clientSecret: config.AUTH_CONFIG.clientSecret,
   tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
   scopes: config.AUTH_CONFIG.scopes,

package/auth/oauth-server.js

@@ -4,6 +4,7 @@ const _https = require('https'); // Reserved for future HTTPS support
 const _fs = require('fs'); // Reserved for future HTTPS support
 const crypto = require('crypto'); // Added for generating random string
 const TokenStorage = require('./token-storage'); // Assuming TokenStorage is in the same directory
+const { loadSavedClientId } = require('./client-config');
 
 // HTML templates
 function escapeHtml(unsafe) {
@@ -54,8 +55,11 @@ const templates = {
 
 function createAuthConfig(envPrefix = 'OUTLOOK_') {
   return {
+    // Env first; then the ID saved via `auth action=authenticate clientId=…`.
     clientId:
-      process.env[`${envPrefix}CLIENT_ID`] || process.env.MS_CLIENT_ID || '',
+      process.env[`${envPrefix}CLIENT_ID`] ||
+      process.env.MS_CLIENT_ID ||
+      loadSavedClientId(),
     clientSecret:
       process.env[`${envPrefix}CLIENT_SECRET`] ||
       process.env.MS_CLIENT_SECRET ||

package/auth/token-storage.js

@@ -4,6 +4,7 @@ const path = require('path');
 const https = require('https');
 const querystring = require('querystring');
 const { describeAuthError } = require('./auth-errors');
+const { resolveClientId } = require('./client-config');
 
 /**
  * Decide which scopes a refresh request should use. Prefer the scopes that were
@@ -42,7 +43,9 @@ class TokenStorage {
         process.env.HOME || process.env.USERPROFILE,
         '.outlook-assistant-tokens.json'
       ),
-      clientId: process.env.OUTLOOK_CLIENT_ID || process.env.MS_CLIENT_ID,
+      // No default clientId: when none is passed, getClientId() resolves it on
+      // every use (env → saved ~/.outlook-assistant-config.json), so an ID
+      // saved at runtime via the auth tool takes effect without a restart.
       clientSecret:
         process.env.OUTLOOK_CLIENT_SECRET || process.env.MS_CLIENT_SECRET,
       redirectUri:
@@ -80,7 +83,7 @@ class TokenStorage {
       }
     }
 
-    if (!this.config.clientId) {
+    if (!this.getClientId()) {
       console.warn(
         'TokenStorage: OUTLOOK_CLIENT_ID is not configured. Token operations will fail.'
       );
@@ -89,6 +92,15 @@ class TokenStorage {
     // Device code flow (public client) does not use client_secret.
   }
 
+  /**
+   * Client ID for token requests: an explicitly configured value wins,
+   * otherwise it is resolved now (OUTLOOK_CLIENT_ID → MS_CLIENT_ID → saved).
+   * @returns {string}
+   */
+  getClientId() {
+    return this.config.clientId || resolveClientId();
+  }
+
   async _loadTokensFromFile() {
     try {
       const tokenData = await fs.readFile(this.config.tokenStorePath, 'utf8');
@@ -149,12 +161,12 @@ class TokenStorage {
     await this.getTokens(); // Ensure tokens are loaded
 
     if (!this.tokens || !this.tokens.access_token) {
-      console.log('No access token available.');
+      console.error('No access token available.');
       return null;
     }
 
     if (this.isTokenExpired()) {
-      console.log(
+      console.error(
         'Access token expired or nearing expiration. Attempting refresh.'
       );
       if (this.tokens.refresh_token) {
@@ -193,7 +205,7 @@ class TokenStorage {
 
     // Prevent multiple concurrent refresh attempts
     if (this._refreshPromise) {
-      console.log('Refresh already in progress, returning existing promise.');
+      console.error('Refresh already in progress, returning existing promise.');
       return this._refreshPromise.then((tokens) => tokens.access_token);
     }
 
@@ -201,12 +213,12 @@ class TokenStorage {
     // in refresh requests for tokens obtained via device code.
     // Browser flow (confidential client) requires client_secret.
     const isDeviceCode = this.tokens.auth_method === 'device-code';
-    console.log(
+    console.error(
       `Attempting to refresh access token (auth_method: ${this.tokens.auth_method || 'browser'})...`
     );
 
     const refreshParams = {
-      client_id: this.config.clientId,
+      client_id: this.getClientId(),
       grant_type: 'refresh_token',
       refresh_token: this.tokens.refresh_token,
       // Use the GRANTED scopes, not the full configured set. After a base-only
@@ -247,7 +259,9 @@ class TokenStorage {
                   Date.now() + responseBody.expires_in * 1000;
                 try {
                   await this._saveTokensToFile();
-                  console.log('Access token refreshed and saved successfully.');
+                  console.error(
+                    'Access token refreshed and saved successfully.'
+                  );
                   resolve(this.tokens);
                 } catch (saveError) {
                   console.error('Failed to save refreshed tokens:', saveError);
@@ -298,15 +312,16 @@ class TokenStorage {
   }
 
   async exchangeCodeForTokens(authCode) {
-    if (!this.config.clientId || !this.config.clientSecret) {
+    const clientId = this.getClientId();
+    if (!clientId || !this.config.clientSecret) {
       throw new Error(
         'Client ID or Client Secret is not configured. Cannot exchange code for tokens.'
       );
     }
-    console.log('Exchanging authorization code for tokens...');
+    console.error('Exchanging authorization code for tokens...');
     const requestedScopes = this.config.scopes;
     const postData = querystring.stringify({
-      client_id: this.config.clientId,
+      client_id: clientId,
       client_secret: this.config.clientSecret,
       grant_type: 'authorization_code',
       code: authCode,
@@ -351,7 +366,7 @@ class TokenStorage {
                 };
                 try {
                   await this._saveTokensToFile();
-                  console.log('Tokens exchanged and saved successfully.');
+                  console.error('Tokens exchanged and saved successfully.');
                   resolve(this.tokens);
                 } catch (saveError) {
                   console.error('Failed to save exchanged tokens:', saveError);
@@ -408,10 +423,10 @@ class TokenStorage {
     this.tokens = null;
     try {
       await fs.unlink(this.config.tokenStorePath);
-      console.log('Token file deleted successfully.');
+      console.error('Token file deleted successfully.');
     } catch (error) {
       if (error.code === 'ENOENT') {
-        console.log('Token file not found, nothing to delete.');
+        console.error('Token file not found, nothing to delete.');
       } else {
         console.error('Error deleting token file:', error);
       }

package/auth/tools.js

@@ -6,6 +6,13 @@ const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
+const {
+  CONFIG_FILE_NAME,
+  isValidClientId,
+  saveClientId,
+  getEnvClientId,
+  getClientIdSource,
+} = require('./client-config');
 const {
   initiateDeviceCodeFlow,
   pollForToken,
@@ -19,6 +26,112 @@ const DEVICE_CODE_STATE_PATH = path.join(
   '.outlook-assistant-pending-auth.json'
 );
 
+const SETUP_GUIDE_URL =
+  'https://github.com/littlebearapps/outlook-assistant/blob/main/docs/how-to/getting-started/connect-outlook-to-claude.md';
+const SAVED_CONFIG_DISPLAY_PATH = `~/${CONFIG_FILE_NAME}`;
+
+/**
+ * Error shown when no client ID resolves (no env var, nothing saved). Written
+ * for the AI client: it tells it what to ask the user and which call to make.
+ * @returns {object} - MCP response ({ content, isError: true })
+ */
+function buildMissingClientIdResponse() {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: [
+          'Error: OUTLOOK_CLIENT_ID is not configured, so sign-in cannot start.',
+          '',
+          '1. Ask the user for the **Application (client) ID** of their Azure app registration (Azure portal → App registrations → their app → Overview). It is a GUID such as `00000000-0000-0000-0000-000000000000`.',
+          `2. Call \`auth action=authenticate clientId=<id>\`. The ID is saved to \`${SAVED_CONFIG_DISPLAY_PATH}\` (it is not a secret) and device-code sign-in starts.`,
+          '',
+          'The client secret is not needed for device-code sign-in (the default); only the browser flow uses it.',
+          `No app registration yet? Follow the setup guide: ${SETUP_GUIDE_URL}`,
+          'Alternatively, set OUTLOOK_CLIENT_ID in the MCP server environment and restart it.',
+        ].join('\n'),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Validate and save a client ID supplied via `auth action=authenticate`.
+ * @param {unknown} clientId
+ * @returns {{error: object}|{saved: string}} - An MCP error response, or the saved ID
+ */
+function applyClientIdArg(clientId) {
+  if (!isValidClientId(clientId)) {
+    return {
+      error: {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Error: `clientId` is not a valid Azure Application (client) ID.',
+              '',
+              'It must be the GUID shown as **Application (client) ID** on the app registration Overview page in the Azure portal, e.g. `00000000-0000-0000-0000-000000000000`. Do not use the Directory (tenant) ID, the Object ID or a client secret.',
+              `Setup guide: ${SETUP_GUIDE_URL}`,
+            ].join('\n'),
+          },
+        ],
+        isError: true,
+      },
+    };
+  }
+
+  const env = getEnvClientId();
+  if (env && env.value.trim().toLowerCase() !== clientId.trim().toLowerCase()) {
+    return {
+      error: {
+        content: [
+          {
+            type: 'text',
+            text: [
+              `Error: the ${env.name} environment variable is set to a different client ID, and it takes precedence over a saved one, so the \`clientId\` you supplied would be ignored.`,
+              '',
+              `To use the new ID, change or remove ${env.name} in the MCP server configuration, restart the server, then call \`auth action=authenticate\` again. Nothing was saved.`,
+            ].join('\n'),
+          },
+        ],
+        isError: true,
+      },
+    };
+  }
+
+  try {
+    return { saved: saveClientId(clientId) };
+  } catch (error) {
+    return {
+      error: {
+        content: [
+          {
+            type: 'text',
+            text: `Error: could not save the client ID to ${SAVED_CONFIG_DISPLAY_PATH}: ${error.message}`,
+          },
+        ],
+        isError: true,
+      },
+    };
+  }
+}
+
+/**
+ * Client ID row for `auth about`. The ID itself is never shown.
+ * @returns {string}
+ */
+function describeClientIdStatus() {
+  const source = getClientIdSource();
+  if (source === 'env') {
+    return `Configured (environment: ${getEnvClientId().name})`;
+  }
+  if (source === 'saved') {
+    return `Configured (saved in ${SAVED_CONFIG_DISPLAY_PATH})`;
+  }
+  return 'Not set (run `auth action=authenticate clientId=<Application (client) ID>`)';
+}
+
 // Dynamic tool count — set by index.js after TOOLS array is built
 let _toolCount = 0;
 function setToolCount(count) {
@@ -122,6 +235,7 @@ async function handleAbout() {
     `| Setting | Value |`,
     `|---------|-------|`,
     `| Mailbox | ${identity} |`,
+    `| Client ID | ${describeClientIdStatus()} |`,
     `| Tools | ${_toolCount} across 9 modules |`,
     `| Modules | auth, email, calendar, folder, rules, contacts, categories, settings, advanced |`,
     `| Timezone | ${config.DEFAULT_TIMEZONE} |`,
@@ -185,19 +299,54 @@ async function handleAuthenticate(args) {
     };
   }
 
+  // Optional runtime client ID (for clients that can't set env vars, e.g.
+  // plugin marketplaces): validate, refuse if an env var would override it,
+  // save, then carry on with the normal flow.
+  // null / blank counts as not supplied: some clients send empty optionals.
+  let savedPrefix;
+  const suppliedClientId = args?.clientId;
+  if (
+    suppliedClientId !== undefined &&
+    suppliedClientId !== null &&
+    String(suppliedClientId).trim() !== ''
+  ) {
+    const result = applyClientIdArg(suppliedClientId);
+    if (result.error) {
+      return result.error;
+    }
+    savedPrefix = `Saved your Azure Application (client) ID to \`${SAVED_CONFIG_DISPLAY_PATH}\`.`;
+  }
+
   const method = args?.method || config.AUTH_CONFIG.defaultAuthMethod;
 
   if (method === 'device-code') {
-    return handleDeviceCodeAuth();
+    return handleDeviceCodeAuth(savedPrefix);
   }
 
   // Browser redirect flow (existing behaviour)
-  const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${config.AUTH_CONFIG.clientId}`;
+  const clientId = config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    return buildMissingClientIdResponse();
+  }
+  const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${encodeURIComponent(clientId)}`;
+  const lines = [];
+  if (savedPrefix) {
+    lines.push(savedPrefix, '');
+  }
+  lines.push(
+    `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.`
+  );
+  if (getClientIdSource() !== 'env') {
+    lines.push(
+      '',
+      'The browser flow also needs the client secret: the auth server (`npm run auth-server`) reads OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET from its own environment and does not use a saved client ID. Device-code sign-in (the default) needs only the client ID.'
+    );
+  }
   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.`,
+        text: lines.join('\n'),
       },
     ],
   };
@@ -254,26 +403,20 @@ function loadDeviceCodeState() {
  * Device code flow step 1 — request a code for the user to enter.
  * Returns the code + URL immediately. Call device-code-complete to finish.
  * State is persisted to disk so it survives MCP server restarts.
+ * @param {string} [prefix] - Optional leading line (e.g. "client ID saved")
  * @returns {object} - MCP response
  */
-async function handleDeviceCodeAuth() {
+async function handleDeviceCodeAuth(prefix) {
   const clientId = config.AUTH_CONFIG.clientId;
   if (!clientId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Error: OUTLOOK_CLIENT_ID is not configured.',
-        },
-      ],
-    };
+    return buildMissingClientIdResponse();
   }
 
   console.error('[AUTH] Starting device code flow...');
   // Attempt the configured scope set (base, plus `.Shared` when
   // OUTLOOK_SHARED_MAILBOX opts in). If the account can't consent to
   // `.Shared`, handleDeviceCodeComplete re-issues with base scopes.
-  return initiateDeviceCode(config.AUTH_CONFIG.scopes, 'full');
+  return initiateDeviceCode(config.AUTH_CONFIG.scopes, 'full', prefix);
 }
 
 /**
@@ -318,13 +461,15 @@ async function initiateDeviceCode(scopes, scopesUsed, prefix) {
     return buildDeviceCodeErrorResponse(error);
   }
 
-  // Store in memory and persist to disk
+  // Store in memory and persist to disk. The client ID is recorded because
+  // the device code is bound to it: completion must poll with the same one.
   pendingDeviceCode = {
     deviceCode: response.deviceCode,
     interval: response.interval,
     expiresIn: response.expiresIn,
     expiresAt: Date.now() + response.expiresIn * 1000,
     scopesUsed,
+    clientId,
   };
   saveDeviceCodeState(pendingDeviceCode);
 
@@ -430,7 +575,14 @@ async function handleDeviceCodeComplete() {
     };
   }
 
-  const clientId = config.AUTH_CONFIG.clientId;
+  // Poll with the client ID the code was issued to (older state files don't
+  // record it, so fall back to the current one).
+  const clientId = pendingDeviceCode.clientId || config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    pendingDeviceCode = null;
+    saveDeviceCodeState(null);
+    return buildMissingClientIdResponse();
+  }
   // Capture which scope set this pending flow attempted, before any mutation.
   const scopesUsed = pendingDeviceCode.scopesUsed || 'full';
   // The scopes we attempted — used as the granted_scopes fallback when the
@@ -455,7 +607,7 @@ async function handleDeviceCodeComplete() {
     // Save tokens using TokenStorage — mark as device-code auth
     const TokenStorage = require('./token-storage');
     const tokenStorage = new TokenStorage({
-      clientId: config.AUTH_CONFIG.clientId,
+      clientId,
       clientSecret: config.AUTH_CONFIG.clientSecret,
       tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
       scopes: config.AUTH_CONFIG.scopes,
@@ -593,8 +745,12 @@ async function handleCheckAuthStatus() {
 
   if (!accessToken) {
     console.error('[CHECK-AUTH-STATUS] No valid access token');
+    const text =
+      getClientIdSource() === 'none'
+        ? `Not authenticated. No Azure Application (client) ID is configured yet: ask the user for the Application (client) ID of their Azure app registration, then call \`auth action=authenticate clientId=<id>\`. Setup guide: ${SETUP_GUIDE_URL}`
+        : 'Not authenticated';
     return {
-      content: [{ type: 'text', text: 'Not authenticated' }],
+      content: [{ type: 'text', text }],
     };
   }
 
@@ -622,7 +778,7 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state and auto-refreshes the access token if it\'s expired but the refresh token is still valid (~90-day window) — call this first to check before other tools. action=`authenticate` starts the OAuth flow: with `method: "device-code"` (default, works headlessly) it returns a code + URL for the user to visit; with `method: "browser"` it opens the local auth server on :3333 (run `npm run auth-server` first). Pass `force: true` to re-authenticate over an existing valid session. action=`device-code-complete` finishes device-code auth after the user enters the code in their browser — call this once authentication shows as successful in the browser. action=`about` returns server version, configured audience, scope list, and other diagnostic info. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
+      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state and auto-refreshes the access token if it\'s expired but the refresh token is still valid (~90-day window) — call this first to check before other tools. action=`authenticate` starts the OAuth flow: with `method: "device-code"` (default, works headlessly) it returns a code + URL for the user to visit; with `method: "browser"` it opens the local auth server on :3333 (run `npm run auth-server` first). Pass `force: true` to re-authenticate over an existing valid session. If sign-in reports that OUTLOOK_CLIENT_ID is not configured, ask the user for their Azure Application (client) ID and pass it as `clientId`. action=`device-code-complete` finishes device-code auth after the user enters the code in their browser — call this once authentication shows as successful in the browser. action=`about` returns server version, configured audience, scope list, and other diagnostic info. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
     annotations: {
       title: 'Authentication',
       readOnlyHint: false,
@@ -648,6 +804,11 @@ const authTools = [
           description:
             'Force re-authentication even if already authenticated (action=authenticate only)',
         },
+        clientId: {
+          type: 'string',
+          description:
+            "Optional, action=authenticate only. The user's Azure Application (client) ID (a GUID from the app registration's Overview page). Saved to `~/.outlook-assistant-config.json` and used from then on; it is not a secret. The OUTLOOK_CLIENT_ID environment variable takes precedence when set.",
+        },
       },
       additionalProperties: false,
       required: [],

package/config.js

@@ -14,6 +14,7 @@ const {
   getFolderFields,
 } = require('./utils/field-presets');
 const { VERBOSITY, DEFAULT_LIMITS } = require('./utils/response-formatter');
+const { resolveClientId } = require('./auth/client-config');
 
 // Ensure we have a home directory path — never fall back to /tmp (world-readable)
 const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
@@ -165,7 +166,12 @@ module.exports = {
 
   // Authentication configuration
   AUTH_CONFIG: {
-    clientId: process.env.OUTLOOK_CLIENT_ID || '',
+    // Getter, resolved on every read: OUTLOOK_CLIENT_ID → MS_CLIENT_ID →
+    // ~/.outlook-assistant-config.json (saved via `auth action=authenticate
+    // clientId=…`), so a saved ID takes effect without a restart.
+    get clientId() {
+      return resolveClientId();
+    },
     clientSecret: process.env.OUTLOOK_CLIENT_SECRET || '',
     redirectUri: 'http://localhost:3333/auth/callback',
     // Base scopes, plus the `.Shared` scopes only when OUTLOOK_SHARED_MAILBOX

package/index.js

@@ -31,8 +31,10 @@ stdio. It is normally launched by an MCP client (Claude Desktop, Claude Code)
 rather than run by hand — started from a terminal it will simply wait on stdin.
 
 Key environment variables:
-  OUTLOOK_CLIENT_ID                 Azure app registration client ID
-  OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID)
+  OUTLOOK_CLIENT_ID                 Azure Application (client) ID. If you can't set env
+                                    vars, pass it to the auth tool instead (action=authenticate
+                                    clientId=<id>); it's saved to ~/.outlook-assistant-config.json
+  OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID); browser flow only
   OUTLOOK_AUTH_METHOD               device-code (default) | browser
   OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
   OUTLOOK_SHARED_MAILBOX            Opt in to shared mailboxes: read | true (work/school only)

package/llms-install.md

@@ -11,8 +11,7 @@ Add to your MCP client configuration:
       "command": "npx",
       "args": ["-y", "@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "<user-must-provide>",
-        "OUTLOOK_CLIENT_SECRET": "<user-must-provide>"
+        "OUTLOOK_CLIENT_ID": "<user-must-provide>"
       }
     }
   }
@@ -36,7 +35,10 @@ Users must create an Azure app registration to get credentials:
 6. Click "Register"
 7. Copy the **Application (client) ID** → this is `OUTLOOK_CLIENT_ID`
 
-### Create a client secret:
+If the client ID is left out of the config, the `auth` tool asks for it at sign-in (`auth action=authenticate clientId=<id>`) and saves it to `~/.outlook-assistant-config.json`.
+
+### Create a client secret (browser flow only):
+The default device-code sign-in doesn't need a secret; skip this unless you'll use `method=browser`, and then add `OUTLOOK_CLIENT_SECRET` to the `env` block.
 1. Go to "Certificates & secrets" → "New client secret"
 2. Add a description, select expiration, click "Add"
 3. **Copy the Value immediately** (not the Secret ID) → this is `OUTLOOK_CLIENT_SECRET`
@@ -69,9 +71,13 @@ Add these to the same `env` block if needed:
 |----------|---------|
 | `OUTLOOK_AUTH_AUDIENCE` | `consumers` for Azure apps registered as personal-accounts-only (fixes `AADSTS9002331`); `organizations` or a tenant GUID for work-only apps. Default `common` |
 | `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone for calendar times (default `Australia/Melbourne`) |
-| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on sends per server session |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Default per-session cap for `send-email`, `draft` and `manage-rules` (override one tool with `OUTLOOK_MAX_<TOOL>_PER_SESSION`, e.g. `OUTLOOK_MAX_SEND_EMAIL_PER_SESSION`) |
 | `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of recipient domains/addresses |
 | `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support, work/school accounts only: `read` or `true` (read and organise). Also add `Mail.Read.Shared` (and `Mail.ReadWrite.Shared` for `true`) in Azure, restart, then run `auth` with `action=authenticate` and `force=true` |
+| `OUTLOOK_SEARCH_SCAN_LIMIT` | Messages scanned by the local search fallback on personal accounts (default 500, max 5000) |
+| `OUTLOOK_REQUEST_TIMEOUT_MS` | Per-attempt Graph inactivity timeout in milliseconds (default 60000); not an overall deadline |
+
+Run `npx @littlebearapps/outlook-assistant --help` for the full list of environment variables.
 
 ## Configuration Files by Client
 

package/llms.txt

@@ -36,7 +36,8 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **MCP safety annotations** on all 22 tools — AI clients auto-approve reads and prompt for destructive operations
 - **Send-email protections**: pre-send mail tips, dry-run preview, session rate limiting, recipient allowlist
 - **Rule protections**: dry-run preview on create/update, rate limiting, recipient allowlist on forward/redirect, no permanent-delete action
-- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports confined to the output directory without overwriting
+- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports (including conversation exports) confined to the output directory without overwriting, and a partly written file removed if a write fails
+- **Throttling-aware Graph client**: `429` (and `503`/`504` for non-POST requests) retried honouring `Retry-After`, a per-attempt inactivity timeout (`OUTLOOK_REQUEST_TIMEOUT_MS`, default 60000 ms) and at most 4 requests in flight, so bulk operations neither hang nor throttle themselves
 - **Shared mailboxes off by default**: `.Shared` scopes are requested only when `OUTLOOK_SHARED_MAILBOX` is set (`read` keeps shared access read-only)
 - **Token-optimised**: 22 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
 - These safeguards reduce risk but are not foolproof — always review actions before approving
@@ -50,15 +51,14 @@ Built by [Little Bear Apps](https://littlebearapps.com).
       "command": "npx",
       "args": ["@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }
 }
 ```
 
-Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
+`OUTLOOK_CLIENT_SECRET` is only needed for the browser sign-in flow; the default device-code flow uses the client ID alone. Claude Code users can instead install the plugin: `claude plugin marketplace add littlebearapps/outlook-assistant`, then `claude plugin install outlook-assistant@littlebearapps`. Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
 
 ## Tool Categories
 
@@ -83,6 +83,6 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.12.1 — Graph reliability and correctness fixes: throttling retries, a request inactivity timeout and a 4-request concurrency cap (#244), complete delta paging (#254), a draft-only guard on `draft` update/send/delete (#246), nested folder paths in `manage-rules` (#248), flag dates honouring `Z` and offsets (#247), attendee types kept on `manage-event update` (#249), no "via API" text on decline/cancel (#242), escaped `$search` phrases (#251), and conversation read/export working on personal accounts. Preceded by v3.12.0 — opt-in shared-mailbox read and organise support via `sharedMailbox` and `OUTLOOK_SHARED_MAILBOX` (#228), `list-events` `startAfter`/`startBefore`/`subject` filters (#193), token refresh requesting the granted scopes plus `offline_access` (#241), and two security fixes: dot segments in resource paths rejected, `export` writes confined to the output directory. Preceded by v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2); v3.11.1 — search and export correctness (filters combined with dates no longer silently dropped, batch export no longer overwrites same-day reply chains); v3.11.0 — `--version`/`--help` CLI flags (#68) and the `AADSTS7000215` Secret ID vs Value explanation (#69); v3.10.0 — search correctness (#217, #229, #230, #231))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, v3.8.x carry-over, v3.13.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.13.0 — marketplace plugin bundle for Claude Code, GitHub Copilot and Cursor; Azure client ID can be given at sign-in and saved locally; client secret documented as browser-flow only)
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, the patch-release fix queue, v3.8.x carry-over, v3.13.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy (report vulnerabilities privately via GitHub private vulnerability reporting; acknowledged within 7 days), token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -18,7 +18,8 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepare": "husky || true",
-    "version": "node -e \"const s=require('./server.json');const p=require('./package.json');s.version=p.version;s.packages[0].version=p.version;require('fs').writeFileSync('./server.json',JSON.stringify(s,null,2)+'\\n')\" && git add server.json"
+    "version": "node scripts/sync-version.js && git add server.json plugins/outlook-assistant",
+    "version:check": "node scripts/sync-version.js --check"
   },
   "lint-staged": {
     "*.js": [