@sfranalytics/mcp 0.6.0

package/dist/tools/sfr/rentalStats.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { structuredResult, kvSummary, markdownTable, truncatedJson } from "../formatters.js";
+import { action, locationArgs } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+const Input = z.object({
+    search_type: z
+        .enum(["state", "city", "zip", "county", "neighborhood"])
+        .describe("Location search type"),
+    state: z.string().optional().describe("State abbreviation, e.g. 'AZ'"),
+    city: z.string().optional().describe("City name, e.g. 'Phoenix'"),
+    zips: z.string().optional().describe("Comma-separated zip codes, e.g. '85281'"),
+    county: z.string().optional().describe("County name"),
+    neighborhood: z.string().optional().describe("Neighborhood name (used with search_type='neighborhood', e.g. 'Downtown' — try city-level first if unsure of valid names)"),
+    bedrooms: z.coerce.number().optional().describe("Filter by number of bedrooms"),
+    look_back: z.coerce.number().default(365).describe("Days to look back (default 365, max 365)"),
+});
+export function registerRentalStatsTool(server, sfr) {
+    registerToolSafe(server, "sfr_rental_stats", {
+        title: "Rental market statistics (SFR)",
+        description: "Get rental market STATISTICS for a location: median, average, percentiles (p25/p75), " +
+            "min/max rent, and price distributions. Requires search_type + location param. " +
+            "Supports county and neighborhood search_types (unique to this tool). " +
+            "search_type='city' requires state param. " +
+            "For individual rental comps near a specific address, use sfr_rental_comparables.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = {
+            search_type: args.search_type,
+            look_back: args.look_back,
+        };
+        if (args.state)
+            query.state = args.state;
+        if (args.city)
+            query.city = args.city;
+        if (args.zips)
+            query.zips = args.zips;
+        if (args.county)
+            query.county = args.county;
+        if (args.neighborhood)
+            query.neighborhood = args.neighborhood;
+        if (args.bedrooms)
+            query.bedrooms = args.bedrooms;
+        const data = await sfr.getRentalStats(query);
+        const loc = args.zips ?? args.city ?? args.county ?? args.state ?? "All";
+        const lines = [
+            `## Rental Market Stats — ${loc}`,
+            `_${args.look_back}-day lookback_`,
+            "",
+        ];
+        if (data == null) {
+            lines.push("_No data returned. The query may be too broad (e.g. state-level) — try narrowing to a city or zip._");
+            return structuredResult(lines.join("\n"), { location: { search_type: args.search_type, value: loc }, error: "no_data" });
+        }
+        if (data?.stats) {
+            const fmtRent = (v) => v != null ? `$${Math.round(Number(v)).toLocaleString()}/mo` : undefined;
+            lines.push(kvSummary([
+                ["Median Rent", fmtRent(data.stats.median)],
+                ["Average Rent", fmtRent(data.stats.average)],
+                ["25th Percentile", fmtRent(data.stats.p25)],
+                ["75th Percentile", fmtRent(data.stats.p75)],
+                ["Min", fmtRent(data.stats.min)],
+                ["Max", fmtRent(data.stats.max)],
+            ]));
+            if (data.prices?.data && Array.isArray(data.prices.data)) {
+                lines.push("");
+                lines.push("### Price Distribution");
+                // Aggregate duplicate price bins by summing counts
+                const binMap = new Map();
+                for (const d of data.prices.data) {
+                    if (d.price != null) {
+                        const p = Number(d.price);
+                        binMap.set(p, (binMap.get(p) ?? 0) + (d.count ?? 0));
+                    }
+                }
+                const rows = [...binMap.entries()]
+                    .sort((a, b) => a[0] - b[0])
+                    .map(([price, count]) => [
+                    `$${price.toLocaleString()}`,
+                    count,
+                ]);
+                lines.push(markdownTable(["Rent Range", "Listings"], rows));
+            }
+        }
+        else {
+            lines.push("```json");
+            lines.push(truncatedJson(data, 3000));
+            lines.push("```");
+        }
+        // Extract key metrics instead of passing the entire raw upstream response
+        // (which can be 150K+ chars for some locations)
+        const structured = {};
+        if (data?.stats)
+            structured.stats = data.stats;
+        if (data?.prices?.data && Array.isArray(data.prices.data)) {
+            // Aggregate price distribution bins (same logic as markdown)
+            const binMap = new Map();
+            for (const d of data.prices.data) {
+                if (d.price != null) {
+                    const p = Number(d.price);
+                    binMap.set(p, (binMap.get(p) ?? 0) + (d.count ?? 0));
+                }
+            }
+            structured.priceDistribution = [...binMap.entries()]
+                .sort((a, b) => a[0] - b[0])
+                .map(([price, count]) => ({ price, count }));
+        }
+        structured.location = { search_type: args.search_type, value: loc };
+        structured.lookBack = args.look_back;
+        const locArgs = locationArgs(args);
+        const actions = [
+            ...(args.zips ? [action("sfr_zip_detail", "Deep-dive zip metrics", { zipCode: args.zips.split(",")[0] })] : []),
+            action("sfr_top_buyers", "Active buyers in this area", locArgs),
+            action("sfr_search_properties", "Browse individual transactions", locArgs),
+        ];
+        return structuredResult(lines.join("\n"), structured, actions);
+    });
+}
+//# sourceMappingURL=rentalStats.js.map

