@sfranalytics/mcp 0.6.0

package/dist/tools/plr/topLenders.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, truncatedJson, fmtDollars } from "../formatters.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+import { autoFillPlrDates } from "../dateHelper.js";
+import { action } from "../nextActions.js";
+const Input = z.object({
+    search: z.string().optional().describe("Search text for lender name (matches both short 'lender' and display 'clean_name')"),
+    states: z.string().optional().describe("Comma-separated state abbreviations"),
+    msas: z.string().optional().describe("Semicolon-separated MSA names (use ; because MSA names contain commas), e.g. 'Phoenix-Mesa-Chandler, AZ; Dallas-Fort Worth-Arlington, TX'"),
+    startDate: z.string().optional().describe("Start date, e.g. '2024-01-01'"),
+    endDate: z.string().optional().describe("End date"),
+    loanTypes: z.string().optional().describe("Comma-separated: 'Bridge', 'DSCR', 'Unknown'"),
+    page: z.coerce.number().default(1).describe("Page number (default 1)"),
+    pageSize: z.coerce.number().default(25).describe("Results per page (default 25, max 25)"),
+});
+export function registerTopLendersTool(server, plr) {
+    registerToolSafe(server, "plr_top_lenders", {
+        title: "Rank lenders by DOLLAR VOLUME — with geographic filters (PLR)",
+        description: "Rank private lenders by total dollar volume originated, with geographic filters (state/MSA). " +
+            "Use for market share analysis: 'top lenders in FL', 'lender market share in Texas', or 'biggest lenders in Phoenix MSA'. " +
+            "Different from plr_lender_rankings which ranks by loan count and has NO geographic filters. " +
+            "Returns lender names, origination volume, loan count, and HQ location. " +
+            "Filter by loanTypes ('Bridge', 'DSCR', 'Unknown') for portfolio/DSCR-specific market share.",
+        inputSchema: Input,
+    }, async (args) => {
+        const body = {
+            page: args.page,
+            page_size: Math.min(args.pageSize, 25),
+        };
+        if (args.search)
+            body.search = args.search;
+        if (args.states)
+            body.states = args.states.split(",").map((s) => s.trim());
+        if (args.msas)
+            body.msas = args.msas.split(";").map((s) => s.trim());
+        if (args.startDate)
+            body.start_date = args.startDate;
+        if (args.endDate)
+            body.end_date = args.endDate;
+        if (args.loanTypes)
+            body.loan_types = args.loanTypes.split(",").map((s) => s.trim());
+        autoFillPlrDates(body);
+        const data = await plr.topLendersByVolume(body);
+        const items = data?.results ?? data?.data ?? (Array.isArray(data) ? data : []);
+        const total = data?.count ?? items.length;
+        const lines = [
+            `## Top Lenders by Volume`,
+            `**Total:** ${total} | **Page:** ${args.page}`,
+            "",
+        ];
+        if (items.length > 0) {
+            const rows = items.slice(0, 25).map((l, i) => [
+                i + 1 + (args.page - 1) * args.pageSize,
+                l.clean_name ?? l.lender ?? "—",
+                fmtDollars(l.origination_volume ?? l.total_amount),
+                l.loan_count != null ? Number(l.loan_count).toLocaleString() : "—",
+                l.headquarters_location ?? "—",
+            ]);
+            lines.push(markdownTable(["#", "Lender", "Volume", "Loans", "HQ"], rows));
+        }
+        else {
+            lines.push("```json");
+            lines.push(truncatedJson(data, 3000));
+            lines.push("```");
+        }
+        const firstName = items[0]?.lender ?? items[0]?.clean_name;
+        const actions = [
+            ...(firstName ? [action("plr_lender_borrowers", "Borrowers of top lender", { lenders: firstName })] : []),
+            ...(firstName ? [action("plr_churned_borrowers", "Churned borrowers from top lender", { lenders: firstName })] : []),
+            action("plr_lender_rankings", "Rank by loan count (nationwide)", {}),
+        ];
+        return structuredResult(lines.join("\n"), { items, total, page: args.page }, actions);
+    });
+}
+//# sourceMappingURL=topLenders.js.map

package/dist/tools/plr/topLenders.js.map

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

package/dist/tools/plr/transactionHistory.d.ts

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

