@littlebearapps/outlook-assistant 3.10.0 → 3.11.0

package/README.md

@@ -161,6 +161,17 @@ Or run directly without installing:
 npx @littlebearapps/outlook-assistant
 ```
 
+To check which version you have, or to see the available options:
+
+```bash
+outlook-assistant --version     # prints e.g. 3.11.0
+outlook-assistant --help        # usage, options and key environment variables
+```
+
+With no arguments the server speaks the Model Context Protocol over stdio. It's
+normally launched by your MCP client rather than run by hand — started from a
+terminal it will simply wait on stdin.
+
 ### 2. Register an Azure App
 
 You need a Microsoft Azure app registration to authenticate. See the **[Azure Setup Guide](docs/guides/azure-setup.md)** for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:
@@ -278,6 +289,17 @@ cd outlook-assistant
 npm install
 ```
 
+### CLI options
+
+| Option | What it does |
+|--------|-------------|
+| `-v`, `--version` | Print the version to stdout and exit 0 |
+| `-h`, `--help` | Print usage, options and key environment variables, and exit 0 |
+| _(none)_ | Start the MCP server on stdio — the normal mode, invoked by your MCP client |
+
+An unrecognised argument is reported on stderr and exits 1, rather than starting
+a server that would ignore it.
+
 ## Azure App Registration
 
 > **First time with Azure?** The [Azure Setup Guide](docs/guides/azure-setup.md) covers everything from creating an account to your first authentication, including billing setup and common pitfalls.
@@ -446,7 +468,11 @@ npm run auth-server
 
 ### "Invalid client secret" (AADSTS7000215)
 
-You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column.
+You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Portal > Certificates & secrets and copy the **Value** column into `OUTLOOK_CLIENT_SECRET`.
+
+The Value is shown only once, when the secret is created — if you've navigated away it can't be read again, so create a new secret. An **expired** secret produces this same error, so check the Expires column too.
+
+Since v3.11.0 the server detects this error and appends the explanation to Microsoft's original message, so you see both the raw error code and what to do about it.
 
 ### Authentication URL doesn't work
 
