msteams-mcp 0.3.3 → 0.3.5

package/README.md

@@ -10,7 +10,7 @@ This server calls Microsoft's internal Teams APIs directly (Substrate, chatsvc,
 1. Run `teams_login` to open a browser and log in
 2. OAuth tokens are extracted and cached
 3. All operations use cached tokens directly (no browser needed)
-4. When tokens expire (~1 hour), run `teams_login` again
+4. Automatic token refresh (~1 hour)
 
 ## Installation
 
@@ -111,17 +111,17 @@ The search supports Teams' native operators:
 
 ```
 from:sarah@company.com     # Messages from person
-sent:today                 # Messages from today
-sent:lastweek              # Messages from last week
+sent:2026-01-20            # Messages from specific date
+sent:>=2026-01-15          # Messages since date
 in:project-alpha           # Messages in channel
 "Rob Smith"                # Find @mentions (name in quotes)
 hasattachment:true         # Messages with files
 NOT from:email@co.com      # Exclude results
 ```
 
-Combine operators: `from:sarah@co.com sent:lastweek hasattachment:true`
+Combine operators: `from:sarah@co.com sent:>=2026-01-18 hasattachment:true`
 
-**Note:** `@me`, `from:me`, `to:me` do NOT work. Use `teams_get_me` first to get your email/displayName, then use those values.
+**Note:** `@me`, `from:me`, `to:me` do NOT work. Use `teams_get_me` first to get your email/displayName. Also `sent:lastweek`, `sent:today`, `sent:thisweek` do NOT work - use explicit dates or omit (results are sorted by recency).
 
 ## MCP Resources
 
@@ -176,7 +176,7 @@ npm run test:mcp -- unread                # Check unread counts
 ## Limitations
 
 - **Login required** - Run `teams_login` to authenticate (opens browser)
-- **Token expiry** - Tokens expire after ~1 hour; run `teams_login` again when needed
+- **Token expiry** - Tokens expire after ~1 hour; headless refresh is attempted or run `teams_login` again when needed
 - **Undocumented APIs** - Uses Microsoft's internal APIs which may change without notice
 - **Search limitations** - Full-text search only; thread replies not matching search terms won't appear (use `teams_get_thread` for full context)
 - **Own messages only** - Edit/delete only works on your own messages

package/dist/api/substrate-api.js

@@ -8,14 +8,14 @@ import { SUBSTRATE_API, getBearerHeaders } from '../utils/api-config.js';
 import { ErrorCode } from '../types/errors.js';
 import { ok } from '../types/result.js';
 import { clearTokenCache } from '../auth/token-extractor.js';
