get_random_properties

Instructions

Implementation Reference

• src/index.ts:370-398 (handler)

  Inline async handler function for the get_random_properties MCP tool. Builds search parameters, calls rentcastAPI.getRandomProperties, processes and formats up to 5 sample properties using formatPropertyInfo, and returns a formatted text response.

  async (params) => {
    try {
      const searchParams = buildPropertySearchParams(params);
      
      const result = await rentcastAPI.getRandomProperties(searchParams);
  
      if (!result.success) {
        return createErrorResponse("Error getting random properties", result.error);
      }
  
      const properties = result.data as any[];
      
  
      
      const summary = `Retrieved ${properties.length} random properties`;
      
      // Process each property individually
      const sampleProperties = properties.slice(0, 5).map(prop => {
        
        return formatPropertyInfo(prop);
      }).join('\n\n');
  
      const resultText = `${summary}\n\nSample Properties:\n\n${sampleProperties}${properties.length > 5 ? '\n\n... and more properties available' : ''}`;
      return createSuccessResponse(resultText);
  
          } catch (error) {
        return createErrorResponse("Failed to get random properties", error instanceof Error ? error.message : 'Unknown error');
      }
  }

• src/index.ts:366-399 (registration)

  MCP server.tool registration for the 'get_random_properties' tool, specifying name, description, input schema (RandomPropertiesSchema.shape), and inline handler function.

  server.tool(
    "get_random_properties",
    "Get random properties with comprehensive info (default: 10, max: 50 for free tier) for market analysis including price history, lot size, and year built",
    RandomPropertiesSchema.shape,
    async (params) => {
      try {
        const searchParams = buildPropertySearchParams(params);
        
        const result = await rentcastAPI.getRandomProperties(searchParams);
  
        if (!result.success) {
          return createErrorResponse("Error getting random properties", result.error);
        }
  
        const properties = result.data as any[];
        
  
        
        const summary = `Retrieved ${properties.length} random properties`;
        
        // Process each property individually
        const sampleProperties = properties.slice(0, 5).map(prop => {
          
          return formatPropertyInfo(prop);
        }).join('\n\n');
  
        const resultText = `${summary}\n\nSample Properties:\n\n${sampleProperties}${properties.length > 5 ? '\n\n... and more properties available' : ''}`;
        return createSuccessResponse(resultText);
  
            } catch (error) {
          return createErrorResponse("Failed to get random properties", error instanceof Error ? error.message : 'Unknown error');
        }
    }
  );

• src/types/index.ts:246-261 (schema)

  Zod schema defining input parameters for the get_random_properties tool: optional city, state, zipCode, and limit (default 10, max 50).

  export const RandomPropertiesSchema = z.object({
    city: z.string().optional().describe("City for random property selection"),
    state: z.string().optional().describe("State for random property selection"),
    zipCode: z
      .string()
      .optional()
      .describe("ZIP code for random property selection"),
    limit: z
      .number()
      .min(1)
      .max(50)
      .default(10)
      .describe(
        "Number of random properties to return (default: 10, max: 50 for free tier)",
      ),
  });

• src/services/rentcast-api.ts:92-108 (helper)

  RentcastAPI service method getRandomProperties: constructs API request to Rentcast /properties/random endpoint with location params and limit (default 10), using makeRequest helper for HTTP call and error handling.

  async getRandomProperties(
    params: {
      city?: string;
      state?: string;
      zipCode?: string;
      limit?: number;
    } = {},
  ): Promise<ApiCallResult> {
    const result = await this.makeRequest<RentcastProperty[]>(
      "/properties/random",
      {
        ...params,
        limit: params.limit || 10, // Default to 10 for free tier optimization
      },
    );
    return result;
  }

• src/index.ts:209-224 (helper)

  buildPropertySearchParams utility function: maps tool input parameters to API search parameters, optionally including limit.

  function buildPropertySearchParams(params: any, includeLimit: boolean = true): any {
    const searchParams: any = {};
    
    if (includeLimit && params.limit) {
      searchParams.limit = params.limit;
    }
    
    if (params.city) searchParams.city = params.city;
    if (params.state) searchParams.state = params.state;
    if (params.zipCode) searchParams.zipCode = params.zipCode;
    if (params.bedrooms) searchParams.bedrooms = params.bedrooms;
    if (params.bathrooms) searchParams.bathrooms = params.bathrooms;
    if (params.propertyType) searchParams.propertyType = params.propertyType;
    
    return searchParams;
  }