package/dist/tools/plr/transactionHistory.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { structuredResult, markdownTable, truncatedJson } from "../formatters.js";
+import { registerToolSafe } from "../registerToolSafe.js";
+import { action } from "../nextActions.js";
+const Input = z.object({
+    propertyAddress: z.string().describe("Full property address, e.g. '123 Main St, Phoenix, AZ 85004'"),
+    page: z.coerce.number().default(1).describe("Page number (default 1)"),
+    pageSize: z.coerce.number().default(10).describe("Results per page (default 10, max 25)"),
+});
+export function registerTransactionHistoryTool(server, plr) {
+    registerToolSafe(server, "plr_transaction_history", {
+        title: "Property private lending history (PLR)",
+        description: "Get the private lending transaction history for a property address. " +
+            "Returns all recorded private loans (bridge/DSCR) with lender names, amounts, " +
+            "recording dates, and loan types. Includes property details (AVM, owner info). " +
+            "Complements sfr_property_transactions which shows deeds/sales.",
+        inputSchema: Input,
+    }, async (args) => {
+        const body = {
+            property_address: args.propertyAddress,
+            page: args.page,
+            page_size: Math.min(args.pageSize, 25),
+        };
+        const data = await plr.transactionHistory(body);
+        const items = data?.results ?? data?.data ?? (Array.isArray(data) ? data : []);
+        const total = data?.count ?? items.length;
+        const lines = [
+            `## Private Lending History — ${args.propertyAddress}`,
+            `**Total:** ${total} transactions`,
+            "",
+        ];
+        if (items.length > 0) {
+            const fmt$ = (v) => v != null && Number(v) > 0 ? `$${Number(v).toLocaleString()}` : "—";
+            const rows = items.slice(0, 20).map((t) => [
+                t.recording_date ?? "—",
+                t.tx_type ?? t.transaction_type_clean ?? "—",
+                fmt$(t.sale_amt),
+                t.buyer_borrower1_name ?? "—",
+                t.seller1_name ?? "—",
+                t.lender_clean ?? t.first_mtg_lender_name ?? "—",
+                fmt$(t.first_mtg_amt),
+            ]);
+            lines.push(markdownTable(["Date", "Type", "Sale Price", "Buyer", "Seller", "Lender", "Mortgage"], rows));
+            if (data.property_details) {
+                const pd = data.property_details;
+                lines.push("", "### Property Details");
+                const detailLines = [
+                    pd.avm_value ? `**AVM:** $${Number(pd.avm_value).toLocaleString()}` : null,
+                    pd.market_value ? `**Market Value:** $${Number(pd.market_value).toLocaleString()}` : null,
+                    pd.owner ? `**Owner:** ${pd.owner}` : null,
+                    pd.property_type ? `**Type:** ${pd.property_type}` : null,
+                    pd.beds ? `**Beds:** ${pd.beds}` : null,
+                    pd.total_sqft ? `**Sqft:** ${pd.total_sqft}` : null,
+                ].filter(Boolean);
+                lines.push(detailLines.join(" | "));
+            }
+        }
+        else {
+            lines.push("_No private lending transactions found for this property._");
+            if (data && typeof data === "object") {
+                lines.push("```json");
+                lines.push(truncatedJson(data, 2000));
+                lines.push("```");
+            }
+        }
+        const actions = [
+            action("sfr_get_property", "Full property details & valuation", { address: args.propertyAddress }),
+            action("plr_loans_nearby", "Other loans in the area", { propertyAddress: args.propertyAddress }),
+            action("sfr_property_transactions", "Deed & sale history", { address: args.propertyAddress }),
+        ];
+        return structuredResult(lines.join("\n"), { items, total, page: args.page }, actions);
+    });
+}
+//# sourceMappingURL=transactionHistory.js.map

package/dist/tools/plr/transactionHistory.js.map

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

package/dist/tools/prompts.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register example prompts that guide users through common workflows.
+ * Prompts are discoverable by MCP clients and serve as entry points.
+ * Only registers prompts for APIs the user has configured.
+ */
+export declare function registerPrompts(server: McpServer, hasSfr: boolean, hasPlr: boolean): void;

