@sfranalytics/mcp 0.6.0

package/dist/tools/sfr/flipStats.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, fmtDollars } from "../formatters.js";
+import { action, locationArgs } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.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')"),
+    zips: z.string().optional().describe("Comma-separated zip codes, e.g. '85281'"),
+    msa: z.string().optional().describe("MSA name"),
+    metric: z
+        .enum(["hold-time", "gross-margin", "both"])
+        .default("both")
+        .describe("Which flip metric to retrieve"),
+});
+/** Format monthly time series as a readable table (last 12 months) */
+function formatTimeSeries(items, valueKey, formatValue, valueHeader) {
+    if (!Array.isArray(items) || items.length === 0)
+        return "_No data_";
+    // Show last 12 months
+    const recent = items.slice(-12);
+    const rows = recent.map((row) => {
+        const date = row.date ?? "—";
+        const month = date.length >= 7 ? date.slice(0, 7) : date;
+        const val = row[valueKey];
+        return [month, val != null ? formatValue(Number(val)) : "—"];
+    });
+    return markdownTable(["Month", valueHeader], rows);
+}
+export function registerFlipStatsTool(server, sfr) {
+    registerToolSafe(server, "sfr_flip_stats", {
+        title: "Flip profitability stats (SFR)",
+        description: "Get flip profitability TRENDS for a market: hold time ranges and gross margin ranges. " +
+            "Choose metric='hold-time', 'gross-margin', or 'both'. " +
+            "Requires search_type + location param (search_type='city' requires state). " +
+            "For market-level flip aggregates (volume, flipper counts), use sfr_flip_activity.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = { search_type: args.search_type };
+        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;
+        let effectiveMsa = args.msa;
+        let resolutionMethod = "exact";
+        // MSA resolution probe — check before making metric-specific calls
+        if (args.search_type === "msa" && args.msa) {
+            const probeData = await sfr.getFlipHoldTime(query);
+            const probeItems = Array.isArray(probeData) ? probeData : probeData?.data ?? [];
+            if (probeItems.length === 0) {
+                resolutionMethod = "none";
+                const resolved = await resolveCanonicalMsa(sfr, { requestedMsa: args.msa });
+                if (resolved.resolvedMsa
+                    && resolved.resolvedMsa.toLowerCase() !== args.msa.trim().toLowerCase()) {
+                    effectiveMsa = resolved.resolvedMsa;
+                    query.msa = effectiveMsa;
+                    resolutionMethod = "fallback";
+                }
+            }
+        }
+        const loc = args.zips ?? args.city ?? (effectiveMsa ?? args.msa) ?? args.state ?? "All";
+        const lines = [`## Flip Statistics — ${loc}`, ""];
+        if (resolutionMethod === "fallback") {
+            lines.push(`_MSA normalized: '${args.msa}' -> '${effectiveMsa}'_`, "");
+        }
+        const result = {};
+        if (args.metric !== "gross-margin") {
+            const holdTime = await sfr.getFlipHoldTime(query);
+            const items = Array.isArray(holdTime) ? holdTime : holdTime?.data ?? [];
+            result.holdTime = items;
+            lines.push("### Median Hold Time (last 12 months)");
+            lines.push(formatTimeSeries(items, "daysDiff", (v) => `${Math.round(v)} days`, "Median Days"));
+            lines.push("");
+        }
+        if (args.metric !== "hold-time") {
+            const margin = await sfr.getFlipGrossMargin(query);
+            const items = Array.isArray(margin) ? margin : margin?.data ?? [];
+            result.grossMargin = items;
+            lines.push("### Median Gross Margin (last 12 months)");
+            lines.push(formatTimeSeries(items, "grossMargin", (v) => fmtDollars(v), "Median Margin"));
+        }
+        const locArgs = locationArgs(args);
+        const actions = [
+            action("sfr_flip_activity", "Browse individual flip transactions", locArgs),
+            action("sfr_search_properties", "All transactions in area", locArgs),
+            action("sfr_top_buyers", "Active buyers in area", locArgs),
+        ];
+        return structuredResult(lines.join("\n"), result, actions);
+    });
+}
+//# sourceMappingURL=flipStats.js.map

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

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

