search_users

Instructions

Implementation Reference

• tools/userTools.js:77-129 (handler)

  The core handler function for the 'search_users' tool. It handles input query (with elicitation fallback), searches users in storage by name/email/role, and returns matching users or error messages.

    async (inputs, context) => {
      try {
        let searchQuery = inputs.query;
  
        if (!searchQuery) {
          const elicitationResult = await elicitationHelper.elicitWithProgress(
            "Please enter your search query to find users",
            {
              type: "object",
              properties: {
                query: {
                  type: "string",
                  title: "Search Query",
                  description: "Enter keywords to search for users by name, email, or role"
                }
              },
              required: ["query"]
            },
            inputs
          );
  
          if (elicitationResult.action === "accept" && elicitationResult.content?.query) {
            searchQuery = elicitationResult.content.query;
          } else if (elicitationResult.action === "decline") {
            return utils.createErrorResponse("User declined to provide search query. Search cancelled.");
          } else {
            return utils.createErrorResponse("User cancelled the search process.");
          }
        }
  
        const { storage } = await import('../storage.js');
        const query = searchQuery.toLowerCase();
        
        const matchingUsers = storage.users.filter(user => {
          return (
            user.name?.toLowerCase().includes(query) ||
            user.email?.toLowerCase().includes(query) ||
            user.role?.toLowerCase().includes(query)
          );
        });
  
        if (matchingUsers.length === 0) {
          return utils.createSuccessResponse(`No users found matching query: "${searchQuery}"`);
        }
  
        return utils.createSuccessResponse(
          `Found ${matchingUsers.length} user(s) matching "${searchQuery}":\n${JSON.stringify(matchingUsers, null, 2)}`
        );
      } catch (error) {
        return utils.createErrorResponse(`Error searching users: ${error.message}`);
      }
    }
  );

• tools/userTools.js:68-76 (schema)

  The primary input schema for the 'search_users' tool, defining a required 'query' string parameter.

  {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Search query to find users by name, email, or role"
      }
    }
  },

• tools/userTools.js:64-130 (registration)

  The searchUsersTool function that registers the 'search_users' MCP tool on the server, including name, description, schema, and handler.

  export function searchUsersTool(server, elicitationHelper) {
    return server.tool(
      "search_users",
      "Search through user profiles using a simple text query",
      {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search query to find users by name, email, or role"
          }
        }
      },
      async (inputs, context) => {
        try {
          let searchQuery = inputs.query;
  
          if (!searchQuery) {
            const elicitationResult = await elicitationHelper.elicitWithProgress(
              "Please enter your search query to find users",
              {
                type: "object",
                properties: {
                  query: {
                    type: "string",
                    title: "Search Query",
                    description: "Enter keywords to search for users by name, email, or role"
                  }
                },
                required: ["query"]
              },
              inputs
            );
  
            if (elicitationResult.action === "accept" && elicitationResult.content?.query) {
              searchQuery = elicitationResult.content.query;
            } else if (elicitationResult.action === "decline") {
              return utils.createErrorResponse("User declined to provide search query. Search cancelled.");
            } else {
              return utils.createErrorResponse("User cancelled the search process.");
            }
          }
  
          const { storage } = await import('../storage.js');
          const query = searchQuery.toLowerCase();
          
          const matchingUsers = storage.users.filter(user => {
            return (
              user.name?.toLowerCase().includes(query) ||
              user.email?.toLowerCase().includes(query) ||
              user.role?.toLowerCase().includes(query)
            );
          });
  
          if (matchingUsers.length === 0) {
            return utils.createSuccessResponse(`No users found matching query: "${searchQuery}"`);
          }
  
          return utils.createSuccessResponse(
            `Found ${matchingUsers.length} user(s) matching "${searchQuery}":\n${JSON.stringify(matchingUsers, null, 2)}`
          );
        } catch (error) {
          return utils.createErrorResponse(`Error searching users: ${error.message}`);
        }
      }
    );
  }

• index.js:18-18 (registration)

  Invocation of searchUsersTool to register the 'search_users' tool during server setup.

  searchUsersTool(server, elicitationHelper);

• index.js:5-5 (helper)

  Import of the searchUsersTool registration helper from userTools.js.

  import { createUserTool, listUsersTool, searchUsersTool } from './tools/userTools.js';