rhombus-node-mcp 0.1.13 → 0.1.16

package/dist/tools/update-tool.js

@@ -0,0 +1,262 @@
+import { updateCameraConfig, getCameraDetails, cleanUpdatePayload, formatCameraSettings, } from "../api/update-tool-api.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS, UpdateCameraConfigPayload, CameraVideoSettings, CameraAudioSettings, CameraDeviceSettings, parseFacetedUuid, } from "../types/update-tool-types.js";
+import { logger } from "../logger.js";
+const TOOL_NAME = "update-tool";
+const TOOL_DESCRIPTION = `
+This tool allows updating configuration settings for various Rhombus entities. Currently supports:
+- **Cameras**: Update video settings (resolution, HDR, WDR, brightness, contrast, etc.), audio settings (recording, microphone, speaker), and device settings (name, timezone, LED control).
+
+For LED control, use EXACTLY these field names in cameraDeviceSettings:
+- To turn LED off: {"led_stealth_mode": true} (recommended) or {"led_mode": "always_off"}
+- To turn LED on: {"led_stealth_mode": false} or {"led_mode": "always_on"} or {"led_mode": "auto"}
+- IMPORTANT: Use underscore in field names (led_mode, led_stealth_mode), not camelCase
+
+The tool supports faceted UUIDs (e.g., "cameraUuid.v0" or "cameraUuid.v1") to update specific camera facets. If no facet is specified, defaults to "v0".
+
+The tool guides users through a multi-step process:
+1. Entity selection (if not provided)
+2. Settings configuration with current values shown
+3. Confirmation and application of changes
+
+Future support planned for:
+- Climate sensors
+- Door controllers
+- Environmental gateways
+
+The tool uses elicitation forms for rich user interaction and shows current settings before updates.
+`;
+const TOOL_HANDLER = async (args, extra) => {
+    const { entityType, entityUuid, cameraVideoSettings, cameraAudioSettings, cameraDeviceSettings, step, } = args;
+    // Handle camera updates
+    if (entityType === "camera") {
+        // Step 3: Apply settings (if settings provided)
+        if (entityUuid &&
+            ((cameraVideoSettings && cameraVideoSettings.trim()) ||
+                (cameraAudioSettings && cameraAudioSettings.trim()) ||
+                (cameraDeviceSettings && cameraDeviceSettings.trim()))) {
+            try {
+                // Parse the faceted UUID to extract base UUID and facet
+                const { baseUuid, facet } = parseFacetedUuid(entityUuid);
+                const updatePayload = {
+                    configUpdate: {
+                        deviceUuid: baseUuid,
+                    },
+                };
+                // Parse and add video settings
+                if (cameraVideoSettings && cameraVideoSettings.trim()) {
+                    const videoSettings = JSON.parse(cameraVideoSettings);
+                    // Validate with zod schema
+                    const validatedVideo = CameraVideoSettings.parse(videoSettings);
+                    updatePayload.configUpdate.videoFacetSettings = {
+                        [facet]: cleanUpdatePayload(validatedVideo),
+                    };
+                }
+                // Parse and add audio settings
+                if (cameraAudioSettings && cameraAudioSettings.trim()) {
+                    const audioSettings = JSON.parse(cameraAudioSettings);
+                    // Validate with zod schema
+                    const validatedAudio = CameraAudioSettings.parse(audioSettings);
+                    updatePayload.configUpdate.audioFacetSettings = {
+                        [facet]: cleanUpdatePayload(validatedAudio),
+                    };
+                }
+                // Parse and add device settings
+                if (cameraDeviceSettings && cameraDeviceSettings.trim()) {
+                    const deviceSettings = JSON.parse(cameraDeviceSettings);
+                    logger.debug("[update-tool] Raw device settings:", deviceSettings);
+                    // Transform ledMode to led_mode and OFF to always_off before validation
+                    if ("ledMode" in deviceSettings) {
+                        deviceSettings.led_mode =
+                            deviceSettings.ledMode === "OFF" ? "always_off" : deviceSettings.ledMode;
+                        delete deviceSettings.ledMode;
+                    }
+                    // Convert string "true"/"false" to boolean for led_stealth_mode
+                    if ("led_stealth_mode" in deviceSettings &&
+                        typeof deviceSettings.led_stealth_mode === "string") {
+                        deviceSettings.led_stealth_mode = deviceSettings.led_stealth_mode === "true";
+                    }
+                    // Validate with zod schema
+                    const validatedDevice = CameraDeviceSettings.parse(deviceSettings);
+                    logger.debug("[update-tool] Validated device settings:", validatedDevice);
+                    const cleaned = cleanUpdatePayload(validatedDevice);
+                    logger.debug("[update-tool] Cleaned device settings:", cleaned);
+                    updatePayload.configUpdate.deviceSettings = cleaned;
+                }
+                // Validate the full payload
+                const validatedPayload = UpdateCameraConfigPayload.parse(updatePayload);
+                // Apply the updates
+                const result = await updateCameraConfig(validatedPayload, extra._meta?.requestModifiers, extra.sessionId);
+                if (!result.success) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to update camera settings: ${result.error}`,
+                            },
+                        ],
+                    };
+                }
+                // Format the updated settings for display
+                const formattedSettings = formatCameraSettings(validatedPayload.configUpdate);
+                const jsonResultResponse = {
+                    needUserInput: false,
+                    success: true,
+                    message: `✅ Camera settings updated successfully!\n\n${formattedSettings}`,
+                    entityType: "camera",
+                    entityUuid,
+                    updatedSettings: validatedPayload.configUpdate,
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: jsonResultResponse.message,
+                        },
+                    ],
+                    structuredContent: jsonResultResponse,
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error updating camera settings: ${error instanceof Error ? error.message : "Unknown error"}`,
+                        },
+                    ],
+                };
+            }
+        }
+        // Step 2: Show settings configuration form (if entityUuid provided but no settings)
+        if (entityUuid && step !== "entity-selection") {
+            try {
+                // Parse the faceted UUID to extract base UUID
+                const { baseUuid } = parseFacetedUuid(entityUuid);
+                // Get current camera details
+                const cameraDetails = await getCameraDetails(baseUuid, extra._meta?.requestModifiers, extra.sessionId);
+                if (!cameraDetails.success || !cameraDetails.data) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to get camera details: ${cameraDetails.error || "Camera not found"}`,
+                            },
+                        ],
+                    };
+                }
+                const camera = cameraDetails.data;
+                const currentVideoSettings = camera.videoSettings || {};
+                const currentAudioSettings = camera.audioSettings || {};
+                const currentDeviceSettings = {
+                    camera_name: camera.name,
+                    camera_timezone: camera.timezone,
+                    led_intensity: camera.ledIntensity,
+                    led_mode: camera.ledMode,
+                };
+                const jsonResultResponse = {
+                    needUserInput: true,
+                    message: `Configure settings for camera "${camera.name}" (${entityUuid})\n\nCurrent settings are shown below. Modify the values you want to change:`,
+                    requestType: "camera-settings-configuration",
+                    submitAction: "update-tool",
+                    entityType: "camera",
+                    entityUuid,
+                    currentSettings: {
+                        video: currentVideoSettings,
+                        audio: currentAudioSettings,
+                        device: currentDeviceSettings,
+                    },
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(jsonResultResponse),
+                        },
+                    ],
+                    structuredContent: jsonResultResponse,
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error retrieving camera details: ${error instanceof Error ? error.message : "Unknown error"}`,
+                        },
+                    ],
+                };
+            }
+        }
+        // Step 1: Entity selection (if no entityUuid)
+        if (!entityUuid) {
+            const jsonResultResponse = {
+                needUserInput: true,
+                message: "Please provide the camera UUID you want to update.\n\nYou can provide a faceted UUID (e.g., 'cameraUuid.v0' or 'cameraUuid.v1') to update a specific facet, or just the base UUID to update facet v0 by default.\n\nYou can find the camera UUID in the Rhombus console or by using the search tools.",
+                requestType: "entity-selection",
+                submitAction: "update-tool",
+                entityType: "camera",
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(jsonResultResponse),
+                    },
+                ],
+                structuredContent: jsonResultResponse,
+            };
+        }
+    }
+    // Handle other entity types (future implementation)
+    if (entityType === "climate-sensor") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Climate sensor updates are not yet implemented. Coming soon!",
+                },
+            ],
+        };
+    }
+    if (entityType === "door-controller") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Door controller updates are not yet implemented. Coming soon!",
+                },
+            ],
+        };
+    }
+    if (entityType === "environmental-gateway") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Environmental gateway updates are not yet implemented. Coming soon!",
+                },
+            ],
+        };
+    }
+    // Step 0: Show initial form (no entityType provided)
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    needUserInput: true,
+                    message: "Welcome to the Rhombus entity update tool!\n\nWhat type of entity would you like to update?\n\n• **camera** - Update camera video, audio, or device settings\n• **climate-sensor** - Update climate sensor settings (coming soon)\n• **door-controller** - Update door controller settings (coming soon)\n• **environmental-gateway** - Update environmental gateway settings (coming soon)\n\nPlease specify the entity type to continue.",
+                    requestType: "entity-type-selection",
+                    submitAction: "update-tool",
+                }),
+            },
+        ],
+    };
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/transports/stdio.js

