search_users_for_mentions
Find users to mention in Microsoft Teams messages by searching names or email addresses. Returns display names, emails, and mention IDs for quick tagging.
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 |
|---|---|---|---|
| query | Yes | Search query (name or email) | |
| limit | No | Maximum number of results to return |
Implementation Reference
- src/tools/teams.ts:787-837 (handler)The main handler function for the 'search_users_for_mentions' tool. It calls the searchUsers helper, processes the results by adding a mentionText field, and returns a 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 the parameters for the tool: required 'query' string and optional 'limit' number (default 10, max 50).{ 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/tools/teams.ts:773-838 (registration)Registration of the 'search_users_for_mentions' tool with the MCP server, including name, description, 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}`, }, ], }; } } ); }
- src/utils/users.ts:13-39 (helper)The core helper function that performs the actual user search via Microsoft Graph API using startswith filter on displayName or userPrincipalName, returning UserInfo array.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 used by searchUsers and returned by the tool handler.export interface UserInfo { id: string; displayName: string; userPrincipalName?: string; }