package/dist/tools/sfr/getProperty.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 registerGetPropertyTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/getProperty.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+import { structuredResult, kvSummary } from "../formatters.js";
+import { action } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+const Input = z.object({
+    address: z.string().describe("Full property address, e.g. '123 Main St, Phoenix, AZ 85004'"),
+});
+export function registerGetPropertyTool(server, sfr) {
+    registerToolSafe(server, "sfr_get_property", {
+        title: "Get property details by address (SFR)",
+        description: "Get comprehensive property details by address: valuation (AVM), tax assessments, " +
+            "owner info, structure (beds/baths/sqft), last sale, lot size, and investment metrics. " +
+            "For multiple addresses at once, use sfr_property_batch. " +
+            "For transaction history, use sfr_property_transactions.",
+        inputSchema: Input,
+    }, async (args) => {
+        const data = await sfr.getPropertyByAddress(args.address);
+        const addr = data?.address;
+        const fullAddr = addr
+            ? `${addr.formatted_street_address}, ${addr.city}, ${addr.state} ${addr.zip_code}`
+            : args.address;
+        const lines = [
+            `## Property Details — ${fullAddr}`,
+            "",
+            "### Location",
+            kvSummary([
+                ["Address", addr?.formatted_street_address],
+                ["City", addr?.city],
+                ["State", addr?.state],
+                ["Zip", addr?.zip_code],
+                ["County", data?.county],
+                ["MSA", data?.msa],
+                ["Latitude", addr?.latitude],
+                ["Longitude", addr?.longitude],
+            ]),
+            "",
+            "### Structure",
+            kvSummary([
+                ["Beds", data?.structure?.beds_count],
+                ["Baths", data?.structure?.baths],
+                ["Sqft", data?.structure?.total_area_sq_ft ?? data?.structure?.living_area_sqft],
+                ["Lot Size (sqft)", data?.parcel?.area_sq_ft],
+                ["Year Built", data?.structure?.year_built],
+                ["Stories", data?.structure?.stories],
+                ["Property Type", data?.property_type ?? data?.property_class_description],
+                ["Units", data?.structure?.units_count],
+            ]),
+            "",
+            "### Valuation & Assessments",
+            kvSummary([
+                ["Assessed Value", data?.assessments?.assessed_value ? `$${Number(data.assessments.assessed_value).toLocaleString()}` : undefined],
+                ["Land Value", data?.assessments?.land_value ? `$${Number(data.assessments.land_value).toLocaleString()}` : undefined],
+                ["Market Value", data?.assessments?.market_value ? `$${Number(data.assessments.market_value).toLocaleString()}` : undefined],
+                ["AVM", data?.valuation?.value ? `$${Number(data.valuation.value).toLocaleString()}` : undefined],
+                ["Tax Amount", data?.tax_amount ? `$${Number(data.tax_amount).toLocaleString()}` : undefined],
+            ]),
+            "",
+            "### Last Sale",
+            kvSummary([
+                ["Date", data?.last_sale?.date],
+                ["Price", data?.last_sale?.price ? `$${Number(data.last_sale.price).toLocaleString()}` : undefined],
+                ["Document Type", data?.last_sale?.document_type],
+                ["Mortgage Amount", data?.last_sale?.mtg_amount ? `$${Number(data.last_sale.mtg_amount).toLocaleString()}` : undefined],
+                ["Lender", data?.last_sale?.lender],
+                ["Months Owned", data?.months_owned],
+            ]),
+            "",
+            "### Owner",
+            kvSummary([
+                ["Name", data?.owner?.name],
+                ["Owner Occupied", data?.owner?.owner_occupied],
+                ["Corporate", data?.owner?.corporate_owner],
+                ["Owner Type", data?.owner_type],
+                ["Purchase Method", data?.purchase_method],
+            ]),
+            "",
+            "### Status",
+            kvSummary([
+                ["Listing Status", data?.listing_status],
+                ["HOA", data?.hoa],
+                ["Vacant", data?.vacant],
+                ["Pre-foreclosure", data?.pre_foreclosure?.flag],
+            ]),
+        ];
+        const actions = [
+            action("sfr_rental_comparables", "Estimate rental income", { address: fullAddr }),
+            action("sfr_property_comps", "Sales comps for valuation", { address: fullAddr }),
+            action("sfr_property_transactions", "Full ownership history", { address: fullAddr }),
+            action("plr_loans_nearby", "Private lending activity nearby", { propertyAddress: fullAddr }),
+        ];
+        const structured = {
+            address: addr ? {
+                formatted_street_address: addr.formatted_street_address,
+                city: addr.city,
+                state: addr.state,
+                zip_code: addr.zip_code,
+                latitude: addr.latitude,
+                longitude: addr.longitude,
+            } : undefined,
+            county: data?.county,
+            msa: data?.msa,
+            structure: data?.structure ? {
+                beds_count: data.structure.beds_count,
+                baths: data.structure.baths,
+                total_area_sq_ft: data.structure.total_area_sq_ft ?? data.structure.living_area_sqft,
+                year_built: data.structure.year_built,
+                stories: data.structure.stories,
+                units_count: data.structure.units_count,
+            } : undefined,
+            property_type: data?.property_type ?? data?.property_class_description,
+            lot_sq_ft: data?.parcel?.area_sq_ft,
+            assessments: data?.assessments ? {
+                assessed_value: data.assessments.assessed_value,
+                land_value: data.assessments.land_value,
+                market_value: data.assessments.market_value,
+            } : undefined,
+            valuation: data?.valuation?.value != null ? { value: data.valuation.value } : undefined,
+            tax_amount: data?.tax_amount,
+            last_sale: data?.last_sale ? {
+                date: data.last_sale.date,
+                price: data.last_sale.price,
+                document_type: data.last_sale.document_type,
+                mtg_amount: data.last_sale.mtg_amount,
+                lender: data.last_sale.lender,
+            } : undefined,
+            months_owned: data?.months_owned,
+            owner: data?.owner ? {
+                name: data.owner.name,
+                owner_occupied: data.owner.owner_occupied,
+                corporate_owner: data.owner.corporate_owner,
+            } : undefined,
+            owner_type: data?.owner_type,
+            purchase_method: data?.purchase_method,
+            listing_status: data?.listing_status,
+            hoa: data?.hoa,
+            vacant: data?.vacant,
+            pre_foreclosure: data?.pre_foreclosure?.flag,
+        };
+        return structuredResult(lines.join("\n"), structured, actions);
+    });
+}
+//# sourceMappingURL=getProperty.js.map

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

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

