rhombus-node-mcp 0.1.11 → 0.1.12

package/dist/network.js

@@ -0,0 +1,81 @@
+import { logger } from "./logger.js";
+export const RHOMBUS_API_KEY = process.env.RHOMBUS_API_KEY;
+if (!RHOMBUS_API_KEY) {
+    console.error("Missing RHOMBUS_API_KEY");
+}
+export const serverUrl = process.env.RHOMBUS_API_SERVER || "api2.rhombussystems.com";
+export const BASE_URL = `https://${serverUrl}/api`;
+export const STATIC_HEADERS = {
+    "Content-Type": "application/json",
+    "x-rhombus-agent": "chatbot",
+    accept: "application/json",
+};
+export const AUTH_HEADERS = {
+    "x-auth-apikey": RHOMBUS_API_KEY,
+    "x-auth-scheme": "api-token",
+};
+const enableLogs = process.env.ENABLE_LOGS;
+const log = (msg) => {
+    if (!enableLogs)
+        return;
+    console.error(msg);
+};
+export const appendQueryParams = (url, params) => {
+    if (!params || typeof params !== "object")
+        return url;
+    const urlObj = new URL(url);
+    const existingSearchParams = new URLSearchParams(urlObj.search);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+            existingSearchParams.append(key, String(value));
+        }
+    }
+    const baseUrl = url.split("?")[0];
+    const queryString = existingSearchParams.toString();
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+};
+export async function postApi(route, body, modifiers = undefined) {
+    let requestHeaders = {
+        ...(modifiers?.headers ?? AUTH_HEADERS),
+        ...STATIC_HEADERS,
+    };
+    let url = BASE_URL + route;
+    if (modifiers?.query) {
+        url = appendQueryParams(url, modifiers.query);
+    }
+    if (typeof body === "object") {
+        body = JSON.stringify(body);
+    }
+    try {
+        logger.info(`[POSTAPI] REQUEST - ${url} - ${body} - ${JSON.stringify(requestHeaders)}`);
+        const response = await fetch(url, {
+            method: "POST",
+            headers: requestHeaders,
+            body,
+        });
+        if (!response.ok) {
+            logger.debug(`❌ RESPONSE - ${response.ok} - ${response.status}`);
+            if (response.status === 401 || response.status === 403) {
+                return {
+                    error: true,
+                    status: "Sorry, I don't have permission to help with this request.  Consider upgrading my permissions by changing the role of the API Key I am using.",
+                };
+            }
+            throw {
+                body: JSON.parse(body),
+                error: await response.text(),
+            };
+            // throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        const ret = await response.json();
+        logger.debug(`✅ RESPONSE - ${response.ok} - ${JSON.stringify(ret)}`);
+        return ret;
+    }
+    catch (error) {
+        logger.error(`[POSTAPI] ERROR - ${JSON.stringify(error || {}, null, 4)}`);
+        return {
+            error: true,
+            status: `Request Error: ${error}`,
+        };
+    }
+}

package/dist/resources/getResources.js

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "node:url";
+import path from "path";
+import { getFilePathsInDirectory } from "../util.js";
+async function getResources() {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const filePaths = getFilePathsInDirectory(currentDir);
+    const resources = [];
+    for (const filePath of filePaths) {
+        const imported = (await import(filePath));
+        if (imported.createResource !== undefined) {
+            resources.push({
+                name: filePath,
+                create: imported.createResource,
+            });
+        }
+    }
+    return resources;
+}
+export default getResources;

package/dist/resources/llms.pdf.js

@@ -0,0 +1,19 @@
+import fs from "fs";
+import { fileURLToPath } from "node:url";
+import path from "path";
+// change from _createResource to createResource to add it back in
+export function _createResource(server) {
+    server.resource("knowledge-base.pdf", "knowledge-base://llms.pdf", async (uri) => {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const filePath = path.resolve(currentDir, "../../assets/llms.pdf");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: fs.readFileSync(filePath).toString(),
+                },
+            ],
+        };
+    });
+    return;
+}

package/dist/resources/routes.json.js

@@ -0,0 +1,31 @@
+import fs from "fs";
+import { fileURLToPath } from "node:url";
+import path from "path";
+// change from _createResource to createResource to add it back in
+export function createResource(server) {
+    server.resource("routes.json", "file://routes.json/", {
+        mimeType: "application/json",
+        description: `
+This resource provides a comprehensive catalog of application paths within the Rhombus Console, including both common and parameterized routes.
+Each path is accompanied by a brief description derived from KBA support articles, offering context on its function within the product.
+The resource also lists relevant external support links.
+The paths are categorized into "common_paths", "parameterized_paths", and "external_paths" for easy navigation and understanding.
+
+It is in the form of a JSON file.
+
+Use these paths to help the user navigate to the correct that they may want to go to. However, try not directly reference the path itself, rather describe it, and make sure to show the user a button to help navigate with.
+When providing a path, make sure to be very exact. You're only allowed to substitute in path segments that begin with : or are surrounded by brackets []. For example, /locations/:locationUuid, you need to get a location's UUID and replace :locationUuid with the actual UUID`,
+    }, async (uri) => {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const filePath = path.resolve(currentDir, "../../assets/routes.json");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: fs.readFileSync(filePath).toString(),
+                },
+            ],
+        };
+    });
+    return;
+}

