Teams MCP

Instructions

Implementation Reference

• src/tools/search.ts:423-571 (registration)

  Registration of the 'get_my_mentions' tool using server.tool(), including description, input schema, and handler function.
  server.tool( "get_my_mentions", "Find all recent messages where the current user was mentioned (@mentioned) across Teams channels and chats.", { hours: z .number() .min(1) .max(168) .optional() .default(24) .describe("Get mentions from the last N hours"), limit: z .number() .min(1) .max(50) .optional() .default(20) .describe("Maximum number of mentions to return"), scope: z .enum(["all", "channels", "chats"]) .optional() .default("all") .describe("Scope of search"), }, async ({ hours, limit, scope }) => { try { const client = await graphService.getClient(); // Get current user ID first const me = await client.api("/me").get(); const userId = me?.id; if (!userId) { return { content: [ { type: "text", text: "❌ Error: Could not determine current user ID", }, ], }; } const since = new Date(Date.now() - hours * 60 * 60 * 1000).toISOString(); // Build query to find mentions of current user const queryParts = [ `sent>=${since.split("T")[0]}`, // Use just the date part to avoid time parsing issues `mentions:${userId}`, ]; const searchQuery = queryParts.join(" AND "); const searchRequest: SearchRequest = { entityTypes: ["chatMessage"], query: { queryString: searchQuery, }, from: 0, size: Math.min(limit, 50), enableTopResults: false, }; const response = (await client .api("/search/query") .post({ requests: [searchRequest] })) as SearchResponse; if ( !response?.value?.length || !response.value[0]?.hitsContainers?.length || !response.value[0].hitsContainers[0]?.hits ) { return { content: [ { type: "text", text: "No recent mentions found.", }, ], }; } const hits = response.value[0].hitsContainers[0].hits || []; if (hits.length === 0) { return { content: [ { type: "text", text: "No recent mentions found.", }, ], }; } const mentions = hits .filter((hit) => { // Apply scope filters const isChannelMessage = hit.resource.channelIdentity?.channelId; const isChatMessage = hit.resource.chatId && !isChannelMessage; if (scope === "channels" && !isChannelMessage) return false; if (scope === "chats" && !isChatMessage) return false; return true; }) .map((hit: SearchHit) => ({ id: hit.resource.id, content: hit.resource.body?.content || "No content", summary: hit.summary, 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", })); return { content: [ { type: "text", text: JSON.stringify( { timeRange: `Last ${hours} hours`, mentionedUser: me?.displayName || "Current User", scope, totalMentions: mentions.length, mentions, }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error getting mentions: ${errorMessage}`, }, ], }; } } );
• src/tools/search.ts:447-570 (handler)

  Handler function that fetches recent messages mentioning the current user using Microsoft Graph Search API with KQL query for mentions, filters by scope and time, and returns formatted results.
  async ({ hours, limit, scope }) => { try { const client = await graphService.getClient(); // Get current user ID first const me = await client.api("/me").get(); const userId = me?.id; if (!userId) { return { content: [ { type: "text", text: "❌ Error: Could not determine current user ID", }, ], }; } const since = new Date(Date.now() - hours * 60 * 60 * 1000).toISOString(); // Build query to find mentions of current user const queryParts = [ `sent>=${since.split("T")[0]}`, // Use just the date part to avoid time parsing issues `mentions:${userId}`, ]; const searchQuery = queryParts.join(" AND "); const searchRequest: SearchRequest = { entityTypes: ["chatMessage"], query: { queryString: searchQuery, }, from: 0, size: Math.min(limit, 50), enableTopResults: false, }; const response = (await client .api("/search/query") .post({ requests: [searchRequest] })) as SearchResponse; if ( !response?.value?.length || !response.value[0]?.hitsContainers?.length || !response.value[0].hitsContainers[0]?.hits ) { return { content: [ { type: "text", text: "No recent mentions found.", }, ], }; } const hits = response.value[0].hitsContainers[0].hits || []; if (hits.length === 0) { return { content: [ { type: "text", text: "No recent mentions found.", }, ], }; } const mentions = hits .filter((hit) => { // Apply scope filters const isChannelMessage = hit.resource.channelIdentity?.channelId; const isChatMessage = hit.resource.chatId && !isChannelMessage; if (scope === "channels" && !isChannelMessage) return false; if (scope === "chats" && !isChatMessage) return false; return true; }) .map((hit: SearchHit) => ({ id: hit.resource.id, content: hit.resource.body?.content || "No content", summary: hit.summary, 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", })); return { content: [ { type: "text", text: JSON.stringify( { timeRange: `Last ${hours} hours`, mentionedUser: me?.displayName || "Current User", scope, totalMentions: mentions.length, mentions, }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error getting mentions: ${errorMessage}`, }, ], }; } }
• src/tools/search.ts:427-446 (schema)

  Input schema using Zod for validating parameters: hours (time range), limit (max results), scope (channels/chats/all).
  hours: z .number() .min(1) .max(168) .optional() .default(24) .describe("Get mentions from the last N hours"), limit: z .number() .min(1) .max(50) .optional() .default(20) .describe("Maximum number of mentions to return"), scope: z .enum(["all", "channels", "chats"]) .optional() .default("all") .describe("Scope of search"), },