rhombus-node-mcp 0.1.52 → 0.1.54

package/dist/api/person-tracking-tool-api.js

@@ -0,0 +1,165 @@
+import { buildMediaHints } from "./badge-correlation.js";
+import { getFaceEvents, getRegisteredFaces, searchSimilarFaces } from "./faces-tool-api.js";
+import { formatTimestamp } from "../util.js";
+/**
+ * Fuzzy-match a free-text name against the registered-faces directory. Mirrors faces-tool's scoring
+ * (4 = exact full name, 3 = first name, 2 = last name, 1 = substring ≥3 chars) but returns every person
+ * tied at the best score so the caller can flag ambiguity instead of silently tracking the wrong person.
+ */
+function matchRegisteredPeople(query, people) {
+    const input = query.toLowerCase().trim();
+    if (!input)
+        return [];
+    let bestScore = 0;
+    const scored = [];
+    for (const person of people) {
+        if (!person.name || !person.uuid)
+            continue;
+        const fullName = person.name.toLowerCase().trim();
+        const parts = fullName.split(/\s+/);
+        let score = 0;
+        if (fullName === input)
+            score = 4;
+        else if (parts[0] === input)
+            score = 3;
+        else if (parts.length > 1 && parts[parts.length - 1] === input)
+            score = 2;
+        else if (input.length >= 3 && fullName.includes(input))
+            score = 1;
+        if (score > 0) {
+            scored.push({ name: person.name, uuid: person.uuid, score });
+            if (score > bestScore)
+                bestScore = score;
+        }
+    }
+    // Dedupe by uuid among the best-scoring tier.
+    const seen = new Set();
+    const top = [];
+    for (const s of scored) {
+        if (s.score !== bestScore || seen.has(s.uuid))
+            continue;
+        seen.add(s.uuid);
+        top.push({ name: s.name, personUuid: s.uuid });
+    }
+    return top;
+}
+/**
+ * Reconstructs one person's movements across cameras as a chronological track of face sightings, each
+ * with the still/clip hints needed to show the moment. Pure orchestration over the face-recognition
+ * APIs:
+ *   - faceEventUuid  -> searchSimilarFaces (appearance match; works for unrecognized people)
+ *   - personUuid     -> getFaceEvents filtered to that person
+ *   - personQuery    -> resolve name against registered faces, then getFaceEvents
+ */
+export async function getPersonTrack(args, timeZone, requestModifiers, sessionId) {
+    let resolvedPerson;
+    let raw = [];
+    if (args.faceEventUuid) {
+        // Appearance-based track from a seed sighting — handles people who aren't registered/named.
+        const similar = await searchSimilarFaces(args.faceEventUuid, timeZone, requestModifiers, sessionId);
+        raw = similar.map((s) => ({
+            deviceUuid: s.deviceUuid,
+            timestampMs: s.eventTimestampMs,
+            datetime: s.eventTimestamp,
+            similarity: s.similarity,
+            faceName: undefined,
+        }));
+    }
+    else {
+        // Resolve to a person UUID (directly or by name) before pulling their face events.
+        let personUuid = args.personUuid;
+        if (!personUuid && args.personQuery) {
+            const peopleResponse = await getRegisteredFaces({}, requestModifiers, sessionId);
+            const matches = matchRegisteredPeople(args.personQuery, peopleResponse.people ?? []);
+            if (matches.length > 1) {
+                return { ambiguousPeople: matches, sightings: [], path: [], count: 0 };
+            }
+            if (matches.length === 0) {
+                return { sightings: [], path: [], count: 0 };
+            }
+            resolvedPerson = matches[0];
+            personUuid = matches[0].personUuid;
+        }
+        else if (personUuid) {
+            resolvedPerson = { personUuid };
+        }
+        if (!personUuid) {
+            return { sightings: [], path: [], count: 0 };
+        }
+        const faceEventArgs = {
+            pageRequest: { maxPageSize: args.limit ?? 200, lastEvaluatedKey: null },
+            searchFilter: {
+                faceNameContains: null,
+                faceNames: [],
+                hasEmbedding: null,
+                hasName: null,
+                labels: [],
+                locationUuids: args.locationUuids ?? [],
+                personUuids: [personUuid],
+                timestampFilter: args.afterMs != null || args.beforeMs != null
+                    ? {
+                        rangeStart: args.afterMs != null ? new Date(args.afterMs).toISOString() : null,
+                        rangeEnd: args.beforeMs != null ? new Date(args.beforeMs).toISOString() : null,
+                    }
+                    : null,
+            },
+        };
+        const { faceEvents } = await getFaceEvents(faceEventArgs, timeZone, requestModifiers, sessionId);
+        raw = faceEvents.map((e) => ({
+            deviceUuid: e.deviceUuid,
+            timestampMs: e.eventTimestampMs,
+            datetime: e.eventTimestamp,
+            locationUuid: e.locationUuid,
+            faceName: e.faceName,
+            thumbnailS3Key: e.thumbnailS3Key,
+        }));
+        if (!resolvedPerson?.name) {
+            const named = raw.find((r) => r.faceName);
+            if (named?.faceName)
+                resolvedPerson = { name: named.faceName, personUuid };
+        }
+    }
+    // Always enforce the time window client-side (searchSimilarFaces has no time filter, and the face-event
+    // time filter defaults to the last 7 days if unset) and order chronologically.
+    const ordered = raw
+        .filter((r) => r.timestampMs != null)
+        .filter((r) => (args.afterMs == null || r.timestampMs >= args.afterMs))
+        .filter((r) => (args.beforeMs == null || r.timestampMs <= args.beforeMs))
+        .sort((a, b) => (a.timestampMs ?? 0) - (b.timestampMs ?? 0))
+        .slice(0, args.limit ?? 200);
+    const sightings = buildSightings(ordered, timeZone, args.clipPaddingSeconds);
+    // Camera sequence the person moved through, collapsing consecutive repeats.
+    const path = [];
+    for (const s of sightings) {
+        if (s.deviceUuid && s.deviceUuid !== path[path.length - 1])
+            path.push(s.deviceUuid);
+    }
+    return {
+        resolvedPerson,
+        sightings,
+        path,
+        lastKnownSighting: sightings[sightings.length - 1],
+        count: sightings.length,
+    };
+}
+function buildSightings(ordered, timeZone, clipPaddingSeconds) {
+    return ordered.map((s, i) => {
+        const next = ordered[i + 1];
+        const gapToNextSeconds = next?.timestampMs != null && s.timestampMs != null
+            ? Math.round((next.timestampMs - s.timestampMs) / 1000)
+            : undefined;
+        const { clipHint, stillHint } = buildMediaHints({ deviceUuid: s.deviceUuid, timestampMs: s.timestampMs }, clipPaddingSeconds);
+        return {
+            timestampMs: s.timestampMs,
+            datetime: s.datetime ?? (s.timestampMs != null ? formatTimestamp(s.timestampMs, timeZone) : undefined),
+            deviceUuid: s.deviceUuid,
+            locationUuid: s.locationUuid,
+            faceName: s.faceName,
+            similarity: s.similarity,
+            thumbnailS3Key: s.thumbnailS3Key,
+            clipHint,
+            stillHint,
+            gapToNextSeconds,
+        };
+    });
+}

