@sfranalytics/mcp 0.6.3 → 0.6.5

package/dist/tools/sfr/zipDetail.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { structuredResult, kvSummary, truncatedJson } from "../formatters.js";
 import { action } from "../nextActions.js";
 import { registerToolSafe } from "../registerToolSafe.js";
+import { ApiError } from "../../services/httpClient.js";
 const Input = z.object({
     zipCode: z.string().describe("5-digit zip code, e.g. '85281'"),
 });
@@ -13,80 +14,90 @@ export function registerZipDetailTool(server, sfr) {
             "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._`, {});
+        try {
+            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 grossYieldRaw = data.grossYield ?? data.gross_yield;
+            const grossYieldCapped = grossYieldRaw != null && Number.isFinite(Number(grossYieldRaw)) && Number(grossYieldRaw) >= 0 && Number(grossYieldRaw) <= 0.4
+                ? Number(grossYieldRaw)
+                : null;
+            const grossYieldDisplay = grossYieldCapped != null
+                ? fmtPct01(grossYieldCapped)
+                : "— (no reliable rent data)";
+            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", grossYieldDisplay],
+                    ["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: grossYieldCapped,
+                instOwnPercentage: data.instOwnPercentage,
+                incomeRelativeToMsa: data.incomeRelativeToMsa,
+            };
+            return structuredResult(lines.join("\n"), structured, actions);
         }
-        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 grossYieldRaw = data.grossYield ?? data.gross_yield;
-        const grossYieldCapped = grossYieldRaw != null && Number.isFinite(Number(grossYieldRaw)) && Number(grossYieldRaw) >= 0 && Number(grossYieldRaw) <= 0.4
-            ? Number(grossYieldRaw)
-            : null;
-        const grossYieldDisplay = grossYieldCapped != null
-            ? fmtPct01(grossYieldCapped)
-            : "— (no reliable rent data)";
-        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", grossYieldDisplay],
-                ["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;
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404) {
+                return structuredResult(`## Zip Code Detail — ${args.zipCode}\n\n` +
+                    `_No data found for zip code "${args.zipCode}". Verify the 5-digit zip code is correct. ` +
+                    `Use sfr_zip_finder to discover zip codes with investment data._`, { zipCode: args.zipCode, error: "not_found" }, [action("sfr_zip_finder", "Find valid zip codes", {})]);
+            }
+            throw err;
         }
-        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: grossYieldCapped,
-            instOwnPercentage: data.instOwnPercentage,
-            incomeRelativeToMsa: data.incomeRelativeToMsa,
-        };
-        return structuredResult(lines.join("\n"), structured, actions);
     });
 }
 //# sourceMappingURL=zipDetail.js.map

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

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

package/dist/tools/sfr/zipFinder.js

