msteams-mcp 0.2.0 → 0.3.0

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

@@ -76,6 +76,30 @@ export declare const DeleteMessageInputSchema: z.ZodObject<{
     conversationId: string;
     messageId: string;
 }>;
+export declare const GetUnreadInputSchema: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    conversationId?: string | undefined;
+}, {
+    conversationId?: string | undefined;
+}>;
+export declare const MarkAsReadInputSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    messageId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    conversationId: string;
+    messageId: string;
+}, {
+    conversationId: string;
+    messageId: string;
+}>;
+export declare const GetActivityInputSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+}, {
+    limit?: number | undefined;
+}>;
 export declare const sendMessageTool: RegisteredTool<typeof SendMessageInputSchema>;
 export declare const replyToThreadTool: RegisteredTool<typeof ReplyToThreadInputSchema>;
 export declare const getFavoritesTool: RegisteredTool<z.ZodObject<Record<string, never>>>;
@@ -86,6 +110,9 @@ export declare const unsaveMessageTool: RegisteredTool<typeof SaveMessageInputSc
 export declare const getChatTool: RegisteredTool<typeof GetChatInputSchema>;
 export declare const editMessageTool: RegisteredTool<typeof EditMessageInputSchema>;
 export declare const deleteMessageTool: RegisteredTool<typeof DeleteMessageInputSchema>;
+export declare const getUnreadTool: RegisteredTool<typeof GetUnreadInputSchema>;
+export declare const markAsReadTool: RegisteredTool<typeof MarkAsReadInputSchema>;
+export declare const getActivityTool: RegisteredTool<typeof GetActivityInputSchema>;
 /** All message-related tools. */
 export declare const messageTools: (RegisteredTool<z.ZodObject<{
     content: z.ZodString;
@@ -136,4 +163,16 @@ export declare const messageTools: (RegisteredTool<z.ZodObject<{
     userId: string;
 }, {
     userId: string;
+}>> | RegisteredTool<z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    conversationId?: string | undefined;
+}, {
+    conversationId?: string | undefined;
+}>> | RegisteredTool<z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+}, {
+    limit?: number | undefined;
 }>>)[];

package/dist/tools/message-tools.js

@@ -2,9 +2,10 @@
  * Messaging-related tool handlers.
  */
 import { z } from 'zod';
-import { sendMessage, sendNoteToSelf, replyToThread, saveMessage, unsaveMessage, getOneOnOneChatId, editMessage, deleteMessage, } from '../api/chatsvc-api.js';
+import { sendMessage, sendNoteToSelf, replyToThread, saveMessage, unsaveMessage, getOneOnOneChatId, editMessage, deleteMessage, getUnreadStatus, markAsRead, getActivityFeed, } from '../api/chatsvc-api.js';
 import { getFavorites, addFavorite, removeFavorite } from '../api/csa-api.js';
-import { SELF_CHAT_ID } from '../constants.js';
+import { SELF_CHAT_ID, MAX_UNREAD_AGGREGATE_CHECK } from '../constants.js';
+import { ErrorCode } from '../types/errors.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // Schemas
 // ─────────────────────────────────────────────────────────────────────────────
@@ -37,6 +38,16 @@ export const DeleteMessageInputSchema = z.object({
     conversationId: z.string().min(1, 'Conversation ID cannot be empty'),
     messageId: z.string().min(1, 'Message ID cannot be empty'),
 });
+export const GetUnreadInputSchema = z.object({
+    conversationId: z.string().optional(),
+});
+export const MarkAsReadInputSchema = z.object({
+    conversationId: z.string().min(1, 'Conversation ID cannot be empty'),
+    messageId: z.string().min(1, 'Message ID cannot be empty'),
+});
+export const GetActivityInputSchema = z.object({
+    limit: z.number().min(1).max(200).optional(),
+});
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Definitions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -210,6 +221,50 @@ const deleteMessageToolDefinition = {
         required: ['conversationId', 'messageId'],
     },
 };