package/dist/tools/sfr/institutionalOwners.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 registerInstitutionalOwnersTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/institutionalOwners.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, truncatedJson } from "../formatters.js";
+import { action, locationArgs } from "../nextActions.js";
+import { registerToolSafe } from "../registerToolSafe.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')"),
+    zips: z.string().optional().describe("Comma-separated zip codes"),
+    msa: z.string().optional().describe("MSA name"),
+    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)"),
+});
+export function registerInstitutionalOwnersTool(server, sfr) {
+    registerToolSafe(server, "sfr_institutional_owners", {
+        title: "Institutional REITs & funds owning SFR in area (SFR)",
+        description: "Find institutional SFR owners (REITs and private equity funds) in a location, " +
+            "ranked by portfolio size. Covers tracked entities like Invitation Homes, American Homes 4 Rent, " +
+            "Progress Residential, Tricon, FirstKey, etc. " +
+            "Different from sfr_top_buyers which shows ALL active buyers (individuals + institutions). " +
+            "Different from sfr_market_highlights which shows MSA-only buyer rankings by acquisition count. " +
+            "NOTE: search_type='city' requires state param (e.g. city='Phoenix', state='AZ'). " +
+            "Use sfr_buyer_profile to get full profile for any listed owner. " +
+            "CHAIN: To find where an institution is SELLING, use sfr_search_properties with seller_name filter (e.g. seller_name='INVITATION').",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = { search_type: args.search_type };
+        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;
+        query.page = args.page;
+        query.page_size = args.page_size;
+        let effectiveMsa = args.msa;
+        let resolutionMethod = "exact";
+        const data = await sfr.getInstitutionalLargestOwners(query);
+        let items = data?.data ?? (Array.isArray(data) ? data : []);
+        let total = data?.total ?? items.length;
+        if (items.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.getInstitutionalLargestOwners({ ...query, msa: effectiveMsa });
+                items = retryData?.data ?? (Array.isArray(retryData) ? retryData : []);
+                total = retryData?.total ?? items.length;
+                if (items.length > 0)
+                    resolutionMethod = "fallback";
+            }
+        }
+        const loc = args.zips ?? args.city ?? (effectiveMsa ?? args.msa) ?? args.state ?? "All";
+        const lines = [
+            `## Institutional Owners — ${loc}`,
+            `**Total:** ${total}`,
+            "",
+        ];
+        if (resolutionMethod === "fallback") {
+            lines.push(`_MSA normalized: '${args.msa}' -> '${effectiveMsa}'_`, "");
+        }
+        if (items.length > 0) {
+            const rows = items.slice(0, 25).map((o, i) => [
+                i + 1,
+                o.fundName ?? o.name ?? o.owner_name ?? "—",
+                o.totalHomes ?? o.properties ?? o.property_count ?? "—",
+            ]);
+            lines.push(markdownTable(["#", "Owner", "Properties"], rows));
+        }
+        else {
+            lines.push("```json");
+            lines.push(truncatedJson(data, 3000));
+            lines.push("```");
+        }
+        const firstName = items[0]?.fundName ?? items[0]?.name ?? items[0]?.owner_name;
+        const actions = [
+            ...(firstName ? [action("sfr_buyer_profile", "Profile top institutional owner", { name: firstName })] : []),
+            ...(args.zips ? [action("sfr_zip_detail", "Deep-dive zip metrics", { zipCode: args.zips.split(",")[0] })] : []),
+            action("sfr_top_buyers", "All buyers (not just institutional)", locationArgs(args)),
+        ];
+        return structuredResult(lines.join("\n"), { items, total, page: args.page }, actions);
+    });
+}
+//# sourceMappingURL=institutionalOwners.js.map

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

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

