Teams MCP

Instructions

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;
  }