@@ -497,7 +523,7 @@ 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) | 29 practical guides for email, calendar, contacts, and settings |
-| [Roadmap](ROADMAP.md) | Active milestones (v3.7.5, v3.8.x, v3.11.0+) and recent releases |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.11.1, v3.8.x, v3.12.0+) and recent releases |
 | [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 22 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 |

package/auth/auth-errors.js

@@ -0,0 +1,89 @@
+/**
+ * Azure AD (AADSTS) error translation.
+ *
+ * Microsoft's identity platform returns accurate but unfriendly errors: the
+ * error_description is a wall of prose ending in a correlation ID, and the
+ * single most common setup mistake — pasting the client secret's *ID* instead
+ * of its *Value* — surfaces only as `AADSTS7000215: Invalid client secret
+ * provided`. (#69)
+ *
+ * This module maps known codes to actionable remediation text. It only ever
+ * *adds* to the original message; the raw Azure error is always preserved so
+ * that searching for the code still works.
+ */
+
+/**
+ * Known Azure error signatures and their remediation hints.
+ * Ordered most-specific first; every matching entry contributes a hint.
+ */
+const AUTH_ERROR_HINTS = [
+  {
+    // The Secret ID vs Secret Value mistake. First row of docs/troubleshooting.md.
+    test: /AADSTS7000215/i,
+    hint:
+      'Invalid client secret. The usual cause is pasting the **Secret ID** (a UUID like `a1b2c3d4-…`) instead of the **Secret Value** (a longer string with mixed case and symbols). ' +
+      'In Azure → App registrations → your app → Certificates & secrets → Client secrets, copy the *Value* column into `OUTLOOK_CLIENT_SECRET`. ' +
+      'The Secret Value is shown only once, when the secret is created — if you have navigated away it can no longer be read, so create a new secret. ' +
+      'An expired secret produces this same error, so check the Expires column too. ' +
+      'See docs/guides/azure-setup.md#4-create-a-client-secret.',
+  },
+  {
+    test: /AADSTS9002331|personal.*account/i,
+    hint: 'This app registration appears to accept personal Microsoft accounts only. Set `OUTLOOK_AUTH_AUDIENCE=consumers` (or the correct tenant GUID) in your MCP env and retry.',
+  },
+  {
+    test: /AADSTS7000218|unauthorized_client|invalid_client/i,
+    // AADSTS7000215 is also delivered as error=invalid_client, but it means the
+    // secret is wrong, not that public client flows are disabled. Suppress the
+    // generic hint so the specific one above is not drowned out.
+    notWhen: /AADSTS7000215/i,
+    hint: "Enable 'Allow public client flows' under Azure → App registration → Authentication → Advanced settings, and add the `nativeclient` redirect URI (Mobile and desktop applications platform).",
+  },
+  {
+    test: /AADSTS700016/i,
+    hint: 'The application was not found in this directory. Check `OUTLOOK_CLIENT_ID` matches the Application (client) ID in Azure, and that `OUTLOOK_AUTH_AUDIENCE` targets the right tenant.',
+  },
+  {
+    test: /invalid_grant|AADSTS700082|AADSTS50173/i,
+    hint: 'The refresh token is expired or has been revoked (refresh tokens last ~90 days). Re-authenticate with the `auth` tool: `action=authenticate`, then `action=device-code-complete`.',
+  },
+];
+
+/** Normalise an Error or string into a searchable message. */
+function toMessage(input) {
+  if (input === null || input === undefined) return '';
+  if (input instanceof Error) return input.message || String(input);
+  if (typeof input === 'object' && input.message) return String(input.message);
+  return String(input);
+}
+
+/**
+ * Return remediation hints for a Microsoft auth error.
+ * @param {Error|string|null|undefined} input - Error or error_description
+ * @returns {string[]} - Zero or more hints; empty when the error is unknown
+ */
+function getAuthErrorHints(input) {
+  const msg = toMessage(input);
+  if (!msg) return [];
+  return AUTH_ERROR_HINTS.filter(
+    (e) => e.test.test(msg) && !(e.notWhen && e.notWhen.test(msg))
+  ).map((e) => e.hint);
+}
+
+/**
+ * Append any known remediation hints to an auth error message.
+ * Returns the message unchanged when nothing is known, so callers can use this
+ * unconditionally without polluting unrelated errors.
+ * @param {Error|string} input
+ * @returns {string}
+ */
+function describeAuthError(input) {
+  const msg = toMessage(input);
+  const hints = getAuthErrorHints(msg);
+  if (!hints.length) return msg;
+  return [msg, '', 'Suggested fixes:', ...hints.map((h) => `- ${h}`)].join(
+    '\n'
+  );
+}
+
+module.exports = { getAuthErrorHints, describeAuthError, AUTH_ERROR_HINTS };

package/auth/oauth-server.js

@@ -38,7 +38,8 @@ const templates = {
       <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
         <h1 style="color: #e74c3c;">❌ Token Exchange Failed</h1>
         <p>Failed to exchange authorization code for access token.</p>
-        <p><strong>Error:</strong> ${escapeHtml(error instanceof Error ? error.message : String(error))}</p>
+        <p><strong>Error:</strong></p>
+        <pre style="white-space: pre-wrap; text-align: left; display: inline-block; max-width: 40em; font-family: inherit;">${escapeHtml(error instanceof Error ? error.message : String(error))}</pre>
         <p>You can close this window and try again.</p>
       </body>
     </html>`,
@@ -227,7 +228,7 @@ function setupOAuthRoutes(
 module.exports = {
   setupOAuthRoutes,
   createAuthConfig,
-  // Exporting templates for potential direct use or testing, though not typical
-  // templates
+  // Exported so the rendered error pages can be asserted on directly (#69).
+  templates,
 };
 // Adding a newline at the end of the file as requested by Gemini Code Assist

package/auth/token-storage.js

@@ -3,6 +3,7 @@ const fsSync = require('fs');
 const path = require('path');
 const https = require('https');
 const querystring = require('querystring');
+const { describeAuthError } = require('./auth-errors');
 
 class TokenStorage {
   constructor(config) {
@@ -131,16 +132,22 @@ class TokenStorage {
           return await this.refreshAccessToken();
         } catch (refreshError) {
           console.error('Failed to refresh access token:', refreshError);
-          this.tokens = null; // Invalidate tokens on refresh failure
-          await this._saveTokensToFile(); // Persist invalidation
+          // Drop the in-memory tokens so callers re-authenticate. The save
+          // below is intentionally a no-op — `_saveTokensToFile` returns early
+          // when `tokens` is null — which is the behaviour we want: a transient
+          // network failure must not erase a still-valid refresh token from
+          // disk. The next process start reloads it and retries. (#72)
+          this.tokens = null;
+          await this._saveTokensToFile();
           return null;
         }
       } else {
         console.warn(
           'No refresh token available. Cannot refresh access token.'
         );
-        this.tokens = null; // Invalidate tokens as they are expired and cannot be refreshed
-        await this._saveTokensToFile(); // Persist invalidation
+        // Same as above: clears memory, leaves the file alone. (#72)
+        this.tokens = null;
+        await this._saveTokensToFile();
         return null;
       }
     }
@@ -226,8 +233,10 @@ class TokenStorage {
                 console.error('Error refreshing token:', responseBody);
                 reject(
                   new Error(
-                    responseBody.error_description ||
-                      `Token refresh failed with status ${res.statusCode}`
+                    describeAuthError(
+                      responseBody.error_description ||
+                        `Token refresh failed with status ${res.statusCode}`
+                    )
                   )
                 );
               }
@@ -320,8 +329,10 @@ class TokenStorage {
                 );
                 reject(
                   new Error(
-                    responseBody.error_description ||
-                      `Token exchange failed with status ${res.statusCode}`
+                    describeAuthError(
+                      responseBody.error_description ||
+                        `Token exchange failed with status ${res.statusCode}`
+                    )
                   )
                 );
               }

package/auth/tools.js

@@ -2,6 +2,7 @@
  * Authentication-related tools for the Outlook Assistant server
  */
 const config = require('../config');
+const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
@@ -264,20 +265,10 @@ async function handleDeviceCodeAuth() {
 function buildDeviceCodeErrorResponse(error) {
   const msg = (error && error.message) || String(error);
   const code = error && error.code;
-  const hints = [];
+  // Shared AADSTS hint table (#69) so this path and the token-endpoint paths in
+  // token-storage.js cannot drift apart.
+  const hints = getAuthErrorHints(msg);
 
-  if (/AADSTS9002331/i.test(msg) || /personal.*account/i.test(msg)) {
-    hints.push(
-      'This app registration appears to accept personal Microsoft accounts only. Set `OUTLOOK_AUTH_AUDIENCE=consumers` (or the correct tenant GUID) in your MCP env and retry.'
-    );
-  }
-  if (
-    /invalid_client|unauthorized_client|AADSTS7000218|AADSTS700016/i.test(msg)
-  ) {
-    hints.push(
-      "Enable 'Allow public client flows' under Azure → App registration → Authentication → Advanced settings, and add the `nativeclient` redirect URI (Mobile and desktop applications platform)."
-    );
-  }
   if (
     code === 'ENOTFOUND' ||
     code === 'ETIMEDOUT' ||

package/index.js

@@ -5,6 +5,65 @@
  * A Model Context Protocol server that provides access to
  * Microsoft Outlook through the Microsoft Graph API.
  */
+// CLI flag handling (#68).
+//
+// Deliberately the first thing that runs: it must complete before the SDK
+// imports, before the auth modules load, and before the startup banner below
+// writes to stderr — otherwise `--version` output is buried in server noise and
+// the process never exits (the SIGTERM handler below keeps it alive).
+//
+// `config.js` is required lazily here so this costs nothing on the normal
+// server path; it is the single source of truth for the version, which it
+// reads from package.json.
+const cliArgs = process.argv.slice(2);
+if (cliArgs.length > 0) {
+  const HELP_TEXT = `outlook-assistant — MCP server for Microsoft Outlook via the Microsoft Graph API.
+
+Usage:
+  outlook-assistant [options]
+
+Options:
+  -v, --version   Print the version and exit
+  -h, --help      Show this help and exit
+
+With no options the server starts and speaks the Model Context Protocol over
+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_AUTH_METHOD               device-code (default) | browser
+  OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
+  OUTLOOK_MAX_EMAILS_PER_SESSION    Cap on sends per session
+  OUTLOOK_ALLOWED_RECIPIENTS        Comma-separated recipient allowlist
+  USE_TEST_MODE                     Set to "true" to run against mock data
+
+Documentation: https://github.com/littlebearapps/outlook-assistant`;
+
+  const KNOWN_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+
+  // Validate every argument before acting on any of them. Checking for a
+  // recognised flag first would let `--version --nope` succeed and silently
+  // swallow the typo — an unrecognised argument is a user error regardless of
+  // what else is on the command line.
+  const unknown = cliArgs.find((arg) => !KNOWN_FLAGS.has(arg));
+  if (unknown) {
+    console.error(
+      `outlook-assistant: unrecognised argument '${unknown}'\nRun 'outlook-assistant --help' for usage.`
+    );
+    process.exit(1);
+  }
+
+  if (cliArgs.includes('--version') || cliArgs.includes('-v')) {
+    console.log(require('./config').SERVER_VERSION);
+    process.exit(0);
+  }
+
+  console.log(HELP_TEXT);
+  process.exit(0);
+}
+
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const {
   StdioServerTransport,

package/llms-install.md

@@ -83,7 +83,7 @@ After authentication, test with:
 
 | Problem | Solution |
 |---------|----------|
-| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID |
+| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID. Also check it hasn't expired. v3.11.0+ appends an explanation to Microsoft's raw error |
 | Auth URL doesn't work | Start the auth server first |
 | "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
 | Empty API responses | Run `auth` tool with `action=status` to check token |

package/llms.txt

@@ -79,6 +79,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.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217); two-filter searches no longer return the single-filter superset, with `searchMetadata.droppedFilters` reporting anything unhonoured (#229); `from`/`to` filter values OData-escaped (#230); no-results guidance derived from what was actually attempted (#231); production `npm audit` gate cleared plus a weekly watchdog (#215). Preceded by v3.9.1 — packaging hotfix restoring `request-handler.js` in the published tarball (#223) — and v3.9.0 — nested folder addressing by path/ID (#216) and reliable cross-folder search with `kqlQuery` renamed to `searchExpression` (#169))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.7.5 polish, v3.8.x carry-over, v3.11.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.11.0 — fixes & polish: `--version`/`--help` CLI flags, where previously any argument was ignored and the server booted and hung on stdin (#68); `AADSTS7000215` (the Secret ID vs Secret Value mistake) now explains itself instead of passing Microsoft's raw error through, via one shared AADSTS hint table (#69); token-refresh round trip covered end to end from disk to the `Authorization` header on the next Graph call (#72); all 17 development-dependency advisories cleared, so `npm audit` reports zero at every severity. Preceded by v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset with `searchMetadata.droppedFilters` reporting anything unhonoured (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231) — and v3.9.1, a packaging hotfix restoring `request-handler.js` in the published tarball (#223))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.1 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.10.0",
+  "version": "3.11.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",