Teams MCP

Instructions

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