@@ -22,18 +22,6 @@ export function registerZipFinderTool(server, sfr) {
             "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 rawItems = data?.data ?? data?.results ?? (Array.isArray(data) ? data : []);
-        const total = data?.total ?? data?.count ?? rawItems.length;
         const normalizedSort = (args.sort ?? "").toLowerCase();
         const isGrossYieldSort = normalizedSort.includes("gross_yield") || normalizedSort.includes("grossyield");
         // Workaround for upstream API bug: grossYield can be corrupt (>1.0) when rent is null.
@@ -46,6 +34,20 @@ export function registerZipFinderTool(server, sfr) {
                 return null;
             return n;
         };
+        // When sorting by yield, over-fetch to compensate for corrupt data being filtered out.
+        // The top results from the API often have invalid yields (>40% from null rents).
+        const fetchPageSize = isGrossYieldSort ? Math.min(args.page_size * 4, 100) : args.page_size;
+        const query = {
+            search_type: args.search_type,
+            page: args.page,
+            page_size: fetchPageSize,
+        };
+        if (args.zips)
+            query.zips = args.zips;
+        if (args.sort)
+            query.sort = args.sort;
+        const data = await sfr.getZipFinder(query);
+        const rawItems = data?.data ?? data?.results ?? (Array.isArray(data) ? data : []);
         const sanitizedItems = rawItems.map((item) => {
             const normalizedGrossYield = normalizeGrossYield(item.grossYield ?? item.gross_yield);
             return {
@@ -54,12 +56,16 @@ export function registerZipFinderTool(server, sfr) {
                 gross_yield: normalizedGrossYield,
             };
         });
-        const items = isGrossYieldSort
+        const allValid = isGrossYieldSort
             ? sanitizedItems.filter((item) => item.grossYield != null || item.gross_yield != null)
             : sanitizedItems;
+        // Trim back to the requested page_size after filtering
+        const items = allValid.slice(0, args.page_size);
+        const filteredOut = sanitizedItems.length - allValid.length;
         const lines = [
             `## Zip Code Finder`,
-            `**Total:** ${total} zips | **Page:** ${args.page}`,
+            `**Total:** ${items.length} zips | **Page:** ${args.page}`,
+            ...(filteredOut > 0 ? [`*${filteredOut} zips excluded due to missing or invalid yield data*`] : []),
             "",
         ];
         if (items.length > 0) {
@@ -81,6 +87,9 @@ export function registerZipFinderTool(server, sfr) {
             ]);
             lines.push(markdownTable(["Zip", "Pop", "Income", "Home Value", "Rent", "Yield", "Inst Own"], rows));
         }
+        else if (filteredOut > 0) {
+            lines.push("All results had invalid yield data and were excluded. Try removing the sort or sorting by a different field (e.g. `-median_home_value`).");
+        }
         else {
             lines.push("```json");
             lines.push(truncatedJson(data, 3000));
@@ -92,7 +101,7 @@ export function registerZipFinderTool(server, sfr) {
             ...(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);
+        return structuredResult(lines.join("\n"), { items, total: items.length, page: args.page }, actions);
     });
 }
 //# sourceMappingURL=zipFinder.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"zipFinder.js","sourceRoot":"","sources":["../../../src/tools/sfr/zipFinder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IACrB,WAAW,EAAE,CAAC;SACX,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;SACpB,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,oEAAoE,CAAC;IACjF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;IACnG,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,4DAA4D,CAAC;CACnG,CAAC,CAAC;AAEH,MAAM,UAAU,qBAAqB,CAAC,MAAiB,EAAE,GAAc;IACrE,gBAAgB,CAAC,MAAM,EACrB,gBAAgB,EAChB;QACE,KAAK,EAAE,mDAAmD;QAC1D,WAAW,EACT,mFAAmF;YACnF,yDAAyD;YACzD,6EAA6E;YAC7E,oDAAoD;YACpD,yDAAyD;QAC3D,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,SAAS;SAC1B,CAAC;QACF,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;QAEtC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,KAAK,CAAQ,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,EAAE,IAAI,IAAI,IAAI,EAAE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClF,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC;QAC5D,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACvD,MAAM,gBAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAEzG,uFAAuF;QACvF,sDAAsD;QACtD,MAAM,mBAAmB,GAAG,CAAC,KAAc,EAAiB,EAAE;YAC5D,IAAI,KAAK,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG;gBAAE,OAAO,IAAI,CAAC;YACzD,OAAO,CAAC,CAAC;QACX,CAAC,CAAC;QAEF,MAAM,cAAc,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAS,EAAE,EAAE;YAChD,MAAM,oBAAoB,GAAG,mBAAmB,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;YACtF,OAAO;gBACL,GAAG,IAAI;gBACP,UAAU,EAAE,oBAAoB;gBAChC,WAAW,EAAE,oBAAoB;aAClC,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,gBAAgB;YAC5B,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,IAAS,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC;YAC3F,CAAC,CAAC,cAAc,CAAC;QAEnB,MAAM,KAAK,GAAG;YACZ,oBAAoB;YACpB,cAAc,KAAK,qBAAqB,IAAI,CAAC,IAAI,EAAE;YACnD,EAAE;SACH,CAAC;QAEF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,CAAC,CAAM,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAClC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;YAEzE,MAAM,QAAQ,GAAG,CAAC,CAAM,EAAE,EAAE;gBAC1B,IAAI,CAAC,IAAI,IAAI;oBAAE,OAAO,GAAG,CAAC;gBAC1B,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;YAC5C,CAAC,CAAC;YACF,MAAM,UAAU,GAAG,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAEpF,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC;gBAC9C,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG;gBAChC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;gBACjB,GAAG,CAAC,CAAC,CAAC,qBAAqB,IAAI,CAAC,CAAC,uBAAuB,EAAE,GAAG,CAAC;gBAC9D,GAAG,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,iBAAiB,EAAE,GAAG,CAAC;gBAClD,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC;gBACvC,QAAQ,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,WAAW,CAAC;gBACvC,UAAU,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,CAAC,mBAAmB,CAAC;aACzD,CAAC,CAAC;YAEH,KAAK,CAAC,IAAI,CAAC,aAAa,CACtB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EACnE,IAAI,CACL,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QACxE,MAAM,OAAO,GAAG;YACd,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,EAAE,wBAAwB,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACpG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,2BAA2B,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1H,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,EAAE,0BAA0B,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACxH,CAAC;QACF,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1F,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"zipFinder.js","sourceRoot":"","sources":["../../../src/tools/sfr/zipFinder.ts"],"names":[],"mappings":"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"}