@@ -0,0 +1,10 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createServer from "../createServer.js";
+import { logger } from "../logger.js";
+export default async function stdioTransport() {
+    const server = await createServer();
+    const transport = new StdioServerTransport();
+    logger.info(`🚙 Starting stdio transport`);
+    await server.connect(transport);
+    logger.info(`🚙🌬️ Connected.`);
+}

package/dist/transports/streamable-http.js

@@ -0,0 +1,201 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import cors from "cors";
+import express from "express";
+import crypto from "node:crypto";
+import createServer from "../createServer.js";
+import { logger } from "../logger.js";
+var AuthScheme;
+(function (AuthScheme) {
+    AuthScheme["API_TOKEN"] = "api-token";
+    AuthScheme["CHATBOT"] = "chatbot";
+    AuthScheme["WEB2"] = "web2";
+})(AuthScheme || (AuthScheme = {}));
+export const authStore = new Map();
+const transports = new Map();
+export default function streamableHttpTransport() {
+    const app = express();
+    app.use(express.json());
+    app.use(cors({
+        // TODO: domain
+        origin: ["*"],
+        exposedHeaders: ["mcp-session-id"],
+        allowedHeaders: ["Content-Type", "mcp-session-id"],
+    }));
+    /**
+     * STATEFUL ENDPOINT
+     */
+    const authRequired = ["tools/call"];
+    app.post("/mcp", async (req, res) => {
+        logger.info(`Received MCP request`, JSON.stringify(req.body));
+        // Check for existing session ID
+        const sessionId = req.headers["mcp-session-id"];
+        let transport;
+        if (sessionId && transports.has(sessionId)) {
+            // Reuse existing transport
+            transport = transports.get(sessionId);
+        }
+        else if (!sessionId && isInitializeRequest(req.body)) {
+            // New initialization request
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: crypto.randomUUID,
+                onsessioninitialized: sessionId => {
+                    // Store the transport by session ID
+                    transports.set(sessionId, transport);
+                    logger.info(`🔒 MCP request initialized with sessionId: ${sessionId}`);
+                    try {
+                        const authScheme = req.headers["x-auth-scheme"] ?? "api-token";
+                        // if api key is provided
+                        if (authScheme === AuthScheme.API_TOKEN) {
+                            const apiKey = "x-auth-apikey" in req.headers
+                                ? req.headers["x-auth-apikey"]
+                                : process.env.RHOMBUS_API_KEY;
+                            if (!apiKey) {
+                                throw new Error("Invalid API Key provided! Please check the headers or environment variables");
+                            }
+                            logger.info(`🔒 MCP request authenticated with api key: ${apiKey}`);
+                            authStore.set(sessionId, {
+                                apiKey: apiKey,
+                                createdMs: Date.now(),
+                            });
+                        }
+                        else if (authScheme === AuthScheme.CHATBOT &&
+                            "x-auth-session" in req.headers &&
+                            "x-auth-chat" in req.headers) {
+                            logger.info(`🔒 MCP request authenticated with x-auth-session: ${req.headers["x-auth-session"]} and x-auth-chat: ${req.headers["x-auth-chat"]}`);
+                            // otherwise, store the sessionId and latestRecordUuid in authStore
+                            authStore.set(sessionId, {
+                                sessionId: req.headers["x-auth-session"],
+                                latestRecordUuid: req.headers["x-auth-chat"],
+                                createdMs: Date.now(),
+                            });
+                        }
+                        else if (authScheme === AuthScheme.WEB2 && "x-auth-cookie" in req.headers) {
+                            authStore.set(sessionId, {
+                                cookie: req.headers["x-auth-cookie"],
+                                createdMs: Date.now(),
+                            });
+                        }
+                        else {
+                            throw new Error(`Invalid auth scheme provided! x-auth-scheme: ${req.headers["x-auth-scheme"]}, x-auth-session: ${req.headers["x-auth-session"]}, x-auth-chat: ${req.headers["x-auth-chat"]}`);
+                        }
+                    }
+                    catch (e) {
+                        // only throw if this is an auth required call
+                        if (authRequired.includes(req.body.method)) {
+                            if (e instanceof Error) {
+                                logger.error(e.message);
+                            }
+                            else {
+                                logger.error(e);
+                            }
+                            throw e;
+                        }
+                    }
+                },
+                // DNS rebinding protection is disabled by default for backwards compatibility. If you are running this server
+                // locally, make sure to set:
+                // enableDnsRebindingProtection: true,
+                // allowedHosts: ['127.0.0.1'],
+            });
+            // Clean up transport when closed
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    transports.delete(transport.sessionId);
+                    authStore.delete(transport.sessionId);
+                }
+            };
+            const server = await createServer();
+            // Connect to the MCP server
+            await server.connect(transport);
+            logger.info(`🔗 Transport connected with sessionId: ${sessionId}`);
+        }
+        else {
+            // Invalid request
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Bad Request: No valid session ID provided",
+                },
+                id: null,
+            });
+            return;
+        }
+        // Handle the request
+        // modify request body to include meta
+        // if (req?.body?.params) {
+        //   req.body.params._meta = {
+        //     ...(req.body.params._meta ?? {}),
+        //     foo: "bar",
+        //   };
+        // }
+        // logger.trace("blah blah blah", JSON.stringify(req.body, null, 2));
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get("/mcp", async (_, res) => {
+        logger.warn("Received Not Allowed GET MCP request");
+        res.writeHead(405).end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        }));
+    });
+    app.delete("/mcp", async (req, res) => {
+        logger.warn("Received Not Allowed DELETE MCP request");
+        res.writeHead(405).end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        }));
+    });
+    /**
+     * STATELESS ENDPOINT
+     */
+    app.post("/mcp-stateless", async (req, res) => {
+        logger.info(`Received stateless MCP request`, req.body);
+        let transport;
+        transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        const server = await createServer();
+        // Connect to the MCP server
+        await server.connect(transport);
+        logger.info(`🔗 Stateless Transport connected`);
+        // Handle the request
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get("/mcp-stateless", async (req, res) => {
+        logger.warn("Received Not Allowed GET MCP request");
+        res.writeHead(405).end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        }));
+    });
+    app.delete("/mcp-stateless", async (req, res) => {
+        logger.warn("Received Not Allowed DELETE MCP request");
+        res.writeHead(405).end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        }));
+    });
+    // Start the server
+    const PORT = process.env.PORT || 3000;
+    app.listen(PORT, () => {
+        logger.info(`rhombus-node-mcp listening on port ${PORT}`);
+    });
+}