package/dist/tools/sfr/investorActivity.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 registerInvestorActivityTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/investorActivity.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { structuredResult, markdownTable } 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({
+    msa: z.string().describe("MSA name, e.g. 'Phoenix-Mesa-Chandler, AZ'"),
+    sales_date_min: z.string().optional().describe("Start date, e.g. '2024-01-01'"),
+    sales_date_max: z.string().optional().describe("End date"),
+    is_cash_buyer: z.boolean().optional().describe("Filter for cash purchases only"),
+    seller_name: z.string().optional().describe("Filter by seller name (partial match)"),
+    page: z.coerce.number().default(1).describe("Page number (default 1)"),
+    page_size: z.coerce.number().default(20).describe("Results per page (default 20, max 100)"),
+});
+export function registerInvestorActivityTool(server, sfr) {
+    registerToolSafe(server, "sfr_investor_activity", {
+        title: "Browse investor transactions in MSA — with portfolio size (SFR)",
+        description: "Browse individual investor PURCHASE transactions in an MSA market. " +
+            "Best for BUYER analysis: shows cash vs financed, corporate vs individual, and buyer's total portfolio size. " +
+            "Each transaction includes isCashBuyer flag — use is_cash_buyer=true to find cash buyer prospects. " +
+            "Also supports seller_name filter, but for 'where is [institution] selling?' queries prefer sfr_search_properties which has broader date coverage. " +
+            "To calculate yields on purchases, chain with sfr_rental_stats by zip: yield = (annual rent / purchase price). " +
+            "Requires an MSA name. For non-MSA transaction searches, use sfr_search_properties. " +
+            "See sfr_buyer_profile for full profiles and sfr_flip_activity for flip stats.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = {
+            search_type: "msa",
+            msa: args.msa,
+            page: args.page,
+            page_size: args.page_size,
+        };
+        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.is_cash_buyer !== undefined)
+            query.is_cash_buyer = args.is_cash_buyer;
+        if (args.seller_name)
+            query.seller_name = args.seller_name;
+        autoFillDateRange(query);
+        let effectiveMsa = args.msa;
+        let resolutionMethod = "exact";
+        const data = await sfr.getBuyerActivity(query);
+        let items = Array.isArray(data) ? data : data?.data ?? [];
+        if (items.length === 0) {
+            resolutionMethod = "none";
+            const resolved = await resolveCanonicalMsa(sfr, {
+                requestedMsa: args.msa,
+                salesDateMin: typeof query.sales_date_min === "string" ? query.sales_date_min : undefined,
+                salesDateMax: typeof query.sales_date_max === "string" ? query.sales_date_max : undefined,
+            });
+            if (resolved.resolvedMsa
+                && resolved.resolvedMsa.toLowerCase() !== args.msa.trim().toLowerCase()) {
+                effectiveMsa = resolved.resolvedMsa;
+                const retryQuery = { ...query, msa: effectiveMsa };
+                const retryData = await sfr.getBuyerActivity(retryQuery);
+                items = Array.isArray(retryData) ? retryData : retryData?.data ?? [];
+                if (items.length > 0)
+                    resolutionMethod = "fallback";
+            }
+        }
+        const loc = effectiveMsa;
+        const lines = [
+            `## Market Investor Activity — ${loc}`,
+            `**Showing:** ${items.length} transactions`,
+            "",
+        ];
+        if (resolutionMethod === "fallback") {
+            lines.push(`_MSA normalized: '${args.msa}' -> '${effectiveMsa}'_`, "");
+        }
+        if (items.length > 0) {
+            const fmt$ = (v) => v != null ? `$${Number(v).toLocaleString()}` : "—";
+            const rows = items.slice(0, 25).map((t) => [
+                t.buyerName ?? "—",
+                t.address ? `${t.address}, ${t.city ?? ""}` : "—",
+                fmt$(t.saleValue),
+                t.isCashBuyer ? "Cash" : "Financed",
+                t.isCorporate ? "Corp" : "Individual",
+                t.buyerPropertiesCount ?? "—",
+            ]);
+            lines.push(markdownTable(["Buyer", "Address", "Price", "Type", "Entity", "Portfolio"], rows));
+        }
+        else {
+            lines.push("_No transactions found for this market._ " +
+                "Try widening the date range" +
+                (args.seller_name ? ` or using a shorter seller name (partial match on '${args.seller_name}')` : "") +
+                (args.is_cash_buyer ? " or removing the cash buyer filter" : "") +
+                ".");
+        }
+        // Slim items — raw API has 30+ fields, many null (exit, profit, URL slugs, lat/lng)
+        const slimItems = items.slice(0, 25).map((t) => ({
+            buyerName: t.buyerName,
+            address: t.address,
+            city: t.city,
+            zip: t.zipCode,
+            state: t.state,
+            propertyType: t.propertyType,
+            saleValue: t.saleValue,
+            saleDate: t.saleDate,
+            avmValue: t.avmValue || undefined,
+            isCashBuyer: t.isCashBuyer || undefined,
+            isCorporate: t.isCorporate || undefined,
+            isDiscountedPurchase: t.isDiscountedPurchase || undefined,
+            loanAmount: t.loanAmount || undefined,
+            lenderName: t.lenderName || undefined,
+            buyerPropertiesCount: t.buyerPropertiesCount || undefined,
+            buyerTransactionsCount: t.buyerTransactionsCount || undefined,
+            sqft: t.buildingArea || undefined,
+            beds: t.bedrooms || undefined,
+        }));
+        const firstBuyer = items[0]?.buyerName;
+        const firstAddr = items[0] ? `${items[0].address}, ${items[0].city}, ${items[0].state} ${items[0].zipCode}` : undefined;
+        const actions = [
+            ...(firstBuyer ? [action("sfr_buyer_profile", "Profile top investor", { name: firstBuyer })] : []),
+            ...(firstAddr ? [action("sfr_get_property", "Details on first property", { address: firstAddr })] : []),
+            action("sfr_search_properties", "Search with more filters", { search_type: "msa", msa: effectiveMsa }),
+        ];
+        return structuredResult(lines.join("\n"), {
+            items: slimItems,
+            total: items.length,
+            page: args.page,
+            requested_msa: args.msa,
+            resolved_msa: effectiveMsa,
+            msa_resolution_method: resolutionMethod,
+        }, actions);
+    });
+}
+//# sourceMappingURL=investorActivity.js.map

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

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