package/dist/tools/clips-tool.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { postApi } from "../network.js";
+import { createToolArgs } from "../util.js";
+const ClipsArgs = z.object({
+    deviceUuidFilters: z
+        .array(z.string())
+        .optional()
+        .describe("A list of UUIDs representing specific devices to filter clips by. Only clips emitted by these devices will be returned."),
+    locationUuidFilters: z
+        .array(z.string())
+        .optional()
+        .describe("A list of UUIDs representing specific locations to filter clips by. Only clips associated with these locations will be returned."),
+    searchFilter: z
+        .string()
+        .optional()
+        .describe("A simple string to search for within the names of the clips."),
+    timestampMsAfter: z
+        .number()
+        .describe("The start of the time range (in milliseconds since epoch) for which to retrieve clips. Only clips that occurred AFTER this timestamp will be returned."),
+    timestampMsBefore: z
+        .number()
+        .describe("The end of the time range (in milliseconds since epoch) for which to retrieve clips. Only clips that occurred BEFORE this timestamp will be returned."),
+});
+async function getSavedClips(args, requestModifiers) {
+    return await postApi("/event/getClipsWithProgress", args, requestModifiers);
+}
+export function createTool(server) {
+    server.tool("clips-tool", `
+Retrieves saved video clips from the Rhombus system. Saved clips can be viewed for up to 2 years and are typically found in the "Clips" tab of the "Saved Video" section of the Rhombus Console.
+
+This tool allows you to filter clips by:
+* Specific devices using their UUIDs.
+* Specific locations using their UUIDs.
+* A simple string search on clip names.
+* A time range, specifying a start (timestampMsAfter) and/or end (timestampMsBefore) timestamp in milliseconds since epoch.
+
+The tool returns a JSON object with the following structure and important fields:
+* **errorMsg (string | null):** An error message if the request failed.
+* **objecterror (boolean | null):** Indicates if an object-level error occurred.
+* **pageToken (string | null):** A token to be supplied on the next search request to get the next page of results. If this token is null, there is no more data available.
+* **savedClips (array of objects | null):** An array where each object represents a saved video clip. Each clip object contains the following important fields:
+    * **uuid (string):** The unique identifier for the video clip.
+    * **title (string):** The name given to the video clip.
+    * **description (string | null):** An optional description for the clip.
+    * **timestampMs (int64):** The start time of the video clip in milliseconds since epoch.
+    * **createdAtMs (int64):** The creation timestamp of the clip in milliseconds since epoch.
+    * **deviceUuid (string):** The UUID of the primary device (e.g., camera) that recorded the clip.
+    * **deviceUuids (array of strings or null):** A list of UUIDs for all devices associated with the clip.
+    * **durationSec (int32):** The length of the video clip in seconds.
+    * **status (string):** The current processing status of the clip, with possible values such as INITIATING, UPLOADING, RENDERING, FAILED, COMPLETE, OFFLINE, or UNKNOWN.
+    * **userUuid (string | null):** The UUID of the user associated with the clip, if applicable.
+    * **sourceAlertUuid (string | null):** The UUID of the alert that triggered the creation of this clip, if any.
+`, createToolArgs({
+        ...ClipsArgs.shape,
+    }), async ({ requestModifiers, ...args }) => {
+        let ret;
+        ret = await getSavedClips(args, requestModifiers);
+        return {
+            content: [{ type: "text", text: JSON.stringify(ret) }],
+        };
+    });
+}

