msteams-mcp 0.17.0 → 0.18.0

package/dist/api/chatsvc-api.js

@@ -9,7 +9,7 @@ import { CHATSVC_API, getMessagingHeaders, getSkypeAuthHeaders, getTeamsHeaders
 import { ErrorCode, createError } from '../types/errors.js';
 import { ok, err } from '../types/result.js';
 import { getUserDisplayName } from '../auth/token-extractor.js';
-import { requireMessageAuth, getRegion, getTeamsBaseUrl } from '../utils/auth-guards.js';
+import { requireMessageAuth, getRegion, getTeamsBaseUrl, getTenantId } from '../utils/auth-guards.js';
 import { stripHtml, extractLinks, buildMessageLink, buildOneOnOneConversationId, extractObjectId, extractActivityTimestamp, parseVirtualConversationMessage, markdownToTeamsHtml } from '../utils/parsers.js';
 import { DEFAULT_ACTIVITY_LIMIT, SAVED_MESSAGES_ID, FOLLOWED_THREADS_ID, VIRTUAL_CONVERSATION_PREFIX, SELF_CHAT_ID, MRI_ORGID_PREFIX } from '../constants.js';
 // Reusable date formatter for human-readable timestamps with day of week
@@ -166,18 +166,24 @@ export async function getThreadMessages(conversationId, options = {}) {
         const timestamp = msg.originalarrivaltime ||
             msg.composetime ||
             new Date(parseInt(id, 10)).toISOString();
-        // Build message link
+        // Extract thread root ID for channel messages
+        // When rootMessageId differs from id, this message is a reply within a thread
+        const rootMessageId = msg.rootMessageId;
+        const isThreadReply = !!rootMessageId && rootMessageId !== id;
+        // Build message link with tenant context for reliable deep links
         const messageLink = /^\d+$/.test(id)
-            ? buildMessageLink(conversationId, id)
+            ? buildMessageLink({
+                conversationId,
+                messageId: id,
+                tenantId: getTenantId() ?? undefined,
+                parentMessageId: isThreadReply ? rootMessageId : undefined,
+                teamsBaseUrl: getTeamsBaseUrl(),
+            })
             : undefined;
         // Extract links before stripping HTML
         const links = extractLinks(content);
         // Format human-readable date with day of week to help LLMs
         const when = formatHumanReadableDate(timestamp);
-        // Extract thread root ID for channel messages
-        // When rootMessageId differs from id, this message is a reply within a thread
-        const rootMessageId = msg.rootMessageId;
-        const isThreadReply = !!rootMessageId && rootMessageId !== id;
         messages.push({
             id,
             content: stripHtml(content),
@@ -243,7 +249,7 @@ export async function getSavedMessages(options = {}) {
     }
     const messages = [];
     for (const raw of rawMessages) {
-        const parsed = parseVirtualConversationMessage(raw, SAVED_MESSAGE_PATTERN);
+        const parsed = parseVirtualConversationMessage(raw, SAVED_MESSAGE_PATTERN, { tenantId: getTenantId() ?? undefined, teamsBaseUrl: getTeamsBaseUrl() });
         if (!parsed)
             continue;
         messages.push({
@@ -288,7 +294,7 @@ export async function getFollowedThreads(options = {}) {
     }
     const threads = [];
     for (const raw of rawMessages) {
-        const parsed = parseVirtualConversationMessage(raw, FOLLOWED_THREAD_PATTERN);
+        const parsed = parseVirtualConversationMessage(raw, FOLLOWED_THREAD_PATTERN, { tenantId: getTenantId() ?? undefined, teamsBaseUrl: getTeamsBaseUrl() });
         if (!parsed)
             continue;
         threads.push({
@@ -998,7 +1004,12 @@ export async function getActivityFeed(options = {}) {
         // Skip virtual conversations (48:xxx) as they don't produce working deep links
         let activityLink;
         if (conversationId && !conversationId.startsWith(VIRTUAL_CONVERSATION_PREFIX) && /^\d+$/.test(id)) {
-            activityLink = buildMessageLink(conversationId, id);
+            activityLink = buildMessageLink({
+                conversationId,
+                messageId: id,
+                tenantId: getTenantId() ?? undefined,
+                teamsBaseUrl: getTeamsBaseUrl(),
+            });
         }
         const activityType = detectActivityType(msg);
         // Extract links before stripping HTML

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

@@ -0,0 +1,51 @@
+/**
+ * Files API client for shared file operations.
+ *
+ * Uses the Substrate AllFiles API to retrieve files and links
+ * shared in a Teams conversation.
+ */
+import { type Result } from '../types/result.js';
+/** A file shared in a conversation. */
+export interface SharedFile {
+    /** Item type: "File" or "Link". */
+    itemType: 'File' | 'Link';
+    /** File name (for files). */
+    fileName?: string;
+    /** File extension (for files). */
+    fileExtension?: string;
+    /** URL to access the file or link. */
+    webUrl?: string;
+    /** File size in bytes (for files). */
+    fileSize?: number;
+    /** Display name of the person who shared the item. */
+    sharedBy?: string;
+    /** Email of the person who shared the item. */
+    sharedByEmail?: string;
+    /** When the item was shared (ISO timestamp). */
+    sharedTime?: string;
+    /** Title (for links). */
+    title?: string;
+}
+/** Result of getting shared files. */
+export interface GetSharedFilesResult {
+    conversationId: string;
+    files: SharedFile[];
+    returned: number;
+    /** Continuation token for pagination (if more results available). */
+    skipToken?: string;
+}
+/**
+ * Gets files and links shared in a Teams conversation.
+ *
+ * Uses the Substrate AllFiles API which indexes files shared across
+ * Teams conversations. Supports both files (SharePoint/OneDrive) and
+ * links shared in chat.
+ *
+ * @param conversationId - The conversation ID to get files for
+ * @param options.pageSize - Number of items per page (default: 25, max: 100)
+ * @param options.skipToken - Continuation token for pagination
+ */
+export declare function getSharedFiles(conversationId: string, options?: {
+    pageSize?: number;
+    skipToken?: string;
+}): Promise<Result<GetSharedFilesResult>>;

package/dist/api/files-api.js

@@ -0,0 +1,123 @@
+/**
+ * Files API client for shared file operations.
+ *
+ * Uses the Substrate AllFiles API to retrieve files and links
+ * shared in a Teams conversation.
+ */
+import { httpRequest } from '../utils/http.js';
+import { ok, err } from '../types/result.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { clearTokenCache } from '../auth/token-extractor.js';
+import { requireSubstrateTokenAsync, getTenantId } from '../utils/auth-guards.js';
+import { extractObjectId } from '../utils/parsers.js';
+import { requireMessageAuth } from '../utils/auth-guards.js';
+import { DEFAULT_FILES_PAGE_SIZE } from '../constants.js';
+import { DEFAULT_SUBSTRATE_BASE_URL } from '../utils/api-config.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// API Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Gets files and links shared in a Teams conversation.
+ *
+ * Uses the Substrate AllFiles API which indexes files shared across
+ * Teams conversations. Supports both files (SharePoint/OneDrive) and
+ * links shared in chat.
+ *
+ * @param conversationId - The conversation ID to get files for
+ * @param options.pageSize - Number of items per page (default: 25, max: 100)
+ * @param options.skipToken - Continuation token for pagination
+ */
+export async function getSharedFiles(conversationId, options = {}) {
+    // Need both Substrate token (for the API) and message auth (for user MRI)
+    const [tokenResult, authResult] = await Promise.all([
+        requireSubstrateTokenAsync(),
+        Promise.resolve(requireMessageAuth()),
+    ]);
+    if (!tokenResult.ok)
+        return tokenResult;
+    if (!authResult.ok)
+        return authResult;
+    const token = tokenResult.value;
+    const auth = authResult.value;
+    // Extract user's object ID from their MRI
+    const userId = extractObjectId(auth.userMri);
+    if (!userId) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, 'Could not extract user ID from session. Please try logging in again.', { suggestions: ['Call teams_login to re-authenticate'] }));
+    }
+    // Get tenant ID
+    const tenantId = getTenantId();
+    if (!tenantId) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, 'Could not determine tenant ID. Please try logging in again.', { suggestions: ['Call teams_login to re-authenticate'] }));
+    }
+    const pageSize = options.pageSize ?? DEFAULT_FILES_PAGE_SIZE;
+    // Build the AllFiles API URL
+    const userPrincipal = `OID:${userId}@${tenantId}`;
+    const params = new URLSearchParams();
+    params.set('ThreadId', conversationId);
+    params.set('ItemTypes', 'File');
+    params.append('ItemTypes', 'Link');
+    params.set('PageSize', String(pageSize));
+    if (options.skipToken) {
+        params.set('$skiptoken', options.skipToken);
+    }
+    const url = `${DEFAULT_SUBSTRATE_BASE_URL}/AllFiles/api/users('${encodeURIComponent(userPrincipal)}')/AllShared?${params.toString()}`;
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+        },
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const data = response.value.data;
+    const rawItems = data.Items;
+    const skipToken = data.SkipToken;
+    if (!rawItems || rawItems.length === 0) {
+        return ok({
+            conversationId,
+            files: [],
+            returned: 0,
+            skipToken: undefined,
+        });
+    }
+    const files = [];
+    for (const item of rawItems) {
+        const itemType = item.ItemType;
+        if (itemType === 'File') {
+            const fileData = item.FileData;
+            files.push({
+                itemType: 'File',
+                fileName: fileData?.FileName,
+                fileExtension: fileData?.FileExtension,
+                webUrl: fileData?.WebUrl,
+                fileSize: fileData?.FileSize,
+                sharedBy: item.SharedByDisplayName,
+                sharedByEmail: item.SharedBySmtp,
+                sharedTime: item.SharedTime,
+            });
+        }
+        else if (itemType === 'Link') {
+            const linkData = item.WeblinkData;
+            files.push({
+                itemType: 'Link',
+                webUrl: linkData?.WebUrl,
+                title: linkData?.Title,
+                sharedBy: item.SharedByDisplayName,
+                sharedByEmail: item.SharedBySmtp,
+                sharedTime: item.SharedTime,
+            });
+        }
+    }
+    return ok({
+        conversationId,
+        files,
+        returned: files.length,
+        skipToken: skipToken || undefined,
+    });
+}

package/dist/api/index.d.ts

@@ -6,3 +6,4 @@ 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';

package/dist/api/index.js

@@ -6,3 +6,4 @@ 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';

package/dist/api/substrate-api.js

@@ -8,7 +8,7 @@ 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 { requireSubstrateTokenAsync } from '../utils/auth-guards.js';
+import { requireSubstrateTokenAsync, getTenantId, getTeamsBaseUrl } from '../utils/auth-guards.js';
 import { parseSearchResults, parsePeopleResults, parseChannelResults, filterChannelsByName, } from '../utils/parsers.js';
 import { getMyTeamsAndChannels } from './csa-api.js';
 /**
@@ -72,7 +72,11 @@ export async function searchMessages(query, options = {}) {
         return response;
     }
     const data = response.value.data;
-    const { results, total } = parseSearchResults(data.EntitySets);
+    const linkContext = {
+        tenantId: getTenantId() ?? undefined,
+        teamsBaseUrl: getTeamsBaseUrl(),
+    };
+    const { results, total } = parseSearchResults(data.EntitySets, linkContext);
     const maxResults = options.maxResults ?? size;
     const limitedResults = results.slice(0, maxResults);
     return ok({

package/dist/api/transcript-api.js

@@ -92,14 +92,15 @@ export async function getTranscriptContent(threadId, meetingDate) {
     try {
         transcriptData = JSON.parse(transcriptJsonStr);
     }
-    catch {
-        return err(createError(ErrorCode.UNKNOWN, 'Failed to parse transcript data.'));
+    catch (parseError) {
+        return err(createError(ErrorCode.UNKNOWN, `Failed to parse transcript data: ${parseError instanceof Error ? parseError.message : 'unknown error'}`));
     }
     const rawEntries = transcriptData.entries || [];
     if (rawEntries.length === 0) {
         return err(createError(ErrorCode.NOT_FOUND, 'Transcript is empty — no speech was detected during the meeting.'));
     }
     // Map to TranscriptEntry format
+    // Substrate returns timestamps with microsecond precision (extra 4 trailing zeros) — normalise to milliseconds
     const entries = rawEntries.map(e => ({
         startTime: (e.startOffset || '').replace(/0{4}$/, ''),
         endTime: (e.endOffset || '').replace(/0{4}$/, ''),

package/dist/constants.d.ts

@@ -83,6 +83,10 @@ export declare const DEFAULT_MEETING_DAYS_AHEAD = 7;
 export declare const DEFAULT_MEETING_LIMIT = 50;
 /** Maximum limit for meeting results. */
 export declare const MAX_MEETING_LIMIT = 200;
+/** Default page size for shared files. */
+export declare const DEFAULT_FILES_PAGE_SIZE = 25;
+/** Maximum page size for shared files. */
+export declare const MAX_FILES_PAGE_SIZE = 100;
 /** Threshold for proactive token refresh (10 minutes before expiry). */
 export declare const TOKEN_REFRESH_THRESHOLD_MS: number;
 /** MRI type prefix for Teams/AAD users (type 8). */

package/dist/constants.js

@@ -111,6 +111,13 @@ export const DEFAULT_MEETING_LIMIT = 50;
 /** Maximum limit for meeting results. */
 export const MAX_MEETING_LIMIT = 200;
 // ─────────────────────────────────────────────────────────────────────────────
+// Files
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default page size for shared files. */
+export const DEFAULT_FILES_PAGE_SIZE = 25;
+/** Maximum page size for shared files. */
+export const MAX_FILES_PAGE_SIZE = 100;
+// ─────────────────────────────────────────────────────────────────────────────
 // Token Refresh
 // ─────────────────────────────────────────────────────────────────────────────
 /** Threshold for proactive token refresh (10 minutes before expiry). */

package/dist/tools/file-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * File-related tool handlers.
+ */
+import { z } from 'zod';
+import type { RegisteredTool } from './index.js';
+export declare const GetSharedFilesInputSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    skipToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    pageSize: number;
+    skipToken?: string | undefined;
+}, {
+    conversationId: string;
+    pageSize?: number | undefined;
+    skipToken?: string | undefined;
+}>;
+export declare const getSharedFilesTool: RegisteredTool<typeof GetSharedFilesInputSchema>;
+/** All file-related tools. */
+export declare const fileTools: RegisteredTool<z.ZodObject<{
+    conversationId: z.ZodString;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    skipToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    pageSize: number;
+    skipToken?: string | undefined;
+}, {
+    conversationId: string;
+    pageSize?: number | undefined;
+    skipToken?: string | undefined;
+}>>[];

package/dist/tools/file-tools.js

@@ -0,0 +1,65 @@
+/**
+ * File-related tool handlers.
+ */
+import { z } from 'zod';
+import { handleApiResult } from './index.js';
+import { getSharedFiles } from '../api/files-api.js';
+import { DEFAULT_FILES_PAGE_SIZE, MAX_FILES_PAGE_SIZE, } from '../constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────────────────────
+export const GetSharedFilesInputSchema = z.object({
+    conversationId: z.string(),
+    pageSize: z.number().min(1).max(MAX_FILES_PAGE_SIZE).optional().default(DEFAULT_FILES_PAGE_SIZE),
+    skipToken: z.string().optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const getSharedFilesToolDefinition = {
+    name: 'teams_get_shared_files',
+    description: 'Get files and links shared in a Teams conversation. Returns file names, URLs, extensions, sizes, and who shared them. Works for channels, group chats, 1:1 chats, and meeting chats. Use the conversationId from other tools (teams_get_favorites, teams_search, teams_find_channel, teams_get_chat). Supports pagination via skipToken for conversations with many files.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            conversationId: {
+                type: 'string',
+                description: 'The conversation ID to get shared files for (e.g., "19:abc@thread.tacv2" for a channel, or a chat conversation ID).',
+            },
+            pageSize: {
+                type: 'number',
+                description: `Number of items per page (default: ${DEFAULT_FILES_PAGE_SIZE}, max: ${MAX_FILES_PAGE_SIZE})`,
+            },
+            skipToken: {
+                type: 'string',
+                description: 'Continuation token from a previous response to get the next page of results.',
+            },
+        },
+        required: ['conversationId'],
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleGetSharedFiles(input, _ctx) {
+    const result = await getSharedFiles(input.conversationId, {
+        pageSize: input.pageSize,
+        skipToken: input.skipToken,
+    });
+    return handleApiResult(result, (value) => ({
+        conversationId: value.conversationId,
+        returned: value.returned,
+        files: value.files,
+        ...(value.skipToken ? { skipToken: value.skipToken, hasMore: true } : { hasMore: false }),
+    }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export const getSharedFilesTool = {
+    definition: getSharedFilesToolDefinition,
+    schema: GetSharedFilesInputSchema,
+    handler: handleGetSharedFiles,
+};
+/** All file-related tools. */
+export const fileTools = [getSharedFilesTool];

package/dist/tools/index.d.ts

@@ -53,4 +53,5 @@ export * from './message-tools.js';
 export * from './people-tools.js';
 export * from './auth-tools.js';
 export * from './meeting-tools.js';
+export * from './file-tools.js';
 export * from './registry.js';

package/dist/tools/index.js

@@ -31,4 +31,5 @@ export * from './message-tools.js';
 export * from './people-tools.js';
 export * from './auth-tools.js';
 export * from './meeting-tools.js';
+export * from './file-tools.js';
 export * from './registry.js';

package/dist/tools/meeting-tools.js

@@ -62,7 +62,7 @@ async function handleGetMeetings(input, _ctx) {
 // ─────────────────────────────────────────────────────────────────────────────
 const getTranscriptToolDefinition = {
     name: 'teams_get_transcript',
-    description: 'Get the transcript of a Teams meeting. Requires the meeting\'s threadId (from teams_get_meetings). Returns the full transcript with timestamps and speakers, formatted as readable text. The meeting must have had transcription enabled. Optionally pass meetingDate (ISO string, e.g. the startTime from teams_get_meetings) to narrow the search.',
+    description: 'Get the transcript of a Teams meeting. Requires the meeting\'s threadId (from teams_get_meetings). Returns formatted transcript text with timestamps and speaker names, ready for reading or summarization. The meeting must have had transcription enabled. Optionally pass meetingDate (ISO string, e.g. the startTime from teams_get_meetings) to narrow the search.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/registry.js

@@ -8,6 +8,7 @@ import { messageTools } from './message-tools.js';
 import { peopleTools } from './people-tools.js';
 import { authTools } from './auth-tools.js';
 import { meetingTools } from './meeting-tools.js';
+import { fileTools } from './file-tools.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // Registry
 // ─────────────────────────────────────────────────────────────────────────────
@@ -19,6 +20,7 @@ const allTools = [
     ...peopleTools,
     ...authTools,
     ...meetingTools,
+    ...fileTools,
 ];
 /** Lookup map for tools by name. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

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

@@ -61,7 +61,14 @@ export declare function getTeamsBaseUrl(): string;
  */
 export declare function getRegionConfig(): RegionConfig | null;
 /**
- * Clears the cached region config.
+ * Clears the cached region config and tenant ID.
  * Call this after login/logout to pick up new session.
  */
 export declare function clearRegionCache(): void;
+/**
+ * Gets the tenant ID from the user's session (JWT tokens).
+ *
+ * Required for building reliable Teams deep links.
+ * Returns null if no valid session is available.
+ */
+export declare function getTenantId(): string | null;

package/dist/utils/auth-guards.js

@@ -6,7 +6,7 @@
  */
 import { ErrorCode, createError } from '../types/errors.js';
 import { err, ok } from '../types/result.js';
-import { getValidSubstrateToken, extractMessageAuth, extractCsaToken, extractSubstrateToken, extractSkypeSpacesToken, extractRegionConfig, } from '../auth/token-extractor.js';
+import { getValidSubstrateToken, extractMessageAuth, extractCsaToken, extractSubstrateToken, extractSkypeSpacesToken, extractRegionConfig, getUserProfile, } from '../auth/token-extractor.js';
 import { TOKEN_REFRESH_THRESHOLD_MS } from '../constants.js';
 import { refreshTokensViaBrowser } from '../auth/token-refresh.js';
 // ─────────────────────────────────────────────────────────────────────────────
@@ -100,8 +100,8 @@ export function requireCalendarAuth() {
 import { DEFAULT_TEAMS_BASE_URL } from './api-config.js';
 /** Default region when session config is unavailable. */
 const DEFAULT_REGION = 'amer';
-/** Cached region config to avoid repeated localStorage parsing. */
-let cachedRegionConfig = null;
+/** Cached region config (undefined = not yet extracted, null = extraction failed). */
+let cachedRegionConfig = undefined;
 /**
  * Gets the user's region from session, with caching.
  *
@@ -109,7 +109,7 @@ let cachedRegionConfig = null;
  * Falls back to 'amer' if not available (shouldn't happen with valid session).
  */
 export function getRegion() {
-    if (!cachedRegionConfig) {
+    if (cachedRegionConfig === undefined) {
         cachedRegionConfig = extractRegionConfig();
     }
     return cachedRegionConfig?.region ?? DEFAULT_REGION;
@@ -122,7 +122,7 @@ export function getRegion() {
  * Falls back to default if config not available.
  */
 export function getTeamsBaseUrl() {
-    if (!cachedRegionConfig) {
+    if (cachedRegionConfig === undefined) {
         cachedRegionConfig = extractRegionConfig();
     }
     return cachedRegionConfig?.teamsBaseUrl ?? DEFAULT_TEAMS_BASE_URL;
@@ -133,15 +133,36 @@ export function getTeamsBaseUrl() {
  * Returns null if no valid session - caller should handle auth error.
  */
 export function getRegionConfig() {
-    if (!cachedRegionConfig) {
+    if (cachedRegionConfig === undefined) {
         cachedRegionConfig = extractRegionConfig();
     }
     return cachedRegionConfig;
 }
 /**
- * Clears the cached region config.
+ * Clears the cached region config and tenant ID.
  * Call this after login/logout to pick up new session.
  */
 export function clearRegionCache() {
-    cachedRegionConfig = null;
+    cachedRegionConfig = undefined;
+    cachedTenantId = undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tenant ID
+// ─────────────────────────────────────────────────────────────────────────────
+/** Cached tenant ID (undefined = not yet extracted, null = extraction failed). */
+let cachedTenantId = undefined;
+/**
+ * Gets the tenant ID from the user's session (JWT tokens).
+ *
+ * Required for building reliable Teams deep links.
+ * Returns null if no valid session is available.
+ */
+export function getTenantId() {
+    if (cachedTenantId !== undefined) {
+        return cachedTenantId;
+    }
+    const profile = getUserProfile();
+    const tid = profile?.tenantId ?? null;
+    cachedTenantId = tid;
+    return tid;
 }

package/dist/utils/parsers.d.ts

@@ -47,17 +47,33 @@ export declare function stripHtml(html: string): string;
  * - Group chats: 19:xxx@thread.v2 (non-meeting)
  */
 export declare function getConversationType(conversationId: string): 'channel' | 'meeting' | 'chat';
+/** Options for building a message deep link. */
+export interface MessageLinkOptions {
+    /** The conversation/channel/chat ID (e.g., "19:xxx@thread.tacv2"). */
+    conversationId: string;
+    /** The message timestamp in epoch milliseconds. */
+    messageId: string | number;
+    /** Tenant ID (GUID) - required for reliable deep links. */
+    tenantId?: string;
+    /** For channel messages: the team's group ID (GUID). */
+    groupId?: string;
+    /** For channel messages: the parent/root message ID (epoch ms). If omitted for channels, messageId is used. */
+    parentMessageId?: string;
+    /** Teams base URL (for GCC/GCC-High support). */
+    teamsBaseUrl?: string;
+}
 /**
  * Builds a deep link to open a message in Teams.
  *
- * Different conversation types require different URL formats:
- * - Channels: /l/message/{channelId}/{msgId}?parentMessageId={parentId} (for thread replies)
- * - Chats/Meetings: /l/message/{chatId}/{msgId}?context={"contextType":"chat"}
+ * Uses Microsoft's documented deep link formats:
+ * - Channels: /l/message/{channelId}/{msgId}?tenantId=...&groupId=...&parentMessageId=...
+ * - Chats/Meetings: /l/message/{chatId}/{msgId}?tenantId=...&context={"contextType":"chat"}
  *
- * @param conversationId - The conversation/thread ID (e.g., "19:xxx@thread.tacv2")
- * @param messageTimestamp - The message timestamp in epoch milliseconds
- * @param parentMessageId - For channel thread replies, the ID of the parent/root message
- * @param teamsBaseUrl - Optional Teams base URL (for GCC/GCC-High support)
+ * @see https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/deep-link-teams
+ */
+export declare function buildMessageLink(opts: MessageLinkOptions): string;
+/**
+ * @deprecated Use the options object overload instead.
  */
 export declare function buildMessageLink(conversationId: string, messageTimestamp: string | number, parentMessageId?: string, teamsBaseUrl?: string): string;
 /**
@@ -77,10 +93,17 @@ export declare function extractMessageTimestamp(source: Record<string, unknown>
  * - Base64-encoded GUID: "93qkaTtFGWpUHjyRafgdhg=="
  */
 export declare function parsePersonSuggestion(item: Record<string, unknown>): PersonSearchResult | null;
+/** Context for building reliable message deep links. */
+export interface LinkContext {
+    /** Tenant ID (GUID) from session. */
+    tenantId?: string;
+    /** Teams base URL (for GCC/GCC-High support). */
+    teamsBaseUrl?: string;
+}
 /**
  * Parses a v2 query result item into a search result.
  */
-export declare function parseV2Result(item: Record<string, unknown>): TeamsSearchResult | null;
+export declare function parseV2Result(item: Record<string, unknown>, linkContext?: LinkContext): TeamsSearchResult | null;
 /**
  * Parses user profile from a JWT payload.
  *
@@ -106,7 +129,7 @@ export declare function calculateTokenStatus(expiryMs: number, nowMs?: number):
  * @param entitySets - Raw EntitySets array from API response
  * @returns Parsed results and total count if available
  */
-export declare function parseSearchResults(entitySets: unknown[] | undefined): {
+export declare function parseSearchResults(entitySets: unknown[] | undefined, linkContext?: LinkContext): {
     results: TeamsSearchResult[];
     total?: number;
 };
@@ -265,7 +288,7 @@ export interface VirtualConversationItem {
  * @param referencePattern - Regex to extract source ID from secondaryReferenceId
  * @returns Parsed virtual conversation item, or null if message should be skipped
  */
-export declare function parseVirtualConversationMessage(msg: Record<string, unknown>, referencePattern: RegExp): VirtualConversationItem | null;
+export declare function parseVirtualConversationMessage(msg: Record<string, unknown>, referencePattern: RegExp, linkContext?: LinkContext): VirtualConversationItem | null;
 /** A single entry from a meeting transcript. */
 export interface TranscriptEntry {
     /** Start time (e.g., "00:00:22.287"). */

package/dist/utils/parsers.js

@@ -59,32 +59,44 @@ export function getConversationType(conversationId) {
 }
 /** Default Teams base URL for message links. */
 const DEFAULT_TEAMS_LINK_BASE = 'https://teams.microsoft.com';
-/**
- * Builds a deep link to open a message in Teams.
- *
- * Different conversation types require different URL formats:
- * - Channels: /l/message/{channelId}/{msgId}?parentMessageId={parentId} (for thread replies)
- * - Chats/Meetings: /l/message/{chatId}/{msgId}?context={"contextType":"chat"}
- *
- * @param conversationId - The conversation/thread ID (e.g., "19:xxx@thread.tacv2")
- * @param messageTimestamp - The message timestamp in epoch milliseconds
- * @param parentMessageId - For channel thread replies, the ID of the parent/root message
- * @param teamsBaseUrl - Optional Teams base URL (for GCC/GCC-High support)
- */
-export function buildMessageLink(conversationId, messageTimestamp, parentMessageId, teamsBaseUrl = DEFAULT_TEAMS_LINK_BASE) {
-    const timestamp = typeof messageTimestamp === 'string' ? messageTimestamp : String(messageTimestamp);
-    const linkUrl = `${teamsBaseUrl}/l/message/${encodeURIComponent(conversationId)}/${timestamp}`;
-    const convType = getConversationType(conversationId);
-    // Chats and meetings require the context parameter
-    if (convType === 'chat' || convType === 'meeting') {
-        const context = encodeURIComponent('{"contextType":"chat"}');
-        return `${linkUrl}?context=${context}`;
-    }
-    // Channel messages - add parentMessageId for thread replies
-    if (convType === 'channel' && parentMessageId && parentMessageId !== timestamp) {
-        return `${linkUrl}?parentMessageId=${parentMessageId}`;
-    }
-    return linkUrl;
+export function buildMessageLink(optsOrConversationId, messageTimestamp, parentMessageId, teamsBaseUrl) {
+    // Normalise arguments: support both old positional and new options-object signatures
+    let opts;
+    if (typeof optsOrConversationId === 'string') {
+        opts = {
+            conversationId: optsOrConversationId,
+            messageId: messageTimestamp,
+            parentMessageId,
+            teamsBaseUrl,
+        };
+    }
+    else {
+        opts = optsOrConversationId;
+    }
+    const base = opts.teamsBaseUrl ?? DEFAULT_TEAMS_LINK_BASE;
+    const msgId = typeof opts.messageId === 'string' ? opts.messageId : String(opts.messageId);
+    const convType = getConversationType(opts.conversationId);
+    // Build the base URL path — encode the conversationId for URL safety
+    const linkUrl = `${base}/l/message/${encodeURIComponent(opts.conversationId)}/${msgId}`;
+    const params = new URLSearchParams();
+    if (convType === 'channel') {
+        // Channel deep links require tenantId, groupId, and parentMessageId
+        if (opts.tenantId)
+            params.set('tenantId', opts.tenantId);
+        if (opts.groupId)
+            params.set('groupId', opts.groupId);
+        // parentMessageId is always required — for top-level posts it equals the messageId
+        params.set('parentMessageId', opts.parentMessageId ?? msgId);
+        params.set('createdTime', msgId);
+    }
+    else {
+        // Chat and meeting deep links require tenantId and context
+        if (opts.tenantId)
+            params.set('tenantId', opts.tenantId);
+        params.set('context', '{"contextType":"chat"}');
+    }
+    const qs = params.toString();
+    return qs ? `${linkUrl}?${qs}` : linkUrl;
 }
 /**
  * Extracts a timestamp-based message ID from various sources.
@@ -170,7 +182,7 @@ export function parsePersonSuggestion(item) {
 /**
  * Parses a v2 query result item into a search result.
  */
-export function parseV2Result(item) {
+export function parseV2Result(item, linkContext) {
     const content = item.HitHighlightedSummary ||
         item.Summary ||
         '';
@@ -235,7 +247,13 @@ export function parseV2Result(item) {
     // Build message link if we have the required data
     let messageLink;
     if (conversationId && messageTimestamp) {
-        messageLink = buildMessageLink(conversationId, messageTimestamp, parentMessageId);
+        messageLink = buildMessageLink({
+            conversationId,
+            messageId: messageTimestamp,
+            tenantId: linkContext?.tenantId,
+            parentMessageId,
+            teamsBaseUrl: linkContext?.teamsBaseUrl,
+        });
     }
     return {
         id,
@@ -317,7 +335,7 @@ export function calculateTokenStatus(expiryMs, nowMs = Date.now()) {
  * @param entitySets - Raw EntitySets array from API response
  * @returns Parsed results and total count if available
  */
-export function parseSearchResults(entitySets) {
+export function parseSearchResults(entitySets, linkContext) {
     const results = [];
     let total;
     if (!Array.isArray(entitySets)) {
@@ -337,7 +355,7 @@ export function parseSearchResults(entitySets) {
                 const items = rs.Results;
                 if (Array.isArray(items)) {
                     for (const item of items) {
-                        const parsed = parseV2Result(item);
+                        const parsed = parseV2Result(item, linkContext);
                         if (parsed)
                             results.push(parsed);
                     }
@@ -829,7 +847,7 @@ export function hasMarkdownFormatting(text) {
  * @param referencePattern - Regex to extract source ID from secondaryReferenceId
  * @returns Parsed virtual conversation item, or null if message should be skipped
  */
-export function parseVirtualConversationMessage(msg, referencePattern) {
+export function parseVirtualConversationMessage(msg, referencePattern, linkContext) {
     // Skip non-message types
     const messageType = msg.messagetype || msg.type;
     if (!messageType || messageType.startsWith('Control/')) {
@@ -859,7 +877,12 @@ export function parseVirtualConversationMessage(msg, referencePattern) {
     }
     // Build message link to original message
     const messageLink = sourceConversationId && sourceReferenceId
-        ? buildMessageLink(sourceConversationId, sourceReferenceId)
+        ? buildMessageLink({
+            conversationId: sourceConversationId,
+            messageId: sourceReferenceId,
+            tenantId: linkContext?.tenantId,
+            teamsBaseUrl: linkContext?.teamsBaseUrl,
+        })
         : undefined;
     // Extract links before stripping HTML
     const links = extractLinks(content);

package/dist/utils/parsers.test.js

@@ -91,9 +91,11 @@ describe('getConversationType', () => {
     });
 });
 describe('buildMessageLink', () => {
-    it('builds channel link without context parameter', () => {
+    it('builds channel link with parentMessageId and createdTime', () => {
+        // Channel links always include parentMessageId (defaults to messageId for top-level posts)
         const link = buildMessageLink('19:abc@thread.tacv2', '1705760000000');
-        expect(link).toBe('https://teams.microsoft.com/l/message/19%3Aabc%40thread.tacv2/1705760000000');
+        expect(link).toContain('parentMessageId=1705760000000');
+        expect(link).toContain('createdTime=1705760000000');
         expect(link).not.toContain('context');
     });
     it('builds chat link with context parameter', () => {
@@ -111,17 +113,47 @@ describe('buildMessageLink', () => {
     it('builds channel thread reply link with parentMessageId', () => {
         // Thread reply: message timestamp differs from parent
         const link = buildMessageLink('19:abc@thread.tacv2', '1705770000000', '1705760000000');
-        expect(link).toBe('https://teams.microsoft.com/l/message/19%3Aabc%40thread.tacv2/1705770000000?parentMessageId=1705760000000');
+        expect(link).toContain('parentMessageId=1705760000000');
+        expect(link).toContain('createdTime=1705770000000');
     });
-    it('omits parentMessageId for top-level channel posts', () => {
-        // Top-level post: message timestamp equals parent (or no parent)
-        const link = buildMessageLink('19:abc@thread.tacv2', '1705760000000', '1705760000000');
-        expect(link).not.toContain('parentMessageId');
+    it('includes parentMessageId for top-level channel posts (defaults to messageId)', () => {
+        // Per MS docs, parentMessageId is always required for channel links
+        const link = buildMessageLink('19:abc@thread.tacv2', '1705760000000');
+        expect(link).toContain('parentMessageId=1705760000000');
     });
     it('encodes special characters in conversation ID', () => {
         const link = buildMessageLink('19:special@thread.tacv2', '123');
         expect(link).toContain('19%3Aspecial%40thread.tacv2');
     });
+    it('builds channel link with tenantId and groupId via options object', () => {
+        const link = buildMessageLink({
+            conversationId: '19:abc@thread.tacv2',
+            messageId: '1705760000000',
+            tenantId: '0d9b645f-597b-41f0-a2a3-ef103fbd91bb',
+            groupId: '3606f714-ec2e-41b3-9ad1-6afb331bd35d',
+        });
+        expect(link).toContain('tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb');
+        expect(link).toContain('groupId=3606f714-ec2e-41b3-9ad1-6afb331bd35d');
+        expect(link).toContain('parentMessageId=1705760000000');
+        expect(link).toContain('createdTime=1705760000000');
+    });
+    it('builds chat link with tenantId via options object', () => {
+        const link = buildMessageLink({
+            conversationId: '19:guid1_guid2@unq.gbl.spaces',
+            messageId: '1705760000000',
+            tenantId: '0d9b645f-597b-41f0-a2a3-ef103fbd91bb',
+        });
+        expect(link).toContain('tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb');
+        expect(link).toContain('context=%7B%22contextType%22%3A%22chat%22%7D');
+    });
+    it('uses custom teamsBaseUrl for GCC support', () => {
+        const link = buildMessageLink({
+            conversationId: '19:guid1_guid2@unq.gbl.spaces',
+            messageId: '1705760000000',
+            teamsBaseUrl: 'https://teams.microsoft.us',
+        });
+        expect(link.startsWith('https://teams.microsoft.us/l/message/')).toBe(true);
+    });
 });
 describe('extractMessageTimestamp', () => {
     it('extracts from MessageId field', () => {
@@ -252,11 +284,13 @@ describe('parseV2Result', () => {
         // The message's own timestamp (from DateTimeReceived 2026-01-20T15:00:00.000Z)
         expect(result.messageLink).toContain('/1768921200000');
     });
-    it('generates messageLink without parentMessageId for top-level posts', () => {
+    it('generates messageLink with parentMessageId for top-level channel posts', () => {
         const result = parseV2Result(searchResultItem);
         expect(result).not.toBeNull();
-        // Top-level post: messageid matches the message timestamp, so no parentMessageId needed
-        expect(result.messageLink).not.toContain('parentMessageId');
+        // Top-level post: parentMessageId equals the message's own timestamp
+        // Per MS docs, parentMessageId is always required for channel links
+        expect(result.messageLink).toContain('parentMessageId=1768919400000');
+        expect(result.messageLink).toContain('createdTime=1768919400000');
     });
     it('generates messageLink with context for meeting chats', () => {
         const result = parseV2Result(searchResultWithHtml);

package/package.json

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