@butlr/butlr-mcp-server 0.1.0

package/dist/tools/butlr-get-occupancy-timeseries.js

@@ -0,0 +1,145 @@
+import { ReportingRequestBuilder } from "../clients/reporting-client.js";
+import { z } from "zod";
+import { validateTimeRange } from "../utils/time-range-validator.js";
+import { fetchTopologyAndSensors, resolveAssetContext, getPresenceMeasurement, getTrafficMeasurement, getPresenceCoverageNote, getTrafficCoverageNote, buildRecommendation, } from "../utils/occupancy-helpers.js";
+import { rethrowIfGraphQLError } from "../utils/graphql-helpers.js";
+const GET_OCCUPANCY_TIMESERIES_DESCRIPTION = "Get occupancy timeseries data for floors, rooms, or zones. Automatically queries both traffic and presence measurements, " +
+    "analyzes which are available based on sensor configuration, and returns structured data with timezone context. " +
+    "Single tool call provides complete occupancy picture without guessing measurement types.";
+/** Shared shape — used by both registerTool (SDK schema) and full validation */
+const getOccupancyTimeseriesInputShape = {
+    asset_ids: z.array(z.string()).min(1).max(50).describe("Floor, room, or zone IDs"),
+    interval: z
+        .enum(["1m", "1h", "1d"])
+        .describe("Aggregation interval (1m=max 1hr range, 1h=max 48hrs, 1d=max 60 days)"),
+    start: z.string().describe("ISO-8601 timestamp or relative time (e.g., '-24h')"),
+    stop: z.string().describe("ISO-8601 timestamp or relative time (e.g., 'now')"),
+};
+export const GetOccupancyTimeseriesArgsSchema = z.object(getOccupancyTimeseriesInputShape).strict();
+/**
+ * Query a single measurement type and map to TimeseriesPoint[].
+ * Returns the array on success, or undefined on failure (with warning set on data).
+ */
+async function queryTimeseries(assetType, assetId, measurement, start, stop, interval) {
+    const response = await new ReportingRequestBuilder()
+        .assets(assetType, [assetId])
+        .measurements([measurement])
+        .timeRange(start, stop)
+        .window(interval, "median")
+        .execute();
+    if (response.data && Array.isArray(response.data)) {
+        return response.data.map((d) => ({
+            timestamp: new Date(d.time).toISOString(),
+            value: d.value,
+        }));
+    }
+    return [];
+}
+/**
+ * Execute unified occupancy timeseries tool
+ */
+export async function executeGetOccupancyTimeseries(args) {
+    // Validate time range — let errors throw naturally
+    validateTimeRange(args.interval, args.start, args.stop);
+    if (process.env.DEBUG) {
+        console.error(`[butlr-get-occupancy-timeseries] Querying ${args.asset_ids.length} assets`);
+    }
+    // Fetch topology and sensors in parallel
+    const ctx = await fetchTopologyAndSensors();
+    // Process each asset
+    const assets = [];
+    for (const assetId of args.asset_ids) {
+        const asset = resolveAssetContext(assetId, ctx);
+        // Build presence measurement data
+        const presenceData = {
+            available: asset.presenceSensors.length > 0,
+            sensor_count: asset.presenceSensors.length,
+            coverage_note: getPresenceCoverageNote(asset.assetType, asset.presenceSensors.length),
+            timeseries: [],
+        };
+        if (asset.presenceSensors.length > 0) {
+            const measurement = getPresenceMeasurement(asset.assetType);
+            try {
+                const points = await queryTimeseries(asset.assetType, assetId, measurement, args.start, args.stop, args.interval);
+                if (points) {
+                    presenceData.timeseries = points;
+                }
+            }
+            catch (error) {
+                console.error(`[occupancy-timeseries] Presence query failed:`, error);
+                presenceData.warning =
+                    "Failed to retrieve presence timeseries data. Results may be incomplete.";
+            }
+        }
+        // Build traffic measurement data
+        const trafficData = {
+            available: asset.trafficSensors.length > 0,
+            entrance_sensor_count: asset.assetType === "floor" ? asset.trafficSensors.length : undefined,
+            sensor_count: asset.assetType === "room" ? asset.trafficSensors.length : undefined,
+            coverage_note: getTrafficCoverageNote(asset.assetType, asset.trafficSensors.length),
+            timeseries: [],
+        };
+        if (asset.trafficSensors.length > 0 && asset.assetType !== "zone") {
+            const measurement = getTrafficMeasurement(asset.assetType);
+            try {
+                const points = await queryTimeseries(asset.assetType, assetId, measurement, args.start, args.stop, args.interval);
+                if (points) {
+                    trafficData.timeseries = points;
+                }
+            }
+            catch (error) {
+                console.error(`[occupancy-timeseries] Traffic query failed:`, error);
+                trafficData.warning =
+                    "Failed to retrieve traffic timeseries data. Results may be incomplete.";
+            }
+        }
+        // Recommendation checks data success, not just sensor count
+        const recommendation = buildRecommendation(presenceData, trafficData, presenceData.timeseries.length > 0, trafficData.timeseries.length > 0);
+        assets.push({
+            asset_id: assetId,
+            asset_type: asset.assetType,
+            asset_name: asset.assetName,
+            ...asset.tzMetadata,
+            presence: presenceData,
+            traffic: trafficData,
+            ...recommendation,
+        });
+    }
+    return {
+        assets,
+        interval: args.interval,
+        start: args.start,
+        stop: args.stop,
+        timezone_note: "All timestamps are UTC (ISO-8601). Use site_timezone for each asset to convert to local time.",
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Register butlr_get_occupancy_timeseries with an McpServer instance
+ */
+export function registerGetOccupancyTimeseries(server) {
+    server.registerTool("butlr_get_occupancy_timeseries", {
+        title: "Get Occupancy Timeseries",
+        description: GET_OCCUPANCY_TIMESERIES_DESCRIPTION,
+        inputSchema: getOccupancyTimeseriesInputShape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            const validated = GetOccupancyTimeseriesArgsSchema.parse(args);
+            const result = await executeGetOccupancyTimeseries(validated);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            rethrowIfGraphQLError(error);
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=butlr-get-occupancy-timeseries.js.map

package/dist/tools/butlr-get-occupancy-timeseries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"butlr-get-occupancy-timeseries.js","sourceRoot":"","sources":["../../src/tools/butlr-get-occupancy-timeseries.ts"],"names":[],"mappings":"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"}

package/dist/tools/butlr-hardware-snapshot.d.ts

@@ -0,0 +1,55 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { Sensor } from "../clients/types.js";
+import type { BatteryStatus, HardwareSnapshotResponse } from "../types/responses.js";
+export declare const HardwareSnapshotArgsSchema: z.ZodEffects<z.ZodObject<{
+    scope_type: z.ZodDefault<z.ZodEnum<["org", "site", "building", "floor"]>>;
+    scope_id: z.ZodOptional<z.ZodString>;
+    include_battery_details: z.ZodDefault<z.ZodBoolean>;
+    battery_status_filter: z.ZodDefault<z.ZodEnum<["critical", "due_soon", "healthy", "all"]>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offline_devices_limit: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    scope_type: "site" | "building" | "floor" | "org";
+    include_battery_details: boolean;
+    battery_status_filter: "all" | "critical" | "due_soon" | "healthy";
+    limit: number;
+    offline_devices_limit: number;
+    scope_id?: string | undefined;
+}, {
+    scope_type?: "site" | "building" | "floor" | "org" | undefined;
+    scope_id?: string | undefined;
+    include_battery_details?: boolean | undefined;
+    battery_status_filter?: "all" | "critical" | "due_soon" | "healthy" | undefined;
+    limit?: number | undefined;
+    offline_devices_limit?: number | undefined;
+}>, {
+    scope_type: "site" | "building" | "floor" | "org";
+    include_battery_details: boolean;
+    battery_status_filter: "all" | "critical" | "due_soon" | "healthy";
+    limit: number;
+    offline_devices_limit: number;
+    scope_id?: string | undefined;
+}, {
+    scope_type?: "site" | "building" | "floor" | "org" | undefined;
+    scope_id?: string | undefined;
+    include_battery_details?: boolean | undefined;
+    battery_status_filter?: "all" | "critical" | "due_soon" | "healthy" | undefined;
+    limit?: number | undefined;
+    offline_devices_limit?: number | undefined;
+}>;
+export type HardwareSnapshotArgs = z.output<typeof HardwareSnapshotArgsSchema>;
+/**
+ * Calculate battery status for a sensor
+ * Exported for unit testing
+ */
+export declare function getBatteryStatus(sensor: Sensor, currentDate?: Date): BatteryStatus;
+/**
+ * Execute hardware snapshot tool
+ */
+export declare function executeHardwareSnapshot(args: HardwareSnapshotArgs): Promise<HardwareSnapshotResponse>;
+/**
+ * Register butlr_hardware_snapshot with an McpServer instance
+ */
+export declare function registerHardwareSnapshot(server: McpServer): void;
+//# sourceMappingURL=butlr-hardware-snapshot.d.ts.map

package/dist/tools/butlr-hardware-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"butlr-hardware-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/butlr-hardware-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAyB,MAAM,EAAQ,MAAM,qBAAqB,CAAC;AAO/E,OAAO,KAAK,EAEV,aAAa,EAEb,wBAAwB,EAEzB,MAAM,uBAAuB,CAAC;AAqC/B,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAcpC,CAAC;AA8BJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AA0B/E;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,GAAE,IAAiB,GAAG,aAAa,CAqB9F;AAyFD;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,qCAwYvE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsBhE"}