RandomUser MCP Server

Instructions

Implementation Reference

• src/index.ts:531-562 (handler)

  Executes the 'get_random_user' tool: builds parameters from args (gender, nat, fields, password), calls randomuser.me API, formats and returns results.

  private async handleGetRandomUser(args: any) {
    try {
      const params: any = {};
      
      if (args.gender) params.gender = args.gender;
      if (args.nationality) params.nat = args.nationality;
  
      if (args.fields?.mode === 'include') {
        params.inc = args.fields.values.join(',');
      } else if (args.fields?.mode === 'exclude') {
        params.exc = args.fields.values.join(',');
      }
  
      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}`;
      }
  
      const response = await this.axiosInstance.get('', { params });
      return this.formatResults(response.data.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:95-119 (schema)

  Input schema definition for the 'get_random_user' tool, including properties for gender, nationality, fields, format, and password options.

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

• src/index.ts:92-120 (registration)

  Registration of the 'get_random_user' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

  {
    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()
        }
      }
    }
  },

• src/index.ts:181-182 (registration)

  Dispatch registration: switch case in CallToolRequestSchema handler that routes to the get_random_user handler function.

  case 'get_random_user':
    return this.handleGetRandomUser(request.params.arguments);