search_users_for_mentions
Find and retrieve user details for mentions in Microsoft Teams messages by searching names or emails, and obtain display names, email addresses, and mention IDs for effective communication.
Instructions
Search for users to mention in messages. Returns users with their display names, email addresses, and mention IDs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| query | Yes | Search query (name or email) |
Implementation Reference
- src/tools/teams.ts:787-837 (handler)Handler function that calls the searchUsers helper, processes the results by computing mentionText, and returns formatted JSON response or error.async ({ query, limit }) => { try { const users = await searchUsers(graphService, query, limit); if (users.length === 0) { return { content: [ { type: "text", text: `No users found matching "${query}".`, }, ], }; } return { content: [ { type: "text", text: JSON.stringify( { query, totalResults: users.length, users: users.map((user: UserInfo) => ({ id: user.id, displayName: user.displayName, userPrincipalName: user.userPrincipalName, mentionText: user.userPrincipalName?.split("@")[0] || user.displayName.toLowerCase().replace(/\s+/g, ""), })), }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error: ${errorMessage}`, }, ], }; } } );
- src/tools/teams.ts:777-786 (schema)Zod input schema defining parameters for the tool: required 'query' string and optional 'limit' number.{ query: z.string().describe("Search query (name or email)"), limit: z .number() .min(1) .max(50) .optional() .default(10) .describe("Maximum number of results to return"), },
- src/utils/users.ts:13-39 (helper)Core search logic using Microsoft Graph API to query users whose displayName or userPrincipalName starts with the given query.export async function searchUsers( graphService: GraphService, query: string, limit = 10 ): Promise<UserInfo[]> { try { const client = await graphService.getClient(); // Use filter query to search users by displayName or userPrincipalName const searchQuery = `$filter=startswith(displayName,'${query}') or startswith(userPrincipalName,'${query}')&$top=${limit}&$select=id,displayName,userPrincipalName`; const response = await client.api(`/users?${searchQuery}`).get(); if (!response?.value?.length) { return []; } return response.value.map((user: User) => ({ id: user.id || "", displayName: user.displayName || "Unknown User", userPrincipalName: user.userPrincipalName || undefined, })); } catch (error) { console.error("Error searching users:", error); return []; } }
- src/utils/users.ts:4-8 (schema)TypeScript interface defining the UserInfo type returned by searchUsers and used in the tool response.export interface UserInfo { id: string; displayName: string; userPrincipalName?: string; }
- src/tools/teams.ts:773-838 (registration)Registration of the tool with MCP server in registerTeamsTools function, including name, description, input schema, and handler reference.// Search users for @mentions server.tool( "search_users_for_mentions", "Search for users to mention in messages. Returns users with their display names, email addresses, and mention IDs.", { query: z.string().describe("Search query (name or email)"), limit: z .number() .min(1) .max(50) .optional() .default(10) .describe("Maximum number of results to return"), }, async ({ query, limit }) => { try { const users = await searchUsers(graphService, query, limit); if (users.length === 0) { return { content: [ { type: "text", text: `No users found matching "${query}".`, }, ], }; } return { content: [ { type: "text", text: JSON.stringify( { query, totalResults: users.length, users: users.map((user: UserInfo) => ({ id: user.id, displayName: user.displayName, userPrincipalName: user.userPrincipalName, mentionText: user.userPrincipalName?.split("@")[0] || user.displayName.toLowerCase().replace(/\s+/g, ""), })), }, null, 2 ), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error: ${errorMessage}`, }, ], }; } } ); }