+const getUnreadToolDefinition = {
+    name: 'teams_get_unread',
+    description: 'Get unread message status. Without parameters, returns aggregate unread counts across all favourite/pinned conversations. With a conversationId, returns unread status for that specific conversation.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            conversationId: {
+                type: 'string',
+                description: 'Optional. A specific conversation ID to check. If omitted, checks all favourites.',
+            },
+        },
+    },
+};
+const markAsReadToolDefinition = {
+    name: 'teams_mark_read',
+    description: 'Mark a conversation as read up to a specific message. This updates your read position so messages up to (and including) the specified message are marked as read.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            conversationId: {
+                type: 'string',
+                description: 'The conversation ID to mark as read',
+            },
+            messageId: {
+                type: 'string',
+                description: 'The message ID to mark as read up to (all messages up to this point will be marked read)',
+            },
+        },
+        required: ['conversationId', 'messageId'],
+    },
+};
+const getActivityToolDefinition = {
+    name: 'teams_get_activity',
+    description: 'Get the user\'s activity feed - mentions, reactions, replies, and other notifications. Returns recent activity items with sender, content, and source conversation context.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: {
+                type: 'number',
+                description: 'Maximum number of activity items to return (default: 50, max: 200)',
+            },
+        },
+    },
+};
 // ─────────────────────────────────────────────────────────────────────────────
 // Handlers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -365,6 +420,108 @@ async function handleDeleteMessage(input, _ctx) {
         },
     };
 }
+async function handleGetUnread(input, _ctx) {
+    // If a specific conversation is provided, just check that one
+    if (input.conversationId) {
+        const result = await getUnreadStatus(input.conversationId);
+        if (!result.ok) {
+            return { success: false, error: result.error };
+        }
+        return {
+            success: true,
+            data: {
+                conversationId: result.value.conversationId,
+                unreadCount: result.value.unreadCount,
+                lastReadMessageId: result.value.lastReadMessageId,
+                latestMessageId: result.value.latestMessageId,
+            },
+        };
+    }
+    // Aggregate mode: check all favourites
+    const favResult = await getFavorites();
+    if (!favResult.ok) {
+        return { success: false, error: favResult.error };
+    }
+    const favorites = favResult.value.favorites;
+    const conversations = [];
+    let totalUnread = 0;
+    let checkedCount = 0;
+    let errorCount = 0;
+    // Check unread status for each favourite (limit to prevent timeout)
+    const maxToCheck = MAX_UNREAD_AGGREGATE_CHECK;
+    for (const fav of favorites.slice(0, maxToCheck)) {
+        const unreadResult = await getUnreadStatus(fav.conversationId);
+        checkedCount++;
+        if (unreadResult.ok) {
+            if (unreadResult.value.unreadCount > 0) {
+                conversations.push({
+                    conversationId: fav.conversationId,
+                    displayName: fav.displayName,
+                    conversationType: fav.conversationType,
+                    unreadCount: unreadResult.value.unreadCount,
+                });
+                totalUnread += unreadResult.value.unreadCount;
+            }
+        }
+        else {
+            errorCount++;
+        }
+    }
+    // If all checks failed, return an error rather than misleading success
+    if (checkedCount > 0 && errorCount === checkedCount) {
+        return {
+            success: false,
+            error: {
+                code: ErrorCode.API_ERROR,
+                message: `Failed to check unread status for all ${checkedCount} favourites`,
+                retryable: true,
+                suggestions: ['Check authentication status with teams_status', 'Try teams_login to refresh session'],
+            },
+        };
+    }
+    return {
+        success: true,
+        data: {
+            totalUnread,
+            conversationsWithUnread: conversations.length,
+            conversations,
+            checked: checkedCount,
+            totalFavorites: favorites.length,
+            errors: errorCount > 0 ? errorCount : undefined,
+            note: favorites.length > maxToCheck
+                ? `Checked first ${maxToCheck} of ${favorites.length} favourites`
+                : undefined,
+        },
+    };
+}
+async function handleMarkAsRead(input, _ctx) {
+    const result = await markAsRead(input.conversationId, input.messageId);
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            message: 'Conversation marked as read',
+            conversationId: result.value.conversationId,
+            markedUpTo: result.value.markedUpTo,
+        },
+    };
+}
+async function handleGetActivity(input, _ctx) {
+    const result = await getActivityFeed({ limit: input.limit });
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        data: {
+            count: result.value.activities.length,
+            activities: result.value.activities,
+            syncState: result.value.syncState,
+        },
+    };
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Exports
 // ─────────────────────────────────────────────────────────────────────────────
