msteams-mcp 0.29.2 → 0.30.1

package/README.md

@@ -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/api/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * API module exports.
+ */
+export * from './substrate-api.js';
+export * from './chatsvc-api.js';
+export * from './csa-api.js';
+export * from './calendar-api.js';
+export * from './transcript-api.js';
+export * from './files-api.js';
+export * from './tags-api.js';

package/dist/api/index.js

@@ -0,0 +1,10 @@
+/**
+ * API module exports.
+ */
+export * from './substrate-api.js';
+export * from './chatsvc-api.js';
+export * from './csa-api.js';
+export * from './calendar-api.js';
+export * from './transcript-api.js';
+export * from './files-api.js';
+export * from './tags-api.js';

package/dist/auth/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth module exports.
+ */
+export * from './session-store.js';
+export * from './token-extractor.js';
+export * from './token-refresh.js';
+export { encrypt, decrypt, isEncrypted, type EncryptedData } from './crypto.js';

package/dist/auth/index.js

@@ -0,0 +1,7 @@
+/**
+ * Auth module exports.
+ */
+export * from './session-store.js';
+export * from './token-extractor.js';
+export * from './token-refresh.js';
+export { encrypt, decrypt, isEncrypted } from './crypto.js';

package/dist/browser/auth.js

@@ -386,7 +386,7 @@ export async function ensureAuthenticated(page, context, onProgress, showOverlay
     log('Navigating to Teams...');
     const status = await navigateToTeams(page);
     if (status.isAuthenticated) {
-        log('Already authenticated — saving session state.');
+        log('Teams loaded — saving session state.');
         await saveSessionState(context);
         // Check if the saved tokens are actually valid
         // Browser session cookies can outlive MSAL tokens (cookies last days, tokens ~1 hour)
@@ -407,9 +407,11 @@ export async function ensureAuthenticated(page, context, onProgress, showOverlay
             // Still no valid tokens after waiting
             throw new Error('Headless SSO failed: MSAL token refresh timed out');
         }
-        // In visible mode, the tokens might refresh while user interacts, or they can
-        // manually complete any prompts. We've saved what we have.
-        log('Session state saved (tokens may need refresh).');
+        // No redirect to login does not mean signed in: Teams can render with the
+        // Microsoft SSO session gone and only a dead SPA refresh token in its cache.
+        // Keep the window open until a live token appears (silently or by sign-in).
+        log('Tokens expired. Sign in in the browser window if prompted.');
+        await waitForManualLogin(page, context, onProgress, showOverlay);
         return;
     }
     // User interaction required - fail fast if headless

package/dist/browser/auth.test.js

@@ -1,7 +1,7 @@
 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';
+import { ensureAuthenticated, getAuthStatus, isTeamsUrl } from './auth.js';
 /** A page on `url` with no Teams DOM markers and `tokenMinutes` left on MSAL. */
 function fakePage(url, tokenMinutes) {
     return {
@@ -43,3 +43,22 @@ describe('getAuthStatus', () => {
         expect(status).toMatchObject({ isAuthenticated: false, isOnLoginPage: true });
     });
 });
+describe('ensureAuthenticated', () => {
+    it('keeps a visible browser open for sign-in when Teams loads with expired tokens', async () => {
+        // Teams can render without redirecting to login while the Microsoft SSO
+        // session is gone; only a fresh MSAL token proves the user has signed in.
+        const tokenMinutes = [-1, -1, 55];
+        const page = {
+            goto: async () => null,
+            waitForURL: async () => { throw new Error('timeout'); },
+            url: () => 'https://teams.cloud.microsoft/',
+            evaluate: async () => tokenMinutes.length > 1 ? tokenMinutes.shift() : tokenMinutes[0],
+            waitForTimeout: async () => { },
+        };
+        const messages = [];
+        await ensureAuthenticated(page, {}, msg => messages.push(msg), false, false);
+        expect(messages).toContain('Waiting for manual login...');
+        expect(messages).toContain('Authentication successful!');
+        expect(tokenMinutes).toEqual([55]);
+    });
+});

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[];

package/dist/cli/render.js

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ */
+const COLOUR = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+export const bold = (text) => (COLOUR ? `\x1b[1m${text}\x1b[0m` : text);
+export const dim = (text) => (COLOUR ? `\x1b[2m${text}\x1b[0m` : text);
+export const icon = (emoji) => (COLOUR ? `${emoji} ` : '');
+/** Terminal width, with a sane default when output is piped. */
+export const termWidth = () => process.stdout.columns ?? 80;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T/;
+/** Fields tried, in order, as an item's headline. */
+const HEADLINE_KEYS = ['content', 'displayName', 'subject', 'name', 'topic', 'title', 'text', 'preview', 'channelName', 'fileName'];
+/** Response keys that are metadata rather than content. */
+const META_KEYS = new Set(['success', 'pagination', 'resultCount', 'count', 'total']);
+export function oneLine(text, max = termWidth() - 4) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/** Best human label for an object value (sender shapes, profiles, mentions). */
+function objectLabel(value) {
+    const email = value.EmailAddress;
+    const candidate = value.displayName ?? value.name ?? value.Name ?? email?.Name ?? email?.Address;
+    return candidate === undefined || candidate === null ? null : String(candidate);
+}
+/** Renders any field value as a single line, or '' when there is nothing to show. */
+export function summarise(value, max = termWidth() - 4, depth = 0) {
+    if (value === null || value === undefined || value === '')
+        return '';
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '';
+        const scalars = value.filter(item => typeof item !== 'object' || item === null);
+        return scalars.length === value.length
+            ? oneLine(value.join(', '), max)
+            : `${value.length} items`;
+    }
+    if (typeof value === 'object') {
+        const label = objectLabel(value);
+        if (label !== null)
+            return label;
+        if (depth > 0)
+            return oneLine(JSON.stringify(value), max);
+        // No name to show, so inline the fields: `available=true, expiresAt=...`.
+        const parts = Object.entries(value)
+            .map(([key, nested]) => [key, summarise(nested, max, depth + 1)])
+            .filter(([, text]) => text !== '')
+            .map(([key, text]) => `${key}=${text}`);
+        return parts.length ? oneLine(parts.join(', '), max) : '';
+    }
+    if (typeof value === 'string' && ISO_DATE.test(value)) {
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime()))
+            return date.toLocaleString();
+    }
+    return oneLine(String(value), max);
+}
+/** A nested object with more fields than fit on one line, e.g. a profile. */
+function isBlock(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && Object.keys(value).length > 3;
+}
+function printFields(record, indent, skip = new Set()) {
+    for (const [key, value] of Object.entries(record)) {
+        if (skip.has(key) || META_KEYS.has(key))
+            continue;
+        if (indent === '' && isBlock(value)) {
+            console.log(dim(`${key}:`));
+            printFields(value, '  ');
+            continue;
+        }
+        const text = summarise(value, termWidth() - indent.length - key.length - 3);
+        if (text)
+            console.log(`${indent}${dim(`${key}:`)} ${text}`);
+    }
+}
+function printItem(item, number) {
+    if (typeof item !== 'object' || item === null) {
+        console.log(`${bold(`${number}.`)} ${summarise(item)}`);
+        return;
+    }
+    const record = item;
+    const headlineKey = HEADLINE_KEYS.find(key => typeof record[key] === 'string' && record[key] !== '');
+    const headline = headlineKey ? oneLine(String(record[headlineKey])) : '';
+    console.log(`${bold(`${number}.`)} ${headline || dim('—')}`);
+    printFields(record, '   ', new Set(headlineKey ? [headlineKey] : []));
+    console.log('');
+}
+/** Prints a successful tool response. */
+export function printResponse(response) {
+    const listEntry = Object.entries(response)
+        .find(([key, value]) => Array.isArray(value) && !META_KEYS.has(key));
+    if (listEntry) {
+        const [key, value] = listEntry;
+        const pagination = response.pagination;
+        const offset = typeof pagination?.from === 'number' ? pagination.from : 0;
+        const count = Number(response.resultCount ?? value.length);
+        const label = count === 1 ? key.replace(/s$/, '') : key;
+        console.log(`${bold(String(count))} ${label}:\n`);
+        value.forEach((item, index) => printItem(item, offset + index + 1));
+        printFields(response, '', new Set([key]));
+    }
+    else {
+        printFields(response, '');
+    }
+    const pagination = response.pagination;
+    if (pagination) {
+        const total = pagination.total !== undefined ? ` of ${pagination.total}` : '';
+        console.log(dim(`\nShowing ${pagination.returned}${total} (from ${pagination.from}, size ${pagination.size})`));
+        if (pagination.hasMore)
+            console.log(dim(`More available: --from ${pagination.nextFrom}`));
+    }
+}
+/** Prints a failed tool response to stderr. */
+export function printFailure(response) {
+    console.error(`${icon('❌')}${response.error ?? 'Unknown error'}`);
+    if (response.errorCode)
+        console.error(dim(`   code: ${response.errorCode}`));
+    const suggestions = response.suggestions;
+    if (Array.isArray(suggestions)) {
+        for (const suggestion of suggestions)
+            console.error(dim(`   try: ${suggestion}`));
+    }
+}
+/** Wraps text to the terminal width with a hanging indent, clipped to maxLines. */
+export function wrap(text, indent, maxLines = 2) {
+    const width = Math.max(40, termWidth()) - indent;
+    const lines = [];
+    let line = '';
+    for (const word of text.replace(/\s+/g, ' ').trim().split(' ')) {
+        const next = line ? `${line} ${word}` : word;
+        if (next.length <= width) {
+            line = next;
+        }
+        else {
+            if (line)
+                lines.push(line);
+            line = word;
+        }
+        if (lines.length > maxLines)
+            break;
+    }
+    if (line)
+        lines.push(line);
+    if (lines.length <= maxLines)
+        return lines;
+    const clipped = lines.slice(0, maxLines);
+    clipped[maxLines - 1] = `${clipped[maxLines - 1].slice(0, Math.max(0, width - 2))}…`;
+    return clipped;
+}