package/dist/tools-console/elements-tool.js

@@ -6,6 +6,14 @@ const TOOL_DESCRIPTION = `
 Searches Honeywell Elements (LenelS2 Elements) badge / access-control events for the organization. Use this to answer
 "who entered WHERE and WHEN" questions, e.g. "who entered the back office yesterday".
 
+NOTE: an organization may run any combination of Honeywell OnGuard (Lenel), Honeywell Elements (LenelS2
+Elements), and Lenel S2 NetBox badge integrations — each searched by its own sibling tool
+(onguard-events-tool / elements-events-tool / netbox-events-tool), all taking identical arguments and
+returning the same shape. For a general "who badged in / did anyone enter" question you usually do NOT
+know which integration recorded the event, so call ALL THREE sibling tools (in parallel) and combine the
+results — each returns an empty list when its integration isn't configured. Restrict to one vendor only
+when the user explicitly names it.
+
 Each returned event includes:
 - cardholderName: the person's name
 - deviceUuid: the camera that saw the event

package/dist/tools-console/netbox-tool.js

@@ -6,6 +6,14 @@ const TOOL_DESCRIPTION = `
 Searches Lenel S2 NetBox (Honeywell NetBox) badge / access-control events for the organization. Use this to answer
 "who entered WHERE and WHEN" questions, e.g. "who entered the back office yesterday".
 