package/dist/tools/sfr/rentalStats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rentalStats.js","sourceRoot":"","sources":["../../../src/tools/sfr/rentalStats.ts"],"names":[],"mappings":"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"}

package/dist/tools/sfr/searchProperties.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SfrClient } from "../../services/sfr.js";
+export declare function registerSearchPropertiesTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/searchProperties.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, fmtDollars } from "../formatters.js";
+import { action, locationArgs } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+import { autoFillDateRange } from "../dateHelper.js";
+const Input = z.object({
+    search_type: z
+        .enum(["state", "city", "zip", "msa", "address"])
+        .describe("Location search type"),
+    state: z.string().optional().describe("State abbreviation, e.g. 'AZ'"),
+    city: z.string().optional().describe("City name, e.g. 'Phoenix'"),
+    zips: z.string().optional().describe("Comma-separated zip codes, e.g. '85281,85282'"),
+    msa: z.string().optional().describe("MSA name, e.g. 'Phoenix-Mesa-Chandler, AZ'"),
+    latitude: z.coerce.number().optional().describe("Latitude for address search"),
+    longitude: z.coerce.number().optional().describe("Longitude for address search"),
+    radius: z.coerce.number().optional().describe("Radius in miles for address search"),
+    sales_price_min: z.coerce.number().optional().describe("Minimum sale price"),
+    sales_price_max: z.coerce.number().optional().describe("Maximum sale price"),
+    sales_date_min: z.string().optional().describe("Earliest sale date, e.g. '2024-01-01'"),
+    sales_date_max: z.string().optional().describe("Latest sale date"),
+    beds_min: z.coerce.number().optional().describe("Minimum bedrooms"),
+    beds_max: z.coerce.number().optional().describe("Maximum bedrooms"),
+    building_sqft_min: z.coerce.number().optional().describe("Minimum sqft"),
+    building_sqft_max: z.coerce.number().optional().describe("Maximum sqft"),
+    property_types: z.string().optional().describe("Property type filter: 'SFR', 'Condo', 'Multi-Family', 'Townhouse', 'Mobile Home'"),
+    seller_name: z.string().optional().describe("Filter by seller name (partial match)"),
+    purchase_type: z.string().optional().describe("Discount filter: 'all' (default), 'discounted' (below-AVM), or 'non-discount'. " +
+        "NOTE: This is NOT a cash/financed filter. For cash buyer data, use sfr_investor_activity which includes isCashBuyer per transaction."),
+    buyer_type: z.string().optional().describe("Buyer type: 'individual', 'corporate', or 'all'"),
+    page: z.coerce.number().default(1).describe("Page number (default 1)"),
+    page_size: z.coerce.number().default(25).describe("Results per page (default 25, max 100)"),
+    sort: z.string().optional().describe("Sort field: 'recording_date', 'sale_value', 'sale_date', 'bedrooms', 'building_area', 'city', 'buyer_name'. Prefix with - for descending, e.g. '-recording_date'"),
+});
+export function registerSearchPropertiesTool(server, sfr) {
+    registerToolSafe(server, "sfr_search_properties", {
+        title: "Search buyer activity / property transactions (SFR)",
+        description: "Search property transactions by location with filters for price, date, size, and buyer type. " +
+            "Returns individual transaction records with address, price, date, and buyer name. " +
+            "Requires search_type + matching location param (e.g. search_type='zip' + zips='85281'). " +
+            "BEST TOOL for 'where is [institution] selling?' queries — use seller_name filter (e.g. seller_name='INVITATION' to find Invitation Homes dispositions). " +
+            "Supports broader date ranges than sfr_investor_activity. " +
+            "To calculate yields, chain results with sfr_rental_stats using the property's zip code: yield = (annual rent / purchase price). " +
+            "For market-level summaries without individual records, use sfr_activity_highlights instead.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = {
+            search_type: args.search_type,
+            page: args.page,
+            page_size: Math.min(args.page_size, 100),
+        };
+        if (args.state)
+            query.state = args.state;
+        if (args.city)
+            query.city = args.city;
+        if (args.zips)
+            query.zips = args.zips;
+        if (args.msa)
+            query.msa = args.msa;
+        if (args.latitude)
+            query.latitude = args.latitude;
+        if (args.longitude)
+            query.longitude = args.longitude;
+        if (args.radius)
+            query.radius = args.radius;
+        if (args.sales_price_min)
+            query.sales_price_min = args.sales_price_min;
+        if (args.sales_price_max)
+            query.sales_price_max = args.sales_price_max;
+        if (args.sales_date_min)
+            query.sales_date_min = args.sales_date_min;
+        if (args.sales_date_max)
+            query.sales_date_max = args.sales_date_max;
+        if (args.beds_min)
+            query.beds_min = args.beds_min;
+        if (args.beds_max)
+            query.beds_max = args.beds_max;
+        if (args.building_sqft_min)
+            query.building_sqft_min = args.building_sqft_min;
+        if (args.building_sqft_max)
+            query.building_sqft_max = args.building_sqft_max;
+        if (args.property_types)
+            query.property_types = args.property_types;
+        if (args.seller_name)
+            query.seller_name = args.seller_name;
+        if (args.purchase_type)
+            query.purchase_type = args.purchase_type;
+        if (args.buyer_type)
+            query.buyer_type = args.buyer_type;
+        if (args.sort)
+            query.sort = args.sort;
+        autoFillDateRange(query);
+        // Fetch page + total count in parallel
+        const [data, countData] = await Promise.all([
+            sfr.getBuyerActivity(query),
+            sfr.getActivityCount(query).catch(() => null),
+        ]);
+        // External API returns a flat array
+        const items = Array.isArray(data) ? data : (data?.data ?? []);
+        const total = countData?.count ?? countData ?? items.length;
+        const lines = [
+            `## Property Transactions`,
+            `**Total:** ${typeof total === "number" ? total.toLocaleString() : total} | **Page:** ${args.page} | **Showing:** ${items.length}`,
+            "",
+        ];
+        if (items.length > 0) {
+            const rows = items.slice(0, 25).map((p) => [
+                p.address ?? "—",
+                p.city ?? "—",
+                p.zipCode ?? "—",
+                p.bedrooms ?? "—",
+                p.buildingArea ? Number(p.buildingArea).toLocaleString() : "—",
+                fmtDollars(p.saleValue),
+                p.recordingDate ?? p.saleDate ?? "—",
+                p.buyerName ?? "—",
+            ]);
+            lines.push(markdownTable(["Address", "City", "ZIP", "Beds", "Sqft", "Price", "Date", "Buyer"], rows));
+        }
+        else {
+            lines.push("_No transactions found matching criteria._ " +
+                "Try relaxing filters: widen price range, extend date range, or remove seller_name. " +
+                "For MSA searches, check that the MSA name matches exactly.");
+        }
+        // Slim items — raw API has 30+ fields, many null (exit, profit, lat/lng, URL slugs)
+        const slimItems = items.slice(0, 25).map((p) => ({
+            address: p.address,
+            city: p.city,
+            zip: p.zipCode,
+            state: p.state,
+            beds: p.bedrooms || undefined,
+            baths: p.bathrooms || undefined,
+            sqft: p.buildingArea || undefined,
+            yearBuilt: p.yearBuilt || undefined,
+            propertyType: p.propertyType,
+            saleValue: p.saleValue,
+            saleDate: p.saleDate,
+            recordingDate: p.recordingDate,
+            avmValue: p.avmValue || undefined,
+            buyerName: p.buyerName,
+            sellerName: p.sellerName,
+            isCorporate: p.isCorporate || undefined,
+            isCashBuyer: p.isCashBuyer || undefined,
+            isDiscountedPurchase: p.isDiscountedPurchase || undefined,
+            loanAmount: p.loanAmount || undefined,
+            lenderName: p.lenderName || undefined,
+            buyerPropertiesCount: p.buyerPropertiesCount || undefined,
+            msa: p.msa,
+        }));
+        const firstAddr = items[0] ? `${items[0].address}, ${items[0].city}, ${items[0].state} ${items[0].zipCode}` : undefined;
+        const actions = [
+            ...(firstAddr ? [action("sfr_get_property", "Full details on first result", { address: firstAddr })] : []),
+            action("sfr_top_buyers", "Who's buying here", locationArgs(args)),
+            action("sfr_rental_stats", "Rental market for this area", locationArgs(args)),
+        ];
+        return structuredResult(lines.join("\n"), { items: slimItems, total, page: args.page }, actions);
+    });
+}
+//# sourceMappingURL=searchProperties.js.map

