search_users
Find organization members by name or email to retrieve their basic profile details for collaboration and communication.
Instructions
Search for users in the organization by name or email address. Returns matching users with their basic profile information.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (name or email) |
Implementation Reference
- src/tools/users.ts:55-102 (handler)The core handler function for the 'search_users' tool. It uses the GraphService client to query the Microsoft Graph /users endpoint with a filter for displayName, mail, or userPrincipalName starting with the input query. Maps results to UserSummary and returns as JSON text content or error message.async ({ query }) => { try { const client = await graphService.getClient(); const response = (await client .api("/users") .filter( `startswith(displayName,'${query}') or startswith(mail,'${query}') or startswith(userPrincipalName,'${query}')` ) .get()) as GraphApiResponse<User>; if (!response?.value?.length) { return { content: [ { type: "text", text: "No users found matching your search.", }, ], }; } const userList: UserSummary[] = response.value.map((user: User) => ({ displayName: user.displayName, userPrincipalName: user.userPrincipalName, mail: user.mail, id: user.id, })); return { content: [ { type: "text", text: JSON.stringify(userList, null, 2), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error: ${errorMessage}`, }, ], }; } }
- src/tools/users.ts:52-54 (schema)Input schema using Zod, defining a single required 'query' parameter as string for the search term.{ query: z.string().describe("Search query (name or email)"), },
- src/tools/users.ts:49-103 (registration)Registers the 'search_users' tool on the MCP server with name, description, input schema, and handler function within the registerUsersTools function.server.tool( "search_users", "Search for users in the organization by name or email address. Returns matching users with their basic profile information.", { query: z.string().describe("Search query (name or email)"), }, async ({ query }) => { try { const client = await graphService.getClient(); const response = (await client .api("/users") .filter( `startswith(displayName,'${query}') or startswith(mail,'${query}') or startswith(userPrincipalName,'${query}')` ) .get()) as GraphApiResponse<User>; if (!response?.value?.length) { return { content: [ { type: "text", text: "No users found matching your search.", }, ], }; } const userList: UserSummary[] = response.value.map((user: User) => ({ displayName: user.displayName, userPrincipalName: user.userPrincipalName, mail: user.mail, id: user.id, })); return { content: [ { type: "text", text: JSON.stringify(userList, null, 2), }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `❌ Error: ${errorMessage}`, }, ], }; } } );
- src/index.ts:133-133 (registration)Top-level call to register all user tools (including search_users) during MCP server initialization.registerUsersTools(server, graphService);