rhombus-node-mcp 0.1.45 → 0.1.47

package/dist/analytics/amplitude.js

@@ -0,0 +1,74 @@
+import { flush, init, track } from "@amplitude/analytics-node";
+import { logger } from "../logger.js";
+/**
+ * Amplitude analytics for the Rhombus MCP server.
+ *
+ * Analytics are **opt-in**: nothing is sent unless `AMPLITUDE_API_KEY` is set.
+ * This keeps the published npm package / self-hosted deployments silent by
+ * default and confines telemetry to Rhombus-operated deployments that supply
+ * the key. Every function here is defensive — analytics must never throw into,
+ * slow down, or otherwise affect the request path.
+ */
+let enabled = false;
+/**
+ * Initialize the Amplitude client once at process start. No-op (and leaves
+ * analytics disabled) when `AMPLITUDE_API_KEY` is unset or init fails.
+ */
+export function initAnalytics() {
+    const apiKey = process.env.AMPLITUDE_API_KEY;
+    if (!apiKey) {
+        logger.info("📊 Amplitude analytics disabled (AMPLITUDE_API_KEY not set)");
+        return;
+    }
+    const serverZone = (process.env.AMPLITUDE_SERVER_ZONE ?? "US").toUpperCase() === "EU" ? "EU" : "US";
+    try {
+        init(apiKey, {
+            serverZone,
+            // Batch in the background; the request path never waits on Amplitude.
+            flushIntervalMillis: 10_000,
+            flushQueueSize: 50,
+        });
+        enabled = true;
+        logger.info(`📊 Amplitude analytics enabled (zone=${serverZone})`);
+    }
+    catch (error) {
+        logger.warn(`📊 Failed to initialize Amplitude analytics: ${String(error)}`);
+    }
+}
+/** Whether analytics are active (key present and init succeeded). */
+export function analyticsEnabled() {
+    return enabled;
+}
+/**
+ * Record an analytics event. Fire-and-forget and fully guarded — callers do
+ * not await this and a failure here is logged at debug level only.
+ */
+export function trackEvent(eventType, eventProperties, identity = {}) {
+    if (!enabled)
+        return;
+    try {
+        const { userId, orgUuid, deviceId } = identity;
+        track(eventType, eventProperties, {
+            // Amplitude requires a user_id or a device_id. Prefer the stable user id;
+            // fall back to a device id (session id) and finally a constant so the
+            // event is still accepted for stateless (api-key / oauth) callers.
+            user_id: userId,
+            ...(userId ? {} : { device_id: deviceId || "mcp-stateless" }),
+            ...(orgUuid ? { groups: { org: orgUuid } } : {}),
+        });
+    }
+    catch (error) {
+        logger.debug(`📊 trackEvent("${eventType}") failed: ${String(error)}`);
+    }
+}
+/** Flush any buffered events. Call on graceful shutdown. */
+export async function flushAnalytics() {
+    if (!enabled)
+        return;
+    try {
+        await flush().promise;
+    }
+    catch (error) {
+        logger.debug(`📊 flushAnalytics failed: ${String(error)}`);
+    }
+}

package/dist/analytics/analyticsProxy.js

