propstack-mcp-server 1.1.0 → 1.2.0

package/dist/tools/composites.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { textResult, errorResult, fmt, fmtPrice, fmtArea, formatError, stripUndefined, unwrapNumber, validateFields, renderFieldValue, CONTACT_FIELDS } from "./helpers.js";
+import { textResult, errorResult, fmt, fmtPrice, fmtArea, formatError, stripUndefined, unwrapNumber, unwrapPropstackValue, validateFields, renderFieldValue, CONTACT_FIELDS } from "./helpers.js";
 import { enrichDealsWithStageNames, fetchPipelines } from "./deals.js";
 function daysBetween(from, to) {
     return Math.floor((to.getTime() - new Date(from).getTime()) / (1000 * 60 * 60 * 24));
@@ -7,24 +7,160 @@ function daysBetween(from, to) {
 function contactName(c) {
     return fmt(c.name) !== "none" ? fmt(c.name) : ([fmt(c.first_name, ""), fmt(c.last_name, "")].filter(Boolean).join(" ") || "Unknown");
 }
+const FEATURE_LABELS = {
+    balcony: "Balcony",
+    lift: "Lift",
+    garden: "Garden",
+    built_in_kitchen: "Built-in kitchen",
+    cellar: "Cellar",
+    rented: "Rented",
+};
+function profileFeatureWanted(value) {
+    const v = unwrapPropstackValue(value);
+    if (v === true || v === "true")
+        return true;
+    if (v === false || v === "false")
+        return false;
+    return null;
+}
+/**
+ * Score one search profile against one property. Each criterion the profile
+ * actually sets adds to maxScore; criteria it leaves empty are ignored, so a
+ * broad profile is not penalised for what it doesn't care about.
+ */
+export function scoreProfileAgainstProperty(sp, property) {
+    let score = 0;
+    let maxScore = 0;
+    const matches = [];
+    const mismatches = [];
+    // Marketing type (weight: 3)
+    if (sp.marketing_type && property.marketing_type) {
+        maxScore += 3;
+        if (sp.marketing_type === property.marketing_type) {
+            score += 3;
+            matches.push(`Type: ${sp.marketing_type}`);
+        }
+        else {
+            mismatches.push(`Type: wants ${sp.marketing_type}, property is ${property.marketing_type}`);
+        }
+    }
+    // City (weight: 3)
+    const propCity = fmt(property.city, "");
+    if (sp.cities?.length && propCity) {
+        maxScore += 3;
+        if (sp.cities.some((c) => propCity.toLowerCase().includes(c.toLowerCase()))) {
+            score += 3;
+            matches.push(`City: ${propCity}`);
+        }
+        else {
+            mismatches.push(`City: wants ${sp.cities.join("/")}, property in ${propCity}`);
+        }
+    }
+    // Price range (weight: 2)
+    const propPrice = unwrapNumber(property.price);
+    if ((sp.price !== null || sp.price_to !== null) && propPrice !== null) {
+        maxScore += 2;
+        const inRange = (sp.price === null || sp.price === undefined || propPrice >= sp.price) &&
+            (sp.price_to === null || sp.price_to === undefined || propPrice <= sp.price_to);
+        if (inRange) {
+            score += 2;
+            matches.push(`Price: ${fmtPrice(property.price)} in range`);
+        }
+        else {
+            mismatches.push(`Price: ${fmtPrice(property.price)} outside ${fmtPrice(sp.price)}–${fmtPrice(sp.price_to)}`);
+        }
+    }
+    // Rent range (weight: 2)
+    const propRent = unwrapNumber(property.base_rent);
+    if ((sp.base_rent !== null || sp.base_rent_to !== null) && propRent !== null) {
+        maxScore += 2;
+        const inRange = (sp.base_rent === null || sp.base_rent === undefined || propRent >= sp.base_rent) &&
+            (sp.base_rent_to === null || sp.base_rent_to === undefined || propRent <= sp.base_rent_to);
+        if (inRange) {
+            score += 2;
+            matches.push(`Rent: ${fmtPrice(property.base_rent)} in range`);
+        }
+        else {
+            mismatches.push(`Rent: ${fmtPrice(property.base_rent)} outside ${fmtPrice(sp.base_rent)}–${fmtPrice(sp.base_rent_to)}`);
+        }
+    }
+    // Rooms (weight: 2)
+    const propRooms = unwrapNumber(property.number_of_rooms);
+    if ((sp.number_of_rooms !== null || sp.number_of_rooms_to !== null) && propRooms !== null) {
+        maxScore += 2;
+        const inRange = (sp.number_of_rooms === null || sp.number_of_rooms === undefined || propRooms >= sp.number_of_rooms) &&
+            (sp.number_of_rooms_to === null || sp.number_of_rooms_to === undefined || propRooms <= sp.number_of_rooms_to);
+        if (inRange) {
+            score += 2;
+            matches.push(`Rooms: ${fmt(property.number_of_rooms)}`);
+        }
+        else {
+            mismatches.push(`Rooms: ${fmt(property.number_of_rooms)} outside ${fmt(sp.number_of_rooms)}–${fmt(sp.number_of_rooms_to)}`);
+        }
+    }
+    // Living space (weight: 1)
+    const propSpace = unwrapNumber(property.living_space);
+    if ((sp.living_space !== null || sp.living_space_to !== null) && propSpace !== null) {
+        maxScore += 1;
+        const inRange = (sp.living_space === null || sp.living_space === undefined || propSpace >= sp.living_space) &&
+            (sp.living_space_to === null || sp.living_space_to === undefined || propSpace <= sp.living_space_to);
+        if (inRange) {
+            score += 1;
+            matches.push(`Space: ${fmtArea(property.living_space)}`);
+        }
+        else {
+            mismatches.push(`Space: ${fmtArea(property.living_space)} outside ${fmt(sp.living_space)}–${fmt(sp.living_space_to)} m²`);
+        }
+    }
+    // Property type (weight: 2)
+    const propRsType = fmt(property.rs_type, "");
+    if (sp.rs_types?.length && propRsType) {
+        maxScore += 2;
+        if (sp.rs_types.includes(propRsType)) {
+            score += 2;
+            matches.push(`Property type: ${propRsType}`);
+        }
+        else {
+            mismatches.push(`Property type: wants ${sp.rs_types.join("/")}, is ${propRsType}`);
+        }
+    }
+    // Features (weight: 1 each) — profile says "true" (required) or "false" (excluded)
+    const record = property;
+    const spRecord = sp;
+    for (const [key, label] of Object.entries(FEATURE_LABELS)) {
+        const wanted = profileFeatureWanted(spRecord[key]);
+        const has = unwrapPropstackValue(record[key]);
+        if (wanted === null || (has !== true && has !== false))
+            continue;
+        maxScore += 1;
+        if (has === wanted) {
+            score += 1;
+            matches.push(`${label}: ${has ? "yes" : "no"}`);
+        }
+        else {
+            mismatches.push(`${label}: wants ${wanted ? "yes" : "no"}, is ${has ? "yes" : "no"}`);
+        }
+    }
+    return { score, maxScore, matches, mismatches };
+}
 // ── Tool registration ────────────────────────────────────────────────
 export function registerCompositeTools(server, client) {
     // ── full_contact_360 ────────────────────────────────────────────
-    server.tool("full_contact_360", `Get a complete 360° view of a contact — everything you need before calling a client.
-
-Combines 4 API calls in parallel:
-- Full contact details with children, documents, relationships, owned properties
-- Search profiles (what they're looking for)
-- Active deals (which properties they're linked to)
-- Recent activity (last 10 interactions)
-
-Returns a complete contact dossier in one request. Use this when you
-need the full picture: "Tell me everything about Herr Weber."
-
-Data minimization (Art. 25 DSGVO): pass 'fields' with an array of contact
-field names to limit the contact detail section to only those fields (e.g.
-["first_name", "last_name", "email"]). The search profiles, deals, and
-activity sections are unaffected. Omit 'fields' for the full detail section.
+    server.tool("full_contact_360", `Get a complete 360° view of a contact — everything you need before calling a client.
+
+Combines 4 API calls in parallel:
+- Full contact details with children, documents, relationships, owned properties
+- Search profiles (what they're looking for)
+- Active deals (which properties they're linked to)
+- Recent activity (last 10 interactions)
+
+Returns a complete contact dossier in one request. Use this when you
+need the full picture: "Tell me everything about Herr Weber."
+
+Data minimization (Art. 25 DSGVO): pass 'fields' with an array of contact
+field names to limit the contact detail section to only those fields (e.g.
+["first_name", "last_name", "email"]). The search profiles, deals, and
+activity sections are unaffected. Omit 'fields' for the full detail section.
 Unknown field names produce an error listing the valid options.`, {
         contact_id: z.number()
             .describe("Contact ID to get 360° view for"),
@@ -207,17 +343,17 @@ Unknown field names produce an error listing the valid options.`, {
         }
     });
     // ── property_performance_report ─────────────────────────────────
-    server.tool("property_performance_report", `Performance report for a property — days on market, inquiry count,
-pipeline breakdown, and activity summary.
-
-Combines 3 API calls in parallel:
-- Full property details (with custom fields)
-- All deals/inquiries for this property
-- Activity feed (last 50 interactions)
-
-Calculates: days on market, total inquiries, deals by stage/category,
-and recent activity breakdown by type.
-
+    server.tool("property_performance_report", `Performance report for a property — days on market, inquiry count,
+pipeline breakdown, and activity summary.
+
+Combines 3 API calls in parallel:
+- Full property details (with custom fields)
+- All deals/inquiries for this property
+- Activity feed (last 50 interactions)
+
+Calculates: days on market, total inquiries, deals by stage/category,
+and recent activity breakdown by type.
+
 Use when asked: "How is the Friedrichstr property doing?"`, {
         property_id: z.number()
             .describe("Property ID to generate report for"),
@@ -347,15 +483,15 @@ Use when asked: "How is the Friedrichstr property doing?"`, {
         }
     });
     // ── pipeline_summary ────────────────────────────────────────────
-    server.tool("pipeline_summary", `Pipeline overview — deals per stage, total values, and stale deals
-needing attention.
-
-Fetches all deal pipelines and deals, then aggregates:
-- Deal count per stage
-- Total value per stage (from deal price or property price)
-- Stale deals: deals with no update in 14+ days
-
-Filter by pipeline_id and/or broker_id. Use when asked:
+    server.tool("pipeline_summary", `Pipeline overview — deals per stage, total values, and stale deals
+needing attention.
+
+Fetches all deal pipelines and deals, then aggregates:
+- Deal count per stage
+- Total value per stage (from deal price or property price)
+- Stale deals: deals with no update in 14+ days
+
+Filter by pipeline_id and/or broker_id. Use when asked:
 "How's the pipeline looking?" or "Give me a sales overview."`, {
         pipeline_id: z.number().optional()
             .describe("Filter by specific pipeline ID"),
@@ -474,18 +610,18 @@ Filter by pipeline_id and/or broker_id. Use when asked:
         }
     });
     // ── smart_lead_intake ───────────────────────────────────────────
-    server.tool("smart_lead_intake", `Complete lead intake workflow — dedup check, create/update contact,
-log notes, create deal if specific property, and set follow-up reminder.
-
-Perfect for post-call processing from a voice agent. Handles the entire
-intake in one tool call:
-
-1. If phone or email provided → search for existing contact (dedup)
-2. If found → update contact; if not → create new contact
-3. If notes provided → log as a note task
-4. If property_id provided → create deal at first pipeline stage
-5. Create follow-up reminder for broker (due tomorrow 9am)
-
+    server.tool("smart_lead_intake", `Complete lead intake workflow — dedup check, create/update contact,
+log notes, create deal if specific property, and set follow-up reminder.
+
+Perfect for post-call processing from a voice agent. Handles the entire
+intake in one tool call:
+
+1. If phone or email provided → search for existing contact (dedup)
+2. If found → update contact; if not → create new contact
+3. If notes provided → log as a note task
+4. If property_id provided → create deal at first pipeline stage
+5. Create follow-up reminder for broker (due tomorrow 9am)
+
 Returns what was done: created vs updated, IDs of all created records.`, {
         first_name: z.string()
             .describe("Contact first name"),
@@ -647,17 +783,17 @@ Returns what was done: created vs updated, IDs of all created records.`, {
         }
     });
     // ── match_contacts_to_property ──────────────────────────────────
-    server.tool("match_contacts_to_property", `Find contacts whose search profiles match a property. Returns a
-ranked list with match scores.
-
-Use when a new listing comes in to find potential buyers/renters:
-"Who should I send this new listing to?"
-
-Logic:
-1. Fetches the property details (type, price, rooms, space, city, features)
-2. Fetches active search profiles (paginates, capped by max_profiles)
-3. Scores each profile against the property on: marketing type, city,
-   price range, room count, living space, property type, and features
+    server.tool("match_contacts_to_property", `Find contacts whose search profiles match a property. Returns a
+ranked list with match scores.
+
+Use when a new listing comes in to find potential buyers/renters:
+"Who should I send this new listing to?"
+
+Logic:
+1. Fetches the property details (type, price, rooms, space, city, features)
+2. Fetches active search profiles (paginates, capped by max_profiles)
+3. Scores each profile against the property on: marketing type, city,
+   price range, room count, living space, property type, and features
 4. Returns top 20 matches sorted by score with match/mismatch details`, {
         property_id: z.number()
             .describe("Property ID to find matching contacts for"),
@@ -691,101 +827,7 @@ Logic:
             for (const sp of allProfiles) {
                 if (!sp.active)
                     continue;
-                let score = 0;
-                let maxScore = 0;
-                const matches = [];
-                const mismatches = [];
-                // Marketing type (weight: 3)
-                if (sp.marketing_type && property.marketing_type) {
-                    maxScore += 3;
-                    if (sp.marketing_type === property.marketing_type) {
-                        score += 3;
-                        matches.push(`Type: ${sp.marketing_type}`);
-                    }
-                    else {
-                        mismatches.push(`Type: wants ${sp.marketing_type}, property is ${property.marketing_type}`);
-                    }
-                }
-                // City (weight: 3)
-                const propCity = fmt(property.city, "");
-                if (sp.cities?.length && propCity) {
-                    maxScore += 3;
-                    if (sp.cities.some((c) => propCity.toLowerCase().includes(c.toLowerCase()))) {
-                        score += 3;
-                        matches.push(`City: ${propCity}`);
-                    }
-                    else {
-                        mismatches.push(`City: wants ${sp.cities.join("/")}, property in ${propCity}`);
-                    }
-                }
-                // Price range (weight: 2)
-                const propPrice = unwrapNumber(property.price);
-                if ((sp.price !== null || sp.price_to !== null) && propPrice !== null) {
-                    maxScore += 2;
-                    const inRange = (sp.price === null || sp.price === undefined || propPrice >= sp.price) &&
-                        (sp.price_to === null || sp.price_to === undefined || propPrice <= sp.price_to);
-                    if (inRange) {
-                        score += 2;
-                        matches.push(`Price: ${fmtPrice(property.price)} in range`);
-                    }
-                    else {
-                        mismatches.push(`Price: ${fmtPrice(property.price)} outside ${fmtPrice(sp.price)}–${fmtPrice(sp.price_to)}`);
-                    }
-                }
-                // Rent range (weight: 2)
-                const propRent = unwrapNumber(property.base_rent);
-                if ((sp.base_rent !== null || sp.base_rent_to !== null) && propRent !== null) {
-                    maxScore += 2;
-                    const inRange = (sp.base_rent === null || sp.base_rent === undefined || propRent >= sp.base_rent) &&
-                        (sp.base_rent_to === null || sp.base_rent_to === undefined || propRent <= sp.base_rent_to);
-                    if (inRange) {
-                        score += 2;
-                        matches.push(`Rent: ${fmtPrice(property.base_rent)} in range`);
-                    }
-                    else {
-                        mismatches.push(`Rent: ${fmtPrice(property.base_rent)} outside ${fmtPrice(sp.base_rent)}–${fmtPrice(sp.base_rent_to)}`);
-                    }
-                }
-                // Rooms (weight: 2)
-                const propRooms = unwrapNumber(property.number_of_rooms);
-                if ((sp.number_of_rooms !== null || sp.number_of_rooms_to !== null) && propRooms !== null) {
-                    maxScore += 2;
-                    const inRange = (sp.number_of_rooms === null || sp.number_of_rooms === undefined || propRooms >= sp.number_of_rooms) &&
-                        (sp.number_of_rooms_to === null || sp.number_of_rooms_to === undefined || propRooms <= sp.number_of_rooms_to);
-                    if (inRange) {
-                        score += 2;
-                        matches.push(`Rooms: ${fmt(property.number_of_rooms)}`);
-                    }
-                    else {
-                        mismatches.push(`Rooms: ${fmt(property.number_of_rooms)} outside ${fmt(sp.number_of_rooms)}–${fmt(sp.number_of_rooms_to)}`);
-                    }
-                }
-                // Living space (weight: 1)
-                const propSpace = unwrapNumber(property.living_space);
-                if ((sp.living_space !== null || sp.living_space_to !== null) && propSpace !== null) {
-                    maxScore += 1;
-                    const inRange = (sp.living_space === null || sp.living_space === undefined || propSpace >= sp.living_space) &&
-                        (sp.living_space_to === null || sp.living_space_to === undefined || propSpace <= sp.living_space_to);
-                    if (inRange) {
-                        score += 1;
-                        matches.push(`Space: ${fmtArea(property.living_space)}`);
-                    }
-                    else {
-                        mismatches.push(`Space: ${fmtArea(property.living_space)} outside ${fmt(sp.living_space)}–${fmt(sp.living_space_to)} m²`);
-                    }
-                }
-                // Property type (weight: 2)
-                const propRsType = fmt(property.rs_type, "");
-                if (sp.rs_types?.length && propRsType) {
-                    maxScore += 2;
-                    if (sp.rs_types.includes(propRsType)) {
-                        score += 2;
-                        matches.push(`Property type: ${propRsType}`);
-                    }
-                    else {
-                        mismatches.push(`Property type: wants ${sp.rs_types.join("/")}, is ${propRsType}`);
-                    }
-                }
+                const { score, maxScore, matches, mismatches } = scoreProfileAgainstProperty(sp, property);
                 // Only include profiles that matched on at least 1 criterion
                 if (score > 0) {
                     results.push({
@@ -828,5 +870,122 @@ Logic:
             return errorResult("Property matching", err);
         }
     });
+    // ── match_properties_to_contact ─────────────────────────────────
+    server.tool("match_properties_to_contact", `Reverse matching: find properties that fit a contact's search profiles.
+
+The counterpart to match_contacts_to_property. Use it for "Which of our
+listings fit Herr Weber?" or before calling a buyer.
+
+Logic:
+1. Loads the contact's active search profiles (or one specific profile)
+2. Pre-filters properties via the API on marketing type, price/rent,
+   rooms and living space (single property type too, when the profile
+   names exactly one)
+3. Scores every candidate on type, city, price/rent, rooms, space,
+   property type and features (balcony, lift, garden, kitchen, cellar,
+   rented)
+4. Returns the top 20 properties with score and match/mismatch details
+
+Tip: pass status with the IDs of your "on the market" statuses
+(get_property_statuses) so sold or reserved listings are left out.
+Scores are a shortlist for the agent to review, not an automatic decision.`, {
+        contact_id: z.number()
+            .describe("Contact whose search profiles should be matched"),
+        search_profile_id: z.number().optional()
+            .describe("Only use this search profile (default: all active profiles of the contact)"),
+        status: z.string().optional()
+            .describe("Comma-separated property status IDs to consider (use get_property_statuses)"),
+        max_properties: z.number().optional()
+            .describe("Max candidate properties to fetch per profile (default: 300)"),
+    }, async (args) => {
+        try {
+            const profilesRes = await client.get("/saved_queries", { params: { client: args.contact_id, per: 100 } });
+            let profiles = (profilesRes.data ?? []).filter((sp) => sp.active);
+            if (args.search_profile_id !== undefined) {
+                profiles = (profilesRes.data ?? []).filter((sp) => sp.id === args.search_profile_id);
+                if (profiles.length === 0) {
+                    return textResult(`Search profile ${args.search_profile_id} not found for contact ${args.contact_id}.`);
+                }
+            }
+            if (profiles.length === 0) {
+                return textResult(`Contact ${args.contact_id} has no active search profiles. ` +
+                    `Create one with create_search_profile first.`);
+            }
+            const maxProperties = args.max_properties ?? 300;
+            const best = new Map();
+            let candidatesChecked = 0;
+            for (const sp of profiles) {
+                const params = {
+                    with_meta: 1,
+                    per_page: 100,
+                    marketing_type: sp.marketing_type ?? undefined,
+                    price_from: sp.price ?? undefined,
+                    price_to: sp.price_to ?? undefined,
+                    base_rent_from: sp.base_rent ?? undefined,
+                    base_rent_to: sp.base_rent_to ?? undefined,
+                    number_of_rooms_from: sp.number_of_rooms ?? undefined,
+                    number_of_rooms_to: sp.number_of_rooms_to ?? undefined,
+                    living_space_from: sp.living_space ?? undefined,
+                    living_space_to: sp.living_space_to ?? undefined,
+                    rs_type: sp.rs_types?.length === 1 ? sp.rs_types[0] : undefined,
+                    status: args.status,
+                };
+                const candidates = [];
+                let page = 1;
+                while (candidates.length < maxProperties) {
+                    const res = await client.get("/units", { params: { ...params, page } });
+                    const batch = res.data ?? [];
+                    candidates.push(...batch);
+                    const total = res.meta?.total_count ?? 0;
+                    if (batch.length === 0 || candidates.length >= total)
+                        break;
+                    page++;
+                }
+                candidatesChecked += candidates.length;
+                for (const property of candidates.slice(0, maxProperties)) {
+                    const result = scoreProfileAgainstProperty(sp, property);
+                    if (result.score === 0)
+                        continue;
+                    const prev = best.get(property.id);
+                    const ratio = result.maxScore > 0 ? result.score / result.maxScore : 0;
+                    const prevRatio = prev && prev.result.maxScore > 0 ? prev.result.score / prev.result.maxScore : -1;
+                    if (!prev || ratio > prevRatio) {
+                        best.set(property.id, { property, profileId: sp.id, result });
+                    }
+                }
+            }
+            const ranked = [...best.values()].sort((a, b) => {
+                const ra = a.result.maxScore > 0 ? a.result.score / a.result.maxScore : 0;
+                const rb = b.result.maxScore > 0 ? b.result.score / b.result.maxScore : 0;
+                return rb - ra || b.result.score - a.result.score || a.result.mismatches.length - b.result.mismatches.length;
+            });
+            const top = ranked.slice(0, 20);
+            if (top.length === 0) {
+                return textResult(`No matching properties found for contact ${args.contact_id} ` +
+                    `(${profiles.length} search profile(s), ${candidatesChecked} candidate properties checked).`);
+            }
+            const header = [
+                `# Matching Properties for Contact #${args.contact_id}`,
+                `Search profiles used: ${profiles.map((sp) => `#${sp.id}`).join(", ")}`,
+                "",
+                `Found **${ranked.length}** matching properties out of ${candidatesChecked} candidates (showing top ${top.length}):`,
+                "",
+            ].join("\n");
+            const lines = top.map(({ property: p, profileId, result: m }, i) => {
+                const pct = m.maxScore > 0 ? Math.round((m.score / m.maxScore) * 100) : 0;
+                const price = p.price ? fmtPrice(p.price) : p.base_rent ? `${fmtPrice(p.base_rent)} rent` : "no price";
+                return [
+                    `**${i + 1}. ${fmt(p.title, "Untitled")}** (ID: ${p.id}) — Score: ${m.score}/${m.maxScore} (${pct}%) — Profile #${profileId}`,
+                    `  ${fmt(p.city, "?")} · ${price} · ${fmt(p.number_of_rooms)} rooms · ${fmtArea(p.living_space)}`,
+                    m.matches.length ? `  Matches: ${m.matches.join(", ")}` : null,
+                    m.mismatches.length ? `  Mismatches: ${m.mismatches.join(", ")}` : null,
+                ].filter(Boolean).join("\n");
+            });
+            return textResult(header + lines.join("\n\n"));
+        }
+        catch (err) {
+            return errorResult("Property matching", err);
+        }
+    });
 }
 //# sourceMappingURL=composites.js.map