package/dist/tools/create-tool.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { createToolArgs } from "../util.js";
+import { CreateVideoWallOptions } from "../types.js";
+import { postApi } from "../network.js";
+import { logger } from "../logger.js";
+import { addConfirmationParams, requireConfirmation } from "../utils/confirmation.js";
+async function createVideoWall(options, headers) {
+    const body = {
+        videoWall: {
+            displayName: options?.displayName,
+            deviceList: options?.deviceList,
+            othersCanEdit: true,
+            orgUuid: options?.orgUuid,
+            shared: true,
+            settings: {
+                gridSize: { width: options?.settings.columnCount, height: options?.settings.columnCount },
+                gridLayout: "1 2\n3 4",
+                intervalSeconds: options?.settings.intervalSeconds || 5,
+            },
+        },
+    };
+    const response = await postApi("/camera/createVideoWall", body, headers);
+    return response;
+}
+async function handleCreateVideoWallRequest(videoWallCreateOptions, headers) {
+    let text = "Unable to create video wall!";
+    logger.error("🔨 Creating video wall");
+    if (!videoWallCreateOptions?.displayName) {
+        text = JSON.stringify({
+            needUserInput: true,
+            commandForUser: "What should the name of the video wall be?",
+        });
+    }
+    else if ((videoWallCreateOptions?.deviceList || []).length === 0) {
+        text = JSON.stringify({
+            needUserInput: true,
+            commandForUser: "Which cameras would you like on this video wall?",
+        });
+    }
+    else {
+        logger.error("Creating video wall with options: ", JSON.stringify(videoWallCreateOptions));
+        text = JSON.stringify(await createVideoWall(videoWallCreateOptions, headers));
+    }
+    return Promise.resolve({
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+    });
+}
+export function createTool(server) {
+    server.tool("create-tool", "Tool for creating many entity types such as video walls.", addConfirmationParams(createToolArgs({
+        entityType: z
+            .enum(["video-wall"])
+            .describe("The entity type to create.  Example: video wall."),
+        videoWallCreateOptions: CreateVideoWallOptions,
+    })), async ({ entityType, videoWallCreateOptions, requestModifiers, confirmationId }) => {
+        const confirmation = requireConfirmation(confirmationId);
+        if (confirmation === true) {
+            switch (entityType) {
+                case "video-wall":
+                    return await handleCreateVideoWallRequest(videoWallCreateOptions, requestModifiers);
+                default:
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "",
+                    },
+                ],
+            };
+        }
+        else {
+            return confirmation;
+        }
+    });
+}

package/dist/tools/devices/camera-tool/camera-tool.js