@@ -0,0 +1,97 @@
+import { resolveSessionIdentity } from "../api/get-accessible-apps.js";
+import { logger } from "../logger.js";
+import { extractFromToolExtra } from "../util.js";
+import { analyticsEnabled, trackEvent } from "./amplitude.js";
+const TOOL_CALLED_EVENT = "MCP Tool Called";
+/**
+ * Resolve identity (cached `getCurrentUser` — no extra API call for session
+ * callers) and emit the tool-call event. Fire-and-forget: never awaited by the
+ * handler and fully guarded so analytics cannot affect the response.
+ */
+async function emitToolCall(toolName, 
+// biome-ignore lint/suspicious/noExplicitAny: dynamic tool args
+args, extra, success, durationMs, errorMessage) {
+    try {
+        const { sessionId } = extractFromToolExtra(extra);
+        const identity = sessionId ? await resolveSessionIdentity(sessionId) : null;
+        trackEvent(TOOL_CALLED_EVENT, {
+            tool_name: toolName,
+            success,
+            duration_ms: durationMs,
+            // Record which arguments were supplied, never their values (avoid PII).
+            arg_keys: args && typeof args === "object" ? Object.keys(args) : [],
+            transport: process.env.TRANSPORT_TYPE ?? "stdio",
+            ...(errorMessage ? { error_message: errorMessage } : {}),
+        }, {
+            userId: identity?.userId,
+            orgUuid: identity?.orgUuid,
+            deviceId: sessionId,
+        });
+    }
+    catch (error) {
+        logger.debug(`📊 emitToolCall("${toolName}") failed: ${String(error)}`);
+    }
+}
+/** Wrap a tool handler so each invocation is timed and tracked. */
+function wrapHandler(toolName, handler) {
+    return async (args, extra) => {
+        const start = Date.now();
+        let success = true;
+        let errorMessage;
+        try {
+            const result = await handler(args, extra);
+            // A tool can signal failure via `isError` rather than throwing.
+            if (result && typeof result === "object" && result.isError) {
+                success = false;
+            }
+            return result;
+        }
+        catch (error) {
+            success = false;
+            errorMessage = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+        finally {
+            void emitToolCall(toolName, args, extra, success, Date.now() - start, errorMessage);
+        }
+    };
+}
+/**
+ * Returns a Proxy over an `McpServer` that wraps every tool handler to emit a
+ * `"${TOOL_CALLED_EVENT}"` analytics event. Both registration methods are
+ * intercepted: `registerTool` (most tools) and the legacy `tool` (a handful,
+ * including the filtering-blacklisted ones), so coverage is complete.
+ *
+ * When analytics are disabled the proxy returns the server untouched, so there
+ * is zero overhead on deployments without `AMPLITUDE_API_KEY`.
+ *
+ * Compose it *inside* the filtering proxy — `createFilteringProxy(createAnalyticsProxy(server))`
+ * — so handlers are timed after filtering strips `includeFields`/`filterBy`,
+ * keeping those synthetic args out of `arg_keys`.
+ */
+export function createAnalyticsProxy(server) {
+    if (!analyticsEnabled())
+        return server;
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === "registerTool") {
+                // biome-ignore lint/suspicious/noExplicitAny: proxy intercept
+                return (name, config, handler) => target.registerTool(name, config, wrapHandler(name, handler));
+            }
+            if (prop === "tool") {
+                // Legacy signature: tool(name, [description], [paramsSchema], [annotations], handler).
+                // The handler is always the final argument.
+                // biome-ignore lint/suspicious/noExplicitAny: proxy intercept
+                return (...toolArgs) => {
+                    const name = toolArgs[0];
+                    const lastIdx = toolArgs.length - 1;
+                    if (typeof toolArgs[lastIdx] === "function") {
+                        toolArgs[lastIdx] = wrapHandler(name, toolArgs[lastIdx]);
+                    }
+                    return target.tool(...toolArgs);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}

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/api/get-accessible-apps.js

@@ -1,16 +1,13 @@
 import { logger } from "../logger.js";
 import { postApi } from "../network/network.js";
 /**
- * Fetches `user.accessibleRhombusApps` from getCurrentUser for the given session.
- * Successful results are cached in-memory for the lifetime of the session;
- * failures are NOT cached so transient errors don't poison the session.
- * Returns null on error or missing session; callers should fall back to a
- * permissive default.
+ * Single cached `getCurrentUser` fetch per session. Both `resolveAccessibleApps`
+ * and `resolveSessionIdentity` read from this cache, so identity for analytics
+ * costs no extra API call. Successful results are cached for the lifetime of
+ * the session; failures are NOT cached so transient errors don't poison it.
  */
 const cache = new Map();
-export async function resolveAccessibleApps(sessionId) {
-    if (!sessionId)
-        return null;
+async function fetchSession(sessionId) {
     const cached = cache.get(sessionId);
     if (cached !== undefined)
         return cached;
@@ -24,16 +21,43 @@ export async function resolveAccessibleApps(sessionId) {
             logger.warn(`resolveAccessibleApps: getCurrentUser failed for session ${sessionId}`);
             return null;
         }
-        const apps = (res.user?.accessibleRhombusApps ?? []).filter((a) => a !== null && a !== undefined);
-        cache.set(sessionId, apps);
+        const user = res.user;
+        const apps = (user?.accessibleRhombusApps ?? []).filter((a) => a !== null && a !== undefined);
+        const identity = {
+            userId: user?.uuid ?? user?.rhombusUserUuid ?? undefined,
+            orgUuid: user?.orgUuid ?? undefined,
+            email: user?.email ?? undefined,
+        };
+        const entry = { apps, identity };
+        cache.set(sessionId, entry);
         logger.info(`resolveAccessibleApps: session ${sessionId} -> [${apps.join(", ")}]`);
-        return apps;
+        return entry;
     }
     catch (e) {
         logger.warn(`resolveAccessibleApps: error for session ${sessionId}: ${String(e)}`);
         return null;
     }
 }
+/**
+ * Fetches `user.accessibleRhombusApps` from getCurrentUser for the given session.
+ * Returns null on error or missing session; callers should fall back to a
+ * permissive default.
+ */
+export async function resolveAccessibleApps(sessionId) {
+    if (!sessionId)
+        return null;
+    return (await fetchSession(sessionId))?.apps ?? null;
+}
+/**
+ * Fetches identity (user uuid, org uuid, email) from getCurrentUser for the
+ * given session, reusing the same cached response as `resolveAccessibleApps`.
+ * Returns null on error or missing session.
+ */
+export async function resolveSessionIdentity(sessionId) {
+    if (!sessionId)
+        return null;
+    return (await fetchSession(sessionId))?.identity ?? null;
+}
 /** Drop the cached entry — call when a session ends. */
 export function clearAccessibleAppsCache(sessionId) {
     cache.delete(sessionId);

package/dist/createServer.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import path from "path";
+import { createAnalyticsProxy } from "./analytics/analyticsProxy.js";
 import { resolveAccessibleApps } from "./api/get-accessible-apps.js";
 import { logger } from "./logger.js";
 import { createFilteringProxy } from "./util.js";
@@ -105,7 +106,10 @@ export default async function createServer({ sessionId } = {}) {
     const toolsToRegister = pickToolsForSession(apps);
     logDevToolRegistration(sessionId, apps, toolsToRegister);
     logger.info(`🔒 Session ${sessionId ?? "(none)"}: apps=[${apps?.join(", ") ?? "unknown"}] — registering ${toolsToRegister.length} tools`);
-    const filteredServer = createFilteringProxy(server, new Set(["time-tool", "count-tool", "time-conversion-tool"]));
+    // Analytics wraps every tool handler; filtering wraps on top so handlers are
+    // timed after includeFields/filterBy are stripped (keeping them out of
+    // arg_keys). Both are no-ops when their respective features are disabled.
+    const filteredServer = createFilteringProxy(createAnalyticsProxy(server), new Set(["time-tool", "count-tool", "time-conversion-tool"]));
     for (const tool of toolsToRegister) {
         try {
             await tool.create(filteredServer);

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import "dotenv/config";
+import { flushAnalytics, initAnalytics } from "./analytics/amplitude.js";
 import { serverInit } from "./createServer.js";
 import { logger } from "./logger.js";
 import stdioTransport from "./transports/stdio.js";
@@ -12,6 +13,7 @@ async function main() {
         logger.info(`🔑 Using API_KEY: ${RHOMBUS_API_KEY}`);
     }
     logger.info("🌐 Using server url", serverUrl);
+    initAnalytics();
     await serverInit();
     if (TRANSPORT_TYPE === "stdio") {
         await stdioTransport();
@@ -23,6 +25,13 @@ async function main() {
         throw new Error(`Invalid transport type: ${TRANSPORT_TYPE}`);
     }
 }
+// Flush buffered analytics on graceful shutdown so in-flight events aren't lost.
+for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, async () => {
+        await flushAnalytics();
+        process.exit(0);
+    });
+}
 main().catch(error => {
     console.error("Fatal error in main():", error);
     process.exit(1);

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/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.45",
+  "version": "0.1.47",
   "description": "MCP server for Rhombus API",
   "keywords": [
     "ai",
@@ -49,6 +49,7 @@
     "dist"
   ],
   "dependencies": {
+    "@amplitude/analytics-node": "^1.5.60",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "axios": "^1.11.0",
     "cheerio": "^1.1.2",