rhombus-node-mcp 0.1.44 → 0.1.46

package/dist/api/badge-correlation.js

@@ -0,0 +1,33 @@
+/**
+ * Keystone correlation helper for the OnGuard feature set.
+ *
+ * Given a badge-event-like entry (a camera `deviceUuid` + a `timestampMs`), produce the media hints
+ * the agent needs to *show* the moment: a still (camera-tool `image`) and a short clip window
+ * (clips-tool `createClip`). Pure and reusable — the follow-the-badge timeline, anomaly review, and
+ * lost-badge tracking all turn badge events into "here's the picture/video" the same way.
+ *
+ * Kept deliberately small and side-effect-free. Richer correlation (co-located face events,
+ * people-count in the window) layers on top of this when those features land.
+ */
+export const DEFAULT_CLIP_PADDING_SECONDS = 15;
+/**
+ * Build still + clip hints for a single badge event. Returns empty hints (no clip/still) when the
+ * event lacks a camera or timestamp, so callers can render those events without media gracefully.
+ */
+export function buildMediaHints(event, clipPaddingSeconds = DEFAULT_CLIP_PADDING_SECONDS) {
+    if (!event.deviceUuid || event.timestampMs == null) {
+        return {};
+    }
+    const padMs = Math.max(0, clipPaddingSeconds) * 1000;
+    return {
+        clipHint: {
+            deviceUuid: event.deviceUuid,
+            startTimeMs: event.timestampMs - padMs,
+            endTimeMs: event.timestampMs + padMs,
+        },
+        stillHint: {
+            deviceUuid: event.deviceUuid,
+            timestampMs: event.timestampMs,
+        },
+    };
+}

package/dist/api/badge-timeline-tool-api.js

@@ -0,0 +1,56 @@
+import { buildMediaHints } from "./badge-correlation.js";
+import { searchOnGuardEvents } from "./onguard-tool-api.js";
+/**
+ * Reconstructs a single cardholder's movements as a chronological timeline of OnGuard badge taps,
+ * each with the still/clip hints needed to show what happened. Pure orchestration over
+ * searchOnGuardEvents + the shared correlation helper.
+ */
+export async function getBadgeTimeline(args, timeZone, requestModifiers, sessionId) {
+    const { events } = await searchOnGuardEvents({
+        cardholderQuery: args.cardholderQuery,
+        locationUuids: args.locationUuids,
+        afterMs: args.afterMs,
+        beforeMs: args.beforeMs,
+        limit: args.limit ?? 200,
+    }, timeZone, requestModifiers, sessionId);
+    // searchOnGuardEvents returns newest-first; a timeline reads chronologically.
+    const ordered = events
+        .filter((e) => e.timestampMs != null)
+        .sort((a, b) => (a.timestampMs ?? 0) - (b.timestampMs ?? 0));
+    const stops = ordered.map((e, i) => {
+        const next = ordered[i + 1];
+        const gapToNextSeconds = next?.timestampMs != null && e.timestampMs != null
+            ? Math.round((next.timestampMs - e.timestampMs) / 1000)
+            : undefined;
+        const { clipHint, stillHint } = buildMediaHints({ deviceUuid: e.deviceUuid, timestampMs: e.timestampMs }, args.clipPaddingSeconds);
+        return {
+            timestampMs: e.timestampMs,
+            datetime: e.datetime,
+            deviceUuid: e.deviceUuid,
+            area: e.areaEntering ?? e.areaExiting,
+            label: e.label,
+            isAnomaly: e.isAnomaly,
+            clipHint,
+            stillHint,
+            gapToNextSeconds,
+        };
+    });
+    // The sequence of areas traversed, collapsing consecutive repeats.
+    const path = [];
+    for (const stop of stops) {
+        if (stop.area && stop.area !== path[path.length - 1]) {
+            path.push(stop.area);
+        }
+    }
+    // cardholderQuery is full-text, so it can match more than one person — surface that so the agent
+    // can disambiguate rather than silently merge two people's movements.
+    const distinctCardholders = [
+        ...new Set(ordered.map((e) => e.cardholderName).filter((n) => !!n)),
+    ];
+    return {
+        cardholderName: distinctCardholders[0],
+        ambiguousCardholders: distinctCardholders.length > 1 ? distinctCardholders : undefined,
+        stops,
+        path,
+    };
+}

package/dist/api/camera-tool-api.js

