get_multiple_users

Instructions

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "count": "<count>"
    },
    "name": "get_multiple_users"
  }
}

Implementation Reference

• src/index.ts:587-636 (handler)

  The main handler function that implements the get_multiple_users tool. It constructs API parameters based on input args, makes multiple requests to randomuser.me API for different gender/nationality combinations to fulfill the requested count, collects results, and returns formatted output.

  private async handleGetMultipleUsers(args: any) {
    try {
      const results = [];
      const params: any = {};
  
      // Add field parameters
      this.addFieldParams(params, args);
  
      if (args.password) {
        const charsets = args.password.charsets?.join(',') || 'upper,lower,number';
        params.password = args.password.maxLength ?
          `${charsets},${args.password.minLength || 8}-${args.password.maxLength}` :
          `${charsets},${args.password.minLength || 8}`;
      }
  
      // Make one API call per requested nationality+gender combination
      for (const gender of ['female', 'male']) {
        if (args.gender && args.gender !== gender) continue;
        
        params.gender = gender;
        
        // Handle single nationality or array of nationalities
        const nationalities = Array.isArray(args.nationality) 
          ? args.nationality 
          : [args.nationality];
  
        for (const nat of nationalities) {
          params.nat = nat;
          
          const count = this.calculateCountForNationalityAndGender(args, nat, gender);
          if (count === 0) continue;
          
          params.results = count;
          
          const response = await this.axiosInstance.get('', { params });
          results.push(...response.data.results);
        }
      }
  
      return this.formatResults(results, args.format);
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new McpError(
          ErrorCode.InternalError,
          `API Error: ${error.response?.data.error || error.message}`
        );
      }
      throw error;
    }
  }

• src/index.ts:121-174 (schema)

  Input schema definition for the get_multiple_users tool, specifying parameters like count (required), gender, nationality (single or array), weights, fields, format, and password options.

  {
    name: 'get_multiple_users',
    description: 'Get multiple random users',
    inputSchema: {
      type: 'object',
      properties: {
        count: {
          type: 'number',
          minimum: 1,
          maximum: 5000,
          description: 'Number of users to generate'
        },
        gender: {
          type: 'string',
          enum: ['male', 'female']
        },
        nationality: {
          oneOf: [
            {
              type: 'string',
              enum: NATIONALITIES
            },
            {
              type: 'array',
              items: {
                type: 'string',
                enum: NATIONALITIES
              }
            }
          ]
        },
        nationalityWeights: {
          type: 'object',
          patternProperties: {
            "^[A-Z]{2}$": {
              type: 'number',
              minimum: 0,
              maximum: 1
            }
          }
        },
        fields: {
          type: 'object',
          properties: this.getFieldProperties()
        },
        format: this.getFormatOptionsSchema(),
        password: {
          type: 'object',
          properties: this.getPasswordOptionsSchema()
        }
      },
      required: ['count']
    }
  }

• src/index.ts:179-191 (registration)

  Registration of tool call handler via setRequestHandler for CallToolRequestSchema, including the switch case that dispatches 'get_multiple_users' calls to handleGetMultipleUsers.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    switch (request.params.name) {
      case 'get_random_user':
        return this.handleGetRandomUser(request.params.arguments);
      case 'get_multiple_users':
        return this.handleGetMultipleUsers(request.params.arguments);
      default:
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Unknown tool: ${request.params.name}`
        );
    }
  });

• src/index.ts:90-176 (registration)

  Tool list registration in ListToolsRequestSchema handler, where get_multiple_users is included in the returned tools array with its schema.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'get_random_user',
        description: 'Get a single random user',
        inputSchema: {
          type: 'object',
          properties: {
            gender: {
              type: 'string',
              enum: ['male', 'female'],
              description: 'Filter results by gender'
            },
            nationality: {
              type: 'string',
              enum: NATIONALITIES,
              description: 'Specify nationality'
            },
            fields: {
              type: 'object',
              description: 'Specify which fields to include',
              properties: this.getFieldProperties()
            },
            format: this.getFormatOptionsSchema(),
            password: {
              type: 'object',
              properties: this.getPasswordOptionsSchema()
            }
          }
        }
      },
      {
        name: 'get_multiple_users',
        description: 'Get multiple random users',
        inputSchema: {
          type: 'object',
          properties: {
            count: {
              type: 'number',
              minimum: 1,
              maximum: 5000,
              description: 'Number of users to generate'
            },
            gender: {
              type: 'string',
              enum: ['male', 'female']
            },
            nationality: {
              oneOf: [
                {
                  type: 'string',
                  enum: NATIONALITIES
                },
                {
                  type: 'array',
                  items: {
                    type: 'string',
                    enum: NATIONALITIES
                  }
                }
              ]
            },
            nationalityWeights: {
              type: 'object',
              patternProperties: {
                "^[A-Z]{2}$": {
                  type: 'number',
                  minimum: 0,
                  maximum: 1
                }
              }
            },
            fields: {
              type: 'object',
              properties: this.getFieldProperties()
            },
            format: this.getFormatOptionsSchema(),
            password: {
              type: 'object',
              properties: this.getPasswordOptionsSchema()
            }
          },
          required: ['count']
        }
      }
    ]
  }));

• src/index.ts:564-585 (helper)

  Helper function used by the handler to compute the exact count of users to request for each nationality-gender pair, respecting filters and weights.

  private calculateCountForNationalityAndGender(
    args: any,
    nationality: string,
    gender: string
  ): number {
    if (!args.nationality) return 0;
    if (args.gender && args.gender !== gender) return 0;
    
    const totalCount = args.count || 0;
    const weights = args.nationalityWeights || {};
    
    if (!Array.isArray(args.nationality)) {
      return nationality === args.nationality ? totalCount : 0;
    }
    
    if (!args.nationality.includes(nationality)) return 0;
    
    const natWeight = weights[nationality] || (1 / args.nationality.length);
    const genderRatio = args.gender ? 1 : 0.5; // If gender specified use full count, else split 50/50
    
    return Math.round(totalCount * natWeight * genderRatio);
  }