package/dist/tools/support.d.ts

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

package/dist/tools/support.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { structuredResult } from "./formatters.js";
+import { registerToolSafe } from "./registerToolSafe.js";
+const SUPPORT_EMAIL = "support@sfranalytics.com";
+const CHAT_URL = "https://mcp.sfranalytics.com";
+const CALENDLY_URL = "https://calendly.com/d/ckd7-sw4-g46";
+const Input = z.object({
+    topic: z
+        .enum(["general", "contacts", "address", "keys"])
+        .default("general")
+        .describe("Help topic: 'general' (overview + contact), 'contacts' (getting investor contact data), 'address' (address format issues), 'keys' (API key setup)"),
+});
+export function registerSupportTool(server, config) {
+    const hasSfr = config.sfr !== null;
+    const hasPlr = config.plr !== null;
+    registerToolSafe(server, "sfra_support", {
+        title: "Help, troubleshooting & support (SFRA)",
+        description: "Get help with common issues: API key setup, accessing investor contact data, " +
+            "address format problems, or general guidance. " +
+            "Includes direct support contact info (email, chat, booking link). " +
+            "Call this when a user is stuck, confused, or asks about getting access to more data.",
+        inputSchema: Input,
+    }, async (args) => {
+        const lines = [];
+        const topic = args.topic;
+        if (topic === "general" || topic === "keys") {
+            lines.push("## API Keys & Data Access", "");
+            lines.push("SFR Analytics has two APIs, each with its own key:", "", "| API | What it covers | Tools |", "|-----|---------------|-------|", `| **SFR** | Property transactions, buyer rankings, rental stats, zip screening, flip activity | 21 tools (sfr_*) ${hasSfr ? "— **connected**" : "— not configured"} |`, `| **PLR** | Private lending: borrower search, loan history, **contact info** (phone/email), lender intelligence | 17 tools (plr_*) ${hasPlr ? "— **connected**" : "— not configured"} |`, "");
+            if (!hasSfr || !hasPlr) {
+                lines.push(`You currently have ${hasSfr && hasPlr ? "both" : hasSfr ? "SFR only" : hasPlr ? "PLR only" : "no"} API key(s) configured.`, !hasPlr ? "Add a PLR key to unlock investor contact info, lending history, and borrower intelligence." : "", !hasSfr ? "Add an SFR key to unlock property data, buyer rankings, and market analytics." : "", "");
+            }
+            lines.push("### Setup", "**Recommended (HTTP — auto-updates):**", "```", "claude mcp add sfranalytics --transport http https://mcp.sfranalytics.com/mcp \\", '  -H "Api-Token: <YOUR_KEY>"', "```", "A single Api-Token works if your key covers one API. For both APIs, use separate headers:", "```", '  -H "SFR-Api-Token: <SFR_KEY>" -H "PLR-Api-Token: <PLR_KEY>"', "```", "");
+        }
+        if (topic === "general" || topic === "contacts") {
+            lines.push("## Investor Contact Data", "");
+            lines.push("Contact information (phone, email, principal names) is available through **PLR API tools**:", "- `plr_borrower_profile` — Full profile including contacts, lending history, and lender relationships", "- `plr_borrower_contacts` — Direct contact lookup (phone, email, social links)", "- `plr_borrower_search` — Find borrowers by geography, loan type, and contact availability", "");
+            if (hasPlr) {
+                lines.push("You have a PLR key configured — these tools are available to you now.", "**Workflow:** sfr_top_buyers (find investors) -> plr_borrower_profile (contacts + lending activity)", "");
+            }
+            else {
+                lines.push("**You need a PLR API key to access contact data.** The SFR API shows which buyers have contacts " +
+                    "(Contact* column in sfr_top_buyers) but cannot expose the actual phone/email fields.", "", "Get a PLR key to unlock investor contacts, lending history, and borrower intelligence.", "");
+            }
+        }
+        if (topic === "general" || topic === "address") {
+            lines.push("## Address Format Troubleshooting", "");
+            lines.push("Address-based tools require **exact matches** against the recorded dataset. Common issues:", "", "- **Directional prefixes matter:** '123 University Dr' vs '123 **E** University Dr'", "- **Abbreviations matter:** 'Street' vs 'St', 'Avenue' vs 'Ave', 'Boulevard' vs 'Blvd'", "- **Unit numbers:** Include or exclude exactly as recorded", "- **Format:** '123 Main St, Phoenix, AZ 85004' (street, city, state zip)", "", "**If a property lookup fails:** Use `sfr_search_properties` with the zip code to browse " +
+                "recent transactions and find the exact recorded address.", "");
+        }
+        // Always include contact info
+        lines.push("---", "### Get Help", `- **Chat:** ${CHAT_URL} (bottom-right chat widget)`, `- **Email:** ${SUPPORT_EMAIL}`, `- **Book a call:** ${CALENDLY_URL}`);
+        return structuredResult(lines.join("\n"), {
+            topic,
+            sfrConnected: hasSfr,
+            plrConnected: hasPlr,
+            support: { email: SUPPORT_EMAIL, chat: CHAT_URL, calendly: CALENDLY_URL },
+        });
+    });
+}
+//# sourceMappingURL=support.js.map