+NOTE: an organization may run any combination of Honeywell OnGuard (Lenel), Honeywell Elements (LenelS2
+Elements), and Lenel S2 NetBox badge integrations — each searched by its own sibling tool
+(onguard-events-tool / elements-events-tool / netbox-events-tool), all taking identical arguments and
+returning the same shape. For a general "who badged in / did anyone enter" question you usually do NOT
+know which integration recorded the event, so call ALL THREE sibling tools (in parallel) and combine the
+results — each returns an empty list when its integration isn't configured. Restrict to one vendor only
+when the user explicitly names it.
+
 Each returned event includes:
 - cardholderName: the person's name
 - deviceUuid: the camera that saw the event

package/dist/tools-console/onguard-tool.js

@@ -6,6 +6,14 @@ const TOOL_DESCRIPTION = `
 Searches Honeywell OnGuard (Lenel) badge / access-control events for the organization. Use this to answer
 "who entered WHERE and WHEN" questions, e.g. "who entered the back office yesterday".
 
+NOTE: an organization may run any combination of Honeywell OnGuard (Lenel), Honeywell Elements (LenelS2
+Elements), and Lenel S2 NetBox badge integrations — each searched by its own sibling tool
+(onguard-events-tool / elements-events-tool / netbox-events-tool), all taking identical arguments and
+returning the same shape. For a general "who badged in / did anyone enter" question you usually do NOT
+know which integration recorded the event, so call ALL THREE sibling tools (in parallel) and combine the
+results — each returns an empty list when its integration isn't configured. Restrict to one vendor only
+when the user explicitly names it.
+
 Each returned event includes:
 - cardholderName: the person's name
 - deviceUuid: the camera that saw the event

package/dist/tools-console/person-tracking-tool.js

@@ -0,0 +1,60 @@
+import { getPersonTrack } from "../api/person-tracking-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/person-tracking-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+const TOOL_NAME = "person-tracking-tool";
+const TOOL_DESCRIPTION = `
+Tracks one person's movements across cameras using face recognition. Use this for "track this person",
+"where did X go", "follow this person across the building", or "where was X last seen" — the camera-based
+counterpart to the badge-timeline tools (which follow door taps).
+
+Identify the person ONE of three ways (in priority order):
+- faceEventUuid: track by APPEARANCE from a specific sighting — works even for an unrecognized/unnamed
+  person (e.g. follow the person in this face event). Get a faceEventUuid from the faces-tool.
+- personUuid: the exact registered-person UUID (from faces-tool get-registered-faces).
+- personQuery: a full-text name (e.g. "Eve" or "Eve Adams"); it is resolved against the registered-faces
+  directory. If "ambiguousPeople" is returned the name matched more than one person — ask the user which
+  one before trusting the track.
+
+Returns the person's sightings in CHRONOLOGICAL order (oldest first), each with:
+- datetime / timestampMs, deviceUuid (the camera), and locationUuid
+- similarity (only on appearance/faceEventUuid tracks) and a face thumbnail key
+- clipHint (camera + start/end window) and stillHint (camera + timestamp)
+- gapToNextSeconds: time until the next sighting (a large gap = unobserved movement between cameras)
+plus a "path" array (the camera sequence, consecutive repeats collapsed) and "lastKnownSighting" (the
+person's last-known location).
+
+Resolve relative times like "yesterday" to ISO 8601 first (use the timestamp tool), then pass
+startTime/endTime. Face tracking depends on face-recognition coverage, so treat the track as investigative.
+
+IMPORTANT — to show the movement visually: for each sighting (or the key transitions), call the camera-tool
+(requestType "image", cameraUuid = sighting.deviceUuid, timestamp = sighting.timestampMs) for a still, and/or
+the clips-tool (requestType "createClip", using sighting.clipHint) for video. Issue those per-sighting media
+calls in PARALLEL, then present the track as a chronological narrative.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        const result = await getPersonTrack({
+            personQuery: args.personQuery ?? undefined,
+            personUuid: args.personUuid ?? undefined,
+            faceEventUuid: args.faceEventUuid ?? undefined,
+            locationUuids: args.locationUuids ?? undefined,
+            afterMs: args.startTime ? new Date(args.startTime).getTime() : undefined,
+            beforeMs: args.endTime ? new Date(args.endTime).getTime() : undefined,
+            clipPaddingSeconds: args.clipPaddingSeconds ?? undefined,
+            limit: args.limit ?? undefined,
+        }, args.timeZone ?? "UTC", requestModifiers, sessionId);
+        return createToolStructuredContent(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return createToolStructuredContent({ error: message });
+    }
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/types/person-tracking-tool-types.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { createUuidSchema } from "../types.js";
+import { ISOTimestampFormatDescription } from "../utils/timestampInput.js";
+export const TOOL_ARGS = {
+    personQuery: z
+        .string()
+        .nullable()
+        .describe('The recognized person to track, full-text name match against registered faces, e.g. "Eve" or "Eve Adams". ' +
+        "Provide this OR personUuid OR faceEventUuid."),
+    personUuid: z
+        .string()
+        .nullable()
+        .describe("The exact person UUID to track (from faces-tool get-registered-faces). Takes precedence over personQuery."),
+    faceEventUuid: z
+        .string()
+        .nullable()
+        .describe("Track by appearance from a specific face sighting (a faceEvent UUID), even when the person isn't a registered/named face. " +
+        "Use this for 'track THIS person' from a sighting. Takes precedence over personQuery/personUuid."),
+    locationUuids: z
+        .array(createUuidSchema())
+        .nullable()
+        .describe("Optional: restrict to these Rhombus location UUIDs. Use the location-tool to resolve names."),
+    startTime: z
+        .string()
+        .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
+        .nullable()
+        .describe("Start of the window (inclusive). " + ISOTimestampFormatDescription),
+    endTime: z
+        .string()
+        .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
+        .nullable()
+        .describe("End of the window (inclusive). " + ISOTimestampFormatDescription),
+    clipPaddingSeconds: z
+        .number()
+        .nullable()
+        .describe("Seconds of video before/after each sighting to include in the clip hint (default 15)."),
+    limit: z.number().nullable().describe("Maximum sightings to include (default 200)."),
+    timeZone: z
+        .string()
+        .nullable()
+        .describe("IANA timezone used to format times, e.g. America/New_York. Defaults to UTC."),
+};
+const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+const ClipHintSchema = z
+    .object({
+    deviceUuid: z.string(),
+    startTimeMs: z.number(),
+    endTimeMs: z.number(),
+})
+    .describe("Pass to clips-tool createClip to get video of this sighting.");
+const StillHintSchema = z
+    .object({
+    deviceUuid: z.string(),
+    timestampMs: z.number(),
+})
+    .describe("Pass to camera-tool (requestType image) to get a still of this sighting.");
+const PersonRefSchema = z.object({
+    name: z.string().optional(),
+    personUuid: z.string().optional(),
+});
+export const SightingSchema = z.object({
+    timestampMs: z.number().optional(),
+    datetime: z.string().optional().describe("Human-readable sighting time in the requested timezone."),
+    deviceUuid: z
+        .string()
+        .optional()
+        .describe("The camera that saw the person. Pass to camera-tool (image) or clips-tool (createClip)."),
+    locationUuid: z.string().optional().describe("The location where the sighting occurred."),
+    faceName: z.string().optional().describe("The recognized name on this sighting, if any."),
+    similarity: z
+        .number()
+        .optional()
+        .describe("Appearance-match similarity (0-1) when tracking from a faceEventUuid seed."),
+    thumbnailS3Key: z.string().optional().describe("Thumbnail key for the detected face on this sighting."),
+    clipHint: ClipHintSchema.optional(),
+    stillHint: StillHintSchema.optional(),
+    gapToNextSeconds: z
+        .number()
+        .optional()
+        .describe("Seconds until the next sighting — large gaps mean the person was unobserved between cameras."),
+});
+export const OUTPUT_SCHEMA = z.object({
+    resolvedPerson: PersonRefSchema.optional().describe("The person actually tracked (name + UUID), when resolved."),
+    ambiguousPeople: z
+        .array(PersonRefSchema)
+        .optional()
+        .describe("Set when personQuery matched more than one registered person — disambiguate with the user before trusting the track."),
+    sightings: z
+        .array(SightingSchema)
+        .optional()
+        .describe("The person's camera sightings in chronological order (oldest first)."),
+    path: z
+        .array(z.string())
+        .optional()
+        .describe("Camera UUIDs the person passed through, in order (consecutive repeats collapsed)."),
+    lastKnownSighting: SightingSchema.optional().describe("The most recent sighting — the person's last-known location."),
+    count: z.number().optional().describe("Number of sightings returned."),
+    error: z.string().optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rhombus-node-mcp",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "MCP server for Rhombus API",
   "keywords": [
     "ai",