package/dist/cli/resolve.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Command and argument resolution for the `msteams` CLI.
+ *
+ * Everything here is derived from the MCP tool definitions - their names and
+ * JSON input schemas - so a new tool is callable, documented and type-coerced
+ * without touching the CLI.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+/** Thrown for anything the user can fix by retyping the command (exit code 2). */
+export declare class UsageError extends Error {
+}
+/** The subset of JSON Schema the tool definitions use. */
+export interface SchemaProp {
+    type?: string;
+    description?: string;
+    enum?: string[];
+    items?: {
+        type?: string;
+    };
+}
+/** Flag aliases that read better than the raw parameter name. */
+export declare const FLAG_ALIASES: Record<string, string>;
+export declare function schemaProps(tool: Tool): Record<string, SchemaProp>;
+export declare function requiredProps(tool: Tool): string[];
+/** The parameter a bare value after the command maps to: the first required string. */
+export declare function positionalProp(tool: Tool): string | null;
+/**
+ * Resolves a typed command to a tool name.
+ *
+ * Tries, in order: the exact name, `teams_<cmd>`, `teams_get_<cmd>`,
+ * `teams_search_<cmd>`, a unique `teams_<cmd>*` prefix, then a unique
+ * substring match ignoring underscores. So `search`, `get_thread`, `thread`,
+ * `send` and `markread` all land on the right tool.
+ */
+export declare function resolveToolName(names: string[], command: string): string;
+/** The shortest form that still resolves back to this tool - used in help output. */
+export declare function shortName(names: string[], toolName: string): string;
+export interface ParsedToolArgs {
+    args: Record<string, unknown>;
+    json: boolean;
+    help: boolean;
+}
+/**
+ * Parses a command's arguments against its input schema.
+ *
+ * Flags are whatever the schema declares (plus the aliases above), values are
+ * coerced to the schema's types, and an unknown flag is a usage error rather
+ * than something the server has to reject.
+ */
+export declare function parseToolArgs(tool: Tool, argv: string[], label?: string): ParsedToolArgs;