package/dist/tools/support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.js","sourceRoot":"","sources":["../../src/tools/support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,aAAa,GAAG,0BAA0B,CAAC;AACjD,MAAM,QAAQ,GAAG,8BAA8B,CAAC;AAChD,MAAM,YAAY,GAAG,qCAAqC,CAAC;AAE3D,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IACrB,KAAK,EAAE,CAAC;SACL,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;SAChD,OAAO,CAAC,SAAS,CAAC;SAClB,QAAQ,CAAC,mJAAmJ,CAAC;CACjK,CAAC,CAAC;AAEH,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,MAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,KAAK,IAAI,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,KAAK,IAAI,CAAC;IAEnC,gBAAgB,CAAC,MAAM,EACrB,cAAc,EACd;QACE,KAAK,EAAE,wCAAwC;QAC/C,WAAW,EACT,+EAA+E;YAC/E,gDAAgD;YAChD,oEAAoE;YACpE,sFAAsF;QACxF,WAAW,EAAE,KAAK;KACnB,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAEzB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;YAC5C,KAAK,CAAC,IAAI,CACR,oDAAoD,EAAE,EAAE,EACxD,kCAAkC,EAClC,iCAAiC,EACjC,oHAAoH,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,IAAI,EACvK,sIAAsI,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,IAAI,EACzL,EAAE,CACH,CAAC;YACF,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;gBACvB,KAAK,CAAC,IAAI,CACR,sBAAsB,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,yBAAyB,EAC3H,CAAC,MAAM,CAAC,CAAC,CAAC,4FAA4F,CAAC,CAAC,CAAC,EAAE,EAC3G,CAAC,MAAM,CAAC,CAAC,CAAC,+EAA+E,CAAC,CAAC,CAAC,EAAE,EAC9F,EAAE,CACH,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,IAAI,CACR,WAAW,EACX,wCAAwC,EACxC,KAAK,EACL,kFAAkF,EAClF,8BAA8B,EAC9B,KAAK,EACL,2FAA2F,EAC3F,KAAK,EACL,+DAA+D,EAC/D,KAAK,EACL,EAAE,CACH,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;YAC3C,KAAK,CAAC,IAAI,CACR,6FAA6F,EAC7F,uGAAuG,EACvG,gFAAgF,EAChF,4FAA4F,EAC5F,EAAE,CACH,CAAC;YACF,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,CAAC,IAAI,CACR,uEAAuE,EACvE,qGAAqG,EACrG,EAAE,CACH,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CACR,kGAAkG;oBAClG,sFAAsF,EACtF,EAAE,EACF,wFAAwF,EACxF,EAAE,CACH,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CACR,4FAA4F,EAAE,EAAE,EAChG,qFAAqF,EACrF,wFAAwF,EACxF,4DAA4D,EAC5D,0EAA0E,EAAE,EAAE,EAC9E,0FAA0F;gBAC1F,0DAA0D,EAC1D,EAAE,CACH,CAAC;QACJ,CAAC;QAED,8BAA8B;QAC9B,KAAK,CAAC,IAAI,CACR,KAAK,EACL,cAAc,EACd,eAAe,QAAQ,6BAA6B,EACpD,gBAAgB,aAAa,EAAE,EAC/B,sBAAsB,YAAY,EAAE,CACrC,CAAC;QAEF,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACxC,KAAK;YACL,YAAY,EAAE,MAAM;YACpB,YAAY,EAAE,MAAM;YACpB,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE;SAC1E,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sfranalytics/mcp",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "MCP server for SFR Analytics — single-family residential property data, buyer intelligence, and private lending insights",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",