package/dist/tools/sfr/searchProperties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchProperties.js","sourceRoot":"","sources":["../../../src/tools/sfr/searchProperties.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IACrB,WAAW,EAAE,CAAC;SACX,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;SAChD,QAAQ,CAAC,sBAAsB,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;IACtE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACjE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;IACrF,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACjF,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC9E,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAChF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IACnF,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAC5E,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAC5E,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IACvF,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAClE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACnE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACnE,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IACxE,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IACxE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kFAAkF,CAAC;IAClI,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IACpF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAC3C,iFAAiF;QACjF,sIAAsI,CACvI;IACD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAC7F,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IACtE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAC3F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kKAAkK,CAAC;CACzM,CAAC,CAAC;AAEH,MAAM,UAAU,4BAA4B,CAAC,MAAiB,EAAE,GAAc;IAC5E,gBAAgB,CAAC,MAAM,EACrB,uBAAuB,EACvB;QACE,KAAK,EAAE,qDAAqD;QAC5D,WAAW,EACT,+FAA+F;YAC/F,oFAAoF;YACpF,0FAA0F;YAC1F,0JAA0J;YAC1J,2DAA2D;YAC3D,kIAAkI;YAClI,6FAA6F;QAC/F,WAAW,EAAE,KAAK;KACnB,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACX,MAAM,KAAK,GAA4B;YACrC,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC;SACzC,CAAC;QACF,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzC,IAAI,IAAI,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtC,IAAI,IAAI,CAAC,GAAG;YAAE,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAClD,IAAI,IAAI,CAAC,SAAS;YAAE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM;YAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5C,IAAI,IAAI,CAAC,eAAe;YAAE,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QACvE,IAAI,IAAI,CAAC,eAAe;YAAE,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QACvE,IAAI,IAAI,CAAC,cAAc;YAAE,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QACpE,IAAI,IAAI,CAAC,cAAc;YAAE,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QACpE,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAClD,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAClD,IAAI,IAAI,CAAC,iBAAiB;YAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAC7E,IAAI,IAAI,CAAC,iBAAiB;YAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAC7E,IAAI,IAAI,CAAC,cAAc;YAAE,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QACpE,IAAI,IAAI,CAAC,WAAW;YAAE,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QAC3D,IAAI,IAAI,CAAC,aAAa;YAAE,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACjE,IAAI,IAAI,CAAC,UAAU;YAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACxD,IAAI,IAAI,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAEzB,uCAAuC;QACvC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC1C,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAQ;YAClC,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAQ;SACrD,CAAC,CAAC;QAEH,oCAAoC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,SAAS,EAAE,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;QAE5D,MAAM,KAAK,GAAG;YACZ,0BAA0B;YAC1B,cAAc,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,KAAK,gBAAgB,IAAI,CAAC,IAAI,mBAAmB,KAAK,CAAC,MAAM,EAAE;YAClI,EAAE;SACH,CAAC;QAEF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC;gBAC9C,CAAC,CAAC,OAAO,IAAI,GAAG;gBAChB,CAAC,CAAC,IAAI,IAAI,GAAG;gBACb,CAAC,CAAC,OAAO,IAAI,GAAG;gBAChB,CAAC,CAAC,QAAQ,IAAI,GAAG;gBACjB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,GAAG;gBAC9D,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;gBACvB,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,QAAQ,IAAI,GAAG;gBACpC,CAAC,CAAC,SAAS,IAAI,GAAG;aACnB,CAAC,CAAC;YAEH,KAAK,CAAC,IAAI,CAAC,aAAa,CACtB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,CACL,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CACR,6CAA6C;gBAC7C,qFAAqF;gBACrF,4DAA4D,CAC7D,CAAC;QACJ,CAAC;QAED,oFAAoF;QACpF,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;YACpD,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,EAAE,CAAC,CAAC,OAAO;YACd,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,IAAI,EAAE,CAAC,CAAC,QAAQ,IAAI,SAAS;YAC7B,KAAK,EAAE,CAAC,CAAC,SAAS,IAAI,SAAS;YAC/B,IAAI,EAAE,CAAC,CAAC,YAAY,IAAI,SAAS;YACjC,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,SAAS;YACnC,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,aAAa,EAAE,CAAC,CAAC,aAAa;YAC9B,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,SAAS;YACjC,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,SAAS;YACvC,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,SAAS;YACvC,oBAAoB,EAAE,CAAC,CAAC,oBAAoB,IAAI,SAAS;YACzD,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,SAAS;YACrC,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,SAAS;YACrC,oBAAoB,EAAE,CAAC,CAAC,oBAAoB,IAAI,SAAS;YACzD,GAAG,EAAE,CAAC,CAAC,GAAG;SACX,CAAC,CAAC,CAAC;QAEJ,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACxH,MAAM,OAAO,GAAG;YACd,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,8BAA8B,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1G,MAAM,CAAC,gBAAgB,EAAE,mBAAmB,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;YACjE,MAAM,CAAC,kBAAkB,EAAE,6BAA6B,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;SAC9E,CAAC;QACF,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IACrG,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/sfr/topBuyers.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SfrClient } from "../../services/sfr.js";
+export declare function registerTopBuyersTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/topBuyers.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, argsToQuery } from "../formatters.js";
+import { action } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+import { autoFillDateRange } from "../dateHelper.js";
+import { resolveCanonicalMsa } from "./msaResolver.js";
+const Input = z.object({
+    search_type: z
+        .enum(["state", "city", "zip", "msa"])
+        .describe("Location search type"),
+    state: z.string().optional().describe("State abbreviation, e.g. 'AZ'"),
+    city: z.string().optional().describe("City name (requires state param when search_type='city'), e.g. 'Birmingham'"),
+    zips: z.string().optional().describe("Comma-separated zip codes, e.g. '85281'"),
+    msa: z.string().optional().describe("MSA name"),
+    sales_date_min: z.string().optional().describe("Start date, e.g. '2024-01-01'"),
+    sales_date_max: z.string().optional().describe("End date"),
+});
+export function registerTopBuyersTool(server, sfr) {
+    registerToolSafe(server, "sfr_top_buyers", {
+        title: "Top buyers by geography — state/city/zip/MSA (SFR)",
+        description: "Find the most active property buyers/investors in ANY geography (state, city, zip, or MSA) " +
+            "ranked by recent acquisition count. Use for 'who is buying in [location]' or " +
+            "'where are investors buying in [city/state]' queries. " +
+            "Returns buyer names, acquisition counts, contact availability, and profile availability. " +
+            "NOTE: search_type='city' requires state param (e.g. city='Birmingham', state='AL'). " +
+            "For MSA-only with city/date filters, use sfr_market_highlights. " +
+            "For institutional REITs/funds only, use sfr_institutional_owners. " +
+            "To drill into a buyer, use sfr_buyer_profile. " +
+            "CHAIN: Use plr_borrower_search with a buyer name to check if they borrow from private lenders.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = argsToQuery(args);
+        autoFillDateRange(query);
+        let effectiveMsa = args.msa;
+        let resolutionMethod = "exact";
+        const data = await sfr.getTopBuyers(query);
+        let buyers = Array.isArray(data) ? data : data?.data ?? [];
+        if (buyers.length === 0 && args.search_type === "msa" && args.msa) {
+            resolutionMethod = "none";
+            const resolved = await resolveCanonicalMsa(sfr, { requestedMsa: args.msa });
+            if (resolved.resolvedMsa
+                && resolved.resolvedMsa.toLowerCase() !== args.msa.trim().toLowerCase()) {
+                effectiveMsa = resolved.resolvedMsa;
+                const retryData = await sfr.getTopBuyers({ ...query, msa: effectiveMsa });
+                buyers = Array.isArray(retryData) ? retryData : retryData?.data ?? [];
+                if (buyers.length > 0)
+                    resolutionMethod = "fallback";
+            }
+        }
+        const loc = args.zips ?? args.city ?? (effectiveMsa ?? args.msa) ?? args.state ?? "All";
+        const lines = [
+            `## Top Buyers — ${loc}`,
+            `**Showing:** ${buyers.length} investors`,
+            "",
+        ];
+        if (resolutionMethod === "fallback") {
+            lines.push(`_MSA normalized: '${args.msa}' -> '${effectiveMsa}'_`, "");
+        }
+        if (buyers.length > 0) {
+            const sorted = [...buyers].sort((a, b) => (b.acquisitions ?? 0) - (a.acquisitions ?? 0));
+            const rows = sorted.slice(0, 30).map((b, i) => [
+                i + 1,
+                b.name ?? "—",
+                b.acquisitions ?? "—",
+                b.hasContactInfo ? "Yes" : "No",
+                b.hasProfilePage ? "Yes" : "No",
+            ]);
+            lines.push(markdownTable(["#", "Buyer", "Acquisitions", "Contact Info", "Profile"], rows));
+        }
+        else {
+            lines.push("_No buyers found for this location._ " +
+                "Verify search_type matches the location param (e.g. search_type='city' needs city= and state=). " +
+                "For MSA searches, the name must match exactly — try sfr_activity_highlights for a quick check.");
+        }
+        // Slim buyers — strip formattedName URL slugs and unnecessary metadata
+        const slimBuyers = buyers.slice(0, 50).map((b) => ({
+            name: b.name ?? b.buyer_name,
+            acquisitions: b.acquisitions ?? b.count,
+            hasProfile: b.hasProfilePage || undefined,
+            hasContact: b.hasContactInfo || undefined,
+        }));
+        const firstName = buyers[0]?.name ?? buyers[0]?.buyer_name;
+        const actions = [
+            ...(firstName ? [action("sfr_buyer_profile", "Profile top buyer", { name: firstName })] : []),
+            ...(firstName ? [action("sfr_buyer_growth", "Growth trend for top buyer", { name: firstName })] : []),
+            ...(firstName ? [action("plr_borrower_search", "Check if top buyer borrows privately", { search: firstName })] : []),
+        ];
+        return structuredResult(lines.join("\n"), { items: slimBuyers, total: buyers.length, page: 1 }, actions);
+    });
+}
+//# sourceMappingURL=topBuyers.js.map

