msteams-mcp 0.29.1 → 0.30.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/msteams-mcp.svg)](https://www.npmjs.com/package/msteams-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/msteams-mcp.svg)](https://www.npmjs.com/package/msteams-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
 
 Give AI access to Microsoft Teams easily with your standard Teams login. 
 
@@ -27,7 +27,7 @@ Search messages and email, catch up on unread chats, read threads, send replies,
 
 ### Prerequisites
 
-- Node.js 18+
+- Node.js 20+
 - A Microsoft account with Teams access
 - Google Chrome, Microsoft Edge, or Chromium browser installed
 
@@ -102,7 +102,7 @@ This installs two binaries: `msteams-mcp` (the MCP server) and `msteams` (the CL
 npx -y msteams-mcp msteams status
 ```
 
-See [CLI Usage](#cli-usage) for commands.
+See [CLI Usage](#cli-usage) for commands, or run `msteams` for the command list.
 
 ## Available Tools
 
@@ -268,13 +268,18 @@ The server also exposes passive resources for context discovery:
 
 ## CLI Usage
 
-`msteams` exposes every tool the MCP server does - full parity, same authentication, same session files. Run with no arguments to list all tools and shortcuts.
+`msteams` exposes every tool the MCP server does - full parity, same authentication, same session files. Commands, flags and help are generated from the tool definitions, so the CLI never lags behind the server.
 
 If you installed globally (`npm install -g msteams-mcp`), invoke it directly:
 
 ```bash
-# List available tools and shortcuts
+# The command list, one line each
 msteams
+msteams --version
+
+# What one command does, and all of its flags
+msteams help send_message
+msteams search --help
 
 # Check authentication status
 msteams status
@@ -288,9 +293,9 @@ msteams search "meeting notes"
 msteams search "project" --from 0 --size 50
 
 # Search emails
-msteams teams_search_email --query "from:sarah@company.com"
+msteams email "from:sarah@company.com"
 
-# Send a message (default: your own notes/self-chat)
+# Send a message (default: your own self-chat, 48:notes)
 msteams send "Hello from Teams MCP!"
 msteams send "Message" --to "conversation-id"
 
@@ -300,29 +305,30 @@ msteams favorites
 msteams activity
 msteams unread
 
-# Any tool by name (the teams_ prefix is optional)
-msteams teams_search_emoji --query "heart"
-msteams find_channel --query "support"
-
-# Machine-readable output
-msteams search "query" --json
+# Machine-readable output, on stdout, for scripts
+msteams search "query" --json | jq '.results[0].conversationId'
 ```
 
-**Command form:** `msteams <command> [primaryArg] [--key value ...]`. Any unrecognised command is treated as a tool name (`teams_` is added automatically). Common flags like `--to`, `--from`, `--size`, `--query`, `--force` map to the matching tool parameters; run `msteams` with no arguments to see the full list.
+**Command form:** `msteams <command> [value] [--flag value]`.
+
+- **Commands** are the tool names without the `teams_`/`get_` prefix (`search`, `send_message`, `thread`, `meetings`). Any unambiguous abbreviation works, so `send` reaches `send_message`; the full tool name always works too.
+- **Flags** are the tool's own parameters, in camelCase (`--conversationId`, `--threadRootId`, `--fromUrl`). A few short aliases exist where they read better: `--to`, `--msg`, `--reply`, `--user`, `--force`. Booleans work bare (`--markRead`) or with a value (`--markRead false`). Unknown flags are rejected with the list of valid ones.
+- **The first bare value** goes to the command's main parameter: `msteams search "query"` is `--query "query"`.
+- **Output** goes to stdout, diagnostics to stderr, so pipes and redirects behave. Colour and emoji appear only on a terminal, and `NO_COLOR` turns them off.
+- **Exit codes:** `0` success, `1` the tool failed, `2` the command was malformed.
+- **`--json`** prints the tool's JSON payload, ready for `jq`.
 
 ### From a repo clone
 
 If you're working from source, the same CLI is wired to `npm run cli` (runs via `tsx`, no build needed):
 
 ```bash
-npm run cli                          # list tools
+npm run cli                          # command list
 npm run cli -- search "your query"
 npm run cli -- status
 npm run cli -- send "Hi" --to "conversation-id"
 ```
 
-
-
 ## Limitations
 
 - **Login required** - Run `teams_login` to authenticate (opens browser)

package/dist/auth/session-store.js

@@ -13,7 +13,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { encrypt, decrypt } from './crypto.js';
-import { SESSION_EXPIRY_HOURS } from '../constants.js';
+import { SESSION_EXPIRY_HOURS, TEAMS_HOSTS } from '../constants.js';
 import * as log from '../utils/logger.js';
 /**
  * User-specific config directory for teams-mcp-server.
@@ -131,12 +131,7 @@ export function clearTokenCache() {
  * Known Teams origins (commercial and government clouds).
  * Used to find the correct origin in session state.
  */
-const TEAMS_ORIGINS = [
-    'https://teams.cloud.microsoft', // New Teams URL (often holds SubstrateSearch tokens)
-    'https://teams.microsoft.com', // Commercial legacy
-    'https://teams.microsoft.us', // GCC-High
-    'https://dod.teams.microsoft.us', // DoD
-];
+const TEAMS_ORIGINS = TEAMS_HOSTS.map(host => `https://${host}`);
 /**
  * Returns true if localStorage has a SubstrateSearch MSAL token entry.
  */
@@ -177,6 +172,6 @@ export function getTeamsOrigin(state) {
         if (origin)
             return origin;
     }
-    // Fallback: find any origin containing 'teams.microsoft'
-    return state.origins.find(o => o.origin.includes('teams.microsoft') || o.origin.includes('teams.cloud')) ?? null;
+    // Fallback: any origin on a known Teams host
+    return state.origins.find(o => TEAMS_HOSTS.some(host => o.origin.includes(host))) ?? null;
 }

package/dist/browser/auth.d.ts

@@ -3,6 +3,19 @@
  * Manages login detection and manual authentication flows.
  */
 import type { Page, BrowserContext } from 'playwright';
+interface AuthStatus {
+    isAuthenticated: boolean;
+    isOnLoginPage: boolean;
+    currentUrl: string;
+}
+/**
+ * Gets the current authentication status.
+ */
+export declare function getAuthStatus(page: Page): Promise<AuthStatus>;
+/**
+ * Checks if a URL is a Teams domain.
+ */
+export declare function isTeamsUrl(url: string): boolean;
 /**
  * Performs a full authentication flow:
  * 1. Navigate to Teams
@@ -16,3 +29,4 @@ import type { Page, BrowserContext } from 'playwright';
  * @param headless - If true, throw immediately if user interaction is required (default: false)
  */
 export declare function ensureAuthenticated(page: Page, context: BrowserContext, onProgress?: (message: string) => void, showOverlay?: boolean, headless?: boolean): Promise<void>;
+export {};

package/dist/browser/auth.js

@@ -3,7 +3,7 @@
  * Manages login detection and manual authentication flows.
  */
 import { saveSessionState } from './context.js';
-import { OVERLAY_STEP_PAUSE_MS, OVERLAY_COMPLETE_PAUSE_MS, } from '../constants.js';
+import { OVERLAY_STEP_PAUSE_MS, OVERLAY_COMPLETE_PAUSE_MS, TEAMS_HOSTS, } from '../constants.js';
 import { extractSubstrateToken } from '../auth/token-extractor.js';
 import * as logger from '../utils/logger.js';
 /**
@@ -145,41 +145,16 @@ const LOGIN_URL_PATTERNS = [
     'login.live.com',
     'login.microsoft.com',
 ];
-// Selectors that indicate successful authentication
-const AUTH_SUCCESS_SELECTORS = [
-    '[data-tid="app-bar"]',
-    '[data-tid="search-box"]',
-    'input[placeholder*="Search"]',
-    '[data-tid="chat-list"]',
-    '[data-tid="team-list"]',
-];
 /**
  * Checks if the current page URL indicates a login flow.
  */
 function isLoginUrl(url) {
     return LOGIN_URL_PATTERNS.some(pattern => url.includes(pattern));
 }
-/**
- * Checks if the page shows authenticated Teams content.
- */
-async function hasAuthenticatedContent(page) {
-    for (const selector of AUTH_SUCCESS_SELECTORS) {
-        try {
-            const count = await page.locator(selector).count();
-            if (count > 0) {
-                return true;
-            }
-        }
-        catch {
-            // Selector not found, continue checking others
-        }
-    }
-    return false;
-}
 /**
  * Gets the current authentication status.
  */
-async function getAuthStatus(page) {
+export async function getAuthStatus(page) {
     const currentUrl = page.url();
     const onLoginPage = isLoginUrl(currentUrl);
     // If on login page, definitely not authenticated
@@ -190,11 +165,15 @@ async function getAuthStatus(page) {
             currentUrl,
         };
     }
-    // If on Teams domain, check for authenticated content
-    if (currentUrl.includes('teams.microsoft.com')) {
-        const hasContent = await hasAuthenticatedContent(page);
+    // On a Teams domain, a live MSAL token is the proof of sign-in: it is what
+    // every API call needs and what the saved session is for. Teams' own DOM
+    // markers are not a usable signal — new Teams renders none of the `data-tid`
+    // elements earlier versions exposed, so waiting for them left a completed
+    // login undetected and the browser window open until the manual-login
+    // timeout.
+    if (isTeamsUrl(currentUrl)) {
         return {
-            isAuthenticated: hasContent,
+            isAuthenticated: await checkBrowserTokenExpiry(page) > 0,
             isOnLoginPage: false,
             currentUrl,
         };
@@ -208,18 +187,11 @@ async function getAuthStatus(page) {
 }
 /** Timeout for detecting login redirect (ms). */
 const LOGIN_REDIRECT_TIMEOUT_MS = 5000;
-/** URL patterns that indicate we're on a Teams page (not redirected elsewhere). */
-const TEAMS_URL_PATTERNS = [
-    'teams.microsoft.com',
-    'teams.microsoft.us', // GCC-High
-    'dod.teams.microsoft.us', // DoD
-    'teams.cloud.microsoft', // New Teams URL
-];
 /**
  * Checks if a URL is a Teams domain.
  */
-function isTeamsUrl(url) {
-    return TEAMS_URL_PATTERNS.some(pattern => url.includes(pattern));
+export function isTeamsUrl(url) {
+    return TEAMS_HOSTS.some(host => url.includes(host));
 }
 /**
  * Navigates to Teams and checks authentication status.

package/dist/browser/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/auth.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from 'vitest';
+vi.mock('./context.js', () => ({ saveSessionState: vi.fn() }));
+vi.mock('../auth/token-extractor.js', () => ({ extractSubstrateToken: vi.fn() }));
+import { getAuthStatus, isTeamsUrl } from './auth.js';
+/** A page on `url` with no Teams DOM markers and `tokenMinutes` left on MSAL. */
+function fakePage(url, tokenMinutes) {
+    return {
+        url: () => url,
+        locator: () => ({ count: async () => 0 }),
+        evaluate: async () => tokenMinutes,
+    };
+}
+describe('isTeamsUrl', () => {
+    it('covers every host Microsoft redirects Teams users to', () => {
+        // New Teams settles on the bare host, with no path.
+        for (const url of [
+            'https://teams.microsoft.com/',
+            'https://teams.cloud.microsoft/',
+            'https://teams.chat.microsoft.com/',
+            'https://teams.microsoft.us/',
+            'https://dod.teams.microsoft.us/',
+        ]) {
+            expect(isTeamsUrl(url), url).toBe(true);
+        }
+        expect(isTeamsUrl('https://outlook.office.com/')).toBe(false);
+    });
+    it('matches on the host, whatever path the app has routed to', () => {
+        expect(isTeamsUrl('https://teams.microsoft.com/v2/#/conversations/19:abc@thread.tacv2')).toBe(true);
+    });
+});
+describe('getAuthStatus', () => {
+    it('detects a completed login from the MSAL token alone', async () => {
+        const status = await getAuthStatus(fakePage('https://teams.cloud.microsoft/', 55));
+        expect(status.isAuthenticated).toBe(true);
+        expect(status.isOnLoginPage).toBe(false);
+    });
+    it('stays unauthenticated on a Teams host with no token', async () => {
+        const status = await getAuthStatus(fakePage('https://teams.cloud.microsoft/', -1));
+        expect(status.isAuthenticated).toBe(false);
+    });
+    it('reports the login page', async () => {
+        const status = await getAuthStatus(fakePage('https://login.microsoftonline.com/common/oauth2', 99));
+        expect(status).toMatchObject({ isAuthenticated: false, isOnLoginPage: true });
+    });
+});

package/dist/browser/context.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for browser channel selection.
+ *
+ * The server launches into its own profile dir, so the user's default browser
+ * is irrelevant - what matters is that every platform has an ordered list of
+ * channels to try and ends with a fallback that needs no system browser.
+ */
+export {};

package/dist/browser/context.test.js

@@ -0,0 +1,55 @@
+/**
+ * Tests for browser channel selection.
+ *
+ * The server launches into its own profile dir, so the user's default browser
+ * is irrelevant - what matters is that every platform has an ordered list of
+ * channels to try and ends with a fallback that needs no system browser.
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { browserChannels } from './context.js';
+/** Runs fn with process.platform stubbed, then restores the real value. */
+function withPlatform(platform, fn) {
+    const original = Object.getOwnPropertyDescriptor(process, 'platform');
+    Object.defineProperty(process, 'platform', { value: platform, configurable: true });
+    try {
+        return fn();
+    }
+    finally {
+        Object.defineProperty(process, 'platform', original);
+    }
+}
+describe('browserChannels', () => {
+    afterEach(() => {
+        vi.unstubAllEnvs();
+    });
+    it('prefers Edge on Windows, Chrome elsewhere', () => {
+        vi.stubEnv('TEAMS_BROWSER_CHANNEL', '');
+        expect(withPlatform('win32', browserChannels)[0]).toBe('msedge');
+        expect(withPlatform('darwin', browserChannels)[0]).toBe('chrome');
+        expect(withPlatform('linux', browserChannels)[0]).toBe('chrome');
+    });
+    it('offers both system channels on every platform', () => {
+        vi.stubEnv('TEAMS_BROWSER_CHANNEL', '');
+        for (const platform of ['win32', 'darwin', 'linux']) {
+            const channels = withPlatform(platform, browserChannels);
+            expect(channels).toContain('chrome');
+            expect(channels).toContain('msedge');
+        }
+    });
+    it('ends with bundled Chromium so a machine with no system browser can recover', () => {
+        vi.stubEnv('TEAMS_BROWSER_CHANNEL', '');
+        for (const platform of ['win32', 'darwin', 'linux']) {
+            expect(withPlatform(platform, browserChannels).at(-1)).toBeUndefined();
+        }
+    });
+    it('honours TEAMS_BROWSER_CHANNEL and disables the fallback', () => {
+        vi.stubEnv('TEAMS_BROWSER_CHANNEL', 'msedge');
+        expect(withPlatform('darwin', browserChannels)).toEqual(['msedge']);
+        vi.stubEnv('TEAMS_BROWSER_CHANNEL', 'chrome');
+        expect(withPlatform('win32', browserChannels)).toEqual(['chrome']);
+    });
+    it('ignores an unrecognised TEAMS_BROWSER_CHANNEL', () => {
+        vi.stubEnv('TEAMS_BROWSER_CHANNEL', 'safari');
+        expect(withPlatform('darwin', browserChannels)).toEqual(['chrome', 'msedge', undefined]);
+    });
+});

package/dist/cli/help.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Help text for the `msteams` CLI, generated from the tool definitions.
+ *
+ * The index stays to one screen: one line per command, first sentence only.
+ * Full parameter detail lives in `msteams help <command>`, and the complete
+ * schemas in `msteams help --json`.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * First sentence of a description. The tool descriptions are written for an
+ * LLM and run long, so only the opening sentence is useful in a command list.
+ * A period followed by a non-capital (as in "e.g.") does not end a sentence.
+ */
+export declare function firstSentence(text: string): string;
+/** The one-screen command index. */
+export declare function renderIndex(tools: Tool[], groups: Array<{
+    name: string;
+    tools: string[];
+}>, version: string): string;
+/** Detail for one command: what it does, how to call it, every flag. */
+export declare function renderToolHelp(tools: Tool[], tool: Tool): string;

package/dist/cli/help.js

@@ -0,0 +1,111 @@
+/**
+ * Help text for the `msteams` CLI, generated from the tool definitions.
+ *
+ * The index stays to one screen: one line per command, first sentence only.
+ * Full parameter detail lives in `msteams help <command>`, and the complete
+ * schemas in `msteams help --json`.
+ */
+import { FLAG_ALIASES, positionalProp, requiredProps, schemaProps, shortName } from './resolve.js';
+import { bold, dim, termWidth, wrap } from './render.js';
+/**
+ * First sentence of a description. The tool descriptions are written for an
+ * LLM and run long, so only the opening sentence is useful in a command list.
+ * A period followed by a non-capital (as in "e.g.") does not end a sentence.
+ */
+export function firstSentence(text) {
+    const match = /^(.*?[.!?])(?=\s+[A-Z]|$)/s.exec(text.trim());
+    const sentence = (match?.[1] ?? text).replace(/\s+/g, ' ').trim();
+    return sentence.replace(/\.$/, '');
+}
+function flagLabel(prop) {
+    if (prop.enum)
+        return `<${prop.enum.join('|')}>`;
+    if (prop.type === 'boolean')
+        return '';
+    if (prop.type === 'array')
+        return '<a,b>';
+    return `<${prop.type ?? 'string'}>`;
+}
+/** Aliases pointing at a parameter, e.g. conversationId -> ['--to']. */
+function aliasesFor(prop) {
+    return Object.entries(FLAG_ALIASES)
+        .filter(([, target]) => target === prop)
+        .map(([alias]) => `--${alias}`);
+}
+/** The one-screen command index. */
+export function renderIndex(tools, groups, version) {
+    const names = tools.map(tool => tool.name);
+    const byName = new Map(tools.map(tool => [tool.name, tool]));
+    const labels = new Map(names.map(name => [name, shortName(names, name)]));
+    const column = Math.min(22, Math.max(...[...labels.values()].map(label => label.length)) + 2);
+    const lines = [
+        `${bold('msteams')} ${dim(version)} - Microsoft Teams from your terminal`,
+        '',
+        bold('Usage'),
+        '  msteams <command> [value] [--flag value]',
+        `  msteams help <command>    ${dim('flags and detail for one command')}`,
+        `  msteams <command> --json  ${dim('machine-readable output')}`,
+    ];
+    for (const group of groups) {
+        const members = group.tools.filter(name => byName.has(name));
+        if (members.length === 0)
+            continue;
+        lines.push('', bold(group.name));
+        for (const name of members) {
+            const label = labels.get(name) ?? name;
+            const summary = firstSentence(byName.get(name)?.description ?? '');
+            const room = termWidth() - column - 4;
+            lines.push(`  ${label.padEnd(column)}${dim(summary.length > room ? `${summary.slice(0, room - 1)}…` : summary)}`);
+        }
+    }
+    lines.push('', dim('Commands are tool names without the teams_/get_ prefix; any unambiguous'), dim("abbreviation works (send -> send_message). 'msteams login' first."));
+    return lines.join('\n');
+}
+/** Detail for one command: what it does, how to call it, every flag. */
+export function renderToolHelp(tools, tool) {
+    const names = tools.map(t => t.name);
+    const label = shortName(names, tool.name);
+    const props = schemaProps(tool);
+    const required = new Set(requiredProps(tool));
+    const positional = positionalProp(tool);
+    const usage = [`  msteams ${label}`];
+    if (positional)
+        usage[0] += ` <${positional}>`;
+    if (Object.keys(props).length > (positional ? 1 : 0))
+        usage[0] += ' [--flag value]';
+    const lines = [
+        `${bold(`msteams ${label}`)} ${dim(`(${tool.name})`)}`,
+        '',
+        ...wrap(firstSentence(tool.description ?? ''), 0, 3).map(line => `  ${line}`),
+        '',
+        bold('Usage'),
+        ...usage,
+    ];
+    const entries = Object.entries(props);
+    if (entries.length > 0) {
+        lines.push('', bold('Flags'));
+        const column = Math.min(28, Math.max(...entries.map(([name, prop]) => `--${name} ${flagLabel(prop)}`.trim().length)) + 2);
+        for (const [name, prop] of entries) {
+            const flag = `--${name} ${flagLabel(prop)}`.trim();
+            const alias = aliasesFor(name);
+            const detail = [
+                required.has(name) ? 'Required.' : '',
+                alias.length ? `(or ${alias.join(', ')})` : '',
+                prop.description ?? '',
+            ].filter(Boolean).join(' ');
+            const wrapped = wrap(detail, column + 2, 2);
+            // A flag too long for the column takes a line of its own.
+            if (flag.length >= column) {
+                lines.push(`  ${bold(flag)}`);
+                for (const line of wrapped)
+                    lines.push(`  ${' '.repeat(column)}${line}`);
+                continue;
+            }
+            lines.push(`  ${bold(flag.padEnd(column))}${wrapped[0] ?? ''}`);
+            for (const line of wrapped.slice(1))
+                lines.push(`  ${' '.repeat(column)}${line}`);
+        }
+    }
+    lines.push('', dim('Add --json for the raw payload.'));
+    return lines.join('\n');
+}

package/dist/cli/render.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Terminal output for the `msteams` CLI.
+ *
+ * One generic record renderer covers every tool response: anything with an
+ * array gets a numbered list, anything else gets labelled fields. Colour and
+ * emoji only appear on a TTY, so piped output stays clean.
+ */
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare const icon: (emoji: string) => string;
+/** Terminal width, with a sane default when output is piped. */
+export declare const termWidth: () => number;
+export declare function oneLine(text: string, max?: number): string;
+/** Renders any field value as a single line, or '' when there is nothing to show. */
+export declare function summarise(value: unknown, max?: number, depth?: number): string;
+/** Prints a successful tool response. */
+export declare function printResponse(response: Record<string, unknown>): void;
+/** Prints a failed tool response to stderr. */
+export declare function printFailure(response: Record<string, unknown>): void;
+/** Wraps text to the terminal width with a hanging indent, clipped to maxLines. */
+export declare function wrap(text: string, indent: number, maxLines?: number): string[];