package/dist/tools/sfr/marketHighlights.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 registerMarketHighlightsTool(server: McpServer, sfr: SfrClient): void;

package/dist/tools/sfr/marketHighlights.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { structuredResult, markdownTable } 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({
+    msa: z.string().describe("MSA name, e.g. 'Phoenix-Mesa-Chandler, AZ'"),
+    city: z.string().optional().describe("Optional city filter within the MSA"),
+    sales_date_min: z.string().optional().describe("Start date, e.g. '2024-01-01'"),
+    sales_date_max: z.string().optional().describe("End date"),
+    page_size: z.coerce.number().default(25).describe("Results per page (default 25, max 100)"),
+});
+export function registerMarketHighlightsTool(server, sfr) {
+    registerToolSafe(server, "sfr_market_highlights", {
+        title: "Top buyers in MSA market (SFR)",
+        description: "Rank buyers in an MSA market by acquisition count. Requires an MSA name. " +
+            "Supports optional city filter and date range within the MSA. " +
+            "Different from sfr_top_buyers which accepts any geography (state/city/zip/MSA). " +
+            "Different from sfr_institutional_owners which shows only institutional REITs/funds. " +
+            "Use sfr_buyer_profile to drill into any buyer.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = { msa: args.msa };
+        if (args.city)
+            query.city = args.city;
+        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.page_size)
+            query.page_size = args.page_size;
+        autoFillDateRange(query);
+        let effectiveMsa = args.msa;
+        let resolutionMethod = "exact";
+        const data = await sfr.getMarketTopBuyers(query);
+        // API ignores page_size param — enforce it client-side
+        let rawBuyers = Array.isArray(data) ? data : data?.data ?? [];
+        if (rawBuyers.length === 0) {
+            resolutionMethod = "none";
+            const resolved = await resolveCanonicalMsa(sfr, {
+                requestedMsa: args.msa,
+                salesDateMin: typeof query.sales_date_min === "string" ? query.sales_date_min : undefined,
+                salesDateMax: typeof query.sales_date_max === "string" ? query.sales_date_max : undefined,
+            });
+            if (resolved.resolvedMsa
+                && resolved.resolvedMsa.toLowerCase() !== args.msa.trim().toLowerCase()) {
+                effectiveMsa = resolved.resolvedMsa;
+                const retryQuery = { ...query, msa: effectiveMsa };
+                const retryData = await sfr.getMarketTopBuyers(retryQuery);
+                rawBuyers = Array.isArray(retryData) ? retryData : retryData?.data ?? [];
+                if (rawBuyers.length > 0)
+                    resolutionMethod = "fallback";
+            }
+        }
+        const buyers = rawBuyers.slice(0, args.page_size);
+        const lines = [
+            `## Market Top Buyers — ${effectiveMsa}${args.city ? ` (${args.city})` : ""}`,
+            `**Showing:** ${buyers.length} buyers`,
+            "",
+        ];
+        if (resolutionMethod === "fallback") {
+            lines.push(`_MSA normalized: '${args.msa}' -> '${effectiveMsa}'_`, "");
+        }
+        if (buyers.length > 0) {
+            const rows = buyers.slice(0, 30).map((b, i) => [
+                i + 1,
+                b.name ?? "—",
+                b.acquisitions ?? b.count ?? "—",
+                b.hasContactInfo ? "Yes" : "No",
+            ]);
+            lines.push(markdownTable(["#", "Buyer", "Acquisitions", "Contact Info"], rows));
+        }
+        else {
+            lines.push("_No buyers found for this market._");
+        }
+        // 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 })] : []),
+            action("sfr_top_buyers", "Full buyer list with profiles", { search_type: "msa", msa: effectiveMsa }),
+            action("sfr_search_properties", "Browse individual transactions", { search_type: "msa", msa: effectiveMsa }),
+        ];
+        return structuredResult(lines.join("\n"), {
+            items: slimBuyers,
+            total: buyers.length,
+            page: 1,
+            requested_msa: args.msa,
+            resolved_msa: effectiveMsa,
+            msa_resolution_method: resolutionMethod,
+        }, actions);
+    });
+}
+//# sourceMappingURL=marketHighlights.js.map