-import { requireSubstrateToken } from '../utils/auth-guards.js';
+import { requireSubstrateTokenAsync } from '../utils/auth-guards.js';
 import { parseSearchResults, parsePeopleResults, parseChannelResults, filterChannelsByName, } from '../utils/parsers.js';
 import { getMyTeamsAndChannels } from './csa-api.js';
 /**
  * Searches Teams messages using the Substrate v2 query API.
  */
 export async function searchMessages(query, options = {}) {
-    const tokenResult = requireSubstrateToken();
+    const tokenResult = await requireSubstrateTokenAsync();
     if (!tokenResult.ok) {
         return tokenResult;
     }
@@ -92,7 +92,7 @@ export async function searchMessages(query, options = {}) {
  * Searches for people by name or email.
  */
 export async function searchPeople(query, limit = 10) {
-    const tokenResult = requireSubstrateToken();
+    const tokenResult = await requireSubstrateTokenAsync();
     if (!tokenResult.ok) {
         return tokenResult;
     }
@@ -143,7 +143,7 @@ export async function searchPeople(query, limit = 10) {
  * Gets the user's frequently contacted people.
  */
 export async function getFrequentContacts(limit = 50) {
-    const tokenResult = requireSubstrateToken();
+    const tokenResult = await requireSubstrateTokenAsync();
     if (!tokenResult.ok) {
         return tokenResult;
     }
@@ -201,7 +201,7 @@ export async function getFrequentContacts(limit = 50) {
  * @param limit - Maximum number of results (default: 10, max: 50)
  */
 export async function searchChannels(query, limit = 10) {
-    const tokenResult = requireSubstrateToken();
+    const tokenResult = await requireSubstrateTokenAsync();
     if (!tokenResult.ok) {
         return tokenResult;
     }

package/dist/auth/token-extractor.d.ts

@@ -2,21 +2,23 @@
  * Token extraction from session state.
  *
  * Extracts various authentication tokens from Playwright's saved session state.
+ * Teams stores MSAL tokens in localStorage; we parse these to get bearer tokens
+ * for various APIs (Substrate search, chatsvc messaging, etc.).
  */
 import { clearTokenCache, type SessionState } from './session-store.js';
 import { type UserProfile } from '../utils/parsers.js';
-/** Substrate search token information. */
+/** Substrate search token (for search/people APIs). */
 export interface SubstrateTokenInfo {
     token: string;
     expiry: Date;
 }
-/** Teams API token information. */
+/** Teams chat API token (for chatsvc). */
 export interface TeamsTokenInfo {
     token: string;
     expiry: Date;
     userMri: string;
 }
-/** Message authentication information (cookies). */
+/** Cookie-based auth for messaging APIs. */
 export interface MessageAuthInfo {
     skypeToken: string;
     authToken: string;
@@ -24,6 +26,7 @@ export interface MessageAuthInfo {
 }
 /**
  * Extracts the Substrate search token from session state.
+ * This token is used for search and people APIs.
  */
 export declare function extractSubstrateToken(state?: SessionState): SubstrateTokenInfo | null;
 /**
@@ -44,14 +47,20 @@ export declare function getSubstrateTokenStatus(): {
 };
 /**
  * Extracts the Teams chat API token from session state.
+ *
+ * Teams stores multiple tokens for different services. We prefer:
+ * 1. chatsvcagg.teams.microsoft.com (primary chat API)
+ * 2. api.spaces.skype.com (fallback)
  */
 export declare function extractTeamsToken(state?: SessionState): TeamsTokenInfo | null;
 /**
- * Extracts authentication info needed for messaging API (uses cookies).
+ * Extracts authentication info needed for messaging API.
+ * Unlike other APIs, messaging uses cookies rather than localStorage tokens.
  */
 export declare function extractMessageAuth(state?: SessionState): MessageAuthInfo | null;
 /**
  * Extracts the CSA token for the conversationFolders API.
+ * This searches all origins, not just teams.microsoft.com.
  */
 export declare function extractCsaToken(state?: SessionState): string | null;
 /**
@@ -60,6 +69,7 @@ export declare function extractCsaToken(state?: SessionState): string | null;
 export declare function getUserProfile(state?: SessionState): UserProfile | null;
 /**
  * Gets user's display name from session state.
+ * Searches localStorage entries first, then falls back to JWT claims.
  */
 export declare function getUserDisplayName(state?: SessionState): string | null;
 /**

package/dist/auth/token-extractor.js

@@ -2,12 +2,17 @@
  * Token extraction from session state.
  *
  * Extracts various authentication tokens from Playwright's saved session state.
+ * Teams stores MSAL tokens in localStorage; we parse these to get bearer tokens
+ * for various APIs (Substrate search, chatsvc messaging, etc.).
  */
 import { readSessionState, readTokenCache, writeTokenCache, clearTokenCache, getTeamsOrigin, } from './session-store.js';
 import { parseJwtProfile } from '../utils/parsers.js';
+import { MRI_ORGID_PREFIX } from '../constants.js';
+// ============================================================================
+// JWT Utilities
+// ============================================================================
 /**
  * Decodes a JWT token's payload without verifying the signature.
- * Returns null if the token is invalid.
  */
 function decodeJwtPayload(token) {
     try {
@@ -21,7 +26,7 @@ function decodeJwtPayload(token) {
     }
 }
 /**
- * Gets the expiry date from a JWT token.
+ * Gets the expiry date from a JWT token's `exp` claim.
  */
 function getJwtExpiry(token) {
     const payload = decodeJwtPayload(token);
@@ -30,26 +35,48 @@ function getJwtExpiry(token) {
     return new Date(payload.exp * 1000);
 }
 /**
- * Extracts the Substrate search token from session state.
+ * Checks if a string looks like a JWT (starts with 'ey').
  */
-export function extractSubstrateToken(state) {
+function isJwtToken(value) {
+    return typeof value === 'string' && value.startsWith('ey');
+}
+// ============================================================================
+// Session Helpers
+// ============================================================================
+/**
+ * Resolves session state and Teams origin in one call.
+ * Many functions need both, so this reduces boilerplate.
+ */
+function getTeamsLocalStorage(state) {
     const sessionState = state ?? readSessionState();
     if (!sessionState)
         return null;
     const teamsOrigin = getTeamsOrigin(sessionState);
-    if (!teamsOrigin)
+    return teamsOrigin?.localStorage ?? null;
+}
+// ============================================================================
+// Token Extraction
+// ============================================================================
+/**
+ * Extracts the Substrate search token from session state.
+ * This token is used for search and people APIs.
+ */
+export function extractSubstrateToken(state) {
+    const localStorage = getTeamsLocalStorage(state);
+    if (!localStorage)
         return null;
-    for (const item of teamsOrigin.localStorage) {
+    for (const item of localStorage) {
         try {
-            const val = JSON.parse(item.value);
-            if (val.target?.includes('substrate.office.com/search/SubstrateSearch')) {
-                const token = val.secret;
-                if (!token || typeof token !== 'string')
-                    continue;
-                const expiry = getJwtExpiry(token);
-                if (expiry) {
-                    return { token, expiry };
-                }
+            const entry = JSON.parse(item.value);
+            // Look for the Substrate search token by its target scope
+            if (!entry.target?.includes('substrate.office.com/search/SubstrateSearch')) {
+                continue;
+            }
+            if (!isJwtToken(entry.secret))
+                continue;
+            const expiry = getJwtExpiry(entry.secret);
+            if (expiry) {
+                return { token: entry.secret, expiry };
             }
         }
         catch {
@@ -58,6 +85,9 @@ export function extractSubstrateToken(state) {
     }
     return null;
 }
+// ============================================================================
+// Cached Token Access
+// ============================================================================
 /**
  * Gets a valid Substrate token, either from cache or by extracting from session.
  */
@@ -108,47 +138,40 @@ export function getSubstrateTokenStatus() {
 }
 /**
  * Extracts the Teams chat API token from session state.
+ *
+ * Teams stores multiple tokens for different services. We prefer:
+ * 1. chatsvcagg.teams.microsoft.com (primary chat API)
+ * 2. api.spaces.skype.com (fallback)
  */
 export function extractTeamsToken(state) {
-    const sessionState = state ?? readSessionState();
-    if (!sessionState)
-        return null;
-    const teamsOrigin = getTeamsOrigin(sessionState);
-    if (!teamsOrigin)
+    const localStorage = getTeamsLocalStorage(state);
+    if (!localStorage)
         return null;
-    let chatToken = null;
-    let chatTokenExpiry = null;
-    let skypeToken = null;
-    let skypeTokenExpiry = null;
+    let chatsvcCandidate = null;
+    let skypeCandidate = null;
     let userMri = null;
-    for (const item of teamsOrigin.localStorage) {
+    for (const item of localStorage) {
         try {
-            const val = JSON.parse(item.value);
-            if (!val.target || !val.secret)
-                continue;
-            const secret = val.secret;
-            if (typeof secret !== 'string' || !secret.startsWith('ey'))
+            const entry = JSON.parse(item.value);
+            if (!entry.target || !isJwtToken(entry.secret))
                 continue;
-            const payload = decodeJwtPayload(secret);
+            const payload = decodeJwtPayload(entry.secret);
             if (!payload?.exp || typeof payload.exp !== 'number')
                 continue;
-            const tokenExpiry = new Date(payload.exp * 1000);
-            // Extract user MRI from any token
+            const expiry = new Date(payload.exp * 1000);
+            // Capture user MRI from any token's oid claim
             if (typeof payload.oid === 'string' && !userMri) {
-                userMri = `8:orgid:${payload.oid}`;
+                userMri = `${MRI_ORGID_PREFIX}${payload.oid}`;
             }
-            // Prefer chatsvcagg.teams.microsoft.com token
-            if (val.target.includes('chatsvcagg.teams.microsoft.com')) {
-                if (!chatTokenExpiry || tokenExpiry > chatTokenExpiry) {
-                    chatToken = secret;
-                    chatTokenExpiry = tokenExpiry;
+            // Track best candidate for each service
+            if (entry.target.includes('chatsvcagg.teams.microsoft.com')) {
+                if (!chatsvcCandidate || expiry > chatsvcCandidate.expiry) {
+                    chatsvcCandidate = { token: entry.secret, expiry };
                 }
             }
-            // Fallback to api.spaces.skype.com token
-            if (val.target.includes('api.spaces.skype.com')) {
-                if (!skypeTokenExpiry || tokenExpiry > skypeTokenExpiry) {
-                    skypeToken = secret;
-                    skypeTokenExpiry = tokenExpiry;
+            else if (entry.target.includes('api.spaces.skype.com')) {
+                if (!skypeCandidate || expiry > skypeCandidate.expiry) {
+                    skypeCandidate = { token: entry.secret, expiry };
                 }
             }
         }
@@ -156,107 +179,108 @@ export function extractTeamsToken(state) {
             continue;
         }
     }
-    // If we still don't have userMri, try to get it from the Substrate token
+    // Fallback: extract userMri from Substrate token if not found
     if (!userMri) {
-        const substrateInfo = extractSubstrateToken(sessionState);
-        if (substrateInfo) {
-            const payload = decodeJwtPayload(substrateInfo.token);
-            if (typeof payload?.oid === 'string') {
-                userMri = `8:orgid:${payload.oid}`;
-            }
-        }
+        userMri = extractUserMriFromSubstrate(state);
     }
-    // Prefer chatsvc token, fallback to skype token
-    const token = chatToken || skypeToken;
-    const expiry = chatToken ? chatTokenExpiry : skypeTokenExpiry;
-    if (token && expiry && userMri && expiry.getTime() > Date.now()) {
-        return { token, expiry, userMri };
+    // Prefer chatsvc, fall back to skype
+    const best = chatsvcCandidate ?? skypeCandidate;
+    if (!best || !userMri || best.expiry.getTime() <= Date.now()) {
+        return null;
+    }
+    return { token: best.token, expiry: best.expiry, userMri };
+}
+/**
+ * Extracts user MRI from the Substrate token's oid claim.
+ */
+function extractUserMriFromSubstrate(state) {
+    const substrateInfo = extractSubstrateToken(state);
+    if (!substrateInfo)
+        return null;
+    const payload = decodeJwtPayload(substrateInfo.token);
+    if (typeof payload?.oid === 'string') {
+        return `${MRI_ORGID_PREFIX}${payload.oid}`;
     }
     return null;
 }
 /**
- * Extracts authentication info needed for messaging API (uses cookies).
+ * Extracts authentication info needed for messaging API.
+ * Unlike other APIs, messaging uses cookies rather than localStorage tokens.
  */
 export function extractMessageAuth(state) {
     const sessionState = state ?? readSessionState();
     if (!sessionState)
         return null;
-    let skypeToken = null;
-    let authToken = null;
-    let userMri = null;
-    // Extract tokens from cookies
-    for (const cookie of sessionState.cookies || []) {
-        if (cookie.name === 'skypetoken_asm' && cookie.domain?.includes('teams.microsoft.com')) {
-            skypeToken = cookie.value;
-        }
-        if (cookie.name === 'authtoken' && cookie.domain?.includes('teams.microsoft.com')) {
-            authToken = decodeURIComponent(cookie.value);
-            if (authToken.startsWith('Bearer=')) {
-                authToken = authToken.substring(7);
-            }
-        }
-    }
-    // Get userMri from skypeToken payload
-    if (skypeToken) {
-        const payload = decodeJwtPayload(skypeToken);
-        if (typeof payload?.skypeid === 'string') {
-            userMri = payload.skypeid;
-        }
-    }
-    // Fallback to extracting userMri from authToken
-    if (!userMri && authToken) {
-        const payload = decodeJwtPayload(authToken);
-        if (typeof payload?.oid === 'string') {
-            userMri = `8:orgid:${payload.oid}`;
-        }
-    }
-    if (skypeToken && authToken && userMri) {
-        return { skypeToken, authToken, userMri };
+    const cookies = sessionState.cookies ?? [];
+    const teamsCookies = cookies.filter(c => c.domain?.includes('teams.microsoft.com'));
+    // Extract the two required cookies
+    const skypeToken = teamsCookies.find(c => c.name === 'skypetoken_asm')?.value ?? null;
+    const rawAuthToken = teamsCookies.find(c => c.name === 'authtoken')?.value ?? null;
+    if (!skypeToken || !rawAuthToken)
+        return null;
+    // Decode authtoken (URL-encoded, may have 'Bearer=' prefix)
+    let authToken = decodeURIComponent(rawAuthToken);
+    if (authToken.startsWith('Bearer=')) {
+        authToken = authToken.substring(7);
     }
-    return null;
+    // Extract userMri from skypeToken's skypeid claim, or fall back to authToken's oid
+    const userMri = extractMriFromSkypeToken(skypeToken)
+        ?? extractMriFromAuthToken(authToken);
+    if (!userMri)
+        return null;
+    return { skypeToken, authToken, userMri };
+}
+function extractMriFromSkypeToken(token) {
+    const payload = decodeJwtPayload(token);
+    return typeof payload?.skypeid === 'string' ? payload.skypeid : null;
+}
+function extractMriFromAuthToken(token) {
+    const payload = decodeJwtPayload(token);
+    return typeof payload?.oid === 'string' ? `${MRI_ORGID_PREFIX}${payload.oid}` : null;
 }
 /**
  * Extracts the CSA token for the conversationFolders API.
+ * This searches all origins, not just teams.microsoft.com.
  */
 export function extractCsaToken(state) {
     const sessionState = state ?? readSessionState();
     if (!sessionState)
         return null;
-    for (const origin of sessionState.origins || []) {
-        for (const item of origin.localStorage || []) {
-            if (item.name.includes('chatsvcagg.teams.microsoft.com') && !item.name.startsWith('tmp.')) {
-                try {
-                    const data = JSON.parse(item.value);
-                    if (data.secret) {
-                        return data.secret;
-                    }
-                }
-                catch {
-                    // Ignore parse errors
-                }
+    for (const origin of sessionState.origins ?? []) {
+        for (const item of origin.localStorage ?? []) {
+            // Skip temporary entries, look for chatsvcagg tokens
+            if (item.name.startsWith('tmp.'))
+                continue;
+            if (!item.name.includes('chatsvcagg.teams.microsoft.com'))
+                continue;
+            try {
+                const entry = JSON.parse(item.value);
+                if (entry.secret)
+                    return entry.secret;
+            }
+            catch {
+                // Ignore parse errors
             }
         }
     }
     return null;
 }
+// ============================================================================
+// User Profile
+// ============================================================================
 /**
  * Gets the current user's profile from cached JWT tokens.
  */
 export function getUserProfile(state) {
-    const sessionState = state ?? readSessionState();
-    if (!sessionState)
-        return null;
-    const teamsOrigin = getTeamsOrigin(sessionState);
-    if (!teamsOrigin)
+    const localStorage = getTeamsLocalStorage(state);
+    if (!localStorage)
         return null;
-    for (const item of teamsOrigin.localStorage) {
+    for (const item of localStorage) {
         try {
-            const val = JSON.parse(item.value);
-            if (!val.secret || typeof val.secret !== 'string')
-                continue;
-            if (!val.secret.startsWith('ey'))
+            const entry = JSON.parse(item.value);
+            if (!isJwtToken(entry.secret))
                 continue;
-            const payload = decodeJwtPayload(val.secret);
+            const payload = decodeJwtPayload(entry.secret);
             if (payload) {
                 const profile = parseJwtProfile(payload);
                 if (profile)
@@ -271,30 +295,31 @@ export function getUserProfile(state) {
 }
 /**
  * Gets user's display name from session state.
+ * Searches localStorage entries first, then falls back to JWT claims.
  */
 export function getUserDisplayName(state) {
-    const sessionState = state ?? readSessionState();
-    if (!sessionState)
-        return null;
-    const teamsOrigin = getTeamsOrigin(sessionState);
-    if (!teamsOrigin)
+    const localStorage = getTeamsLocalStorage(state);
+    if (!localStorage)
         return null;
-    for (const item of teamsOrigin.localStorage) {
+    // First pass: look for explicit displayName in localStorage
+    for (const item of localStorage) {
+        // Quick filter before parsing
+        if (!item.value?.includes('displayName') && !item.value?.includes('givenName')) {
+            continue;
+        }
         try {
-            if (item.value?.includes('displayName') || item.value?.includes('givenName')) {
-                const val = JSON.parse(item.value);
-                if (val.displayName)
-                    return val.displayName;
-                if (val.name?.displayName)
-                    return val.name.displayName;
-            }
+            const entry = JSON.parse(item.value);
+            if (entry.displayName)
+                return entry.displayName;
+            if (entry.name?.displayName)
+                return entry.name.displayName;
         }
         catch {
             continue;
         }
     }
-    // Try to get from token
-    const teamsToken = extractTeamsToken(sessionState);
+    // Fallback: extract from Teams token's name claim
+    const teamsToken = extractTeamsToken(state);
     if (teamsToken) {
         const payload = decodeJwtPayload(teamsToken.token);
         if (typeof payload?.name === 'string')
@@ -302,6 +327,9 @@ export function getUserDisplayName(state) {
     }
     return null;
 }
+// ============================================================================
+// Token Status Checks
+// ============================================================================
 /**
  * Checks if tokens in session state are expired.
  */

package/dist/auth/token-refresh.d.ts

@@ -23,25 +23,3 @@ export interface TokenRefreshResult {
  * trigger that and save the updated state.
  */
 export declare function refreshTokensViaBrowser(): Promise<Result<TokenRefreshResult>>;
-/**
- * Checks if tokens need refreshing (less than threshold time remaining).
- *
- * @returns true if tokens should be refreshed proactively
- */
-export declare function shouldRefreshToken(): boolean;
-/**
- * Checks if tokens are completely expired.
- *
- * @returns true if tokens have expired and cannot be used
- */
-export declare function isTokenExpired(): boolean;
-/**
- * Attempts to proactively refresh tokens if they're approaching expiry.
- *
- * This is a convenience function that checks if refresh is needed and
- * performs it if necessary. Safe to call on any operation - it only
- * opens a browser when actually needed.
- *
- * @returns The refresh result if refresh was attempted, null if not needed
- */
-export declare function refreshIfNeeded(): Promise<Result<TokenRefreshResult> | null>;

package/dist/auth/token-refresh.js

@@ -5,7 +5,7 @@
  * requests. We open a headless browser with saved session state, let MSAL
  * silently refresh tokens, then save the updated state. Seamless to the user.
  */
-import { TOKEN_REFRESH_THRESHOLD_MS, MSAL_TOKEN_DELAY_MS } from '../constants.js';
+import { MSAL_TOKEN_DELAY_MS, TOKEN_REFRESH_THRESHOLD_MS } from '../constants.js';
 import { ErrorCode, createError } from '../types/errors.js';
 import { ok, err } from '../types/result.js';
 import { extractSubstrateToken, clearTokenCache, } from './token-extractor.js';
@@ -81,41 +81,3 @@ export async function refreshTokensViaBrowser() {
         return err(createError(ErrorCode.UNKNOWN, `Token refresh via browser failed: ${message}`, { suggestions: ['Call teams_login to re-authenticate'] }));
     }
 }
-/**
- * Checks if tokens need refreshing (less than threshold time remaining).
- *
- * @returns true if tokens should be refreshed proactively
- */
-export function shouldRefreshToken() {
-    const substrate = extractSubstrateToken();
-    if (!substrate)
-        return false;
-    const timeRemaining = substrate.expiry.getTime() - Date.now();
-    return timeRemaining > 0 && timeRemaining < TOKEN_REFRESH_THRESHOLD_MS;
-}
-/**
- * Checks if tokens are completely expired.
- *
- * @returns true if tokens have expired and cannot be used
- */
-export function isTokenExpired() {
-    const substrate = extractSubstrateToken();
-    if (!substrate)
-        return true;
-    return substrate.expiry.getTime() <= Date.now();
-}
-/**
- * Attempts to proactively refresh tokens if they're approaching expiry.
- *
- * This is a convenience function that checks if refresh is needed and
- * performs it if necessary. Safe to call on any operation - it only
- * opens a browser when actually needed.
- *
- * @returns The refresh result if refresh was attempted, null if not needed
- */
-export async function refreshIfNeeded() {
-    if (!shouldRefreshToken()) {
-        return null;
-    }
-    return refreshTokensViaBrowser();
-}

package/dist/constants.d.ts

@@ -62,3 +62,5 @@ export declare const MAX_ACTIVITY_LIMIT = 200;
 export declare const MAX_UNREAD_AGGREGATE_CHECK = 20;
 /** Threshold for proactive token refresh (10 minutes before expiry). */
 export declare const TOKEN_REFRESH_THRESHOLD_MS: number;
+/** MRI prefix for organisation users (orgid). */
+export declare const MRI_ORGID_PREFIX = "8:orgid:";

package/dist/constants.js

@@ -89,3 +89,8 @@ export const MAX_UNREAD_AGGREGATE_CHECK = 20;
 // ─────────────────────────────────────────────────────────────────────────────
 /** Threshold for proactive token refresh (10 minutes before expiry). */
 export const TOKEN_REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
+// ─────────────────────────────────────────────────────────────────────────────
+// User Identity
+// ─────────────────────────────────────────────────────────────────────────────
+/** MRI prefix for organisation users (orgid). */
+export const MRI_ORGID_PREFIX = '8:orgid:';

package/dist/tools/search-tools.js

@@ -28,13 +28,13 @@ export const FindChannelInputSchema = z.object({
 // ─────────────────────────────────────────────────────────────────────────────
 const searchToolDefinition = {
     name: 'teams_search',
-    description: 'Search for messages in Microsoft Teams. Returns matching messages with sender, timestamp, content, conversationId (for replies), and pagination info. Supports search operators: from:email, sent:today/lastweek, in:channel, hasattachment:true, "Name" for @mentions. Combine with NOT to exclude (e.g., NOT from:rob@co.com).',
+    description: 'Search for messages in Microsoft Teams. Returns matching messages with sender, timestamp, content, conversationId (for replies), and pagination info. Supports search operators: from:email, sent:YYYY-MM-DD, in:channel, hasattachment:true, "Name" for @mentions. Combine with NOT to exclude (e.g., NOT from:rob@co.com). Results are sorted by recency.',
     inputSchema: {
         type: 'object',
         properties: {
             query: {
                 type: 'string',
-                description: 'Search query with optional operators. Examples: "budget report", "from:sarah@co.com sent:lastweek", "\"Rob Smith\" NOT from:rob@co.com" (find @mentions of Rob). IMPORTANT: "@me", "from:me", "to:me" do NOT work - use teams_get_me first to get actual email/displayName, then use those values.',
+                description: 'Search query with optional operators. Examples: "budget report", "from:sarah@co.com", "\"Rob Smith\" NOT from:rob@co.com" (find @mentions of Rob). For date filtering use sent:YYYY-MM-DD or sent:>=YYYY-MM-DD (e.g., sent:>=2026-01-20). IMPORTANT: "@me", "from:me", "to:me" do NOT work - use teams_get_me first to get actual email/displayName. Also "sent:lastweek" and "sent:today" do NOT work - use explicit dates or omit (results are sorted by recency).',
             },
             maxResults: {
                 type: 'number',

package/dist/utils/auth-guards.d.ts

@@ -12,11 +12,6 @@ export interface CsaAuthInfo {
     auth: MessageAuthInfo;
     csaToken: string;
 }
-/**
- * Requires a valid Substrate token.
- * Use for search and people APIs.
- */
-export declare function requireSubstrateToken(): Result<string, McpError>;
 /**
  * Requires a valid Substrate token with proactive refresh.
  *

package/dist/utils/auth-guards.js

@@ -13,24 +13,12 @@ import { refreshTokensViaBrowser } from '../auth/token-refresh.js';
 // Error Messages
 // ─────────────────────────────────────────────────────────────────────────────
 const AUTH_ERROR_MESSAGES = {
-    substrateToken: 'No valid token available. Browser login required.',
     messageAuth: 'No valid authentication. Browser login required.',
     csaToken: 'No valid authentication for favourites. Browser login required.',
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Guard Functions
 // ─────────────────────────────────────────────────────────────────────────────
-/**
- * Requires a valid Substrate token.
- * Use for search and people APIs.
- */
-export function requireSubstrateToken() {
-    const token = getValidSubstrateToken();
-    if (!token) {
-        return err(createError(ErrorCode.AUTH_REQUIRED, AUTH_ERROR_MESSAGES.substrateToken));
-    }
-    return ok(token);
-}
 /**
  * Checks if the Substrate token is approaching expiry and needs refresh.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msteams-mcp",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "MCP server for Microsoft Teams - search messages, send replies, manage favourites",
   "type": "module",
   "main": "dist/index.js",