package/dist/tools/prompts.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+/**
+ * Register example prompts that guide users through common workflows.
+ * Prompts are discoverable by MCP clients and serve as entry points.
+ * Only registers prompts for APIs the user has configured.
+ */
+export function registerPrompts(server, hasSfr, hasPlr) {
+    if (hasSfr) {
+        server.registerPrompt("market-screen", {
+            title: "Screen markets by investment criteria",
+            description: "Find the best zip codes for SFR investing by yield, rent, home value, " +
+                "and institutional ownership. Then deep-dive into top picks.",
+            argsSchema: {
+                sortBy: z
+                    .enum(["gross_yield", "median_rent", "median_home_value", "inst_own_percentage"])
+                    .default("gross_yield")
+                    .describe("Primary sort metric (prefix with - for descending)"),
+                count: z
+                    .string()
+                    .default("10")
+                    .describe("Number of top zips to analyze"),
+            },
+        }, async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Find the top ${args.count} zip codes for SFR investing, sorted by ${args.sortBy} (descending).`,
+                            "",
+                            "For each top zip, show:",
+                            "1. Gross yield, median home value, median rent, institutional ownership",
+                            "2. Rental market stats (median, p25, p75)",
+                            "3. Top buyers active in that zip",
+                            "",
+                            "Then recommend the 3 best zips and explain why.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
+        server.registerPrompt("buyer-research", {
+            title: "Research a property buyer/investor",
+            description: "Get a comprehensive view of a buyer: portfolio, strategy, growth trend, and contacts.",
+            argsSchema: {
+                name: z.string().describe("Buyer/investor name, e.g. 'Invitation Homes'"),
+            },
+        }, async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Research the property investor "${args.name}":`,
+                            "",
+                            "1. Pull their full profile (portfolio stats, strategy, geographic focus)",
+                            "2. Show their acquisition growth trend over the past 2 years",
+                            "3. Identify what markets they're most active in",
+                            "4. Summarize their investment strategy and deal parameters",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
+        server.registerPrompt("property-analysis", {
+            title: "Analyze a property for investment",
+            description: "Evaluate a specific property: transaction history, rental comps, and market context.",
+            argsSchema: {
+                address: z.string().describe("Full property address, e.g. '123 Main St, Phoenix, AZ 85004'"),
+            },
+        }, async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            `Analyze this property for SFR investment: ${args.address}`,
+                            "",
+                            "1. Look up the property details and transaction history",
+                            "2. Find rental comparables nearby to estimate fair market rent",
+                            "3. Get rental stats for the zip code",
+                            "4. Get zip code detail for broader market context",
+                            "5. Check who the top buyers are in this area",
+                            "",
+                            "Then give an investment assessment: estimated rent, yield, and market quality.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
+    }
+    if (hasPlr) {
+        server.registerPrompt("lending-overview", {
+            title: "Private lending market overview",
+            description: "Get a comprehensive view of the private lending market: volume trends, " +
+                "top lenders, top borrowers, and MSA rankings.",
+        }, async () => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            "Give me a comprehensive overview of the private lending market:",
+                            "",
+                            "1. Start with the portfolio summary (total loans, volume, lender/borrower counts)",
+                            "2. Show quarterly trends for the past 2 years",
+                            "3. Rank the top 10 MSAs by lending volume",
+                            "4. List the top 10 lenders and top 10 borrowers",
+                            "",
+                            "Highlight any notable trends (growth, contraction, shifts in loan types).",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
+        server.registerPrompt("borrower-outreach", {
+            title: "Build a borrower outreach list",
+            description: "Find active private lending borrowers matching criteria and get their contact info.",
+            argsSchema: {
+                states: z.string().optional().describe("Target states, e.g. 'AZ,TX'"),
+                loanType: z
+                    .enum(["Bridge", "DSCR", "Unknown"])
+                    .optional()
+                    .describe("Loan type filter"),
+                minLoans: z.string().default("3").describe("Minimum loan count"),
+            },
+        }, async (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            "Build a targeted borrower outreach list with these criteria:",
+                            args.states ? `- States: ${args.states}` : "- All states",
+                            args.loanType ? `- Loan type: ${args.loanType}` : "- All loan types",
+                            `- Minimum ${args.minLoans} loans`,
+                            "- Must have contact info (phone or email)",
+                            "",
+                            "For each borrower, show:",
+                            "1. Name, loan count, total volume",
+                            "2. Active states and loan types",
+                            "3. Contact information (phone, email)",
+                            "",
+                            "Sort by loan count descending.",
+                        ].join("\n"),
+                    },
+                },
+            ],
+        }));
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/dist/tools/prompts.js.map

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

