Teams MCP

Instructions

Implementation Reference

• src/tools/search.ts:447-570 (handler)

  Handler function that retrieves recent mentions of the current user from Microsoft Teams using the Graph Search API. It gets the current user ID, builds a KQL query for mentions within the specified time range, performs the search, applies scope filters, and returns formatted results or error messages.
  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:426-446 (schema)

  Zod schema defining the input parameters for the get_my_mentions tool: hours (number, 1-168, default 24), limit (number, 1-50, default 20), scope (enum: 'all'|'channels'|'chats', default '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"), },
• src/tools/search.ts:423-571 (registration)

  Registration of the 'get_my_mentions' tool via server.tool() call, including the tool name, description, input schema, and inline handler function within the registerSearchTools 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}`, }, ], }; } } );