get_sale_listings

Instructions

Implementation Reference

• src/index.ts:655-688 (handler)

  Primary MCP tool handler for 'get_sale_listings': validates params, builds search parameters, calls Rentcast API service, formats listings with property info and parameter suggestions, handles errors, and returns formatted text response.

  async (params) => {
    try {
      const searchParams = buildPropertySearchParams(params);
  
      const result = await rentcastAPI.getSaleListings(searchParams);
  
      if (!result.success) {
        return createErrorResponse("Error getting sale listings", result.error);
      }
  
      const listings = result.data as any[];
      
  
      
      const summary = `Found ${listings.length} sale listings`;
      
      const listingDetails = listings.slice(0, 8).map(listing => {
        
        // Use actual Rentcast API data structure
        const propertyInfo = formatPropertyInfo(listing);
        
        // Add compact parameter suggestions
        const params = `\n💡 **Quick Parameters:** Address: "${listing.formattedAddress}", Lat: ${listing.latitude}, Lng: ${listing.longitude}, Type: "${listing.propertyType}", Beds: ${listing.bedrooms || 'N/A'}, Baths: ${listing.bathrooms || 'N/A'}, SqFt: ${listing.squareFootage || 'N/A'}`;
        
        return propertyInfo + params;
      }).join('\n\n');
  
      const resultText = `${summary}\n\n${listingDetails}${listings.length > 8 ? '\n\n... and more listings available' : ''}`;
      return createSuccessResponse(resultText);
  
          } catch (error) {
        return createErrorResponse("Failed to get sale listings", error instanceof Error ? error.message : 'Unknown error');
      }
  }

• src/types/index.ts:263-275 (schema)

  Zod input schema defining parameters for listing searches (city, state, zipCode, limit), used by get_sale_listings tool.

  export const ListingSearchSchema = z.object({
    city: z.string().optional().describe("City for listing search (e.g., 'Austin', 'New York', 'Los Angeles')"),
    state: z.string().optional().describe("State for listing search (e.g., 'TX', 'NY', 'CA')"),
    zipCode: z.string().optional().describe("ZIP code for listing search (e.g., '78705', '10001', '90210')"),
    limit: z
      .number()
      .min(1)
      .max(50)
      .default(15)
      .describe(
        "Maximum number of listings to return (default: 15, max: 50 for free tier)",
      ),
  });

• src/index.ts:651-654 (registration)

  MCP tool registration call for 'get_sale_listings' with name, description, input schema, and handler reference.

  server.tool(
    "get_sale_listings",
    "Get sale listings with comprehensive property information. This tool searches for properties currently for sale.",
    ListingSearchSchema.shape,

• src/services/rentcast-api.ts:172-185 (helper)

  Rentcast API service method that executes the HTTP request to '/listings/sale' endpoint with parameters and returns ApiCallResult.

  async getSaleListings(
    params: {
      city?: string;
      state?: string;
      zipCode?: string;
      limit?: number;
    } = {},
  ): Promise<ApiCallResult> {
    const result = await this.makeRequest<RentcastListing[]>("/listings/sale", {
      ...params,
      limit: params.limit || 15, // Default to 15 for free tier optimization
    });
    return result;
  }

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

  Utility function to construct search parameters from input params, used in get_sale_listings handler.

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