@@ -0,0 +1,218 @@
+import { z } from "zod";
+import { getLogger } from "../../../logger.js";
+import { appendQueryParams, AUTH_HEADERS, postApi, STATIC_HEADERS } from "../../../network.js";
+import { createToolArgs, createToolTextContent, removeNullFields, } from "../../../util.js";
+import { addConfirmationParams, isConfirmed, requireConfirmation, } from "../../../utils/confirmation.js";
+import { ExternalUpdateableFacetedUserConfigSchema, } from "./types.js";
+const logger = getLogger("camera-tool");
+async function getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers) {
+    const body = {
+        cameraUuid: cameraUuid,
+        downscaleFactor: 10,
+        jpgQuality: 70,
+        permyriadCropHeight: 10000,
+        permyriadCropWidth: 5625,
+        permyriadCropX: 2188,
+        permyriadCropY: 0,
+        timestampMs: timestampMs,
+    };
+    logger.debug(`Getting frameUri from UUID: ${cameraUuid} at timestampMs: ${timestampMs}`);
+    const base64Image = await postApi("/video/getExactFrameUri", body, requestModifiers).then(async (res) => {
+        logger.debug(`Received frameUri ${res.frameUri}`);
+        // construct request headers
+        let requestHeaders = {
+            ...(requestModifiers?.headers ?? AUTH_HEADERS),
+            ...STATIC_HEADERS,
+        };
+        // add query params
+        if (requestModifiers?.query) {
+            res.frameUri = appendQueryParams(res.frameUri, requestModifiers.query);
+        }
+        logger.trace(`Fetching with headers\n${JSON.stringify(requestHeaders)}`);
+        return await fetch(res.frameUri, {
+            method: "GET",
+            headers: requestHeaders,
+        }).then(async (res) => {
+            if (!res.ok) {
+                logger.error(`Failed to fetch image: ${await res.text()}`);
+                logger.error(res);
+                return null;
+            }
+            const arrayBuffer = await res.arrayBuffer();
+            const buffer = Buffer.from(arrayBuffer);
+            const base64 = buffer.toString("base64");
+            return base64;
+        });
+    });
+    if (!base64Image) {
+        return {
+            success: false,
+            status: "failed to fetch image",
+        };
+    }
+    return {
+        success: true,
+        status: "successfully fetched image",
+        imageType: "base64",
+        imageData: base64Image,
+    };
+}
+export async function getCameraSettings(cameraUuid, requestModifiers) {
+    const res = await postApi("/camera/getFacetedConfig", {
+        deviceUuid: cameraUuid,
+    }, requestModifiers);
+    if (res.error) {
+        return {
+            success: false,
+            status: "failed to fetch camera settings",
+        };
+    }
+    return {
+        success: true,
+        config: res.config,
+        status: "fetched camera settings",
+    };
+}
+export async function updateCameraSettings(cameraUuid, update, requestModifiers) {
+    // remove any "null" values
+    const res = await postApi("/camera/updateFacetedConfig", {
+        configUpdate: {
+            deviceUuid: cameraUuid,
+            ...removeNullFields(update),
+        },
+    }, requestModifiers);
+    if (res.error) {
+        return {
+            success: false,
+            status: "failed to update camera settings",
+        };
+    }
+    return {
+        success: true,
+        config: res.config,
+        status: "updated camera settings",
+    };
+}
+export function createTool(server) {
+    server.tool("camera-tool", `
+This tool can perform some action pertaining to the video stream of a camera. There are three types of requests
+that can be passed into "requestType":
+- image
+- get-settings
+- update-settings
+
+What follows is a description of the behavior of this tool given the requestType
+
+If the requestType is "image":
+
+This tool captures and returns a real-time snapshot from a designated security camera.
+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: \n
+ •  Visual Scene Capture: A high-resolution image of what the camera is actively observing, including people, vehicles, license plates, and any detectable objects. \n
+ •  Enriched Data Potential: The image can be paired with AI models or downstream analytics to extract insights such as: \n•  Number and type of objects in frame (e.g., humans, cars, packages) \n•  Unusual behaviors (e.g., loitering, unauthorized access) \n•  Environmental conditions (e.g., lighting, obstruction, cleanliness) \nUse Cases: \n•  Verify what triggered a motion alert or analytic rule. \n•  Provide visual context for access events or alarms. \n• Support live incident triage or retrospective investigations. \n• Feed contextual imagery to agents making security or operational decisions. \nInvocation Notes: \nTo use this tool correctly, the agent should provide the specific camera identifier or location name. If possible, include the intent (e.g., "verify unauthorized access", "identify vehicle", "check for obstructions") to enhance downstream processing or summarization.
+ 
+If the requestType is "get-settings":
+
+THIS TOOL UPDATES AND SETS DATA.
+
+This tool retrieves the current configuration for a specified camera or associated device (e.g., sensor, access controller). The returned JSON object can include detailed camera settings (e.g., resolution, bitrate) and various device-specific configurations.
+Use Cases: Retrieve the current resolution of Camera A.
+
+If the requestType is "update-settings":
+
+THIS TOOL UPDATES AND SETS DATA.
+
+You can call call this tool with requestType "get-settings" and/or with "image" first to get a better idea of what needs to be updated.
+This tool updates the configuration for a camera or associated device using the "configUpdate" parameter, which must be a JSON object containing the specific fields and their new values. For example, you can modify streaming parameters.
+Thus, "configUpdate' is a necessary parameter if updating settings.
+Please make sure you only update the necessary fields, since any unnecessary changes may cause the camera to behave improperly.
+It may be a good idea to call "image" on this tool again after updating settings to make sure the new settings were effective in fulfilling
+the user's request.
+Use Cases: Adjust streaming parameters for Camera E.
+`, addConfirmationParams(createToolArgs({
+        requestType: z.enum(["image", "get-settings", "update-settings"]),
+        timestampMs: z.optional(z.number()).describe(`
+          the timestamp in milliseconds. You can default to the current time if the user didn't specify a time, or you can call time-tool to parse the user's time description
+          `),
+        cameraUuid: z.optional(z.string()).describe("the camera uuid requested"),
+        configUpdate: ExternalUpdateableFacetedUserConfigSchema.optional().describe('the config update that would be applied to the camera if the requestType is "update-settings"'),
+    })), async ({ cameraUuid, timestampMs, requestType, configUpdate, requestModifiers, confirmationId, }) => {
+        if (!cameraUuid) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            needUserInput: true,
+                            commandForUser: "Which camera are you talking about?",
+                        }),
+                    },
+                ],
+            };
+        }
+        let response;
+        switch (requestType) {
+            case "image":
+                if (!timestampMs) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    needUserInput: true,
+                                    commandForUser: "At what time?",
+                                }),
+                            },
+                        ],
+                    };
+                }
+                response = await getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers);
+                if (!response.success || !response.imageData) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(response) }],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "image",
+                            data: response.imageData,
+                            mimeType: "image/jpeg",
+                        },
+                    ],
+                };
+            case "get-settings":
+                response = await getCameraSettings(cameraUuid, requestModifiers);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response) }],
+                };
+            case "update-settings":
+                const confirmation = requireConfirmation(confirmationId);
+                if (!isConfirmed(confirmation)) {
+                    return confirmation;
+                }
+                if (!configUpdate) {
+                    return createToolTextContent("Missing configUpdate");
+                }
+                response = await updateCameraSettings(cameraUuid, configUpdate, requestModifiers);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response) }],
+                };
+            default:
+                response = {
+                    error: true,
+                    status: "missing unknown type from tool call",
+                };
+                break;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ response }),
+                },
+            ],
+        };
+    });
+}