@butlr/butlr-mcp-server 0.1.0

package/dist/tools/butlr-get-asset-details.js

@@ -0,0 +1,391 @@
+import { apolloClient } from "../clients/graphql-client.js";
+import { gql } from "@apollo/client";
+import { z } from "zod";
+import { translateGraphQLError, formatMCPError, createValidationError, } from "../errors/mcp-errors.js";
+import { detectAssetType } from "../utils/asset-helpers.js";
+const assetIdSchema = z
+    .string()
+    .min(1, "Asset ID cannot be empty")
+    .refine((val) => {
+    const validPrefixes = ["site_", "building_", "space_", "floor_", "room_", "zone_"];
+    return validPrefixes.some((prefix) => val.startsWith(prefix));
+}, {
+    message: "Asset ID must start with valid prefix: site_, building_, floor_, space_, room_, or zone_. For sensor/hive details, use butlr_search_assets or butlr_hardware_snapshot.",
+});
+/** Shared shape — used by both registerTool and full validation */
+const getAssetDetailsInputShape = {
+    ids: z
+        .array(assetIdSchema)
+        .min(1, "ids array must contain at least 1 asset ID")
+        .max(50, "ids array cannot exceed 50 assets")
+        .describe("Asset IDs to fetch (e.g., ['room_123', 'floor_456'])"),
+    include_children: z.boolean().default(true).describe("Include child assets"),
+    include_devices: z.boolean().default(false).describe("Include sensors and hives"),
+    include_parent_context: z.boolean().default(true).describe("Include parent names for context"),
+};
+export const GetAssetDetailsArgsSchema = z
+    .object(getAssetDetailsInputShape)
+    .strict()
+    .refine((data) => {
+    const unique = new Set(data.ids);
+    return unique.size === data.ids.length;
+}, {
+    message: "ids array contains duplicate asset IDs",
+    path: ["ids"],
+});
+const GET_ASSET_DETAILS_DESCRIPTION = "Get comprehensive details for specific assets by ID (sites, buildings, floors, rooms, zones). Automatically detects asset type from ID prefix and returns appropriate fields. Supports batch queries (multiple IDs), optional child/parent context, and device inclusion. Essential for configuration validation, integration development, and detailed asset inspection.\n\n" +
+    "Primary Users:\n" +
+    "- IT Manager: Verify sensor configurations (mode, model, online status), validate floor/building setups\n" +
+    "- Field Technician: Get sensor MAC addresses, hive serial numbers, and physical coordinates before site visits\n" +
+    "- Facilities Manager: Verify room capacities, areas, and metadata for space planning\n" +
+    "- Developer/Integrator: Fetch asset metadata for building workplace apps, dashboards, or integrations\n\n" +
+    "Example Queries:\n" +
+    '1. "Show me full details for Conference Room 401" (after finding ID via search)\n' +
+    '2. "Get sensor configuration for all sensors on Floor 3" (mode, model, MAC, online status)\n' +
+    '3. "Show me all rooms on Floor 6 with their capacities and areas"\n' +
+    '4. "Get building details including all floors and their room counts"\n' +
+    "5. \"Show me sensor MAC addresses for Room 'Café Barista' for field tech visit\"\n" +
+    '6. "Get hive serial numbers and online status for Building 2"\n' +
+    '7. "Show me site timezone and all buildings in the Chicago office"\n' +
+    '8. "Get room coordinates and rotation for floor plan mapping"\n\n' +
+    "When to Use:\n" +
+    "- Have asset IDs and need detailed configuration, metadata, or relationships\n" +
+    "- Validating sensor/hive assignments for troubleshooting (which hive is this sensor on?)\n" +
+    "- Need room capacities, areas, or coordinates for space planning or floor plan integrations\n" +
+    "- Preparing for field technician site visit (need device identifiers: MACs, serials)\n" +
+    "- Building integrations and need to fetch parent context (room → floor → building → site)\n\n" +
+    "When NOT to Use:\n" +
+    "- Don't have asset IDs yet → use butlr_search_assets first to find IDs by name\n" +
+    "- Need real-time occupancy or sensor data → use occupancy/traffic tools instead\n" +
+    "- Want to browse organizational hierarchy → use butlr_list_topology for tree view\n" +
+    "- Need to update/configure assets → this is read-only; use Butlr Dashboard for changes\n\n" +
+    "Options: include_children (default true), include_devices (default false), include_parent_context (default true)\n\n" +
+    "Batch Query: Supports multiple IDs in single call - mixed asset types supported\n\n" +
+    "See Also: butlr_search_assets, butlr_list_topology, butlr_fetch_entity_details, butlr_hardware_snapshot";
+/**
+ * Build GraphQL query based on asset type and options
+ */
+function buildQuery(type, includeChildren, includeDevices, includeParentContext) {
+    switch (type) {
+        case "site":
+            return gql `
+        query GetSiteDetails($id: ID!) {
+          site(id: $id) {
+            id
+            name
+            timezone
+            siteNumber
+            customID
+            ${includeChildren
+                ? `
+            buildings {
+              id
+              name
+              building_number
+              capacity { max mid }
+              ${includeChildren
+                    ? `
+              floors {
+                id
+                name
+                floorNumber
+              }
+              `
+                    : ""}
+            }
+            `
+                : ""}
+          }
+        }
+      `;
+        case "building":
+            return gql `
+        query GetBuildingDetails($id: ID!) {
+          building(id: $id) {
+            id
+            name
+            building_number
+            customID
+            capacity { max mid }
+            address { lines country }
+            ${includeParentContext
+                ? `
+            site {
+              id
+              name
+              timezone
+            }
+            `
+                : ""}
+            ${includeChildren
+                ? `
+            floors {
+              id
+              name
+              floorNumber
+              timezone
+              capacity { max mid }
+            }
+            `
+                : ""}
+          }
+        }
+      `;
+        case "floor":
+            return gql `
+        query GetFloorDetails($id: ID!) {
+          floor(id: $id) {
+            id
+            name
+            floorNumber
+            timezone
+            installation_date
+            installation_status
+            customID
+            capacity { max mid }
+            area { value unit }
+            ${includeParentContext
+                ? `
+            building {
+              id
+              name
+              building_number
+              site {
+                id
+                name
+                timezone
+              }
+            }
+            `
+                : ""}
+            ${includeChildren
+                ? `
+            rooms {
+              id
+              name
+              roomType
+              customID
+              capacity { max mid }
+              coordinates
+            }
+            zones {
+              id
+              name
+              roomID
+              customID
+              coordinates
+            }
+            `
+                : ""}
+            ${includeDevices
+                ? `
+            sensors {
+              id
+              name
+              mac_address
+              mode
+              model
+              roomID
+              hive_serial
+              is_online
+            }
+            hives {
+              id
+              name
+              serialNumber
+              roomID
+              isOnline
+              coordinates
+            }
+            `
+                : ""}
+          }
+        }
+      `;
+        case "room":
+            return gql `
+        query GetRoomDetails($id: ID!) {
+          room(id: $id) {
+            id
+            name
+            roomType
+            customID
+            capacity { max mid }
+            area { value unit }
+            coordinates
+            rotation
+            note
+            ${includeParentContext
+                ? `
+            floor {
+              id
+              name
+              floorNumber
+              building {
+                id
+                name
+                site {
+                  id
+                  name
+                }
+              }
+            }
+            `
+                : ""}
+            ${includeDevices
+                ? `
+            sensors {
+              id
+              name
+              mac_address
+              mode
+              model
+              is_online
+              hive_serial
+            }
+            `
+                : ""}
+          }
+        }
+      `;
+        case "zone":
+            return gql `
+        query GetZoneDetails($id: ID!) {
+          zone(id: $id) {
+            id
+            name
+            roomID
+            customID
+            capacity { max mid }
+            area { value unit }
+            coordinates
+            rotation
+            note
+            ${includeDevices
+                ? `
+            sensors {
+              id
+              name
+              mac_address
+              is_online
+            }
+            `
+                : ""}
+          }
+        }
+      `;
+        default:
+            throw createValidationError(`Unsupported asset type: ${type}`);
+    }
+}
+/**
+ * Execute get_asset_details tool
+ */
+export async function executeGetAssetDetails(args) {
+    const includeChildren = args.include_children !== false; // Default true
+    const includeDevices = args.include_devices === true; // Default false
+    const includeParentContext = args.include_parent_context !== false; // Default true
+    if (process.env.DEBUG) {
+        console.error(`[get-asset-details] Fetching details for ${args.ids.length} asset(s): ${args.ids.join(", ")}`);
+    }
+    const results = [];
+    // Group IDs by type
+    const assetsByType = {};
+    for (const id of args.ids) {
+        const type = detectAssetType(id);
+        if (type === "unknown") {
+            if (process.env.DEBUG) {
+                console.error(`[get-asset-details] Warning: Unknown asset type for ID: ${id}`);
+            }
+            results.push({
+                id,
+                _type: "unknown",
+                error: `Unknown asset type for ID: ${id}. Expected prefix: site_, building_, floor_, room_, zone_`,
+            });
+            continue;
+        }
+        if (!assetsByType[type]) {
+            assetsByType[type] = [];
+        }
+        assetsByType[type].push(id);
+    }
+    // Fetch all assets in parallel (grouped by type for query selection)
+    const fetchPromises = [];
+    for (const [type, ids] of Object.entries(assetsByType)) {
+        const query = buildQuery(type, includeChildren, includeDevices, includeParentContext);
+        for (const id of ids) {
+            fetchPromises.push({
+                id,
+                type,
+                promise: apolloClient.query({ query, variables: { id }, fetchPolicy: "network-only" }),
+            });
+        }
+    }
+    const settled = await Promise.allSettled(fetchPromises.map((f) => f.promise));
+    for (let i = 0; i < settled.length; i++) {
+        const { id, type } = fetchPromises[i];
+        const outcome = settled[i];
+        if (outcome.status === "fulfilled") {
+            const { data, error } = outcome.value;
+            if (error) {
+                const mcpError = translateGraphQLError(error);
+                results.push({ id, error: formatMCPError(mcpError), _type: type });
+                continue;
+            }
+            const asset = data[type];
+            if (asset && typeof asset === "object") {
+                results.push({ ...asset, _type: type });
+            }
+            else if (process.env.DEBUG) {
+                console.error(`[get-asset-details] Asset not found: ${id}`);
+            }
+        }
+        else {
+            const err = outcome.reason;
+            if (err && (err.graphQLErrors || err.networkError)) {
+                const mcpError = translateGraphQLError(err);
+                if (process.env.DEBUG) {
+                    console.error(`[get-asset-details] Error fetching ${id}:`, formatMCPError(mcpError));
+                }
+                results.push({ id, error: formatMCPError(mcpError), _type: type });
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    return {
+        assets: results,
+        total_count: results.length,
+        requested_count: args.ids.length,
+        options: {
+            include_children: includeChildren,
+            include_devices: includeDevices,
+            include_parent_context: includeParentContext,
+        },
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Register butlr_get_asset_details with an McpServer instance
+ */
+export function registerGetAssetDetails(server) {
+    server.registerTool("butlr_get_asset_details", {
+        title: "Get Butlr Asset Details",
+        description: GET_ASSET_DETAILS_DESCRIPTION,
+        inputSchema: getAssetDetailsInputShape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const validated = GetAssetDetailsArgsSchema.parse(args);
+        const result = await executeGetAssetDetails(validated);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=butlr-get-asset-details.js.map

package/dist/tools/butlr-get-asset-details.js.map

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

package/dist/tools/butlr-get-current-occupancy.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { CurrentOccupancyResponse } from "../types/responses.js";
+export declare const GetCurrentOccupancyArgsSchema: z.ZodObject<{
+    asset_ids: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    asset_ids: string[];
+}, {
+    asset_ids: string[];
+}>;
+/** Input arguments — inferred from Zod schema */
+export type GetCurrentOccupancyArgs = z.output<typeof GetCurrentOccupancyArgsSchema>;
+/**
+ * Execute unified current occupancy tool
+ */
+export declare function executeGetCurrentOccupancy(args: GetCurrentOccupancyArgs): Promise<CurrentOccupancyResponse>;
+/**
+ * Register butlr_get_current_occupancy with an McpServer instance
+ */
+export declare function registerGetCurrentOccupancy(server: McpServer): void;
+//# sourceMappingURL=butlr-get-current-occupancy.d.ts.map

package/dist/tools/butlr-get-current-occupancy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"butlr-get-current-occupancy.d.ts","sourceRoot":"","sources":["../../src/tools/butlr-get-current-occupancy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,uBAAuB,CAAC;AAY/B,eAAO,MAAM,6BAA6B;;;;;;EAAmD,CAAC;AAE9F,iDAAiD;AACjD,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAErF;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,wBAAwB,CAAC,CA2GnC;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsBnE"}

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

@@ -0,0 +1,126 @@
+import { ReportingRequestBuilder } from "../clients/reporting-client.js";
+import { z } from "zod";
+import { fetchTopologyAndSensors, resolveAssetContext, getPresenceMeasurement, getTrafficMeasurement, getPresenceCoverageNote, getTrafficCoverageNote, buildRecommendation, } from "../utils/occupancy-helpers.js";
+const GET_CURRENT_OCCUPANCY_DESCRIPTION = "Get current occupancy for floors, rooms, or zones (last 5 minutes median). 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 current occupancy picture.";
+/** Shared shape — used by both registerTool (SDK schema) and full validation */
+const getCurrentOccupancyInputShape = {
+    asset_ids: z.array(z.string()).min(1).max(50).describe("Floor, room, or zone IDs"),
+};
+export const GetCurrentOccupancyArgsSchema = z.object(getCurrentOccupancyInputShape).strict();
+/**
+ * Execute unified current occupancy tool
+ */
+export async function executeGetCurrentOccupancy(args) {
+    if (process.env.DEBUG) {
+        console.error(`[butlr-get-current-occupancy] Querying ${args.asset_ids.length} assets`);
+    }
+    // Fetch topology and sensors using shared helper
+    const ctx = await fetchTopologyAndSensors();
+    // Process each asset
+    const assets = [];
+    const now = new Date();
+    const fiveMinAgo = new Date(now.getTime() - 5 * 60 * 1000);
+    for (const assetId of args.asset_ids) {
+        const asset = resolveAssetContext(assetId, ctx);
+        // ---- Presence ----
+        const presenceData = {
+            available: asset.presenceSensors.length > 0,
+            sensor_count: asset.presenceSensors.length,
+            coverage_note: getPresenceCoverageNote(asset.assetType, asset.presenceSensors.length),
+        };
+        let presenceHasData = false;
+        if (asset.presenceSensors.length > 0) {
+            const measurement = getPresenceMeasurement(asset.assetType);
+            try {
+                const response = await new ReportingRequestBuilder()
+                    .assets(asset.assetType, [assetId])
+                    .measurements([measurement])
+                    .timeRange(fiveMinAgo.toISOString(), now.toISOString())
+                    .window("1m", "median")
+                    .execute();
+                if (response.data && Array.isArray(response.data) && response.data.length > 0) {
+                    const latest = response.data[response.data.length - 1];
+                    presenceData.current_occupancy = latest.value;
+                    presenceData.timestamp = new Date(latest.time).toISOString();
+                    presenceHasData = true;
+                }
+            }
+            catch (error) {
+                console.error(`[current-occupancy] Presence query failed:`, error);
+                presenceData.warning =
+                    "Failed to retrieve current presence data. Occupancy value may be missing.";
+            }
+        }
+        // ---- Traffic ----
+        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),
+        };
+        let trafficHasData = false;
+        if (asset.trafficSensors.length > 0) {
+            const measurement = getTrafficMeasurement(asset.assetType);
+            try {
+                const response = await new ReportingRequestBuilder()
+                    .assets(asset.assetType, [assetId])
+                    .measurements([measurement])
+                    .timeRange(fiveMinAgo.toISOString(), now.toISOString())
+                    .window("1m", "median")
+                    .execute();
+                if (response.data && Array.isArray(response.data) && response.data.length > 0) {
+                    const latest = response.data[response.data.length - 1];
+                    trafficData.current_occupancy = latest.value;
+                    trafficData.timestamp = new Date(latest.time).toISOString();
+                    trafficHasData = true;
+                }
+            }
+            catch (error) {
+                console.error(`[current-occupancy] Traffic query failed:`, error);
+                trafficData.warning =
+                    "Failed to retrieve current traffic data. Occupancy value may be missing.";
+            }
+        }
+        // ---- Recommendation (checks data success, not just sensor availability) ----
+        const recommendation = buildRecommendation(presenceData, trafficData, presenceHasData, trafficHasData);
+        assets.push({
+            asset_id: assetId,
+            asset_type: asset.assetType,
+            asset_name: asset.assetName,
+            ...asset.tzMetadata,
+            presence: presenceData,
+            traffic: trafficData,
+            ...recommendation,
+        });
+    }
+    return {
+        assets,
+        timestamp: now.toISOString(),
+        timezone_note: "All timestamps are UTC (ISO-8601). Use site_timezone for local conversion.",
+    };
+}
+/**
+ * Register butlr_get_current_occupancy with an McpServer instance
+ */
+export function registerGetCurrentOccupancy(server) {
+    server.registerTool("butlr_get_current_occupancy", {
+        title: "Get Current Occupancy",
+        description: GET_CURRENT_OCCUPANCY_DESCRIPTION,
+        inputSchema: getCurrentOccupancyInputShape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const validated = GetCurrentOccupancyArgsSchema.parse(args);
+        const result = await executeGetCurrentOccupancy(validated);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=butlr-get-current-occupancy.js.map

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

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

package/dist/tools/butlr-get-occupancy-timeseries.d.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { OccupancyTimeseriesResponse } from "../types/responses.js";
+export declare const GetOccupancyTimeseriesArgsSchema: z.ZodObject<{
+    asset_ids: z.ZodArray<z.ZodString, "many">;
+    interval: z.ZodEnum<["1m", "1h", "1d"]>;
+    start: z.ZodString;
+    stop: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    start: string;
+    stop: string;
+    asset_ids: string[];
+    interval: "1h" | "1m" | "1d";
+}, {
+    start: string;
+    stop: string;
+    asset_ids: string[];
+    interval: "1h" | "1m" | "1d";
+}>;
+/** Inferred args type — no manual interface needed */
+type GetOccupancyTimeseriesArgs = z.output<typeof GetOccupancyTimeseriesArgsSchema>;
+/**
+ * Execute unified occupancy timeseries tool
+ */
+export declare function executeGetOccupancyTimeseries(args: GetOccupancyTimeseriesArgs): Promise<OccupancyTimeseriesResponse>;
+/**
+ * Register butlr_get_occupancy_timeseries with an McpServer instance
+ */
+export declare function registerGetOccupancyTimeseries(server: McpServer): void;
+export {};
+//# sourceMappingURL=butlr-get-occupancy-timeseries.d.ts.map

package/dist/tools/butlr-get-occupancy-timeseries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"butlr-get-occupancy-timeseries.d.ts","sourceRoot":"","sources":["../../src/tools/butlr-get-occupancy-timeseries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,OAAO,KAAK,EACV,2BAA2B,EAI5B,MAAM,uBAAuB,CAAC;AAoB/B,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;EAAsD,CAAC;AAEpG,sDAAsD;AACtD,KAAK,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAgCpF;;GAEG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAwGtC;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2BtE"}