package/dist/{tools/devices/camera-tool/types.js → types/camera-tool-types.js}

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ISOTimestampFormatDescription } from "../utils/timestampInput.js";
 export const VideoFacetSettings = z
     .object({
     // blocked_debounce_time_ms: z.number().int().nullable(),
@@ -170,3 +171,15 @@ export const ExternalUpdateableFacetedUserConfigSchema = z.object({
     })
         .describe("For each of the object keys: v0, v1, v2, v3, they correspond to a specific facet of the camera, since a camera may have multiple facets, up to 4. Hence, why they are zero-indexed."),
 });
+export const BASE_TOOL_ARGS = {
+    cameraUuid: z.string().nullable().describe("the camera uuid requested"),
+    timestampISO: z
+        .string()
+        .datetime({ message: "Invalid ISO 8601 date format.", offset: true })
+        .nullable()
+        .describe(`
+      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"]),
+};
+const BASE_TOOL_ARGS_SCHEMA = z.object(BASE_TOOL_ARGS);

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

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { createEpochSchema, ISOTimestampFormatDescription } from "../utils/timestampInput.js";
+import { createUuidSchema } from "../types.js";
+export const TOOL_ARGS = {
+    queryType: z
+        .enum(["saved", "expiringSoon"])
+        .describe('The type of clips to retrieve. Use "saved" to get regular saved clips, and "expiringSoon" to get clips that are nearing their expiration date.'),
+    deviceUuidFilters: z
+        .array(createUuidSchema())
+        .nullable()
+        .describe("A list of UUIDs representing specific devices to filter clips by. Only clips emitted by these devices will be returned. Please truncate any facets, such as .v0. It is always 22 characters long."),
+    locationUuidFilters: z
+        .array(createUuidSchema())
+        .nullable()
+        .describe("A list of UUIDs representing specific locations to filter clips by. Only clips associated with these locations will be returned. Please truncate any facets, such as .v0. It is always 22 characters long."),
+    searchFilter: z
+        .string()
+        .nullable()
+        .describe("A simple string to search for within the names of the clips."),
+    timestampISOAfter: z
+        .string()
+        .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
+        .describe("The start of the time range for which to retrieve clips. Only clips that occurred AFTER this timestamp will be returned."
+        + ISOTimestampFormatDescription),
+    timestampISOBefore: z
+        .string()
+        .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
+        .describe("The end of the time range for which to retrieve clips. Only clips that occurred BEFORE this timestamp will be returned."
+        + ISOTimestampFormatDescription),
+};
+const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+export const ApiPayloadSchema = TOOL_ARGS_SCHEMA.transform((args) => {
+    const { queryType, timestampISOAfter, timestampISOBefore, ...rest } = args;
+    const timestampMsAfter = createEpochSchema().parse(timestampISOAfter);
+    const timestampMsBefore = createEpochSchema().parse(timestampISOBefore);
+    return {
+        ...rest,
+        timestampMsAfter,
+        timestampMsBefore,
+    };
+});

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

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { schemas } from "./zod-schemas.js";
+// Base schema for the elicitation request
+export const PolicyInfoSchema = z
+    .object({
+    name: z.string().min(1, "Policy name is required"),
+    description: z.string().optional(),
+    orgUuid: z.string().optional(),
+})
+    .describe("Camera policy information");
+export const TOOL_ARGS = {};
+const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+export const ApiPayloadSchema = schemas.Policy_CreateCameraPolicyWSRequest;
+export const OUTPUT_SCHEMA = z.object({
+    needUserInput: z.boolean().optional(),
+    message: z
+        .string()
+        .optional()
+        .describe("The message for this stage in the policy creation process.  This message will be displayed to the user."),
+    requestType: z
+        .enum(["policy-creation-form", "schedule-trigger-configuration", "camera-assignment"])
+        .optional()
+        .describe("The type of form to display to the user as the next step in the policy creation process"),
+    submitAction: z
+        .string()
+        .optional()
+        .describe("The action to take when the user completes the form, corresponds to the tool name to interact with next"),
+    policyUuid: z
+        .string()
+        .optional()
+        .describe("The UUID of the policy that was created during this workflow"),
+    policyName: z
+        .string()
+        .optional()
+        .describe("The name of the policy that was created during this workflow"),
+    scheduleData: z
+        .array(z.object({
+        uuid: z.string(),
+        name: z.string(),
+    }))
+        .nullable()
+        .optional()
+        .describe("The schedules that were created during this workflow, can be null or undefined if user has not created them yet with schedule-trigger-configuration"),
+});

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

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { CreateVideoWallOptions } from "../types.js";
+import { addConfirmationParams } from "../utils/confirmation.js";
+export const TOOL_ARGS = addConfirmationParams({
+    entityType: z.enum(["video-wall"]).describe("The entity type to create.  Example: video wall."),
+    videoWallCreateOptions: CreateVideoWallOptions,
+});
+const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);

package/dist/types/deviceType.js

@@ -10,5 +10,6 @@ var DeviceType;
     DeviceType["MOTION_SENSOR"] = "motion-sensor";
     DeviceType["BUTTON"] = "button";
     DeviceType["KEYPAD"] = "keypad";
+    DeviceType["ENVIRONMENTAL_GATEWAY"] = "environmental-gateway";
 })(DeviceType || (DeviceType = {}));
 export default DeviceType;

package/dist/types/endpoint-to-keys-tool-types.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const TOOL_ARGS = {
+    endpoint: z
+        .string()
+        .describe("The API endpoint to get output keys for (e.g., 'POST /api/camera/getMinimalCameraStateList')"),
+};
+const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);