Teams MCP

Instructions

Implementation Reference

• src/tools/search.ts:151-419 (handler)

  The main execution logic for the 'get_recent_messages' tool. It attempts to use the Microsoft Graph Search API for advanced filtering (keywords, mentions, attachments, importance) and falls back to direct queries on user chats if the search results are poor quality or fail. Supports filtering by time (hours), limit, users, attachments, importance, channels/chats inclusion, teams, and keywords. Returns formatted JSON with message details.
  async ({ hours, limit, mentionsUser, fromUser, hasAttachments, importance, includeChannels, includeChats, teamIds, keywords, }) => { try { const client = await graphService.getClient(); let attemptedAdvancedSearch = false; // Try using the Search API first for rich filtering if (keywords || mentionsUser || hasAttachments !== undefined || importance) { attemptedAdvancedSearch = true; // Calculate the date threshold const since = new Date(Date.now() - hours * 60 * 60 * 1000).toISOString(); // Build KQL query for Microsoft Search API const queryParts: string[] = []; // Add time filter - use a more permissive date format queryParts.push(`sent>=${since.split("T")[0]}`); // Use just the date part // Add user filters if (mentionsUser) { queryParts.push(`mentions:${mentionsUser}`); } if (fromUser) { queryParts.push(`from:${fromUser}`); } // Add content filters if (hasAttachments !== undefined) { queryParts.push(`hasAttachment:${hasAttachments}`); } if (importance) { queryParts.push(`importance:${importance}`); } // Add keyword search if (keywords) { queryParts.push(`"${keywords}"`); } // If no specific filters, search for all recent messages if (queryParts.length === 1) { // Only has the time filter queryParts.push("*"); // Match all messages } const searchQuery = queryParts.join(" AND "); const searchRequest: SearchRequest = { entityTypes: ["chatMessage"], query: { queryString: searchQuery, }, from: 0, size: Math.min(limit, 100), enableTopResults: false, // For recent messages, prefer chronological order }; try { const response = (await client .api("/search/query") .post({ requests: [searchRequest] })) as SearchResponse; if (response?.value?.length && response.value[0]?.hitsContainers?.length) { const hits = response.value[0].hitsContainers[0].hits; const recentMessages = hits .filter((hit) => { // Apply scope filters const isChannelMessage = hit.resource.channelIdentity?.channelId; const isChatMessage = hit.resource.chatId && !isChannelMessage; if (!includeChannels && isChannelMessage) return false; if (!includeChats && isChatMessage) return false; // Apply team filter if specified if (teamIds?.length && isChannelMessage) { return teamIds.includes(hit.resource.channelIdentity?.teamId || ""); } return true; }) .map((hit: SearchHit) => ({ id: hit.resource.id, content: hit.resource.body?.content || "No content", from: hit.resource.from?.user?.displayName || "Unknown", fromUserId: hit.resource.from?.user?.id, createdDateTime: hit.resource.createdDateTime, chatId: hit.resource.chatId, teamId: hit.resource.channelIdentity?.teamId, channelId: hit.resource.channelIdentity?.channelId, type: hit.resource.channelIdentity?.channelId ? "channel" : "chat", })) .slice(0, limit); // Apply final limit after filtering // Check if Search API returned poor quality results (No content/Unknown) const poorQualityResults = recentMessages.filter( (msg) => msg.content === "No content" || msg.from === "Unknown" ).length; const qualityThreshold = 0.5; // If more than 50% of results are poor quality, fall back if ( recentMessages.length > 0 && poorQualityResults / recentMessages.length > qualityThreshold ) { console.log( "Search API returned poor quality results, falling back to direct queries" ); // Fall through to direct chat queries } else { return { content: [ { type: "text", text: JSON.stringify( { method: "search_api", timeRange: `Last ${hours} hours`, filters: { mentionsUser, fromUser, hasAttachments, importance, keywords, }, totalFound: recentMessages.length, messages: recentMessages, }, null, 2 ), }, ], }; } } } catch (searchError) { console.error("Search API failed, falling back to direct queries:", searchError); } } // Fallback: Get recent messages from user's chats directly // This method is more reliable but doesn't support advanced filtering const chatsResponse = await client.api("/me/chats?$expand=members").get(); const chats = chatsResponse?.value || []; const allMessages: Array<{ id: string; content: string; from: string; fromUserId?: string; createdDateTime: string; chatId: string; type: string; }> = []; const since = new Date(Date.now() - hours * 60 * 60 * 1000); // Get recent messages from each chat for (const chat of chats.slice(0, 10)) { // Limit to first 10 chats to avoid rate limits try { let queryString = `$top=${Math.min(limit, 50)}&$orderby=createdDateTime desc`; // Apply user filter if specified if (fromUser) { queryString += `&$filter=from/user/id eq '${fromUser}'`; } const messagesResponse = await client .api(`/me/chats/${chat.id}/messages?${queryString}`) .get(); const messages = messagesResponse?.value || []; for (const message of messages) { // Filter by time if (message.createdDateTime) { const messageDate = new Date(message.createdDateTime); if (messageDate < since) continue; } // Apply scope filter for chats if (!includeChats) { continue; // Skip chat messages if includeChats is false } // Apply keyword filter (simple text search) if ( keywords && message.body?.content && !message.body.content.toLowerCase().includes(keywords.toLowerCase()) ) { continue; } allMessages.push({ id: message.id || "", content: message.body?.content || "No content", from: message.from?.user?.displayName || "Unknown", fromUserId: message.from?.user?.id, createdDateTime: message.createdDateTime || "", chatId: message.chatId || "", type: "chat", }); if (allMessages.length >= limit) break; } if (allMessages.length >= limit) break; } catch (chatError) { console.error(`Error getting messages from chat ${chat.id}:`, chatError); } } // Sort by creation date (newest first) allMessages.sort( (a, b) => new Date(b.createdDateTime).getTime() - new Date(a.createdDateTime).getTime() ); return { content: [ { type: "text", text: JSON.stringify( { method: attemptedAdvancedSearch ? "direct_chat_queries_fallback" : "direct_chat_queries", timeRange: `Last ${hours} hours`, filters: { mentionsUser, fromUser, hasAttachments, importance, keywords, }, note: attemptedAdvancedSearch ? "Search API returned poor quality results, using direct chat queries as fallback" : "Using direct chat queries for better content reliability", totalFound: allMessages.slice(0, limit).length, messages: allMessages.slice(0, limit), }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error getting recent messages: ${errorMessage}`, }, ], }; } }
• src/tools/search.ts:124-150 (schema)

  Zod schema defining input parameters for the tool: hours (1-168, default 24), limit (1-100, default 50), mentionsUser, fromUser, hasAttachments, importance (low/normal/high/urgent), includeChannels (default true), includeChats (default true), teamIds array, keywords.
  { hours: z .number() .min(1) .max(168) .optional() .default(24) .describe("Get messages from the last N hours (max 168 = 1 week)"), limit: z .number() .min(1) .max(100) .optional() .default(50) .describe("Maximum number of messages to return"), mentionsUser: z.string().optional().describe("Filter messages that mention this user ID"), fromUser: z.string().optional().describe("Filter messages from this user ID"), hasAttachments: z.boolean().optional().describe("Filter messages with attachments"), importance: z .enum(["low", "normal", "high", "urgent"]) .optional() .describe("Filter by message importance"), includeChannels: z.boolean().optional().default(true).describe("Include channel messages"), includeChats: z.boolean().optional().default(true).describe("Include chat messages"), teamIds: z.array(z.string()).optional().describe("Specific team IDs to search in"), keywords: z.string().optional().describe("Keywords to search for in message content"), },
• src/tools/search.ts:121-123 (registration)

  Registration of the 'get_recent_messages' tool using server.tool(), including name, description, schema, and handler function.
  server.tool( "get_recent_messages", "Get recent messages from across Teams with advanced filtering options. Can filter by time range, scope (channels vs chats), teams, channels, and users.",