@@ -418,6 +575,21 @@ export const deleteMessageTool = {
     schema: DeleteMessageInputSchema,
     handler: handleDeleteMessage,
 };
+export const getUnreadTool = {
+    definition: getUnreadToolDefinition,
+    schema: GetUnreadInputSchema,
+    handler: handleGetUnread,
+};
+export const markAsReadTool = {
+    definition: markAsReadToolDefinition,
+    schema: MarkAsReadInputSchema,
+    handler: handleMarkAsRead,
+};
+export const getActivityTool = {
+    definition: getActivityToolDefinition,
+    schema: GetActivityInputSchema,
+    handler: handleGetActivity,
+};
 /** All message-related tools. */
 export const messageTools = [
     sendMessageTool,
@@ -430,4 +602,7 @@ export const messageTools = [
     getChatTool,
     editMessageTool,
     deleteMessageTool,
+    getUnreadTool,
+    markAsReadTool,
+    getActivityTool,
 ];

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

@@ -7,8 +7,8 @@ export declare const SearchPeopleInputSchema: z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
-    query: string;
     limit: number;
+    query: string;
 }, {
     query: string;
     limit?: number | undefined;
@@ -32,8 +32,8 @@ export declare const peopleTools: (RegisteredTool<z.ZodObject<Record<string, nev
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
-    query: string;
     limit: number;
+    query: string;
 }, {
     query: string;
     limit?: number | undefined;

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

@@ -22,19 +22,22 @@ export declare const SearchInputSchema: z.ZodObject<{
 export declare const GetThreadInputSchema: z.ZodObject<{
     conversationId: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    markRead: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     conversationId: string;
     limit: number;
+    markRead: boolean;
 }, {
     conversationId: string;
     limit?: number | undefined;
+    markRead?: boolean | undefined;
 }>;
 export declare const FindChannelInputSchema: z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
-    query: string;
     limit: number;
+    query: string;
 }, {
     query: string;
     limit?: number | undefined;
@@ -61,18 +64,21 @@ export declare const searchTools: (RegisteredTool<z.ZodObject<{
 }>> | RegisteredTool<z.ZodObject<{
     conversationId: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    markRead: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     conversationId: string;
     limit: number;
+    markRead: boolean;
 }, {
     conversationId: string;
     limit?: number | undefined;
+    markRead?: boolean | undefined;
 }>> | RegisteredTool<z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
-    query: string;
     limit: number;
+    query: string;
 }, {
     query: string;
     limit?: number | undefined;

package/dist/tools/search-tools.js

@@ -3,7 +3,7 @@
  */
 import { z } from 'zod';
 import { searchMessages, searchChannels } from '../api/substrate-api.js';
-import { getThreadMessages } from '../api/chatsvc-api.js';
+import { getThreadMessages, getConsumptionHorizon, markAsRead } from '../api/chatsvc-api.js';
 import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, DEFAULT_THREAD_LIMIT, MAX_THREAD_LIMIT, DEFAULT_CHANNEL_LIMIT, MAX_CHANNEL_LIMIT, } from '../constants.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // Schemas
@@ -17,6 +17,7 @@ export const SearchInputSchema = z.object({
 export const GetThreadInputSchema = z.object({
     conversationId: z.string().min(1, 'Conversation ID cannot be empty'),
     limit: z.number().min(1).max(MAX_THREAD_LIMIT).optional().default(DEFAULT_THREAD_LIMIT),
+    markRead: z.boolean().optional().default(false),
 });
 export const FindChannelInputSchema = z.object({
     query: z.string().min(1, 'Query cannot be empty'),
@@ -53,7 +54,7 @@ const searchToolDefinition = {
 };
 const getThreadToolDefinition = {
     name: 'teams_get_thread',
-    description: 'Get messages from a Teams conversation/thread. Use this to see replies to a message, check thread context, or read recent messages in a chat. Requires a conversationId (available from search results).',
+    description: 'Get messages from a Teams conversation/thread. Use this to see replies to a message, check thread context, or read recent messages in a chat. Requires a conversationId (available from search results). Returns unread count and can optionally mark the conversation as read.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -65,6 +66,10 @@ const getThreadToolDefinition = {
                 type: 'number',
                 description: 'Maximum number of messages to return (default: 50, max: 200)',
             },
+            markRead: {
+                type: 'boolean',
+                description: 'If true, marks the conversation as read up to the latest message after fetching (default: false)',
+            },
         },
         required: ['conversationId'],
     },
@@ -123,11 +128,53 @@ async function handleGetThread(input, _ctx) {
     if (!result.ok) {
         return { success: false, error: result.error };
     }
+    // Get unread status
+    let unreadCount;
+    let lastReadMessageId;
+    const horizonResult = await getConsumptionHorizon(input.conversationId);
+    if (horizonResult.ok) {
+        lastReadMessageId = horizonResult.value.lastReadMessageId;
+        // Count messages after last read
+        if (lastReadMessageId) {
+            let foundLastRead = false;
+            unreadCount = 0;
+            for (const msg of result.value.messages) {
+                if (msg.id === lastReadMessageId) {
+                    foundLastRead = true;
+                    continue;
+                }
+                if (foundLastRead && !msg.isFromMe) {
+                    unreadCount++;
+                }
+            }
+            // If last read message wasn't found, it's older than our window - all messages are unread
+            if (!foundLastRead) {
+                unreadCount = result.value.messages.filter(m => !m.isFromMe).length;
+            }
+        }
+        else {
+            // No consumption horizon means all messages are unread (new conversation)
+            unreadCount = result.value.messages.filter(m => !m.isFromMe).length;
+        }
+    }
+    // Mark as read if requested
+    let markedAsRead = false;
+    if (input.markRead && result.value.messages.length > 0) {
+        // Find the latest message
+        const latestMessage = result.value.messages[result.value.messages.length - 1];
+        if (latestMessage) {
+            const markResult = await markAsRead(input.conversationId, latestMessage.id);
+            markedAsRead = markResult.ok;
+        }
+    }
     return {
         success: true,
         data: {
             conversationId: result.value.conversationId,
             messageCount: result.value.messages.length,
+            unreadCount,
+            lastReadMessageId,
+            markedAsRead: input.markRead ? markedAsRead : undefined,
             messages: result.value.messages,
         },
     };

package/dist/utils/api-config.d.ts

@@ -46,6 +46,12 @@ export declare const CHATSVC_API: {
     readonly editMessage: (region: Region, conversationId: string, messageId: string) => string;
     /** Delete a specific message URL (soft delete). */
     readonly deleteMessage: (region: Region, conversationId: string, messageId: string) => string;
+    /** Get consumption horizons (read receipts) for a thread. */
+    readonly consumptionHorizons: (region: Region, threadId: string) => string;
+    /** Update consumption horizon (mark as read) for a conversation. */
+    readonly updateConsumptionHorizon: (region: Region, conversationId: string) => string;
+    /** Activity feed (notifications) messages. */
+    readonly activityFeed: (region: Region) => string;
 };
 /** CSA (Chat Service Aggregator) API endpoints. */
 export declare const CSA_API: {

package/dist/utils/api-config.js

@@ -3,6 +3,7 @@
  *
  * Centralises all API URLs and common request headers.
  */
+import { NOTIFICATIONS_ID } from '../constants.js';
 /** Valid API regions. */
 export const VALID_REGIONS = ['amer', 'emea', 'apac'];
 /**
@@ -64,6 +65,12 @@ export const CHATSVC_API = {
     editMessage: (region, conversationId, messageId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages/${messageId}`,
     /** Delete a specific message URL (soft delete). */
     deleteMessage: (region, conversationId, messageId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages/${messageId}?behavior=softDelete`,
+    /** Get consumption horizons (read receipts) for a thread. */
+    consumptionHorizons: (region, threadId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/threads/${encodeURIComponent(threadId)}/consumptionhorizons`,
+    /** Update consumption horizon (mark as read) for a conversation. */
+    updateConsumptionHorizon: (region, conversationId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/properties?name=consumptionhorizon`,
+    /** Activity feed (notifications) messages. */
+    activityFeed: (region) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(NOTIFICATIONS_ID)}/messages`,
 };
 /** CSA (Chat Service Aggregator) API endpoints. */
 export const CSA_API = {

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

@@ -17,6 +17,13 @@ export interface CsaAuthInfo {
  * Use for search and people APIs.
  */
 export declare function requireSubstrateToken(): Result<string, McpError>;
+/**
+ * Requires a valid Substrate token with proactive refresh.
+ *
+ * This async version attempts to refresh tokens if they're approaching
+ * expiry (within 10 minutes). Use this in tool handlers for better UX.
+ */
+export declare function requireSubstrateTokenAsync(): Promise<Result<string, McpError>>;
 /**
  * Requires valid message authentication.
  * Use for chatsvc messaging APIs.

package/dist/utils/auth-guards.js

@@ -6,7 +6,9 @@
  */
 import { ErrorCode, createError } from '../types/errors.js';
 import { err, ok } from '../types/result.js';
-import { getValidSubstrateToken, extractMessageAuth, extractCsaToken, } from '../auth/token-extractor.js';
+import { getValidSubstrateToken, extractMessageAuth, extractCsaToken, extractSubstrateToken, } from '../auth/token-extractor.js';
+import { TOKEN_REFRESH_THRESHOLD_MS } from '../constants.js';
+import { refreshTokensViaBrowser } from '../auth/token-refresh.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // Error Messages
 // ─────────────────────────────────────────────────────────────────────────────
@@ -29,6 +31,45 @@ export function requireSubstrateToken() {
     }
     return ok(token);
 }
+/**
+ * Checks if the Substrate token is approaching expiry and needs refresh.
+ *
+ * @returns true if token will expire within the refresh threshold
+ */
+function shouldRefreshSubstrateToken() {
+    const substrate = extractSubstrateToken();
+    if (!substrate)
+        return false;
+    const timeRemaining = substrate.expiry.getTime() - Date.now();
+    return timeRemaining > 0 && timeRemaining < TOKEN_REFRESH_THRESHOLD_MS;
+}
+/**
+ * Requires a valid Substrate token with proactive refresh.
+ *
+ * This async version attempts to refresh tokens if they're approaching
+ * expiry (within 10 minutes). Use this in tool handlers for better UX.
+ */
+export async function requireSubstrateTokenAsync() {
+    // Check if we need to refresh proactively
+    if (shouldRefreshSubstrateToken()) {
+        const refreshResult = await refreshTokensViaBrowser();
+        if (refreshResult.ok) {
+            // Refresh succeeded, get the new token
+            const token = getValidSubstrateToken();
+            if (token) {
+                return ok(token);
+            }
+        }
+        // Refresh failed but token might still be valid, continue
+    }
+    // Try to get existing token
+    const token = getValidSubstrateToken();
+    if (!token) {
+        // Token expired and refresh not available/failed
+        return err(createError(ErrorCode.AUTH_EXPIRED, 'Token expired and automatic refresh failed. Please run teams_login to re-authenticate.', { suggestions: ['Call teams_login to re-authenticate'] }));
+    }
+    return ok(token);
+}
 /**
  * Requires valid message authentication.
  * Use for chatsvc messaging APIs.

package/dist/utils/parsers.d.ts

@@ -185,3 +185,18 @@ export declare function extractObjectId(identifier: string): string | null;
  * @returns The constructed conversation ID, or null if either ID is invalid
  */
 export declare function buildOneOnOneConversationId(userId1: string, userId2: string): string | null;
+/**
+ * Safely extracts a timestamp from an activity feed message.
+ *
+ * Tries multiple sources in order of preference:
+ * 1. originalarrivaltime - Primary timestamp field
+ * 2. composetime - When message was composed
+ * 3. id as numeric timestamp - Fallback if ID is a Unix timestamp
+ *
+ * Returns null if no valid timestamp can be determined, preventing
+ * RangeError from Date operations on invalid values.
+ *
+ * @param msg - Raw message object from activity feed API
+ * @returns ISO timestamp string, or null if no valid timestamp found
+ */
+export declare function extractActivityTimestamp(msg: Record<string, unknown>): string | null;

package/dist/utils/parsers.js

@@ -572,3 +572,34 @@ export function buildOneOnOneConversationId(userId1, userId2) {
     const sorted = [id1, id2].sort();
     return `19:${sorted[0]}_${sorted[1]}@unq.gbl.spaces`;
 }
+/**
+ * Safely extracts a timestamp from an activity feed message.
+ *
+ * Tries multiple sources in order of preference:
+ * 1. originalarrivaltime - Primary timestamp field
+ * 2. composetime - When message was composed
+ * 3. id as numeric timestamp - Fallback if ID is a Unix timestamp
+ *
+ * Returns null if no valid timestamp can be determined, preventing
+ * RangeError from Date operations on invalid values.
+ *
+ * @param msg - Raw message object from activity feed API
+ * @returns ISO timestamp string, or null if no valid timestamp found
+ */
+export function extractActivityTimestamp(msg) {
+    const arrivalTime = msg.originalarrivaltime;
+    const composeTime = msg.composetime;
+    if (arrivalTime)
+        return arrivalTime;
+    if (composeTime)
+        return composeTime;
+    // Try parsing the message ID as a numeric timestamp
+    const id = msg.id;
+    if (id) {
+        const numericId = parseInt(id, 10);
+        if (!isNaN(numericId) && numericId > 0) {
+            return new Date(numericId).toISOString();
+        }
+    }
+    return null;
+}

package/dist/utils/parsers.test.js

@@ -5,7 +5,7 @@
  * produce expected outputs regardless of internal logic.
  */
 import { describe, it, expect } from 'vitest';
-import { stripHtml, buildMessageLink, extractMessageTimestamp, parsePersonSuggestion, parseV2Result, parseJwtProfile, calculateTokenStatus, parseSearchResults, parsePeopleResults, extractObjectId, buildOneOnOneConversationId, decodeBase64Guid, } from './parsers.js';
+import { stripHtml, buildMessageLink, extractMessageTimestamp, parsePersonSuggestion, parseV2Result, parseJwtProfile, calculateTokenStatus, parseSearchResults, parsePeopleResults, extractObjectId, buildOneOnOneConversationId, decodeBase64Guid, extractActivityTimestamp, } from './parsers.js';
 import { searchResultItem, searchResultWithHtml, searchResultMinimal, searchResultTooShort, searchEntitySetsResponse, personSuggestion, personMinimal, personWithBase64Id, peopleGroupsResponse, jwtPayloadFull, jwtPayloadMinimal, jwtPayloadCommaName, jwtPayloadSpaceName, sourceWithMessageId, sourceWithConvIdMessageId, } from '../__fixtures__/api-responses.js';
 describe('stripHtml', () => {
     it('removes HTML tags', () => {
@@ -358,3 +358,57 @@ describe('buildOneOnOneConversationId', () => {
         expect(buildOneOnOneConversationId('', '')).toBeNull();
     });
 });
+describe('extractActivityTimestamp', () => {
+    it('prefers originalarrivaltime when present', () => {
+        const msg = {
+            originalarrivaltime: '2024-01-15T10:30:00.000Z',
+            composetime: '2024-01-15T10:29:00.000Z',
+            id: '1705315800000',
+        };
+        expect(extractActivityTimestamp(msg)).toBe('2024-01-15T10:30:00.000Z');
+    });
+    it('falls back to composetime when originalarrivaltime is missing', () => {
+        const msg = {
+            composetime: '2024-01-15T10:29:00.000Z',
+            id: '1705315800000',
+        };
+        expect(extractActivityTimestamp(msg)).toBe('2024-01-15T10:29:00.000Z');
+    });
+    it('parses numeric id as timestamp when no time fields present', () => {
+        const msg = {
+            id: '1705315800000', // 2024-01-15T10:30:00.000Z
+        };
+        const result = extractActivityTimestamp(msg);
+        expect(result).toBe(new Date(1705315800000).toISOString());
+    });
+    it('returns null for non-numeric id when no time fields present', () => {
+        const msg = {
+            id: 'abc-not-a-number',
+        };
+        expect(extractActivityTimestamp(msg)).toBeNull();
+    });
+    it('returns null for empty message object', () => {
+        expect(extractActivityTimestamp({})).toBeNull();
+    });
+    it('returns null when id is undefined', () => {
+        const msg = {
+            originalarrivaltime: undefined,
+            composetime: undefined,
+        };
+        expect(extractActivityTimestamp(msg)).toBeNull();
+    });
+    it('handles zero id correctly (returns null)', () => {
+        const msg = {
+            id: '0',
+        };
+        // Zero is not a valid timestamp
+        expect(extractActivityTimestamp(msg)).toBeNull();
+    });
+    it('handles negative id correctly (returns null)', () => {
+        const msg = {
+            id: '-1705315800000',
+        };
+        // Negative timestamps are invalid
+        expect(extractActivityTimestamp(msg)).toBeNull();
+    });
+});

package/package.json

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