package/dist/tools/sfr/topBuyers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topBuyers.js","sourceRoot":"","sources":["../../../src/tools/sfr/topBuyers.ts"],"names":[],"mappings":"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"}

package/dist/tools/sfr/zipDetail.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SfrClient } from "../../services/sfr.js";
+export declare function registerZipDetailTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/zipDetail.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { structuredResult, kvSummary, truncatedJson } from "../formatters.js";
+import { action } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+const Input = z.object({
+    zipCode: z.string().describe("5-digit zip code, e.g. '85281'"),
+});
+export function registerZipDetailTool(server, sfr) {
+    registerToolSafe(server, "sfr_zip_detail", {
+        title: "Detailed stats for a single zip code (SFR)",
+        description: "Get comprehensive investment metrics for a specific zip code: population, income, " +
+            "home values, rent, yield, institutional ownership, transaction volume, and trends. " +
+            "More detailed than sfr_zip_finder which ranks many zips — this deep-dives into one.",
+        inputSchema: Input,
+    }, async (args) => {
+        const data = await sfr.getZipDetail(args.zipCode);
+        if (!data || typeof data !== "object") {
+            return structuredResult(`## Zip Code Detail — ${args.zipCode}\n\n_No data found._`, {});
+        }
+        const fmt$ = (v) => v != null ? `$${Math.round(Number(v)).toLocaleString()}` : undefined;
+        const fmtPct01 = (v) => v != null ? `${(Number(v) * 100).toFixed(1)}%` : undefined;
+        const fmtNum = (v) => v != null ? Number(v).toLocaleString() : undefined;
+        const lines = [
+            `## Zip Code Detail — ${data.zipCode ?? args.zipCode}`,
+            "",
+            "### Demographics",
+            kvSummary([
+                ["Population", fmtNum(data.population)],
+                ["Population Density", data.populationDensity != null
+                        ? `${Number(data.populationDensity).toFixed(0)}/sq mi` : undefined],
+                ["Housing Units", fmtNum(data.housingUnits)],
+                ["Median Household Income", fmt$(data.medianHouseholdIncome)],
+                ["Income vs MSA", fmtPct01(data.incomeRelativeToMsa)],
+            ]),
+            "",
+            "### Investment Metrics",
+            kvSummary([
+                ["Median Home Value", fmt$(data.medianHomeValue)],
+                ["Median Rent", data.medianRent != null ? `$${Math.round(Number(data.medianRent)).toLocaleString()}/mo` : undefined],
+                ["Gross Yield", fmtPct01(data.grossYield)],
+                ["Inst. Ownership", fmtPct01(data.instOwnPercentage)],
+            ]),
+        ];
+        // Append any additional fields as raw JSON
+        const knownKeys = new Set([
+            "zipCode", "population", "populationDensity", "populationGrowthForecast",
+            "housingUnits", "medianHouseholdIncome", "medianHomeValue", "medianRent",
+            "instOwnPercentage", "grossYield", "incomeRelativeToMsa",
+        ]);
+        const extra = {};
+        for (const [k, v] of Object.entries(data)) {
+            if (!knownKeys.has(k) && v != null)
+                extra[k] = v;
+        }
+        if (Object.keys(extra).length > 0) {
+            lines.push("");
+            lines.push("### Additional Data");
+            lines.push("```json");
+            lines.push(truncatedJson(extra, 2000));
+            lines.push("```");
+        }
+        const zip = args.zipCode;
+        const actions = [
+            action("sfr_rental_stats", "Rental market stats", { search_type: "zip", zips: zip }),
+            action("sfr_top_buyers", "Active buyers in zip", { search_type: "zip", zips: zip }),
+            action("sfr_search_properties", "Browse transactions", { search_type: "zip", zips: zip }),
+            action("sfr_institutional_owners", "Institutional owners in zip", { search_type: "zip", zips: zip }),
+        ];
+        const structured = {
+            zipCode: data.zipCode,
+            population: data.population,
+            populationDensity: data.populationDensity,
+            populationGrowthForecast: data.populationGrowthForecast,
+            housingUnits: data.housingUnits,
+            medianHouseholdIncome: data.medianHouseholdIncome,
+            medianHomeValue: data.medianHomeValue,
+            medianRent: data.medianRent,
+            grossYield: data.grossYield,
+            instOwnPercentage: data.instOwnPercentage,
+            incomeRelativeToMsa: data.incomeRelativeToMsa,
+        };
+        return structuredResult(lines.join("\n"), structured, actions);
+    });
+}
+//# sourceMappingURL=zipDetail.js.map

