@butlr/butlr-mcp-server 0.1.0

package/dist/tools/butlr-traffic-flow.js

@@ -0,0 +1,369 @@
+import { apolloClient } from "../clients/graphql-client.js";
+import { gql } from "@apollo/client";
+import { z } from "zod";
+import { ReportingRequestBuilder } from "../clients/reporting-client.js";
+import { GET_ALL_SENSORS, GET_FULL_TOPOLOGY } from "../clients/queries/topology.js";
+import { executeSearchAssets } from "./butlr-search-assets.js";
+import { getTimezoneForAsset, buildTimezoneMetadata, getLocalMidnight, } from "../utils/timezone-helpers.js";
+import { createValidationError } from "../errors/mcp-errors.js";
+import { rethrowIfGraphQLError } from "../utils/graphql-helpers.js";
+const timeStringSchema = z.string().refine((val) => {
+    const isoMatch = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/.test(val);
+    const relativeMatch = /^-\d+[dhm]$/.test(val);
+    const isNow = val === "now";
+    return isoMatch || relativeMatch || isNow;
+}, {
+    message: "Time must be ISO-8601 format (2025-01-15T10:00:00Z), relative (-24h, -7d, -30m), or 'now'",
+});
+/** Shared shape — used by both registerTool (SDK schema) and full validation */
+const trafficFlowInputShape = {
+    space_id_or_name: z
+        .string()
+        .min(1, "space_id_or_name cannot be empty")
+        .max(200)
+        .trim()
+        .describe("Space ID or search term"),
+    time_window: z
+        .enum(["20m", "1h", "today", "custom"])
+        .default("today")
+        .describe("Time period for traffic count"),
+    custom_start: z
+        .string()
+        .pipe(timeStringSchema)
+        .optional()
+        .describe("Custom start time (ISO-8601 or relative '-24h'). Required if time_window='custom'"),
+    custom_stop: z
+        .string()
+        .pipe(timeStringSchema)
+        .optional()
+        .describe("Custom stop time. Defaults to 'now'"),
+};
+export const TrafficFlowArgsSchema = z
+    .object(trafficFlowInputShape)
+    .strict()
+    .refine((data) => {
+    if (data.time_window === "custom" && !data.custom_start) {
+        return false;
+    }
+    return true;
+}, {
+    message: "custom_start is required when time_window='custom'",
+    path: ["custom_start"],
+});
+const TRAFFIC_FLOW_DESCRIPTION = "Get entry and exit counts for spaces equipped with traffic-mode sensors (typically lobbies, building entrances, elevator banks). Returns total movements, net flow (entries - exits), and hourly breakdown in the space's local timezone. Designed for space activation analysis, security/compliance, and amenity demand forecasting.\n\n" +
+    "Primary Users:\n" +
+    "- Facilities Manager: Monitor building entry/exit patterns, optimize security staffing, validate badge system accuracy\n" +
+    "- Workplace Manager: Understand amenity traffic (café, gym, event spaces), measure activation of new spaces\n" +
+    "- Portfolio Manager: Analyze building utilization patterns for lease negotiations, assess occupancy vs. leased capacity\n" +
+    "- Security/Compliance: Validate occupancy limits for fire code compliance, monitor after-hours access\n\n" +
+    "Example Queries:\n" +
+    '1. "How many people entered the main lobby today?"\n' +
+    '2. "Show me entry/exit counts for the café in the last hour"\n' +
+    '3. "What was the peak traffic hour for Building 3 entrance today?"\n' +
+    '4. "How many people visited the fitness center yesterday?"\n' +
+    '5. "Show me lobby traffic for the last 20 minutes"\n' +
+    '6. "What\'s the net flow (entries - exits) for Floor 2 today?"\n' +
+    '7. "How many people entered the event space during lunch hour (12-1pm)?"\n' +
+    '8. "Compare today\'s building entrance traffic to typical Monday"\n\n' +
+    "When to Use:\n" +
+    "- Entry/exit counts for lobbies, building entrances, elevator banks, or amenities\n" +
+    "- Understand peak traffic hours for security, cleaning, or HVAC planning\n" +
+    "- Validate badge system accuracy against actual sensor counts\n" +
+    "- Measure activation/adoption of new spaces or amenities\n" +
+    "- Analyze compliance with occupancy limits (fire code, COVID density restrictions)\n\n" +
+    "When NOT to Use:\n" +
+    "- Current occupancy count (people currently in space) → use butlr_get_current_occupancy or butlr_space_busyness\n" +
+    "- Rooms without traffic-mode sensors → use butlr_get_current_occupancy (presence mode)\n" +
+    "- Spaces that don't have entry/exit chokepoints → traffic mode requires defined entrances\n\n" +
+    "CRE Context: Traffic counts are movements, not unique people - one person exiting/re-entering counts as 2 movements. Net flow helps detect sensor calibration issues (large negative net flow might indicate misconfigured entry/exit sensors).\n\n" +
+    "See Also: butlr_get_current_occupancy, butlr_space_busyness, butlr_search_assets, butlr_get_asset_details";
+const GET_ROOM_SENSORS = gql `
+  query GetRoomSensors($roomId: ID!) {
+    room(id: $roomId) {
+      id
+      name
+      floorID
+      sensors {
+        id
+        mode
+      }
+      floor {
+        id
+        name
+        building {
+          id
+          name
+        }
+      }
+    }
+  }
+`;
+/**
+ * Execute traffic flow tool
+ */
+export async function executeTrafficFlow(args) {
+    let spaceId = args.space_id_or_name;
+    // If not an ID, search for the space
+    if (!spaceId.match(/^room_/)) {
+        if (process.env.DEBUG) {
+            console.error(`[traffic-flow] Searching for space: "${args.space_id_or_name}"`);
+        }
+        const searchResults = await executeSearchAssets({
+            query: args.space_id_or_name,
+            asset_types: ["room"], // Traffic is room-level
+            max_results: 5,
+        });
+        if (searchResults.matches.length === 0) {
+            throw new Error(`No rooms found matching "${args.space_id_or_name}". Try a different search term.`);
+        }
+        spaceId = searchResults.matches[0].id;
+        if (process.env.DEBUG) {
+            console.error(`[traffic-flow] Using best match: ${searchResults.matches[0].name} (${spaceId})`);
+        }
+    }
+    // Query room details, topology for timezone, and all sensors
+    let room = null;
+    let roomPath = "";
+    let timezone;
+    let tzMetadata;
+    let trafficSensors = [];
+    try {
+        const [roomResult, topoResult, sensorsResult] = await Promise.all([
+            apolloClient.query({
+                query: GET_ROOM_SENSORS,
+                variables: { roomId: spaceId },
+                fetchPolicy: "network-only",
+            }),
+            apolloClient.query({
+                query: GET_FULL_TOPOLOGY,
+                fetchPolicy: "network-only",
+            }),
+            apolloClient.query({
+                query: GET_ALL_SENSORS,
+                fetchPolicy: "network-only",
+            }),
+        ]);
+        if (!roomResult.data?.room) {
+            throw new Error(`Room ${spaceId} not found`);
+        }
+        room = roomResult.data.room;
+        const floor = room.floor;
+        const building = floor?.building;
+        roomPath = building ? `${building.name} > ${floor.name} > ${room.name}` : room.name;
+        // Get timezone for this room
+        const sites = topoResult.data?.sites?.data || [];
+        const buildings = sites.flatMap((s) => s.buildings || []);
+        const floors = buildings.flatMap((b) => b.floors || []);
+        const roomTimezone = getTimezoneForAsset(spaceId, "room", floors, buildings, sites);
+        if (!roomTimezone) {
+            throw new Error(`Could not determine timezone for room ${spaceId}`);
+        }
+        timezone = roomTimezone;
+        tzMetadata = buildTimezoneMetadata(timezone);
+        // Analyze traffic sensors for this room
+        const allSensors = sensorsResult.data?.sensors?.data || [];
+        const roomSensors = allSensors.filter((s) => (s.room_id || s.roomID) === spaceId);
+        // Non-entrance traffic sensors (room-level traffic counting)
+        trafficSensors = roomSensors.filter((s) => s.mode === "traffic" && s.is_entrance === false);
+        if (trafficSensors.length === 0) {
+            throw new Error(`Room "${room.name}" does not have traffic-mode sensors. Try butlr_get_current_occupancy for occupancy data instead.`);
+        }
+        if (process.env.DEBUG) {
+            console.error(`[traffic-flow] Found ${trafficSensors.length} traffic sensors for room`);
+        }
+    }
+    catch (error) {
+        rethrowIfGraphQLError(error);
+        throw error;
+    }
+    // Calculate time range
+    const timeWindow = args.time_window || "today";
+    let start;
+    let stop = "now";
+    let periodDescription;
+    let usedUtcFallback = false;
+    if (timeWindow === "custom") {
+        if (!args.custom_start) {
+            throw createValidationError("custom_start is required when time_window='custom'");
+        }
+        start = args.custom_start;
+        stop = args.custom_stop || "now";
+        periodDescription = "custom period";
+    }
+    else if (timeWindow === "20m") {
+        start = "-20m";
+        periodDescription = "last 20 minutes";
+    }
+    else if (timeWindow === "1h") {
+        start = "-1h";
+        periodDescription = "last hour";
+    }
+    else {
+        // today - use site's timezone for local midnight
+        const localMidnight = getLocalMidnight(new Date(), timezone);
+        if (isNaN(localMidnight.getTime())) {
+            // getLocalMidnight returns UTC midnight as fallback on error
+            usedUtcFallback = true;
+        }
+        // Detect if getLocalMidnight silently fell back to UTC by comparing
+        // the result against a plain UTC midnight (which is what the internal fallback does)
+        const utcMidnight = new Date();
+        utcMidnight.setUTCHours(0, 0, 0, 0);
+        if (timezone !== "UTC" && Math.abs(localMidnight.getTime() - utcMidnight.getTime()) < 1000) {
+            // The result suspiciously matches UTC midnight for a non-UTC timezone —
+            // likely the internal fallback fired
+            usedUtcFallback = true;
+        }
+        start = localMidnight.toISOString();
+        periodDescription = usedUtcFallback
+            ? "today (UTC fallback)"
+            : `today (${tzMetadata.timezone_abbr})`;
+        if (process.env.DEBUG) {
+            console.error(`[traffic-flow] Today starts at ${start} (midnight ${usedUtcFallback ? "UTC fallback" : tzMetadata.timezone_abbr})`);
+        }
+    }
+    if (process.env.DEBUG) {
+        console.error(`[traffic-flow] Querying traffic from ${start} to ${stop}`);
+    }
+    let trafficData = [];
+    try {
+        const response = await new ReportingRequestBuilder()
+            .assets("room", [spaceId])
+            .measurements(["traffic"])
+            .timeRange(start, stop)
+            .window("1h", "sum", timezone) // Sum traffic per hour, aligned to local timezone
+            .execute();
+        // Parse flat array response
+        // Traffic returns TWO data points per hour per sensor: "in" and "out"
+        if (!Array.isArray(response.data)) {
+            throw new Error("Expected array response from traffic query");
+        }
+        trafficData = response.data;
+        if (process.env.DEBUG) {
+            console.error(`[traffic-flow] Received ${trafficData.length} data points from ${trafficSensors.length} sensors`);
+        }
+    }
+    catch (error) {
+        rethrowIfGraphQLError(error);
+        if (process.env.DEBUG) {
+            console.error(`[traffic-flow] Failed to get traffic data:`, error);
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get traffic data for ${room.name}. ${msg}`);
+    }
+    // Parse traffic data: group by time, then by sensor, then aggregate
+    // Store time separately to preserve full ISO timestamp
+    const byHourSensor = new Map();
+    for (const point of trafficData) {
+        const key = `${point.time}:${point.sensor_id}`;
+        if (!byHourSensor.has(key)) {
+            byHourSensor.set(key, { time: point.time, in: 0, out: 0 });
+        }
+        const counts = byHourSensor.get(key);
+        if (point.field === "in") {
+            counts.in = point.value || 0;
+        }
+        else if (point.field === "out") {
+            counts.out = point.value || 0;
+        }
+    }
+    // Aggregate across sensors by hour (group by time only)
+    const byHour = new Map();
+    for (const [_key, data] of byHourSensor) {
+        const time = data.time; // Use actual time from data, not split key
+        if (!byHour.has(time)) {
+            byHour.set(time, { in: 0, out: 0 });
+        }
+        const hourCounts = byHour.get(time);
+        hourCounts.in += data.in;
+        hourCounts.out += data.out;
+    }
+    // Build hourly breakdown (keep UTC timestamps like unified tools)
+    const hourlyBreakdown = Array.from(byHour.entries())
+        .map(([time, counts]) => ({
+        hour_utc: time, // Full ISO timestamp from API
+        entries: Math.round(counts.in),
+        exits: Math.round(counts.out),
+        total_traffic: Math.round(counts.in + counts.out),
+        net_flow: Math.round(counts.in - counts.out),
+    }))
+        .sort((a, b) => a.hour_utc.localeCompare(b.hour_utc));
+    // Calculate totals
+    const totalEntries = hourlyBreakdown.reduce((sum, h) => sum + h.entries, 0);
+    const totalExits = hourlyBreakdown.reduce((sum, h) => sum + h.exits, 0);
+    const totalTraffic = totalEntries + totalExits;
+    const netFlow = totalEntries - totalExits;
+    // Find peak hour (by total traffic)
+    let peakHour = hourlyBreakdown.length > 0 ? hourlyBreakdown[0] : null;
+    for (const hour of hourlyBreakdown) {
+        if (hour.total_traffic > (peakHour?.total_traffic || 0)) {
+            peakHour = hour;
+        }
+    }
+    // Build enhanced summary
+    const netFlowStr = netFlow >= 0 ? `+${netFlow}` : `${netFlow}`;
+    const summary = `${room.name}: ${totalTraffic.toLocaleString()} movements ${periodDescription} (${totalEntries.toLocaleString()} entries, ${totalExits.toLocaleString()} exits, net flow: ${netFlowStr})`;
+    // Build response with timezone metadata and in/out breakdown
+    const response = {
+        space: {
+            id: room.id,
+            name: room.name,
+            type: "room",
+            path: roomPath,
+            sensor_mode: "traffic",
+            ...tzMetadata,
+        },
+        traffic: {
+            total_entries: totalEntries,
+            total_exits: totalExits,
+            total_traffic: totalTraffic,
+            net_flow: netFlow,
+            sensor_count: trafficSensors.length,
+            period: {
+                start_utc: start,
+                stop_utc: stop,
+                description: periodDescription,
+            },
+        },
+        hourly_breakdown: hourlyBreakdown,
+        peak_hour: peakHour
+            ? {
+                hour_utc: peakHour.hour_utc,
+                total_traffic: peakHour.total_traffic,
+                entries: peakHour.entries,
+                exits: peakHour.exits,
+                net_flow: peakHour.net_flow,
+            }
+            : null,
+        summary,
+        timestamp: new Date().toISOString(),
+        timezone_note: "All timestamps are UTC (ISO-8601). Use site_timezone to interpret in local time.",
+        ...(usedUtcFallback && {
+            warning: "Could not determine local timezone for this space; timestamps use UTC midnight as fallback. 'Today' may not align with the site's actual local day.",
+        }),
+    };
+    return response;
+}
+/**
+ * Register butlr_traffic_flow with an McpServer instance
+ */
+export function registerTrafficFlow(server) {
+    server.registerTool("butlr_traffic_flow", {
+        title: "Traffic Flow",
+        description: TRAFFIC_FLOW_DESCRIPTION,
+        inputSchema: trafficFlowInputShape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const validated = TrafficFlowArgsSchema.parse(args);
+        const result = await executeTrafficFlow(validated);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=butlr-traffic-flow.js.map

package/dist/tools/butlr-traffic-flow.js.map

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

package/dist/types/responses.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Shared response type interfaces for MCP tool outputs
+ *
+ * These types define the contract between tools and LLM consumers.
+ * Every tool response MUST be typed — no `any` on public API surfaces.
+ */
+import type { Capacity, Area } from "../clients/types.js";
+import type { TimezoneMetadata } from "../utils/timezone-helpers.js";
+/** Base measurement data shared between current-occupancy and timeseries tools */
+export interface BaseMeasurementData {
+    available: boolean;
+    sensor_count?: number;
+    entrance_sensor_count?: number;
+    coverage_note?: string;
+    warning?: string;
+}
+/** Single timeseries data point */
+export interface TimeseriesPoint {
+    timestamp: string;
+    value: number;
+}
+/** Measurement data with timeseries array */
+export interface TimeseriesMeasurementData extends BaseMeasurementData {
+    timeseries: TimeseriesPoint[];
+}
+/** Measurement data with a single current reading */
+export interface CurrentMeasurementData extends BaseMeasurementData {
+    current_occupancy?: number;
+    timestamp?: string;
+}
+/** Measurement recommendation output */
+export interface MeasurementRecommendation {
+    recommended_measurement: "presence" | "traffic" | "none";
+    recommendation_reason: string;
+}
+/** Asset identity block used in occupancy tool responses */
+export interface AssetIdentifier {
+    asset_id: string;
+    asset_type: string;
+    asset_name?: string;
+}
+export interface AvailableRoom {
+    id: string;
+    name: string;
+    path: string;
+    capacity: Capacity;
+    area?: Area;
+    tags?: string[];
+    /** The query window in minutes (NOT how long the room has been empty) */
+    data_window_minutes: number;
+}
+export interface BuildingContext {
+    building_name: string;
+    total_rooms: number;
+    available_rooms: number;
+    occupancy_percent: number;
+}
+export interface AvailableRoomsResponse {
+    summary: string;
+    available_rooms: AvailableRoom[];
+    total_available: number;
+    showing: number;
+    timestamp: string;
+    filtered_by?: Record<string, unknown>;
+    building_context?: BuildingContext;
+    warning?: string;
+}
+export interface SpaceBusynessResponse {
+    space: {
+        id: string;
+        name: string;
+        type: "room" | "zone";
+        path: string;
+    };
+    current: {
+        occupancy: number;
+        capacity: Capacity;
+        utilization_percent: number | null;
+        label: "quiet" | "moderate" | "busy" | null;
+        capacity_configured: boolean;
+        as_of: string;
+    };
+    trend?: {
+        typical_for_time: number;
+        vs_typical_percent: number;
+        trend_label: "lighter" | "typical" | "busier";
+        historical_context: string;
+    };
+    recommendation: string;
+    summary: string;
+    timestamp: string;
+    warning?: string;
+}
+export interface HourlyTraffic {
+    hour_utc: string;
+    entries: number;
+    exits: number;
+    total_traffic: number;
+    net_flow: number;
+}
+export interface TrafficFlowResponse {
+    space: {
+        id: string;
+        name: string;
+        type: "room";
+        path: string;
+        sensor_mode: "traffic";
+    } & TimezoneMetadata;
+    traffic: {
+        total_entries: number;
+        total_exits: number;
+        total_traffic: number;
+        net_flow: number;
+        sensor_count: number;
+        period: {
+            start_utc: string;
+            stop_utc: string;
+            description: string;
+        };
+    };
+    hourly_breakdown: HourlyTraffic[];
+    peak_hour: HourlyTraffic | null;
+    summary: string;
+    timestamp: string;
+    timezone_note: string;
+    warning?: string;
+}
+/** Ultra-compact tree node: [id, displayName] or [id, displayName, children] */
+export type TopologyNode = [string, string] | [string, string, TopologyNode[]];
+export interface ListTopologyResponse {
+    tree: TopologyNode[];
+    query_params: {
+        starting_depth: number;
+        traversal_depth: number;
+        asset_filter: string[] | "all";
+    };
+    timestamp: string;
+    warning?: string;
+}
+export interface EntityResult {
+    id: string;
+    _type: string;
+    error?: string;
+    [key: string]: unknown;
+}
+export interface FetchEntityDetailsResponse {
+    entities: EntityResult[];
+    requested_count: number;
+    fetched_count: number;
+    timestamp: string;
+    warning?: string;
+}
+export type AssetOccupancyTimeseries = AssetIdentifier & TimezoneMetadata & MeasurementRecommendation & {
+    presence: TimeseriesMeasurementData;
+    traffic: TimeseriesMeasurementData;
+};
+export interface OccupancyTimeseriesResponse {
+    assets: AssetOccupancyTimeseries[];
+    interval: string;
+    start: string;
+    stop: string;
+    timezone_note: string;
+    timestamp: string;
+}
+export type AssetCurrentOccupancy = AssetIdentifier & TimezoneMetadata & MeasurementRecommendation & {
+    presence: CurrentMeasurementData;
+    traffic: CurrentMeasurementData;
+};
+export interface CurrentOccupancyResponse {
+    assets: AssetCurrentOccupancy[];
+    timestamp: string;
+    timezone_note: string;
+}
+export type BatteryStatus = "critical" | "due_soon" | "healthy" | "unknown" | "no_battery";
+export interface BatteryDetail {
+    sensor_id: string;
+    sensor_name: string;
+    mac_address: string;
+    path: string;
+    status: BatteryStatus;
+    battery_change_by_date: string;
+    days_remaining: number;
+    last_battery_change_date?: string;
+    next_battery_change_date?: string;
+}
+export interface FloorBreakdown {
+    floor_id: string;
+    floor_name: string;
+    sensors_online: number;
+    sensors_total: number;
+    percent_online: number;
+    batteries_critical: number;
+    batteries_due_soon: number;
+}
+export interface OfflineDevice {
+    type: "sensor" | "hive";
+    id: string;
+    name: string;
+    serial_number?: string;
+    mac_address?: string;
+    path: string;
+    last_heartbeat?: string;
+    hours_offline?: number;
+}
+export interface HardwareSnapshotResponse {
+    summary: string;
+    sensors: {
+        total: number;
+        online: number;
+        offline: number;
+        percent_online: number;
+    };
+    hives: {
+        total: number;
+        online: number;
+        offline: number;
+        percent_online: number;
+    };
+    battery_health: Record<string, number>;
+    scope: {
+        type: string;
+        id?: string;
+        name: string;
+    };
+    timestamp: string;
+    test_devices_excluded?: {
+        sensors: {
+            mirror: number;
+            placeholder: number;
+            total: number;
+        };
+        hives: {
+            fake: number;
+            placeholder: number;
+            total: number;
+        };
+        note: string;
+    };
+    battery_details?: BatteryDetail[];
+    battery_details_truncated?: boolean;
+    battery_details_total?: number;
+    breakdown_by_floor?: FloorBreakdown[];
+    offline_devices?: OfflineDevice[];
+    offline_devices_summary?: {
+        sensors_offline: number;
+        hives_offline: number;
+        total_offline: number;
+        showing: number;
+    };
+    offline_devices_truncated?: boolean;
+    offline_devices_total?: number;
+}
+//# sourceMappingURL=responses.d.ts.map

package/dist/types/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/types/responses.ts"],"names":[],"mappings":"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"}

package/dist/types/responses.js

@@ -0,0 +1,8 @@
+/**
+ * Shared response type interfaces for MCP tool outputs
+ *
+ * These types define the contract between tools and LLM consumers.
+ * Every tool response MUST be typed — no `any` on public API surfaces.
+ */
+export {};
+//# sourceMappingURL=responses.js.map

package/dist/types/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../src/types/responses.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}