msteams-mcp 0.25.1 → 0.27.0

package/README.md

@@ -1,4 +1,4 @@
-# Teams MCP Server
+# Teams MCP Server & CLI
 
 [![CI](https://github.com/m0nkmaster/msteams-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/m0nkmaster/msteams-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -68,6 +68,24 @@ Then configure your MCP client:
 
 The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authentication.
 
+### CLI (alternative to the MCP server)
+
+The same functionality is also available as a standalone command-line tool, `msteams`. This is useful when you want Teams from a shell or script instead of an MCP client (for example, if an MCP integration is unreliable in your environment).
+
+Install it globally from npm:
+
+```bash
+npm install -g msteams-mcp
+```
+
+This installs two binaries: `msteams-mcp` (the MCP server) and `msteams` (the CLI). Or run it without installing:
+
+```bash
+npx -y msteams-mcp msteams status
+```
+
+See [CLI Usage](#cli-usage) for commands.
+
 ## Available Tools
 
 ### Search & Discovery
@@ -180,48 +198,59 @@ The server also exposes passive resources for context discovery:
 | `teams://me/favorites` | Pinned conversations |
 | `teams://status` | Authentication status |
 
-## CLI Tools (Development)
+## 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.
 
-For local development, CLI tools are available for testing and debugging:
+If you installed globally (`npm install -g msteams-mcp`), invoke it directly:
 
 ```bash
+# List available tools and shortcuts
+msteams
+
 # Check authentication status
-npm run cli -- status
+msteams status
+
+# Log in (opens a browser; tries silent SSO first)
+msteams login
+msteams login --force        # clear session and re-login
 
 # Search messages
-npm run cli -- search "meeting notes"
-npm run cli -- search "project" --from 0 --size 50
+msteams search "meeting notes"
+msteams search "project" --from 0 --size 50
 
 # Search emails
-npm run cli -- teams_search_email --query "from:sarah@company.com"
+msteams teams_search_email --query "from:sarah@company.com"
+
+# Send a message (default: your own notes/self-chat)
+msteams send "Hello from Teams MCP!"
+msteams send "Message" --to "conversation-id"
 
-# Send messages (default: your own notes/self-chat)
-npm run cli -- send "Hello from Teams MCP!"
-npm run cli -- send "Message" --to "conversation-id"
+# People, contacts, favourites, activity, unread
+msteams people "john smith"
+msteams favorites
+msteams activity
+msteams unread
 
-# Force login
-npm run cli -- login --force
+# Any tool by name (the teams_ prefix is optional)
+msteams teams_search_emoji --query "heart"
+msteams find_channel --query "support"
 
-# Output as JSON
-npm run cli -- search "query" --json
+# Machine-readable output
+msteams search "query" --json
 ```
 
-### MCP Test Harness
+**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.
 
-Test the server through the actual MCP protocol:
+### From a repo clone
 
-```bash
-# List available tools
-npm run cli
+If you're working from source, the same CLI is wired to `npm run cli` (runs via `tsx`, no build needed):
 
-# Call any tool
+```bash
+npm run cli                          # list tools
 npm run cli -- search "your query"
 npm run cli -- status
-npm run cli -- people "john smith"
-npm run cli -- favorites
-npm run cli -- activity              # Get activity feed
-npm run cli -- unread                # Check unread counts
-npm run cli -- teams_search_emoji --query "heart"  # Search emojis
+npm run cli -- send "Hi" --to "conversation-id"
 ```
 
 ## Limitations

package/dist/auth/session-store.d.ts

@@ -83,5 +83,10 @@ export declare function clearTokenCache(): void;
 /**
  * Gets the Teams origin from session state.
  * Checks multiple known Teams domains to support government clouds.
+ *
+ * Prefers an origin that has a SubstrateSearch token so Outlook/email and
+ * Substrate search keep working when both teams.cloud.microsoft and
+ * teams.microsoft.com are present in the saved session (common after the
+ * New Teams host migration).
  */
 export declare function getTeamsOrigin(state: SessionState): SessionState['origins'][number] | null;

package/dist/auth/session-store.js

@@ -208,18 +208,45 @@ export function clearTokenCache() {
  * Used to find the correct origin in session state.
  */
 const TEAMS_ORIGINS = [
-    'https://teams.microsoft.com', // Commercial
+    '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
-    'https://teams.cloud.microsoft', // New Teams URL
 ];
+/**
+ * Returns true if localStorage has a SubstrateSearch MSAL token entry.
+ */
+function hasSubstrateSearchToken(localStorage) {
+    for (const item of localStorage ?? []) {
+        try {
+            const entry = JSON.parse(item.value);
+            if (entry.target?.includes('SubstrateSearch') &&
+                typeof entry.secret === 'string' &&
+                entry.secret.startsWith('ey')) {
+                return true;
+            }
+        }
+        catch {
+            // ignore non-JSON localStorage values
+        }
+    }
+    return false;
+}
 /**
  * Gets the Teams origin from session state.
  * Checks multiple known Teams domains to support government clouds.
+ *
+ * Prefers an origin that has a SubstrateSearch token so Outlook/email and
+ * Substrate search keep working when both teams.cloud.microsoft and
+ * teams.microsoft.com are present in the saved session (common after the
+ * New Teams host migration).
  */
 export function getTeamsOrigin(state) {
     if (!state.origins)
         return null;
+    const withSubstrate = state.origins.find(o => hasSubstrateSearchToken(o.localStorage));
+    if (withSubstrate)
+        return withSubstrate;
     // Try known Teams origins in priority order
     for (const knownOrigin of TEAMS_ORIGINS) {
         const origin = state.origins.find(o => o.origin === knownOrigin);

package/dist/auth/session-store.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for getTeamsOrigin — especially New Teams (teams.cloud.microsoft)
+ * SubstrateSearch token selection when multiple origins are present.
+ */
+export {};

package/dist/auth/session-store.test.js

@@ -0,0 +1,69 @@
+/**
+ * Tests for getTeamsOrigin — especially New Teams (teams.cloud.microsoft)
+ * SubstrateSearch token selection when multiple origins are present.
+ */
+import { describe, it, expect } from 'vitest';
+import { getTeamsOrigin } from './session-store.js';
+function makeOrigin(origin, localStorage = []) {
+    return { origin, localStorage };
+}
+function makeSubstrateEntry(target = 'https://substrate.office.com/SubstrateSearch-Internal.ReadWrite') {
+    return {
+        name: 'msal-substrate-token',
+        value: JSON.stringify({
+            credentialType: 'AccessToken',
+            target,
+            // JWT-shaped secret (header.payload.sig) — extractor only checks prefix
+            secret: 'eyJhbGciOiJub25lIn0.eyJzdWIiOiJ0ZXN0In0.sig',
+        }),
+    };
+}
+function makeChatSvcEntry() {
+    return {
+        name: 'msal-chatsvc-token',
+        value: JSON.stringify({
+            credentialType: 'AccessToken',
+            target: 'https://chatsvcagg.teams.microsoft.com/.default',
+            secret: 'eyJhbGciOiJub25lIn0.eyJzdWIiOiJjaGF0In0.sig',
+        }),
+    };
+}
+describe('getTeamsOrigin', () => {
+    it('prefers the origin that holds a SubstrateSearch token', () => {
+        const state = {
+            cookies: [],
+            origins: [
+                makeOrigin('https://teams.microsoft.com', [makeChatSvcEntry()]),
+                makeOrigin('https://teams.cloud.microsoft', [makeSubstrateEntry()]),
+            ],
+        };
+        const chosen = getTeamsOrigin(state);
+        expect(chosen?.origin).toBe('https://teams.cloud.microsoft');
+    });
+    it('falls back to teams.cloud.microsoft when no Substrate token exists', () => {
+        const state = {
+            cookies: [],
+            origins: [
+                makeOrigin('https://teams.microsoft.com', [makeChatSvcEntry()]),
+                makeOrigin('https://teams.cloud.microsoft', [makeChatSvcEntry()]),
+            ],
+        };
+        const chosen = getTeamsOrigin(state);
+        expect(chosen?.origin).toBe('https://teams.cloud.microsoft');
+    });
+    it('returns teams.microsoft.com when it is the only known origin', () => {
+        const state = {
+            cookies: [],
+            origins: [makeOrigin('https://teams.microsoft.com', [makeChatSvcEntry()])],
+        };
+        const chosen = getTeamsOrigin(state);
+        expect(chosen?.origin).toBe('https://teams.microsoft.com');
+    });
+    it('returns null when no Teams origins are present', () => {
+        const state = {
+            cookies: [],
+            origins: [makeOrigin('https://login.microsoftonline.com', [])],
+        };
+        expect(getTeamsOrigin(state)).toBeNull();
+    });
+});

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Teams MCP CLI
+ *
+ * A standalone command-line interface with full parity to the MCP server.
+ * It runs the same in-process server over an in-memory transport and speaks
+ * to it through the real MCP protocol, so every registered tool is callable.
+ *
+ * Usage (installed):
+ *   msteams                               # List tools and check status
+ *   msteams search "query"                # Search for messages (shortcut)
+ *   msteams teams_search --query "q"      # Generic tool call
+ *   msteams --json                        # Output as JSON
+ *
+ * Usage (from the repo):
+ *   npm run cli -- search "query"
+ *
+ * Any unrecognised command is treated as a tool name. Use --key value for parameters.
+ */
+export {};

package/dist/{test/mcp-harness.js → cli.js}

@@ -1,22 +1,25 @@
-#!/usr/bin/env npx tsx
+#!/usr/bin/env node
 /**
- * MCP Protocol Test Harness
+ * Teams MCP CLI
  *
- * Tests the MCP server by connecting a client through the actual MCP protocol,
- * rather than calling underlying functions directly. This ensures the full
- * protocol layer works correctly.
+ * A standalone command-line interface with full parity to the MCP server.
+ * It runs the same in-process server over an in-memory transport and speaks
+ * to it through the real MCP protocol, so every registered tool is callable.
  *
- * Usage:
- *   npm run test:mcp                              # List tools and check status
- *   npm run test:mcp -- search "query"            # Search for messages (shortcut)
- *   npm run test:mcp -- teams_search --query "q"  # Generic tool call
- *   npm run test:mcp -- --json                    # Output as JSON
+ * Usage (installed):
+ *   msteams                               # List tools and check status
+ *   msteams search "query"                # Search for messages (shortcut)
+ *   msteams teams_search --query "q"      # Generic tool call
+ *   msteams --json                        # Output as JSON
+ *
+ * Usage (from the repo):
+ *   npm run cli -- search "query"
  *
  * Any unrecognised command is treated as a tool name. Use --key value for parameters.
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { createServer } from '../server.js';
+import { createServer } from './server.js';
 // Shortcuts map command names to tool names and parameter mappings
 const SHORTCUTS = {
     search: { tool: 'teams_search', primaryArg: 'query' },
@@ -160,7 +163,7 @@ async function createTestClient() {
     // Connect the server to its transport
     await server.connect(serverTransport);
     // Create and connect the client
-    const client = new Client({ name: 'mcp-test-harness', version: '1.0.0' }, { capabilities: {} });
+    const client = new Client({ name: 'msteams', version: '1.0.0' }, { capabilities: {} });
     await client.connect(clientTransport);
     const cleanup = async () => {
         await client.close();
@@ -438,8 +441,8 @@ function extractSenderName(sender) {
 async function main() {
     const parsed = parseArgs();
     if (!parsed.json) {
-        console.log('\n🧪 MCP Protocol Test Harness');
-        console.log('============================');
+        console.log('\n💬 Teams MCP CLI');
+        console.log('================');
     }
     let cleanup = null;
     try {
@@ -456,7 +459,7 @@ async function main() {
         }
         if (!parsed.json) {
             logSection('Complete');
-            log('MCP protocol test finished successfully.');
+            log('Done.');
         }
     }
     catch (error) {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "msteams-mcp",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "MCP server for Microsoft Teams - search messages, send replies, manage favourites",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "msteams-mcp": "dist/index.js"
+    "msteams-mcp": "dist/index.js",
+    "msteams": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -29,7 +30,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "cli": "tsx src/test/mcp-harness.ts",
+    "cli": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix"

package/dist/api/graph-api.d.ts

@@ -1,55 +0,0 @@
-/**
- * Microsoft Graph API - Spike for sending messages.
- *
- * This is a spike/experiment to test whether we can use the Graph API
- * with tokens extracted from the Teams browser session (no Azure App
- * registration required).
- *
- * Graph API send message endpoint:
- * POST https://graph.microsoft.com/v1.0/chats/{chatId}/messages
- *
- * Note: Graph API uses a different chat ID format than chatsvc. The
- * conversationId from Teams (e.g., "19:xxx@thread.v2") should work
- * directly as the Graph chatId.
- */
-import { type Result } from '../types/result.js';
-/** Result of sending a message via Graph API. */
-export interface GraphSendMessageResult {
-    /** The Graph-assigned message ID. */
-    id: string;
-    /** When the message was created (ISO 8601). */
-    createdDateTime?: string;
-    /** The web URL for the message (if returned). */
-    webUrl?: string;
-    /** Raw Graph API response for debugging in spike. */
-    _raw?: unknown;
-}
-/**
- * Sends a message to a Teams chat via the Microsoft Graph API.
- *
- * This is a spike to test Graph API access using tokens from the Teams
- * browser session. The Graph API endpoint is:
- * POST /v1.0/chats/{chatId}/messages
- *
- * For channel messages, the endpoint would be:
- * POST /v1.0/teams/{teamId}/channels/{channelId}/messages
- *
- * @param chatId - The Teams conversation ID (e.g., "19:xxx@thread.v2")
- * @param content - The message content (plain text or HTML)
- * @param contentType - "text" for plain text, "html" for HTML (default: "text")
- */
-export declare function graphSendMessage(chatId: string, content: string, contentType?: 'text' | 'html'): Promise<Result<GraphSendMessageResult>>;
-/**
- * Sends a message to a Teams channel via the Microsoft Graph API.
- *
- * POST /v1.0/teams/{teamId}/channels/{channelId}/messages
- *
- * Note: For channels, we need the teamId (group ID) and channelId separately.
- * This is different from the chatsvc API which uses a single conversationId.
- *
- * @param teamId - The team's group ID (GUID)
- * @param channelId - The channel ID (e.g., "19:xxx@thread.tacv2")
- * @param content - The message content
- * @param contentType - "text" for plain text, "html" for HTML (default: "text")
- */
-export declare function graphSendChannelMessage(teamId: string, channelId: string, content: string, contentType?: 'text' | 'html'): Promise<Result<GraphSendMessageResult>>;

package/dist/api/graph-api.js

@@ -1,148 +0,0 @@
-/**
- * Microsoft Graph API - Spike for sending messages.
- *
- * This is a spike/experiment to test whether we can use the Graph API
- * with tokens extracted from the Teams browser session (no Azure App
- * registration required).
- *
- * Graph API send message endpoint:
- * POST https://graph.microsoft.com/v1.0/chats/{chatId}/messages
- *
- * Note: Graph API uses a different chat ID format than chatsvc. The
- * conversationId from Teams (e.g., "19:xxx@thread.v2") should work
- * directly as the Graph chatId.
- */
-import { httpRequest } from '../utils/http.js';
-import { ErrorCode, createError } from '../types/errors.js';
-import { ok, err } from '../types/result.js';
-import { requireGraphAuth } from '../utils/auth-guards.js';
-// ─────────────────────────────────────────────────────────────────────────────
-// Constants
-// ─────────────────────────────────────────────────────────────────────────────
-const GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
-// ─────────────────────────────────────────────────────────────────────────────
-// Send Message via Graph API
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Sends a message to a Teams chat via the Microsoft Graph API.
- *
- * This is a spike to test Graph API access using tokens from the Teams
- * browser session. The Graph API endpoint is:
- * POST /v1.0/chats/{chatId}/messages
- *
- * For channel messages, the endpoint would be:
- * POST /v1.0/teams/{teamId}/channels/{channelId}/messages
- *
- * @param chatId - The Teams conversation ID (e.g., "19:xxx@thread.v2")
- * @param content - The message content (plain text or HTML)
- * @param contentType - "text" for plain text, "html" for HTML (default: "text")
- */
-export async function graphSendMessage(chatId, content, contentType = 'text') {
-    const authResult = requireGraphAuth();
-    if (!authResult.ok) {
-        return authResult;
-    }
-    const { graphToken } = authResult.value;
-    const url = `${GRAPH_BASE_URL}/chats/${encodeURIComponent(chatId)}/messages`;
-    const body = {
-        body: {
-            contentType,
-            content,
-        },
-    };
-    const response = await httpRequest(url, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${graphToken}`,
-        },
-        body: JSON.stringify(body),
-        // Don't retry auth errors - they indicate the token doesn't have the right scopes
-        maxRetries: 1,
-    });
-    if (!response.ok) {
-        // Enhance error message with Graph-specific context
-        const errorMessage = response.error.message;
-        // Check for common Graph API permission errors
-        if (errorMessage.includes('Authorization_RequestDenied') ||
-            errorMessage.includes('Forbidden') ||
-            errorMessage.includes('403')) {
-            return err(createError(ErrorCode.AUTH_REQUIRED, `Graph API permission denied. The token from the Teams session may not have Chat.ReadWrite scope. Error: ${errorMessage}`, {
-                retryable: false,
-                suggestions: [
-                    'The Teams SPA client ID may not have delegated Chat.ReadWrite permission',
-                    'Check the token scopes by decoding the JWT at jwt.ms',
-                ],
-            }));
-        }
-        return response;
-    }
-    const data = response.value.data;
-    // Check if the response is an error response
-    if ('error' in data && data.error) {
-        return err(createError(ErrorCode.API_ERROR, `Graph API error: ${data.error.code}: ${data.error.message}`, { retryable: false }));
-    }
-    const msgData = data;
-    if (!msgData.id) {
-        return err(createError(ErrorCode.UNKNOWN, 'Graph API returned success but no message ID', { retryable: false }));
-    }
-    return ok({
-        id: msgData.id,
-        createdDateTime: msgData.createdDateTime,
-        webUrl: msgData.webUrl,
-        _raw: msgData,
-    });
-}
-/**
- * Sends a message to a Teams channel via the Microsoft Graph API.
- *
- * POST /v1.0/teams/{teamId}/channels/{channelId}/messages
- *
- * Note: For channels, we need the teamId (group ID) and channelId separately.
- * This is different from the chatsvc API which uses a single conversationId.
- *
- * @param teamId - The team's group ID (GUID)
- * @param channelId - The channel ID (e.g., "19:xxx@thread.tacv2")
- * @param content - The message content
- * @param contentType - "text" for plain text, "html" for HTML (default: "text")
- */
-export async function graphSendChannelMessage(teamId, channelId, content, contentType = 'text') {
-    const authResult = requireGraphAuth();
-    if (!authResult.ok) {
-        return authResult;
-    }
-    const { graphToken } = authResult.value;
-    const url = `${GRAPH_BASE_URL}/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/messages`;
-    const body = {
-        body: {
-            contentType,
-            content,
-        },
-    };
-    const response = await httpRequest(url, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${graphToken}`,
-        },
-        body: JSON.stringify(body),
-        maxRetries: 1,
-    });
-    if (!response.ok) {
-        return response;
-    }
-    const data = response.value.data;
-    if ('error' in data && data.error) {
-        return err(createError(ErrorCode.API_ERROR, `Graph API error: ${data.error.code}: ${data.error.message}`, { retryable: false }));
-    }
-    const msgData = data;
-    if (!msgData.id) {
-        return err(createError(ErrorCode.UNKNOWN, 'Graph API returned success but no message ID', { retryable: false }));
-    }
-    return ok({
-        id: msgData.id,
-        createdDateTime: msgData.createdDateTime,
-        webUrl: msgData.webUrl,
-        _raw: msgData,
-    });
-}

package/dist/api/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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';
-export * from './profile-api.js';

package/dist/api/index.js

@@ -1,11 +0,0 @@
-/**
- * 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';
-export * from './profile-api.js';

package/dist/auth/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * 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

@@ -1,7 +0,0 @@
-/**
- * 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/chrome-cookie-import.d.ts

@@ -1,27 +0,0 @@
-/**
- * Import Microsoft SSO cookies from the user's Chrome profile into a Playwright context.
- *
- * When the Teams MCP server needs to open a visible browser for login,
- * the Playwright profile is isolated from the user's real Chrome — so Microsoft
- * can't recognise the user via SSO. This module copies the relevant Microsoft
- * cookies from the user's actual Chrome work profile, enabling silent SSO in
- * the Playwright browser and eliminating the need to re-type credentials.
- *
- * macOS only (Chrome cookies are encrypted with a Keychain-backed key).
- * Fails gracefully on other platforms or when Chrome isn't available.
- *
- * Configuration:
- *   TEAMS_MCP_CHROME_PROFILE env var — Chrome profile directory name
- *   (e.g. "Profile 1"). If unset, auto-detects from Chrome's Local State.
- */
-import type { BrowserContext } from 'playwright';
-/**
- * Imports Microsoft SSO cookies from the user's Chrome profile into a Playwright context.
- *
- * This enables SSO in the Playwright browser so the user doesn't have to type
- * credentials when Microsoft redirects to the login page.
- *
- * Fails silently — cookie import is best-effort. If it doesn't work,
- * the user just has to log in manually as before.
- */
-export declare function importMicrosoftCookies(context: BrowserContext): Promise<void>;