@rubytech/create-realagent-code 0.1.117 → 0.1.120

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@maxy/buyers",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "neo4j-driver": "^5.28.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.2"
+  }
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/index.ts

@@ -0,0 +1,145 @@
+// buyers MCP server — visitor-graph tools (Task 357).
+//
+// Seven tools, all admin-side (none exposed on the public agent):
+//   visitor-recent-by-person      query
+//   visitor-recent-by-page        query
+//   visitor-engagement-score      query
+//   visitor-recommendation-ctr    query (replaces 336 log-scan after parity)
+//   visitor-session-detail        query
+//   visitor-event-ingest          write (test harness / manual replay)
+//   visitor-backfill-from-logs    write (one-shot importer + parity check)
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { closeDriver } from "./lib/neo4j.js";
+import { visitorRecentByPerson } from "./tools/visitor-recent-by-person.js";
+import { visitorRecentByPage } from "./tools/visitor-recent-by-page.js";
+import { visitorEngagementScore } from "./tools/visitor-engagement-score.js";
+import { visitorRecommendationCtr } from "./tools/visitor-recommendation-ctr.js";
+import { visitorSessionDetail } from "./tools/visitor-session-detail.js";
+import { visitorEventIngest } from "./tools/visitor-event-ingest.js";
+import { visitorBackfillFromLogs } from "./tools/visitor-backfill-from-logs.js";
+
+const accountId = process.env.ACCOUNT_ID ?? "local";
+
+const server = new McpServer({ name: "maxy-buyers", version: "0.1.0" });
+
+console.error(`[buyers] server started, account=${accountId}`);
+
+function jsonHandler<T>(fn: (p: Record<string, unknown>) => Promise<T>) {
+  return async (params: Record<string, unknown>) => {
+    try {
+      const result = await fn({ ...params, accountId });
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+        isError: true,
+      };
+    }
+  };
+}
+
+server.tool(
+  "visitor-recent-by-person",
+  "List recent visitor sessions for a known :Person. Returns per-session pageview/click/scroll/dwell counts and the listings each session touched. Use for morning-round briefings and 1:1 outreach context.",
+  {
+    personId: z.string().min(1).describe(":Person elementId"),
+    sinceDays: z.number().int().positive().optional().describe("Lookback window in days (default 30)"),
+    limit: z.number().int().positive().max(200).optional().describe("Max sessions to return (default 50)"),
+  },
+  jsonHandler((p) => visitorRecentByPerson(p as unknown as Parameters<typeof visitorRecentByPerson>[0])),
+);
+
+server.tool(
+  "visitor-recent-by-page",
+  "List recent visitors (Person + AnonVisitor) of a given listing slug or URL. Use to answer 'who has shown interest in 12 Oak Street this week?'.",
+  {
+    listingSlug: z.string().optional().describe("Listing slug (one of slug/url required)"),
+    url: z.string().optional().describe("Page URL (one of slug/url required)"),
+    sinceDays: z.number().int().positive().optional().describe("Lookback window in days (default 7)"),
+    limit: z.number().int().positive().max(200).optional().describe("Max visitors to return (default 50)"),
+  },
+  jsonHandler((p) => visitorRecentByPage(p as unknown as Parameters<typeof visitorRecentByPage>[0])),
+);
+
+server.tool(
+  "visitor-engagement-score",
+  "Engagement-ranked :Person list. score = visits * recency * scroll_depth * dwell. Use to build the nurture-list and prioritise outbound.",
+  {
+    sinceDays: z.number().int().positive().optional().describe("Lookback window in days (default 30)"),
+    limit: z.number().int().positive().max(200).optional().describe("Max persons (default 50)"),
+  },
+  jsonHandler((p) => visitorEngagementScore(p as unknown as Parameters<typeof visitorEngagementScore>[0])),
+);
+
+server.tool(
+  "visitor-recommendation-ctr",
+  "Graph-backed click-through rate for property recommendations over a window. Replaces the Task 336 log-scan after the 14-day parity cutover.",
+  {
+    sinceDays: z.number().int().positive().optional().describe("Lookback window in days (default 7)"),
+    listingSlug: z.string().optional().describe("Optional listing-slug filter"),
+  },
+  jsonHandler((p) => visitorRecommendationCtr(p as unknown as Parameters<typeof visitorRecommendationCtr>[0])),
+);
+
+server.tool(
+  "visitor-session-detail",
+  "Full event timeline for one :Session (pageviews, clicks, scroll milestones in chronological order). Use for diagnosis and outreach prep.",
+  {
+    sessionId: z.string().min(1).describe(":Session.sessionId"),
+  },
+  jsonHandler((p) => visitorSessionDetail(p as unknown as Parameters<typeof visitorSessionDetail>[0])),
+);
+
+server.tool(
+  "visitor-event-ingest",
+  "Admin-side companion to POST /v/event for test harness and manual replay. Writes a single event into the graph.",
+  {
+    type: z.enum(["pageview", "click", "scroll", "dwell"]).describe("Event type"),
+    sessionId: z.string().min(1).describe("Client-provided session id"),
+    visitorId: z.string().min(1).describe("Client-provided visitor id"),
+    personId: z.string().optional().nullable().describe("Optional :Person elementId override"),
+    url: z.string().min(1).describe("Page URL"),
+    path: z.string().optional(),
+    title: z.string().optional(),
+    pageViewId: z.string().optional(),
+    site: z.string().optional(),
+    referrer: z.string().optional(),
+    label: z.string().optional().describe("Click label (data-track value)"),
+    href: z.string().optional(),
+    depth: z.number().int().min(0).max(100).optional().describe("Scroll depth (25/50/75/100)"),
+    dwellMs: z.number().int().min(0).optional(),
+    occurredAt: z.string().optional().describe("ISO timestamp override"),
+  },
+  jsonHandler((p) => visitorEventIngest(p as unknown as Parameters<typeof visitorEventIngest>[0])),
+);
+
+server.tool(
+  "visitor-backfill-from-logs",
+  "One-shot importer: parse [property-recommended] and [property-card-click] log lines and write into the visitor graph. Idempotent for Recommendations; immutable for Click events. Reports a parityCheck comparing graph counts to log counts.",
+  {
+    logPath: z.string().min(1).describe("Absolute path to the platform log file"),
+    sinceIso: z.string().optional().describe("ISO timestamp lower bound (inclusive)"),
+    untilIso: z.string().optional().describe("ISO timestamp upper bound (exclusive)"),
+    batchSize: z.number().int().positive().max(2000).optional().describe("Lines per Cypher batch (default 200)"),
+  },
+  jsonHandler((p) => visitorBackfillFromLogs(p as unknown as Parameters<typeof visitorBackfillFromLogs>[0])),
+);
+
+process.on("SIGINT", async () => {
+  console.error("[buyers] SIGINT — closing driver");
+  await closeDriver();
+  process.exit(0);
+});
+process.on("SIGTERM", async () => {
+  console.error("[buyers] SIGTERM — closing driver");
+  await closeDriver();
+  process.exit(0);
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[buyers] ready");

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/lib/neo4j.ts

@@ -0,0 +1,45 @@
+// Neo4j driver/session helper — same pattern as loop/mcp/src/lib/neo4j.ts.
+// NEO4J_URI must be explicit; defaulting to localhost cross-pollinates
+// Maxy and Real Agent databases on a shared dev host.
+
+import neo4j, { Driver, Session } from "neo4j-driver";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+let driver: Driver | null = null;
+
+function readPassword(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+  const passwordFile = resolve(
+    process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../.."),
+    "config/.neo4j-password",
+  );
+  try {
+    return readFileSync(passwordFile, "utf-8").trim();
+  } catch {
+    throw new Error(`Neo4j password not found. Expected at ${passwordFile} or in NEO4J_PASSWORD env var.`);
+  }
+}
+
+export function getDriver(): Driver {
+  if (!driver) {
+    const uri = process.env.NEO4J_URI;
+    if (!uri) throw new Error("[buyers] NEO4J_URI unset — refusing to default to bolt://localhost:7687");
+    const user = process.env.NEO4J_USER ?? "neo4j";
+    const password = readPassword();
+    console.error(`[buyers] resolved neo4j_uri=${uri}`);
+    driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+  }
+  return driver;
+}
+
+export function getSession(): Session {
+  return getDriver().session();
+}
+
+export async function closeDriver(): Promise<void> {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/tools/visitor-backfill-from-logs.ts

@@ -0,0 +1,189 @@
+// visitor-backfill-from-logs — one-shot importer.
+//
+// Parses [property-recommended] and [property-card-click] log lines from
+// the platform log and writes them into the visitor graph:
+//
+//   [property-recommended] sessionKey=<sk> listingSlug=<slug> ts=<iso>
+//     -> MERGE (Session {sessionKey})
+//        CREATE (Recommendation {sessionKey, listingSlug, recommendedAt})
+//        MERGE (Recommendation)-[:FOR_SESSION]->(Session)
+//
+//   [property-card-click] sessionKey=<sk> listingSlug=<slug> ts=<iso>
+//     -> MATCH/MERGE Session, CREATE Click {label:'card', listingSlug}
+//        MERGE Session-[:HAS_EVENT]->Click
+//
+// Parity check after backfill: graph counts vs log-scan counts for the
+// same window. parityCheck is 'ok' iff both deltas are zero, otherwise
+// 'mismatch' with the delta surfaced for diagnosis.
+//
+// Idempotency: re-running over the same log window does not duplicate
+// Recommendation nodes (MERGE on the exact sessionKey + slug + ts tuple).
+// Click nodes are immutable event records by design; if you re-run on a
+// window already processed you get duplicates. Operator runs once per
+// cutover.
+
+import { readFileSync } from "node:fs";
+import { getSession } from "../lib/neo4j.js";
+
+export interface BackfillParams {
+  accountId: string;
+  logPath: string;
+  sinceIso?: string;
+  untilIso?: string;
+  batchSize?: number;
+}
+
+export interface BackfillResult {
+  windowStart: string | null;
+  windowEnd: string | null;
+  recommendedParsed: number;
+  recommendedWritten: number;
+  recommendedSkippedDuplicate: number;
+  clickedParsed: number;
+  clickedWritten: number;
+  unparseable: number;
+  parityCheck: "ok" | "mismatch";
+  parityDelta: { recommended: number; clicked: number };
+}
+
+interface RecLine { kind: "rec"; sessionKey: string; listingSlug: string; ts: string }
+interface ClickLine { kind: "click"; sessionKey: string; listingSlug: string; ts: string }
+type Line = RecLine | ClickLine
+
+const REC_RE = /\[property-recommended\]\s+sessionKey=(\S+)\s+listingSlug=(\S+)\s+ts=(\S+)/;
+const CLICK_RE = /\[property-card-click\]\s+sessionKey=(\S+)\s+listingSlug=(\S+)\s+ts=(\S+)/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+
+function parseLine(line: string): Line | null {
+  let m = REC_RE.exec(line);
+  if (m) return { kind: "rec", sessionKey: m[1], listingSlug: m[2], ts: m[3] };
+  m = CLICK_RE.exec(line);
+  if (m) return { kind: "click", sessionKey: m[1], listingSlug: m[2], ts: m[3] };
+  return null;
+}
+
+function inWindow(iso: string, sinceMs: number | null, untilMs: number | null): boolean {
+  if (!ISO_RE.test(iso)) return false;
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return false;
+  if (sinceMs !== null && t < sinceMs) return false;
+  if (untilMs !== null && t >= untilMs) return false;
+  return true;
+}
+
+export async function visitorBackfillFromLogs(p: BackfillParams): Promise<BackfillResult> {
+  const sinceMs = p.sinceIso ? Date.parse(p.sinceIso) : null;
+  const untilMs = p.untilIso ? Date.parse(p.untilIso) : null;
+  const batchSize = Math.max(10, Math.min(p.batchSize ?? 200, 2000));
+
+  let body: string;
+  try {
+    body = readFileSync(p.logPath, "utf-8");
+  } catch (err) {
+    throw new Error(`[visitor-backfill] log read failed path=${p.logPath} err=${(err as Error).message}`);
+  }
+
+  const rec: RecLine[] = [];
+  const click: ClickLine[] = [];
+  let unparseable = 0;
+  let windowStart: string | null = null;
+  let windowEnd: string | null = null;
+
+  for (const raw of body.split("\n")) {
+    if (!raw || (!raw.includes("[property-recommended]") && !raw.includes("[property-card-click]"))) continue;
+    const parsed = parseLine(raw);
+    if (!parsed) { unparseable += 1; continue; }
+    if (!inWindow(parsed.ts, sinceMs, untilMs)) continue;
+    if (parsed.kind === "rec") rec.push(parsed);
+    else click.push(parsed);
+    if (windowStart === null || parsed.ts < windowStart) windowStart = parsed.ts;
+    if (windowEnd === null || parsed.ts > windowEnd) windowEnd = parsed.ts;
+  }
+
+  const session = getSession();
+  let recommendedWritten = 0;
+  let recommendedSkippedDuplicate = 0;
+  let clickedWritten = 0;
+
+  console.error(`[visitor-backfill] start accountId=${p.accountId} window=${windowStart}..${windowEnd} rec=${rec.length} click=${click.length}`);
+
+  try {
+    for (let i = 0; i < rec.length; i += batchSize) {
+      const slice = rec.slice(i, i + batchSize);
+      const result = await session.run(
+        `UNWIND $rows AS row
+         MERGE (s:Session {accountId: $accountId, sessionId: row.sessionKey})
+           ON CREATE SET s.startedAt = datetime(row.ts), s.lastSeenAt = datetime(row.ts), s.backfilled = true
+           ON MATCH  SET s.lastSeenAt = CASE WHEN s.lastSeenAt > datetime(row.ts) THEN s.lastSeenAt ELSE datetime(row.ts) END
+         MERGE (r:Recommendation {accountId: $accountId, sessionKey: row.sessionKey, listingSlug: row.listingSlug, recommendedAt: datetime(row.ts)})
+           ON CREATE SET r.createdAt = datetime(), r.created = true
+           ON MATCH  SET r.created = false
+         MERGE (r)-[:FOR_SESSION]->(s)
+         RETURN sum(CASE WHEN r.created THEN 1 ELSE 0 END) AS written,
+                sum(CASE WHEN r.created THEN 0 ELSE 1 END) AS skipped`,
+        { accountId: p.accountId, rows: slice },
+      );
+      const row = result.records[0];
+      recommendedWritten += Number(row?.get("written") ?? 0);
+      recommendedSkippedDuplicate += Number(row?.get("skipped") ?? 0);
+    }
+
+    for (let i = 0; i < click.length; i += batchSize) {
+      const slice = click.slice(i, i + batchSize);
+      const result = await session.run(
+        `UNWIND $rows AS row
+         MERGE (s:Session {accountId: $accountId, sessionId: row.sessionKey})
+           ON CREATE SET s.startedAt = datetime(row.ts), s.lastSeenAt = datetime(row.ts), s.backfilled = true
+           ON MATCH  SET s.lastSeenAt = CASE WHEN s.lastSeenAt > datetime(row.ts) THEN s.lastSeenAt ELSE datetime(row.ts) END
+         CREATE (cl:Click {accountId: $accountId, label: 'card', href: '', listingSlug: row.listingSlug, pageViewId: '', occurredAt: datetime(row.ts), backfilled: true})
+         MERGE (s)-[:HAS_EVENT]->(cl)
+         RETURN count(cl) AS written`,
+        { accountId: p.accountId, rows: slice },
+      );
+      const row = result.records[0];
+      clickedWritten += Number(row?.get("written") ?? 0);
+    }
+
+    const parityRes = await session.run(
+      `MATCH (rec:Recommendation {accountId: $accountId})
+       WHERE rec.recommendedAt >= datetime($since) AND rec.recommendedAt < datetime($until)
+       WITH count(DISTINCT rec) AS recCount
+       OPTIONAL MATCH (cl:Click {accountId: $accountId, label: 'card'})
+       WHERE cl.occurredAt >= datetime($since) AND cl.occurredAt < datetime($until)
+         AND cl.backfilled = true
+       RETURN recCount, count(DISTINCT cl) AS clickCount`,
+      {
+        accountId: p.accountId,
+        since: windowStart ?? new Date(0).toISOString(),
+        until: windowEnd ? new Date(Date.parse(windowEnd) + 1).toISOString() : new Date().toISOString(),
+      },
+    );
+    const head = parityRes.records[0];
+    const recGraph = Number(head?.get("recCount") ?? 0);
+    const clickGraph = Number(head?.get("clickCount") ?? 0);
+    const parityDelta = {
+      recommended: recGraph - rec.length,
+      clicked: clickGraph - click.length,
+    };
+    const parityCheck: "ok" | "mismatch" = parityDelta.recommended === 0 && parityDelta.clicked === 0 ? "ok" : "mismatch";
+
+    console.error(
+      `[visitor-backfill] done parityCheck=${parityCheck} recParsed=${rec.length} recWritten=${recommendedWritten} clickParsed=${click.length} clickWritten=${clickedWritten} unparseable=${unparseable}`,
+    );
+
+    return {
+      windowStart,
+      windowEnd,
+      recommendedParsed: rec.length,
+      recommendedWritten,
+      recommendedSkippedDuplicate,
+      clickedParsed: click.length,
+      clickedWritten,
+      unparseable,
+      parityCheck,
+      parityDelta,
+    };
+  } finally {
+    await session.close();
+  }
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/tools/visitor-engagement-score.ts

@@ -0,0 +1,87 @@
+// visitor-engagement-score — engagement-ranked Person list.
+//
+// score = visit_count * recency_weight * depth_weight * dwell_weight
+//   visit_count    = number of :Session in the window
+//   recency_weight = exp(-daysSinceLast / 14)  (half-life 14d)
+//   depth_weight   = avg(maxScrollDepth / 100)
+//   dwell_weight   = log1p(totalDwellMs / 60000)  (per minute)
+//
+// Score is unitless; the nurture-list skill consumes it for ranking, not
+// absolute meaning. Returns top N most engaged Persons within sinceDays.
+
+import { getSession } from "../lib/neo4j.js";
+
+export interface EngagementParams {
+  accountId: string;
+  sinceDays?: number;
+  limit?: number;
+}
+
+export interface EngagementRow {
+  personId: string;
+  personName: string | null;
+  email: string | null;
+  telephone: string | null;
+  visitCount: number;
+  lastSeenAt: string;
+  daysSinceLast: number;
+  avgScrollDepth: number;
+  totalDwellMs: number;
+  score: number;
+}
+
+export async function visitorEngagementScore(p: EngagementParams): Promise<{ persons: EngagementRow[] }> {
+  const since = p.sinceDays ?? 30;
+  const limit = Math.max(1, Math.min(p.limit ?? 50, 200));
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (per:Person {accountId: $accountId})-[:VISITED]->(s:Session)
+       WHERE s.startedAt >= datetime() - duration({days: $since})
+       OPTIONAL MATCH (s)-[:HAS_EVENT]->(sm:ScrollMilestone)
+       OPTIONAL MATCH (s)-[:HAS_EVENT]->(pv:PageView)
+       WITH per, s,
+            coalesce(avg(sm.maxDepth), 0) AS avgDepth,
+            coalesce(sum(pv.dwellMs), 0) AS dwellMs
+       WITH per, count(s) AS visits, max(s.lastSeenAt) AS lastSeenAt,
+            avg(avgDepth) AS avgDepth, sum(dwellMs) AS totalDwellMs
+       WITH per, visits, lastSeenAt, avgDepth, totalDwellMs,
+            duration.between(lastSeenAt, datetime()).days AS daysSinceLast
+       WITH per, visits, lastSeenAt, avgDepth, totalDwellMs, daysSinceLast,
+            visits
+              * exp(-daysSinceLast / 14.0)
+              * (avgDepth / 100.0 + 0.1)
+              * log(1.0 + totalDwellMs / 60000.0)
+              AS score
+       RETURN elementId(per) AS personId,
+              per.name AS personName,
+              per.email AS email,
+              per.telephone AS telephone,
+              visits AS visitCount,
+              toString(lastSeenAt) AS lastSeenAt,
+              daysSinceLast,
+              avgDepth AS avgScrollDepth,
+              totalDwellMs,
+              score
+       ORDER BY score DESC
+       LIMIT $limit`,
+      { accountId: p.accountId, since, limit },
+    );
+    return {
+      persons: result.records.map((r) => ({
+        personId: r.get("personId"),
+        personName: r.get("personName"),
+        email: r.get("email"),
+        telephone: r.get("telephone"),
+        visitCount: Number(r.get("visitCount") ?? 0),
+        lastSeenAt: r.get("lastSeenAt"),
+        daysSinceLast: Number(r.get("daysSinceLast") ?? 0),
+        avgScrollDepth: Number(r.get("avgScrollDepth") ?? 0),
+        totalDwellMs: Number(r.get("totalDwellMs") ?? 0),
+        score: Number(r.get("score") ?? 0),
+      })),
+    };
+  } finally {
+    await session.close();
+  }
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/tools/visitor-event-ingest.ts

@@ -0,0 +1,119 @@
+// visitor-event-ingest — admin-side companion to POST /v/event for test
+// harness work and manual replay. Takes a single event payload identical
+// in shape to what the pixel sends, writes it into the graph against the
+// caller's accountId. Not exposed on the public agent surface.
+
+import { getSession } from "../lib/neo4j.js";
+
+export interface IngestParams {
+  accountId: string;
+  type: "pageview" | "click" | "scroll" | "dwell";
+  sessionId: string;
+  visitorId: string;
+  /** optional Person elementId — overrides identity resolution */
+  personId?: string | null;
+  url: string;
+  path?: string;
+  title?: string;
+  pageViewId?: string;
+  site?: string;
+  referrer?: string;
+  label?: string;
+  href?: string;
+  depth?: number;
+  dwellMs?: number;
+  occurredAt?: string;
+}
+
+export interface IngestResult {
+  ok: boolean;
+  type: string;
+  sessionId: string;
+}
+
+export async function visitorEventIngest(p: IngestParams): Promise<IngestResult> {
+  const session = getSession();
+  const occurredAt = p.occurredAt ?? new Date().toISOString();
+  try {
+    if (p.type === "pageview") {
+      await session.run(
+        `MERGE (s:Session {accountId: $accountId, sessionId: $sid})
+           ON CREATE SET s.startedAt = datetime($occurredAt), s.lastSeenAt = datetime($occurredAt)
+           ON MATCH  SET s.lastSeenAt = datetime($occurredAt)
+         MERGE (pg:Page {accountId: $accountId, url: $url})
+           ON CREATE SET pg.firstSeenAt = datetime($occurredAt), pg.title = $title
+         CREATE (pv:PageView {
+           accountId: $accountId, pageViewId: $pvId, occurredAt: datetime($occurredAt),
+           referrer: $referrer, path: $path
+         })
+         MERGE (s)-[:HAS_EVENT]->(pv)
+         MERGE (pv)-[:OF_PAGE]->(pg)`,
+        {
+          accountId: p.accountId,
+          sid: p.sessionId,
+          url: p.url,
+          title: p.title ?? "",
+          pvId: p.pageViewId ?? `${p.sessionId}_${Date.parse(occurredAt)}`,
+          path: p.path ?? "",
+          referrer: p.referrer ?? "",
+          occurredAt,
+        },
+      );
+    } else if (p.type === "click") {
+      await session.run(
+        `MERGE (s:Session {accountId: $accountId, sessionId: $sid})
+           ON CREATE SET s.startedAt = datetime($occurredAt), s.lastSeenAt = datetime($occurredAt)
+           ON MATCH  SET s.lastSeenAt = datetime($occurredAt)
+         CREATE (cl:Click {accountId: $accountId, label: $label, href: $href, pageViewId: $pvId, occurredAt: datetime($occurredAt)})
+         MERGE (s)-[:HAS_EVENT]->(cl)`,
+        {
+          accountId: p.accountId,
+          sid: p.sessionId,
+          label: (p.label ?? "unknown").slice(0, 64),
+          href: (p.href ?? "").slice(0, 2048),
+          pvId: p.pageViewId ?? "",
+          occurredAt,
+        },
+      );
+    } else if (p.type === "scroll") {
+      await session.run(
+        `MERGE (s:Session {accountId: $accountId, sessionId: $sid})
+         MERGE (sm:ScrollMilestone {accountId: $accountId, sessionId: $sid, pageViewId: $pvId})
+           ON CREATE SET sm.maxDepth = $depth, sm.firstAt = datetime($occurredAt), sm.lastAt = datetime($occurredAt)
+           ON MATCH  SET sm.maxDepth = CASE WHEN sm.maxDepth >= $depth THEN sm.maxDepth ELSE $depth END,
+                         sm.lastAt = datetime($occurredAt)
+         MERGE (s)-[:HAS_EVENT]->(sm)`,
+        { accountId: p.accountId, sid: p.sessionId, pvId: p.pageViewId ?? "", depth: p.depth ?? 0, occurredAt },
+      );
+    } else if (p.type === "dwell") {
+      await session.run(
+        `MATCH (pv:PageView {accountId: $accountId, pageViewId: $pvId})
+         SET pv.dwellMs = coalesce(pv.dwellMs, 0) + $ms,
+             pv.dwellLastAt = datetime($occurredAt)`,
+        { accountId: p.accountId, pvId: p.pageViewId ?? "", ms: p.dwellMs ?? 0, occurredAt },
+      );
+    }
+
+    if (p.personId) {
+      await session.run(
+        `MATCH (per:Person {accountId: $accountId}) WHERE elementId(per) = $personId
+         MATCH (s:Session {accountId: $accountId, sessionId: $sid})
+         MERGE (per)-[:VISITED {accountId: $accountId}]->(s)`,
+        { accountId: p.accountId, personId: p.personId, sid: p.sessionId },
+      );
+    } else {
+      await session.run(
+        `MERGE (av:AnonVisitor {accountId: $accountId, visitorId: $vid})
+           ON CREATE SET av.firstSeenAt = datetime($occurredAt), av.lastSeenAt = datetime($occurredAt)
+           ON MATCH  SET av.lastSeenAt = datetime($occurredAt)
+         WITH av
+         MATCH (s:Session {accountId: $accountId, sessionId: $sid})
+         MERGE (av)-[:VISITED {accountId: $accountId}]->(s)`,
+        { accountId: p.accountId, vid: p.visitorId, sid: p.sessionId, occurredAt },
+      );
+    }
+    return { ok: true, type: p.type, sessionId: p.sessionId };
+  } finally {
+    await session.close();
+  }
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/tools/visitor-recent-by-page.ts

@@ -0,0 +1,61 @@
+// visitor-recent-by-page — who viewed a given page/listing recently.
+// Operator-side query: "who has shown interest in 12 Oak Street this week?"
+
+import { getSession } from "../lib/neo4j.js";
+
+export interface RecentByPageParams {
+  accountId: string;
+  /** Either listingSlug or url; one is required. */
+  listingSlug?: string;
+  url?: string;
+  sinceDays?: number;
+  limit?: number;
+}
+
+export interface VisitorSummary {
+  personId: string | null;
+  personName: string | null;
+  anonVisitorId: string | null;
+  pageviewCount: number;
+  lastSeenAt: string;
+}
+
+export async function visitorRecentByPage(p: RecentByPageParams): Promise<{ visitors: VisitorSummary[] }> {
+  if (!p.listingSlug && !p.url) {
+    throw new Error("visitor-recent-by-page requires listingSlug or url");
+  }
+  const since = p.sinceDays ?? 7;
+  const limit = Math.max(1, Math.min(p.limit ?? 50, 200));
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (pv:PageView {accountId: $accountId})
+       WHERE pv.occurredAt >= datetime() - duration({days: $since})
+         AND ($url IS NULL OR EXISTS { MATCH (pv)-[:OF_PAGE]->(:Page {accountId: $accountId, url: $url}) })
+         AND ($slug IS NULL OR EXISTS { MATCH (pv)-[:OF_LISTING]->(:Listing {accountId: $accountId, slug: $slug, scope:'public'}) })
+       MATCH (s:Session)-[:HAS_EVENT]->(pv)
+       OPTIONAL MATCH (per:Person)-[:VISITED]->(s)
+       OPTIONAL MATCH (av:AnonVisitor)-[:VISITED]->(s)
+       WITH per, av, s, count(pv) AS pageviews
+       RETURN coalesce(elementId(per), null) AS personId,
+              coalesce(per.name, null) AS personName,
+              coalesce(av.visitorId, null) AS anonVisitorId,
+              sum(pageviews) AS totalPageviews,
+              toString(max(s.lastSeenAt)) AS lastSeenAt
+       ORDER BY lastSeenAt DESC
+       LIMIT $limit`,
+      { accountId: p.accountId, url: p.url ?? null, slug: p.listingSlug ?? null, since, limit },
+    );
+    return {
+      visitors: result.records.map((r) => ({
+        personId: r.get("personId"),
+        personName: r.get("personName"),
+        anonVisitorId: r.get("anonVisitorId"),
+        pageviewCount: Number(r.get("totalPageviews") ?? 0),
+        lastSeenAt: r.get("lastSeenAt"),
+      })),
+    };
+  } finally {
+    await session.close();
+  }
+}