rhombus-node-mcp 0.1.13 → 0.1.16

package/README.md

@@ -49,7 +49,7 @@ Your insights will directly influence our development roadmap and help us create
         "--rm",
         "-e",
         "RHOMBUS_API_KEY=YOUR_API_KEY_HERE",
-        "johnrhombusdocker/mcp-server-rhombus"
+        "rhombussystems/mcp-server-rhombus"
       ],
       "env": {
         "RHOMBUS_API_KEY": "YOUR_API_KEY_HERE"
@@ -106,7 +106,7 @@ docker build -t mcp-server-rhombus .
 ### 2. Update Your Claude Config for Local Use ⚡
 Now, you'll need to adjust your `claude_desktop_config.json` to point to your newly built local Docker image.
 
-> ***Note:*** When running locally, the Docker image name changes to `mcp-server-rhombus` from `johnrhombusdocker/mcp-server-rhombus`. Make sure to update this in your configuration!
+> ***Note:*** When running locally, the Docker image name changes to `mcp-server-rhombus` from `rhombussystems/mcp-server-rhombus`. Make sure to update this in your configuration!
 
 ```json
 {
@@ -129,7 +129,15 @@ Now, you'll need to adjust your `claude_desktop_config.json` to point to your ne
 }
 ```
 
-### Hitting a Snag? We've Got You! 🛟
+## Creating a new tool
+
+We've written a script that you can run to get kickstarted on developing a new tool in addition to our existing tool set. You can simply call:
+
+```sh
+npm run create:tool
+```
+
+## Hitting a Snag? We've Got You! 🛟
 
 Check out Claude's fantastic [troubleshooting guide](https://modelcontextprotocol.io/docs/tools/debugging) for quick fixes! Still stuck? Our team of experts is ready to help!
 

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

@@ -0,0 +1,108 @@
+import { getLogger } from "../logger.js";
+import { appendQueryParams, AUTH_HEADERS, postApi, STATIC_HEADERS } from "../network.js";
+import { removeNullFields } from "../util.js";
+const logger = getLogger("camera-tool");
+export async function getImageForCameraAtTime(cameraUuid, timestampMs, requestModifiers, sessionId) {
+    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({
+        route: "/video/getExactFrameUri",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    }).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");
+            logger.debug(`Received image base64:\n ${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, sessionId) {
+    const res = await postApi({
+        route: "/camera/getFacetedConfig",
+        body: {
+            deviceUuid: cameraUuid,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    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, sessionId) {
+    // remove any "null" values
+    const res = await postApi({
+        route: "/camera/updateFacetedConfig",
+        body: {
+            configUpdate: {
+                deviceUuid: cameraUuid,
+                ...removeNullFields(update),
+            },
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error) {
+        return {
+            success: false,
+            status: "failed to update camera settings",
+        };
+    }
+    return {
+        success: true,
+        config: res.config,
+        status: "updated camera settings",
+    };
+}

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

@@ -0,0 +1,36 @@
+import { postApi } from "../network.js";
+export async function getSavedClips(args, requestModifiers, sessionId) {
+    return await postApi({
+        route: "/event/getClipsWithProgress",
+        body: args,
+        modifiers: requestModifiers,
+        sessionId,
+    }).then(response => {
+        if (response.error)
+            return response;
+        else
+            return (response.savedClips?.map((clip) => ({
+                ...clip,
+                createdAtTimestamp: clip.createdAtMs ? new Date(clip.createdAtMs).toISOString() : null,
+            })) ?? []);
+    });
+}
+export async function getExpiringClips(args, requestModifiers, sessionId) {
+    return await postApi({
+        route: "/event/getExpiringClipsForOrg",
+        body: args,
+        modifiers: requestModifiers,
+        sessionId,
+    }).then(response => {
+        if (response.error)
+            return response;
+        else
+            return {
+                ...response,
+                savedClips: (response.savedClips || []).map((clip) => ({
+                    ...clip,
+                    createdAtTimestamp: clip.createdAtMs ? new Date(clip.createdAtMs).toISOString() : null,
+                })),
+            };
+    });
+}

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

@@ -0,0 +1,9 @@
+import { postApi } from "../network.js";
+export async function createCameraPolicy(args, requestModifiers, sessionId) {
+    return await postApi({
+        route: "/policy/createCameraPolicy",
+        body: args,
+        modifiers: requestModifiers,
+        sessionId,
+    });
+}

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

@@ -0,0 +1,53 @@
+import { logger } from "../logger.js";
+import { postApi } from "../network.js";
+export async function createVideoWall(options, requestModifiers, sessionId) {
+    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({
+        route: "/camera/createVideoWall",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    return response;
+}
+export async function handleCreateVideoWallRequest(videoWallCreateOptions, requestModifiers, sessionId) {
+    let text = "Unable to create video wall!";
+    logger.info("🔨 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.info("Creating video wall with options: ", JSON.stringify(videoWallCreateOptions));
+        text = JSON.stringify(await createVideoWall(videoWallCreateOptions, requestModifiers, sessionId));
+    }
+    return Promise.resolve({
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+    });
+}

package/dist/api/entity-lookup-tool-api.js

@@ -0,0 +1,37 @@
+import { getAccessControlledDoors, getAudioGateways, getBadgeReaders, getButtons, getCameraList, getDoorbellCameras, getDoorSensors, getEnvironmentalGateways, getEnvironmentalSensors, getKeypads, getMotionSensors, } from "./get-entity-tool-api.js";
+export async function getAllEntities(deviceUuids, timeZone, tempUnit, requestModifiers, sessionId) {
+    const promises = [
+        getCameraList(requestModifiers, sessionId),
+        getDoorbellCameras(requestModifiers, sessionId),
+        getBadgeReaders(requestModifiers, sessionId),
+        getAccessControlledDoors(requestModifiers, sessionId),
+        getAudioGateways(timeZone, requestModifiers, sessionId),
+        getDoorSensors(requestModifiers, sessionId),
+        getEnvironmentalSensors(timeZone, tempUnit, requestModifiers, sessionId),
+        getMotionSensors(requestModifiers, sessionId),
+        getButtons(timeZone, requestModifiers, sessionId),
+        getKeypads(requestModifiers, sessionId),
+        getEnvironmentalGateways(timeZone, requestModifiers, sessionId),
+    ];
+    const responses = await Promise.all(promises);
+    // Filter each response to only include devices with matching UUIDs
+    for (let i = 0; i < responses.length; i++) {
+        const response = responses[i];
+        // Look through keys and find any with an array
+        for (const key of Object.keys(response)) {
+            const value = response[key];
+            if (Array.isArray(value)) {
+                // Filter to only include devices with matching UUIDs
+                response[key] = value.filter((item) => {
+                    return deviceUuids.includes(item.uuid);
+                });
+                response[`${key}Count`] = response[key].length;
+            }
+        }
+    }
+    const result = {};
+    for (const response of responses) {
+        Object.assign(result, response);
+    }
+    return result;
+}

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

@@ -0,0 +1,320 @@
+import z from "zod";
+import { FIVE_SECONDS_MS, THREE_HOURS_MS } from "../constants.js";
+import { postApi } from "../network.js";
+import { formatTimestamp } from "../util.js";
+import { tempFunc, TempUnit } from "../utils/temp.js";
+// Type definitions
+export const HumanEvent = z.object({
+    timestamp: z.number(),
+    id: z.number(),
+});
+export async function getFaceEvents(_locationUuid, timeZone, requestModifiers, sessionId) {
+    const nowMs = Date.now();
+    const rangeStartMs = nowMs - THREE_HOURS_MS;
+    const rangeEndMs = nowMs - FIVE_SECONDS_MS;
+    const body = {
+        pageRequest: {
+            lastEvaluatedKey: undefined,
+            maxPageSize: 75,
+        },
+        searchFilter: {
+            deviceUuids: [],
+            faceNames: [],
+            labels: [],
+            locationUuids: [],
+            personUuids: [],
+            timestampFilter: {
+                rangeStart: rangeStartMs,
+                rangeEnd: rangeEndMs,
+            },
+        },
+    };
+    const response = await postApi({
+        route: "/faceRecognition/faceEvent/findFaceEventsByOrg",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    }).then(response => {
+        return {
+            faceEvents: (response.faceEvents || []).map(event => ({
+                ...event,
+                eventTimestamp: event.eventTimestamp
+                    ? formatTimestamp(event.eventTimestamp, timeZone)
+                    : undefined,
+            })),
+        };
+    });
+    return response;
+}
+export async function getAccessControlEvents(doorUuids, startTime, endTime, timeZone, requestModifiers, sessionId) {
+    const bodies = doorUuids.map(doorUuid => ({
+        accessControlledDoorUuid: doorUuid,
+        ...(startTime ? { createdAfterMs: startTime } : {}),
+        ...(endTime ? { createdBeforeMs: endTime } : {}),
+        typeFilter: ["CredentialReceivedEvent"],
+    }));
+    const responses = await Promise.all(bodies.map(body => postApi({
+        route: "/component/findComponentEventsByAccessControlledDoor",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    }).then(response => {
+        return (response.componentEvents || [])
+            .map((credEvent) => {
+            return {
+                authenticationResult: credEvent?.authenticationResult,
+                authorizationResult: credEvent?.authorizationResult,
+                doorUuid: credEvent?.componentCompositeUuid,
+                locationUuid: credEvent?.locationUuid,
+                user: credEvent?.originator?.username,
+                credSource: credEvent?.credSource,
+                datetime: credEvent?.timestampMs
+                    ? formatTimestamp(credEvent.timestampMs, timeZone)
+                    : undefined,
+            };
+        })
+            .filter(Boolean);
+    })));
+    // Flatten all componentEvents into a single array
+    const accessControlEvents = responses.flatMap(events => events);
+    console.error(`componentEvents: ${JSON.stringify(accessControlEvents)}`);
+    return accessControlEvents;
+}
+export async function getHumanMotionEvents(cameraUuid, duration, startTime, requestModifiers, sessionId) {
+    const body = {
+        cameraUuid,
+        duration,
+        startTime: Math.round(startTime / 1000),
+    };
+    const response = await postApi({
+        route: "/camera/getFootageSeekpointsV2",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    }).then(response => {
+        const seekPoints = response.footageSeekPoints || [];
+        const uniqueHumanEvents = seekPoints
+            .reduceRight((acc, point) => {
+            if (point.a === "MOTION_HUMAN" &&
+                typeof point.ts === "number" &&
+                typeof point.id === "number" &&
+                !acc.some(existing => existing.id === point.id)) {
+                acc.unshift({ timestamp: point.ts, id: point.id });
+            }
+            return acc;
+        }, [])
+            .map(event => ({
+            timestamp: event.timestamp,
+            id: event.id,
+        }));
+        return { cameraUuid, uniqueHumanEvents };
+    });
+    return response;
+}
+const EVENT_COUNT_MAX_PER_RESPONSE = 2000;
+export async function getEventsForEnvironmentalGateway(deviceUuid, startTime, endTime, timeZone, tempUnit, requestModifiers, sessionId) {
+    let allEvents = [];
+    let hasMore = true;
+    let lastEvaluatedKey = undefined;
+    while (hasMore) {
+        const body = {
+            deviceUuid,
+            ...(startTime ? { createdAfterMs: startTime } : {}),
+            ...(endTime ? { createdBeforeMs: endTime } : {}),
+            maxPageSize: EVENT_COUNT_MAX_PER_RESPONSE,
+            ...(lastEvaluatedKey ? { lastEvaluatedKey } : {}),
+        };
+        const response = await postApi({
+            route: "/climate/getEventsForEnvironmentalGateway",
+            body,
+            modifiers: requestModifiers,
+            sessionId,
+        }).then(response => {
+            const tempFunc = tempUnit === TempUnit.FAHRENHEIT
+                ? (temp) => (temp * 9) / 5 + 32
+                : (temp) => temp;
+            return {
+                events: (response.events || []).map(event => ({
+                    timestampString: event.timestampMs
+                        ? formatTimestamp(event.timestampMs, timeZone)
+                        : undefined,
+                    temp: tempFunc(event.co2Sense?.tempC ?? 0),
+                    probeTemp: tempFunc(event.tempProbe?.tempC ?? 0),
+                    humidity: event.co2Sense?.relHumid,
+                    pm25: event.pmSense?.pm2p5,
+                    co2: event.co2Sense?.co2Ppm,
+                    vapeDetected: event.derivedValues?.vapeDetected,
+                })),
+                lastEvaluatedKey: response.lastEvaluatedKey,
+            };
+        });
+        // Accumulate the events
+        if (response.events) {
+            allEvents.push(...response.events);
+        }
+        // Check if we should continue pagination
+        if (response.events &&
+            response.events.length === EVENT_COUNT_MAX_PER_RESPONSE &&
+            response.lastEvaluatedKey &&
+            response.lastEvaluatedKey !== null) {
+            // Update the lastEvaluatedKey for the next iteration
+            lastEvaluatedKey = response.lastEvaluatedKey;
+        }
+        else {
+            hasMore = false;
+        }
+    }
+    return {
+        events: allEvents,
+        lastEvaluatedKey: undefined, // Don't return lastEvaluatedKey since we've fetched all pages
+    };
+}
+export async function getClimateEventsForSensor(sensorUuid, startTime, endTime, limit, timeZone, tempUnit, requestModifiers, sessionId) {
+    let allClimateEvents = [];
+    let hasMore = true;
+    let remainingLimit = limit || 1000; // Default to 1000 if no limit specified
+    while (hasMore && allClimateEvents.length < remainingLimit) {
+        const currentBatchSize = Math.min(100, remainingLimit - allClimateEvents.length); // Max 100 per request
+        const body = {
+            sensorUuid,
+            ...(startTime ? { createdAfterMs: startTime } : {}),
+            ...(endTime ? { createdBeforeMs: endTime } : {}),
+            limit: currentBatchSize,
+        };
+        const response = await postApi({
+            route: "/climate/getClimateEventsForSensor",
+            body,
+            modifiers: requestModifiers,
+            sessionId,
+        });
+        if (response?.climateEvents) {
+            // Map the climate events to include formatted timestamp and relevant fields
+            const mappedEvents = response.climateEvents.map(event => ({
+                timestampString: event.timestampMs
+                    ? formatTimestamp(event.timestampMs, timeZone)
+                    : undefined,
+                timestampMs: event.timestampMs,
+                temp: event.temp,
+                probeTemp: tempFunc(event.probeTempC ?? 0, tempUnit),
+                // probeTempC: event.probeTempC,
+                // probeTempF: event.probeTempC ? (event.probeTempC * 9) / 5 + 32 : undefined,
+                humidity: event.humidity,
+                pm25: event.pm25,
+                co2: event.co2,
+                tvoc: event.tvoc,
+                iaq: event.iaq,
+                ethanol: event.ethanol,
+                heatIndexDegF: event.heatIndexDegF,
+                heatIndexRangeWarning: event.heatIndexRangeWarning,
+                vapeSmokeDetected: event.vapeSmokeDetected,
+                vapeSmokePercent: event.vapeSmokePercent,
+                thcDetected: event.thcDetected,
+                thcPercent: event.thcPercent,
+                tampered: event.tampered,
+                batteryPercentage: event.batteryPercentage,
+                locationUuid: event.locationUuid,
+                orgUuid: event.orgUuid,
+            }));
+            allClimateEvents.push(...mappedEvents);
+            // Check if we got a full batch and haven't reached the limit
+            if (response.climateEvents.length === currentBatchSize &&
+                allClimateEvents.length < remainingLimit) {
+                // Prepare for the next batch by updating the endTime to the oldest event's timestamp
+                if (mappedEvents.length > 0) {
+                    const oldestEventTimestamp = mappedEvents[mappedEvents.length - 1].timestampMs;
+                    if (oldestEventTimestamp) {
+                        endTime = oldestEventTimestamp - 1; // Subtract 1ms to avoid duplicates
+                    }
+                    else {
+                        hasMore = false;
+                    }
+                }
+                else {
+                    hasMore = false;
+                }
+            }
+            else {
+                hasMore = false;
+            }
+        }
+        else {
+            hasMore = false;
+        }
+    }
+    // Trim to the requested limit if we got more than needed
+    if (limit && allClimateEvents.length > limit) {
+        allClimateEvents = allClimateEvents.slice(0, limit);
+    }
+    return allClimateEvents;
+}
+export async function getComponentEventsByLocation(locationUuid, eventTypes, // Still accept string[] for flexibility
+startTime, endTime, timeZone, requestModifiers, sessionId) {
+    const MAX_LIMIT = 1000; // API limit for component events
+    const body = {
+        locationUuid,
+        typeFilter: eventTypes.length > 0 ? eventTypes : undefined, // API accepts string array
+        ...(startTime ? { createdAfterMs: startTime } : {}),
+        ...(endTime ? { createdBeforeMs: endTime } : {}),
+        limit: MAX_LIMIT,
+    };
+    const response = await postApi({
+        route: "/component/findComponentEventsByLocation",
+        body,
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    const events = (response.componentEvents || []).map(event => {
+        // Map different event types to a common structure
+        const baseEvent = {
+            eventType: event.type,
+            componentUuid: event.componentUuid,
+            locationUuid: event.locationUuid,
+            orgUuid: event.orgUuid,
+            correlationId: event.correlationId,
+            ownerDeviceUuid: event.ownerDeviceUuid,
+            datetime: event.timestampMs ? formatTimestamp(event.timestampMs, timeZone) : undefined,
+            timestampMs: event.timestampMs,
+            uuid: event.uuid,
+        };
+        // Add event-specific fields based on type
+        if (event.type === "CredentialReceivedEvent") {
+            const credEvent = event;
+            return {
+                ...baseEvent,
+                authenticationResult: credEvent?.authenticationResult,
+                authorizationResult: credEvent?.authorizationResult,
+                user: credEvent?.originator?.username,
+                credSource: credEvent?.credSource,
+                doorUuid: credEvent?.componentCompositeUuid,
+            };
+        }
+        else if (event.type === "DoorbellEvent") {
+            return {
+                ...baseEvent,
+                doorbellCameraUuid: event.componentUuid,
+            };
+        }
+        else if (event.type === "DoorStateChangeEvent") {
+            const doorEvent = event;
+            return {
+                ...baseEvent,
+                previousState: doorEvent?.previousState,
+                newState: doorEvent?.newState,
+                reason: doorEvent?.reason,
+            };
+        }
+        else if (event.type === "ButtonEvent" || event.type === "PanicButtonEvent") {
+            const buttonEvent = event;
+            return {
+                ...baseEvent,
+                buttonState: buttonEvent?.buttonState,
+            };
+        }
+        // For other event types, return the base event
+        return baseEvent;
+    });
+    // Sort events by timestamp (newest first)
+    events.sort((a, b) => (b.timestampMs || 0) - (a.timestampMs || 0));
+    console.error(`componentEvents: ${JSON.stringify(events)}`);
+    return events;
+}