RandomUser MCP Server

Instructions

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