package/dist/tools/sfr/zipDetail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zipDetail.js","sourceRoot":"","sources":["../../../src/tools/sfr/zipDetail.ts"],"names":[],"mappings":"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"}

package/dist/tools/sfr/zipFinder.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SfrClient } from "../../services/sfr.js";
+export declare function registerZipFinderTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/zipFinder.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, truncatedJson } from "../formatters.js";
+import { action } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+const Input = z.object({
+    search_type: z
+        .enum(["all", "zip"])
+        .default("all")
+        .describe("Search type: 'all' for nationwide or 'zip' to filter specific zips"),
+    zips: z.string().optional().describe("Comma-separated zip codes (required when search_type='zip')"),
+    page: z.coerce.number().default(1).describe("Page number (default 1)"),
+    page_size: z.coerce.number().default(25).describe("Results per page (default 25, max 100)"),
+    sort: z.string().optional().describe("Sort field, e.g. '-gross_yield' for descending gross yield"),
+});
+export function registerZipFinderTool(server, sfr) {
+    registerToolSafe(server, "sfr_zip_finder", {
+        title: "Find & rank zip codes by investment metrics (SFR)",
+        description: "Screen and rank zip codes by investment metrics: gross yield, median home value, " +
+            "rent, income, population, and institutional ownership. " +
+            "Use search_type='all' for nationwide ranking or 'zip' with specific codes. " +
+            "Sort by '-gross_yield' for highest-yielding zips. " +
+            "For detailed stats on a single zip, use sfr_zip_detail.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = {
+            search_type: args.search_type,
+            page: args.page,
+            page_size: args.page_size,
+        };
+        if (args.zips)
+            query.zips = args.zips;
+        if (args.sort)
+            query.sort = args.sort;
+        const data = await sfr.getZipFinder(query);
+        const items = data?.data ?? data?.results ?? (Array.isArray(data) ? data : []);
+        const total = data?.total ?? data?.count ?? items.length;
+        const lines = [
+            `## Zip Code Finder`,
+            `**Total:** ${total} zips | **Page:** ${args.page}`,
+            "",
+        ];
+        if (items.length > 0) {
+            const fmt = (v, prefix = "") => v != null ? `${prefix}${Math.round(Number(v)).toLocaleString()}` : "—";
+            // grossYield is 0-1 scale; API returns corrupt values >1.0 for zips with null rent
+            const fmtYield = (v) => {
+                if (v == null)
+                    return "—";
+                const n = Number(v);
+                if (n > 0.40)
+                    return "⚠️ suspect";
+                return `${(n * 100).toFixed(1)}%`;
+            };
+            const pctScale01 = (v) => v != null ? `${(Number(v) * 100).toFixed(1)}%` : "—";
+            const rows = items.slice(0, 30).map((z) => [
+                z.zip_code ?? z.zipCode ?? z.zip,
+                fmt(z.population),
+                fmt(z.medianHouseholdIncome ?? z.median_household_income, "$"),
+                fmt(z.medianHomeValue ?? z.median_home_value, "$"),
+                fmt(z.medianRent ?? z.median_rent, "$"),
+                fmtYield(z.grossYield ?? z.gross_yield),
+                pctScale01(z.instOwnPercentage ?? z.inst_own_percentage),
+            ]);
+            lines.push(markdownTable(["Zip", "Pop", "Income", "Home Value", "Rent", "Yield", "Inst Own"], rows));
+        }
+        else {
+            lines.push("```json");
+            lines.push(truncatedJson(data, 3000));
+            lines.push("```");
+        }
+        const topZip = items[0]?.zip_code ?? items[0]?.zipCode ?? items[0]?.zip;
+        const actions = [
+            ...(topZip ? [action("sfr_zip_detail", "Deep-dive into top zip", { zipCode: String(topZip) })] : []),
+            ...(topZip ? [action("sfr_rental_stats", "Rental market for top zip", { search_type: "zip", zips: String(topZip) })] : []),
+            ...(topZip ? [action("sfr_top_buyers", "Active buyers in top zip", { search_type: "zip", zips: String(topZip) })] : []),
+        ];
+        return structuredResult(lines.join("\n"), { items, total, page: args.page }, actions);
+    });
+}
+//# sourceMappingURL=zipFinder.js.map

package/dist/tools/sfr/zipFinder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zipFinder.js","sourceRoot":"","sources":["../../../src/tools/sfr/zipFinder.ts"],"names":[],"mappings":"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"}

package/dist/tools/slugHelper.d.ts

@@ -0,0 +1,2 @@
+/** Convert a buyer display name like "INVITATION HOMES" to a URL slug like "invitation-homes" */
+export declare function slugifyBuyerName(name: string): string;

package/dist/tools/slugHelper.js

@@ -0,0 +1,5 @@
+/** Convert a buyer display name like "INVITATION HOMES" to a URL slug like "invitation-homes" */
+export function slugifyBuyerName(name) {
+    return name.trim().toLowerCase().replace(/\s+/g, "-");
+}
+//# sourceMappingURL=slugHelper.js.map

package/dist/tools/slugHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugHelper.js","sourceRoot":"","sources":["../../src/tools/slugHelper.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACxD,CAAC"}