package/dist/tools/registerToolSafe.d.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+type AnySchema = z.ZodTypeAny;
+type ZodRawShapeCompat = Record<string, z.ZodTypeAny>;
+type ToolConfig<InputArgs extends undefined | ZodRawShapeCompat | AnySchema> = {
+    title?: string;
+    description?: string;
+    inputSchema?: InputArgs;
+    outputSchema?: ZodRawShapeCompat | AnySchema;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+};
+type ToolCallbackResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+};
+/**
+ * Wrapper around `server.registerTool` that adds:
+ * - readOnlyHint + idempotentHint annotations by default
+ * - automatic try/catch → handleToolError
+ * - latency logging to stderr (>100ms only)
+ */
+export declare function registerToolSafe<InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined>(server: McpServer, toolName: string, config: ToolConfig<InputArgs>, cb: (args: any) => Promise<ToolCallbackResult>): void;
+export {};

package/dist/tools/registerToolSafe.js

@@ -0,0 +1,36 @@
+import { handleToolError } from "./formatters.js";
+/**
+ * Wrapper around `server.registerTool` that adds:
+ * - readOnlyHint + idempotentHint annotations by default
+ * - automatic try/catch → handleToolError
+ * - latency logging to stderr (>100ms only)
+ */
+export function registerToolSafe(server, toolName, config, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+cb) {
+    const mergedConfig = {
+        ...config,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            ...config.annotations,
+        },
+    };
+    server.registerTool(toolName, mergedConfig, async (args) => {
+        const t0 = performance.now();
+        try {
+            const result = await cb(args);
+            return result;
+        }
+        catch (err) {
+            return handleToolError(err, toolName);
+        }
+        finally {
+            const elapsed = performance.now() - t0;
+            if (elapsed > 100) {
+                process.stderr.write(`[sfra-mcp] ${toolName}: ${Math.round(elapsed)}ms\n`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=registerToolSafe.js.map

package/dist/tools/registerToolSafe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerToolSafe.js","sourceRoot":"","sources":["../../src/tools/registerToolSafe.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsBlD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAG9B,MAAiB,EACjB,QAAgB,EAChB,MAA6B;AAC7B,8DAA8D;AAC9D,EAA8C;IAE9C,MAAM,YAAY,GAAG;QACnB,GAAG,MAAM;QACT,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,cAAc,EAAE,IAAI;YACpB,GAAG,MAAM,CAAC,WAAW;SACtB;KACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,QAAQ,EACR,YAAyD,EACzD,KAAK,EAAE,IAAS,EAAE,EAAE;QAClB,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACxC,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;YACvC,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;gBAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,QAAQ,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

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

package/dist/tools/sfr/activityHighlights.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { structuredResult, kvSummary, markdownTable, argsToQuery } 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 (requires state param when search_type='city')"),
+    zips: z.string().optional().describe("Comma-separated zip codes"),
+    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 registerActivityHighlightsTool(server, sfr) {
+    registerToolSafe(server, "sfr_activity_highlights", {
+        title: "Quick market summary — transaction count + top 10 buyers (SFR)",
+        description: "Quick market count: total transactions plus top 10 buyers in a geography. " +
+            "A lightweight preview — use sfr_top_buyers for the full buyer list with contacts/profiles. " +
+            "Best for 'how many transactions in [location]?' before deciding to drill deeper. " +
+            "Supports any geography: state, city, zip, MSA, or address.",
+        inputSchema: Input,
+    }, async (args) => {
+        const query = argsToQuery(args);
+        autoFillDateRange(query);
+        // Fetch count and top buyers in parallel
+        const [countData, topBuyersData] = await Promise.all([
+            sfr.getActivityCount(query),
+            sfr.getTopBuyers({ ...query, page_size: 10 }),
+        ]);
+        const count = typeof countData === "number" ? countData : countData?.count ?? countData;
+        const topBuyers = Array.isArray(topBuyersData)
+            ? topBuyersData
+            : topBuyersData?.data ?? [];
+        const loc = args.zips ?? args.city ?? args.msa ?? args.state ?? "All";
+        const lines = [
+            `## Activity Highlights — ${loc}`,
+            "",
+            kvSummary([
+                ["Total Transactions", count != null ? Number(count).toLocaleString() : undefined],
+            ]),
+            "",
+        ];
+        if (topBuyers.length > 0) {
+            lines.push("### Top Buyers");
+            const sorted = [...topBuyers].sort((a, b) => (b.acquisitions ?? b.count ?? 0) - (a.acquisitions ?? a.count ?? 0));
+            const rows = sorted.slice(0, 10).map((b, i) => [
+                i + 1,
+                b.name ?? b.buyer_name ?? "—",
+                b.acquisitions ?? b.count ?? "—",
+            ]);
+            lines.push(markdownTable(["#", "Buyer", "Acquisitions"], rows));
+        }
+        // Slim topBuyers — strip URL slug hashes, keep only key fields
+        const slimBuyers = topBuyers.slice(0, 15).map((b) => ({
+            name: b.name ?? b.buyer_name,
+            acquisitions: b.acquisitions ?? b.count,
+            hasProfile: b.hasProfilePage || undefined,
+            hasContact: b.hasContactInfo || undefined,
+        }));
+        const locArgs = locationArgs(args);
+        const actions = [
+            action("sfr_top_buyers", "Full buyer list with profiles & contacts", locArgs),
+            action("sfr_search_properties", "Browse individual transactions", locArgs),
+            action("sfr_rental_stats", "Rental market for this area", locArgs),
+        ];
+        return structuredResult(lines.join("\n"), { count, topBuyers: slimBuyers, page: 1 }, actions);
+    });
+}
+//# sourceMappingURL=activityHighlights.js.map

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

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

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

package/dist/tools/sfr/bestBuyers.js

@@ -0,0 +1,60 @@
+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({
+    address: z.string().describe("Full property address, e.g. '123 Main St, Phoenix, AZ 85004'"),
+});
+export function registerBestBuyersTool(server, sfr) {
+    registerToolSafe(server, "sfr_best_buyers", {
+        title: "Best buyers for a property (SFR)",
+        description: "Find the most likely buyers for a specific property based on their acquisition patterns. " +
+            "Returns investors who have bought similar properties in the same area. " +
+            "Ideal for sellers, wholesalers, or agents matching properties to active buyers.",
+        inputSchema: Input,
+    }, async (args) => {
+        const data = await sfr.getBestBuyers(args.address);
+        const buyers = data?.data ?? data?.buyers ?? (Array.isArray(data) ? data : []);
+        const lines = [
+            `## Best Buyers — ${args.address}`,
+            `**Matches:** ${buyers.length} investors`,
+            "",
+        ];
+        if (buyers.length > 0) {
+            // API returns {name, matchScore, totalAcquisitions, recentPurchasesCount, matchReasons}
+            const rows = buyers.slice(0, 25).map((b, i) => [
+                i + 1,
+                b.name ?? b.buyer_name ?? "—",
+                b.totalAcquisitions ?? b.acquisitions ?? "—",
+                b.recentPurchasesCount ?? "—",
+                b.matchScore != null ? `${b.matchScore}%` : "—",
+                Array.isArray(b.matchReasons) ? b.matchReasons[0] ?? "—" : "—",
+            ]);
+            lines.push(markdownTable(["#", "Buyer", "Total Acq.", "Recent", "Match", "Reason"], rows));
+        }
+        else {
+            lines.push("```json");
+            lines.push(truncatedJson(data, 3000));
+            lines.push("```");
+        }
+        // Slim buyers — keep match-specific fields, strip URL slugs
+        const slimBuyers = buyers.slice(0, 25).map((b) => ({
+            name: b.name ?? b.buyer_name,
+            totalAcquisitions: b.totalAcquisitions ?? b.acquisitions,
+            recentPurchasesCount: b.recentPurchasesCount,
+            purchasesWithinQuarterMile: b.purchasesWithinQuarterMile || undefined,
+            matchScore: b.matchScore,
+            matchReasons: b.matchReasons,
+            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 match", { name: firstName })] : []),
+            ...(firstName ? [action("sfr_buyer_growth", "Growth trend for top match", { name: firstName })] : []),
+            action("sfr_get_property", "Full property details", { address: args.address }),
+        ];
+        return structuredResult(lines.join("\n"), { items: slimBuyers, total: buyers.length, page: 1 }, actions);
+    });
+}
+//# sourceMappingURL=bestBuyers.js.map

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

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

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