@@ -1,70 +1,65 @@
 import { getLogger } from "../logger.js";
-import { constructRequestHeaders, postApi } from "../network/network.js";
+import { postApi } from "../network/network.js";
 import { removeNullFields } from "../util.js";
 const logger = getLogger("camera-tool");
 const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
-export async function getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers, sessionId) {
+/** Convert a 0-100 percentage to permyriad (0-10000), clamped to the valid range. */
+function pctToPermyriad(pct) {
+    return Math.round(Math.max(0, Math.min(100, pct)) * 100);
+}
+export async function getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers, sessionId, options) {
+    // biome-ignore lint/suspicious/noExplicitAny: request body is a loose JSON shape
     const body = {
-        cameraUuid: cameraUuid,
-        downscaleFactor: 10,
+        cameraUuid,
+        timestampMs,
+        downscaleFactor: options?.downscaleFactor ?? 10,
         jpgQuality: 70,
-        timestampMs: timestampMs,
     };
-    logger.debug(`Getting frameUri from UUID: ${cameraUuid} at timestampMs: ${timestampMs}`);
-    let frameUri;
-    const base64Image = await postApi({
-        route: "/video/getExactFrameUri",
+    const crop = options?.crop;
+    const hasCrop = crop != null &&
+        (crop.x != null || crop.y != null || crop.width != null || crop.height != null);
+    const resolvedCrop = hasCrop
+        ? {
+            x: crop.x ?? 0,
+            y: crop.y ?? 0,
+            width: crop.width ?? 100,
+            height: crop.height ?? 100,
+        }
+        : null;
+    if (resolvedCrop) {
+        body.permyriadCropX = pctToPermyriad(resolvedCrop.x);
+        body.permyriadCropY = pctToPermyriad(resolvedCrop.y);
+        body.permyriadCropWidth = pctToPermyriad(resolvedCrop.width);
+        body.permyriadCropHeight = pctToPermyriad(resolvedCrop.height);
+    }
+    logger.debug(`Getting exact frame data for UUID: ${cameraUuid} at timestampMs: ${timestampMs}` +
+        (hasCrop ? ` (cropped)` : ``));
+    const res = await postApi({
+        route: "/video/getExactFrameData",
         body,
         modifiers: requestModifiers,
         sessionId,
-    }).then(async (res) => {
-        logger.debug(`Received frameUri ${res.frameUri}`);
-        if (!res.frameUri) {
-            throw new Error("No frameUri given. Maybe camera does not support it.");
-        }
-        // construct request headers
-        const { url: _frameUri, requestHeaders } = constructRequestHeaders(res.frameUri, requestModifiers, sessionId);
-        frameUri = _frameUri;
-        // remove content type
-        delete requestHeaders["Content-Type"];
-        delete requestHeaders["accept"];
-        logger.debug(`Fetching with headers\n${JSON.stringify(requestHeaders, null, 2)}`);
-        return await fetch(frameUri, {
-            method: "GET",
-            headers: requestHeaders,
-        }).then(async (res) => {
-            if (!res.ok) {
-                logger.error(`Failed to fetch image (HTTP ${res.status}): ${await res.text()}`);
-                logger.error(res);
-                return res.status === 404 ? 404 : null;
-            }
-            const arrayBuffer = await res.arrayBuffer();
-            const buffer = Buffer.from(arrayBuffer);
-            const base64 = buffer.toString("base64");
-            logger.debug(`Received image base64:\n ${base64}`);
-            return base64;
-        });
     });
-    if (!base64Image) {
-        return {
-            success: false,
-            status: "failed to fetch image",
-        };
-    }
-    if (base64Image === 404) {
+    if (res.error || !res.frameData) {
+        logger.error(`getExactFrameData failed: ${JSON.stringify({ error: res.error, errorMsg: res.errorMsg, status: res.status, hasFrameData: !!res.frameData })}`);
         return {
             success: false,
             status: "failed to fetch image",
-            message: "Camera snapshot unavailable: this camera has no recorded video (VOD) at the requested time. " +
-                "It may not have any footage stored, or the requested timestamp may be outside its retention window.",
+            // Prefer a structured business error from the endpoint, then any transport-level
+            // status set by postApi (e.g. permission/HTTP errors), and only fall back to the
+            // no-VOD explanation when no error detail is available.
+            message: res.errorMsg ??
+                res.status ??
+                "Camera snapshot unavailable: this camera may have no recorded video (VOD) at the requested time. " +
+                    "It may not have any footage stored, or the requested timestamp may be outside its retention window.",
         };
     }
     return {
         success: true,
         status: "successfully fetched image",
-        frameUri: frameUri ?? "",
         imageType: "base64",
-        imageData: base64Image,
+        imageData: res.frameData,
+        crop: resolvedCrop,
     };
 }
 async function getCameraStorageData(cameraUuid, requestModifiers, sessionId) {

package/dist/tools-console/badge-timeline-tool.js

@@ -0,0 +1,50 @@
+import { getBadgeTimeline } from "../api/badge-timeline-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/badge-timeline-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+const TOOL_NAME = "badge-timeline-tool";
+const TOOL_DESCRIPTION = `
+Reconstructs one person's movements through a building from their Honeywell OnGuard (Lenel) badge taps.
+Use this for incident reconstruction / "follow the badge" requests, e.g. "reconstruct Eve's movements
+yesterday" or "where did this cardholder go".
+
+Returns the cardholder's badge taps in CHRONOLOGICAL order (oldest first), each with:
+- datetime / timestampMs and the area entered
+- deviceUuid: the camera at that door
+- clipHint (camera + start/end window) and stillHint (camera + timestamp)
+- gapToNextSeconds: time until the next tap (a large gap = unobserved movement between doors)
+plus a "path" array summarizing the areas traversed in order.
+
+Resolve relative times like "yesterday" to ISO 8601 first (use the timestamp tool), then pass
+startTime/endTime. cardholderQuery is a full-text name match; if "ambiguousCardholders" is returned the
+query matched more than one person — ask the user which one before trusting the timeline.
+
+IMPORTANT — to show the movement visually: for each stop (or the key transitions), call the camera-tool
+(requestType "image", cameraUuid = stop.deviceUuid, timestamp = stop.timestampMs) for a still you can see,
+and/or the clips-tool (requestType "createClip", using stop.clipHint) for video. Issue those per-stop
+media calls in PARALLEL, then present the timeline as a chronological narrative.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        const result = await getBadgeTimeline({
+            cardholderQuery: args.cardholderQuery,
+            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/tools-console/camera-tool.js

@@ -21,8 +21,8 @@ This tool captures and returns a real-time snapshot from a designated security c
 The image reflects the current scene in the camera's field of view and serves as a contextual
 input source for downstream tasks such as object recognition, anomaly detection, incident investigation,
 or situational assessment. When invoked, the tool provides the following: 
-- Visual Scene Capture: A high-resolution image of what the camera is actively observing, including people, vehicles, license plates, and any detectable objects.  
-- The frameUri that was used to fetch the image. It may be useful to show the user this image as well through the frameUri.
+- Visual Scene Capture: A high-resolution image of what the camera is actively observing, including people, vehicles, license plates, and any detectable objects.
+- Optional zoom: pass cropX, cropY, cropWidth, cropHeight (each a percentage 0-100, origin at the top-left) to return only a sub-region of the frame so you can inspect a detail (e.g. a license plate or a doorway) more closely. Omit them for the full frame. When zooming into a small crop, pass a smaller downscaleFactor (e.g. 1-3) to preserve detail.
 
 What follows is a description of the behavior of this tool given the requestType "get-settings"
 
@@ -56,7 +56,7 @@ Examples that REQUIRE the automatic snapshot flow:
 const logger = getLogger("camera-tool");
 const TOOL_ARGS = BASE_TOOL_ARGS;
 const TOOL_HANDLER = async (args, extra) => {
-    const { cameraUuid, timestampISO, requestType } = args;
+    const { cameraUuid, timestampISO, requestType, cropX, cropY, cropWidth, cropHeight, downscaleFactor } = args;
     if (!cameraUuid) {
         return {
             content: [
@@ -76,13 +76,21 @@ const TOOL_HANDLER = async (args, extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
     switch (requestType) {
         case "image":
-            response = await getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers, sessionId);
+            response = await getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers, sessionId, {
+                crop: {
+                    x: cropX ?? null,
+                    y: cropY ?? null,
+                    width: cropWidth ?? null,
+                    height: cropHeight ?? null,
+                },
+                downscaleFactor: downscaleFactor ?? null,
+            });
             if (!response.success || !response.imageData) {
                 return {
                     content: [{ type: "text", text: JSON.stringify(response) }],
                 };
             }
-            logger.debug(`Received image response:\n ${JSON.stringify(response)}`);
+            logger.debug(`Received image response (base64 length ${response.imageData.length})`);
             return {
                 content: [
                     {
@@ -97,7 +105,7 @@ const TOOL_HANDLER = async (args, extra) => {
                             status: "image-attached",
                             cameraUuid,
                             timestampMs,
-                            frameUri: response.frameUri,
+                            cropApplied: response.crop ?? null,
                         }),
                     },
                 ],

package/dist/types/badge-timeline-tool-types.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { createUuidSchema } from "../types.js";
+import { ISOTimestampFormatDescription } from "../utils/timestampInput.js";
+export const TOOL_ARGS = {
+    cardholderQuery: z
+        .string()
+        .describe('The cardholder (person) to reconstruct, full-text name match, e.g. "Eve" or "Eve Adams".'),
+    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 badge tap to include in the clip hint (default 15)."),
+    limit: z.number().nullable().describe("Maximum badge taps 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 tap.");
+const StillHintSchema = z
+    .object({
+    deviceUuid: z.string(),
+    timestampMs: z.number(),
+})
+    .describe("Pass to camera-tool (requestType image) to get a still of this tap.");
+export const BadgeTimelineStopSchema = z.object({
+    timestampMs: z.number().optional(),
+    datetime: z.string().optional().describe("Human-readable tap time in the requested timezone."),
+    deviceUuid: z
+        .string()
+        .optional()
+        .describe("The camera at this door. Pass to camera-tool (image) or clips-tool (createClip)."),
+    area: z.string().optional().describe("The area entered (or exited) at this tap."),
+    label: z.string().optional(),
+    isAnomaly: z.boolean().optional().describe("True if this tap was an alerting/anomalous event."),
+    clipHint: ClipHintSchema.optional(),
+    stillHint: StillHintSchema.optional(),
+    gapToNextSeconds: z
+        .number()
+        .optional()
+        .describe("Seconds until the next tap — large gaps are unobserved movement between doors."),
+});
+export const OUTPUT_SCHEMA = z.object({
+    cardholderName: z.string().optional().describe("The resolved cardholder name."),
+    ambiguousCardholders: z
+        .array(z.string())
+        .optional()
+        .describe("Set when the query matched more than one person — disambiguate with the user before trusting the timeline."),
+    stops: z
+        .array(BadgeTimelineStopSchema)
+        .optional()
+        .describe("The cardholder's badge taps in chronological order (oldest first)."),
+    path: z.array(z.string()).optional().describe("Areas traversed, in order (consecutive repeats collapsed)."),
+    error: z.string().optional(),
+});

package/dist/types/camera-tool-types.js

@@ -221,5 +221,39 @@ export const BASE_TOOL_ARGS = {
       the timestamp for the image. This will default to 5 minutes before the current time. You can also call time-tool to parse the user's time description.
       ` + ISOTimestampFormatDescription),
     requestType: z.enum(["image", "get-settings", "get-media-uris", "get-ai-thresholds"]),
+    cropX: z
+        .number()
+        .min(0)
+        .max(100)
+        .nullable()
+        .optional()
+        .describe("For requestType 'image' only. Left edge of the crop region as a percentage (0-100) of image width, measured from the left. 0 = left edge. Omit for full frame."),
+    cropY: z
+        .number()
+        .min(0)
+        .max(100)
+        .nullable()
+        .optional()
+        .describe("For requestType 'image' only. Top edge of the crop region as a percentage (0-100) of image height, measured from the top. 0 = top edge. Omit for full frame."),
+    cropWidth: z
+        .number()
+        .min(0)
+        .max(100)
+        .nullable()
+        .optional()
+        .describe("For requestType 'image' only. Width of the crop region as a percentage (0-100) of image width. Omit for full frame (100)."),
+    cropHeight: z
+        .number()
+        .min(0)
+        .max(100)
+        .nullable()
+        .optional()
+        .describe("For requestType 'image' only. Height of the crop region as a percentage (0-100) of image height. Omit for full frame (100)."),
+    downscaleFactor: z
+        .number()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("For requestType 'image' only. Ratio to shrink the image pixels by (default 10). Use a smaller value (e.g. 1-3) when zooming into a crop to keep detail."),
 };
 const BASE_TOOL_ARGS_SCHEMA = z.object(BASE_TOOL_ARGS);

package/package.json

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