@butlr/butlr-mcp-server 0.1.0

package/dist/clients/auth-client.js

@@ -0,0 +1,82 @@
+import dotenv from "dotenv";
+dotenv.config();
+const BASE_URL = process.env.BUTLR_BASE_URL || "https://api.butlr.io";
+const AUTH_ENDPOINT = `${BASE_URL}/api/v2/clients/login`;
+/**
+ * Butlr Authentication Client
+ * Manages OAuth2 client credentials flow for API authentication
+ */
+class ButlrAuthClient {
+    token = null;
+    tokenExpiry = null;
+    clientId;
+    clientSecret;
+    constructor() {
+        this.clientId = process.env.BUTLR_CLIENT_ID || "";
+        this.clientSecret = process.env.BUTLR_CLIENT_SECRET || "";
+    }
+    /**
+     * Get a valid access token, fetching a new one if needed
+     */
+    async getToken() {
+        // Validate credentials on first use (deferred from constructor)
+        if (!this.clientId || !this.clientSecret) {
+            throw new Error("BUTLR_CLIENT_ID and BUTLR_CLIENT_SECRET environment variables are required. " +
+                "See README.md for configuration instructions.");
+        }
+        // Return cached token if still valid (with 5 minute buffer)
+        if (this.token && this.tokenExpiry && Date.now() < this.tokenExpiry.getTime() - 5 * 60 * 1000) {
+            if (process.env.DEBUG) {
+                console.error("[auth-client] Using cached token");
+            }
+            return this.token;
+        }
+        if (process.env.DEBUG) {
+            console.error("[auth-client] Fetching new token...");
+        }
+        // Fetch new token
+        try {
+            const response = await fetch(AUTH_ENDPOINT, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    client_id: this.clientId,
+                    client_secret: this.clientSecret,
+                    audience: "https://butlrauth/",
+                    grant_type: "client_credentials",
+                }),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Authentication failed (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            if (!data.access_token) {
+                throw new Error("No access_token in response");
+            }
+            // Cache the token
+            this.token = data.access_token;
+            this.tokenExpiry = new Date(Date.now() + data.expires_in * 1000);
+            if (process.env.DEBUG) {
+                console.error(`[auth-client] Token acquired, expires at ${this.tokenExpiry.toISOString()}`);
+            }
+            return this.token;
+        }
+        catch (error) {
+            console.error("[auth-client] Token fetch failed:", error);
+            throw new Error(`Failed to authenticate with Butlr API: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Clear cached token (useful for testing)
+     */
+    clearToken() {
+        this.token = null;
+        this.tokenExpiry = null;
+    }
+}
+// Singleton instance
+export const authClient = new ButlrAuthClient();
+//# sourceMappingURL=auth-client.js.map

package/dist/clients/auth-client.js.map

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

package/dist/clients/graphql-client.d.ts

@@ -0,0 +1,6 @@
+import { ApolloClient } from "@apollo/client";
+/**
+ * Apollo Client instance with authentication and error handling
+ */
+export declare const apolloClient: ApolloClient;
+//# sourceMappingURL=graphql-client.d.ts.map

package/dist/clients/graphql-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-client.d.ts","sourceRoot":"","sources":["../../src/clients/graphql-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuC,MAAM,gBAAgB,CAAC;AAiFnF;;GAEG;AACH,eAAO,MAAM,YAAY,cAkCvB,CAAC"}

package/dist/clients/graphql-client.js

@@ -0,0 +1,106 @@
+import { ApolloClient, InMemoryCache, createHttpLink, from } from "@apollo/client";
+import { setContext } from "@apollo/client/link/context";
+import { onError } from "@apollo/client/link/error";
+import { authClient } from "./auth-client.js";
+const BASE_URL = process.env.BUTLR_BASE_URL || "https://api.butlr.io";
+const GRAPHQL_ENDPOINT = `${BASE_URL}/api/v3/graphql`;
+/**
+ * HTTP link for GraphQL endpoint
+ */
+const httpLink = createHttpLink({
+    uri: GRAPHQL_ENDPOINT,
+    fetch,
+});
+/**
+ * Authentication link - adds Bearer token to every request
+ */
+const authLink = setContext(async (_, { headers }) => {
+    try {
+        const token = await authClient.getToken();
+        return {
+            headers: {
+                ...headers,
+                authorization: `Bearer ${token}`,
+            },
+        };
+    }
+    catch (error) {
+        console.error("[graphql-client] Failed to get auth token:", error);
+        throw error;
+    }
+});
+/**
+ * Error handling link - logs errors and provides debugging info
+ */
+const errorLink = onError((errorResponse) => {
+    const { operation } = errorResponse;
+    // Apollo 4.x ErrorHandlerOptions has a single 'error' field.
+    // Cast to access graphQLErrors/networkError which may exist at runtime
+    // depending on the Apollo version's actual implementation.
+    const resp = errorResponse;
+    const graphQLErrors = resp.graphQLErrors;
+    const networkError = resp.networkError;
+    const topError = resp.error;
+    if (graphQLErrors) {
+        for (const err of graphQLErrors) {
+            console.error(`[graphql-client] GraphQL error in ${operation.operationName}:`, err.message);
+            if (err.extensions?.code === "UNAUTHENTICATED") {
+                authClient.clearToken();
+            }
+        }
+    }
+    if (networkError) {
+        console.error(`[graphql-client] Network error in ${operation.operationName}:`, networkError.message);
+        if (networkError.statusCode === 401 || networkError.statusCode === 403) {
+            authClient.clearToken();
+        }
+    }
+    // Fallback for Apollo 4.x single error field
+    if (!graphQLErrors && !networkError && topError) {
+        console.error(`[graphql-client] Error in ${operation.operationName}:`, topError.message);
+        if (topError.message?.includes("UNAUTHENTICATED") ||
+            topError.message?.includes("401") ||
+            topError.message?.includes("403")) {
+            authClient.clearToken();
+        }
+    }
+});
+/**
+ * Apollo Client instance with authentication and error handling
+ */
+export const apolloClient = new ApolloClient({
+    link: from([errorLink, authLink, httpLink]),
+    cache: new InMemoryCache({
+        typePolicies: {
+            // Customize caching behavior if needed
+            Site: {
+                keyFields: ["id"],
+            },
+            Building: {
+                keyFields: ["id"],
+            },
+            Floor: {
+                keyFields: ["id"],
+            },
+            Room: {
+                keyFields: ["id"],
+            },
+            Zone: {
+                keyFields: ["id"],
+            },
+            Sensor: {
+                keyFields: ["id"],
+            },
+            Hive: {
+                keyFields: ["id"],
+            },
+        },
+    }),
+    defaultOptions: {
+        query: {
+            fetchPolicy: "network-only", // Always fetch fresh data from API
+            errorPolicy: "all", // Return partial data on errors
+        },
+    },
+});
+//# sourceMappingURL=graphql-client.js.map

package/dist/clients/graphql-client.js.map

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

package/dist/clients/queries/topology.d.ts

@@ -0,0 +1,36 @@
+/**
+ * GraphQL queries for topology retrieval
+ * Adapted from gauntlet-app for MCP server use
+ */
+/**
+ * Minimal sites list - fast loading, no nested data
+ */
+export declare const GET_SITES_LIST: import("@apollo/client").DocumentNode;
+/**
+ * Single site structure without sensors/hives
+ * Good for quick hierarchy lookup
+ */
+export declare const GET_SITE_STRUCTURE: import("@apollo/client").DocumentNode;
+/**
+ * Full topology with all sites, buildings, floors, rooms, zones
+ * NOTE: Does NOT include sensors/hives in nested fields (broken - only returns 5 sensors)
+ * Use GET_ALL_SENSORS and GET_ALL_HIVES separately, then merge by floor_id/room_id
+ */
+export declare const GET_FULL_TOPOLOGY: import("@apollo/client").DocumentNode;
+/**
+ * Get all sensors for the organization
+ * Uses snake_case fields (floor_id, room_id) which work correctly
+ * CamelCase fields (floorID, roomID) have buggy resolvers that fail for NULL values
+ */
+export declare const GET_ALL_SENSORS: import("@apollo/client").DocumentNode;
+/**
+ * Get all hives for the organization
+ * Uses snake_case fields (floor_id, room_id) for consistency
+ */
+export declare const GET_ALL_HIVES: import("@apollo/client").DocumentNode;
+/**
+ * Lightweight topology without devices
+ * Faster when sensor/hive data isn't needed
+ */
+export declare const GET_TOPOLOGY_NO_DEVICES: import("@apollo/client").DocumentNode;
+//# sourceMappingURL=topology.d.ts.map

package/dist/clients/queries/topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/clients/queries/topology.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,uCAY1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,uCA6B9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uCAiE7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,uCAwB3B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,uCAqBzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,uCAgEnC,CAAC"}

package/dist/clients/queries/topology.js

@@ -0,0 +1,252 @@
+import { gql } from "@apollo/client";
+/**
+ * GraphQL queries for topology retrieval
+ * Adapted from gauntlet-app for MCP server use
+ */
+/**
+ * Minimal sites list - fast loading, no nested data
+ */
+export const GET_SITES_LIST = gql `
+  query GetSitesList {
+    sites {
+      data {
+        id
+        name
+        timezone
+        siteNumber
+        customID
+      }
+    }
+  }
+`;
+/**
+ * Single site structure without sensors/hives
+ * Good for quick hierarchy lookup
+ */
+export const GET_SITE_STRUCTURE = gql `
+  query GetSiteStructure($siteId: ID!) {
+    site(id: $siteId) {
+      id
+      name
+      timezone
+      siteNumber
+      customID
+      buildings {
+        id
+        name
+        building_number
+        capacity {
+          max
+          mid
+        }
+        address {
+          lines
+          country
+        }
+        floors {
+          id
+          name
+          floorNumber
+          timezone
+        }
+      }
+    }
+  }
+`;
+/**
+ * Full topology with all sites, buildings, floors, rooms, zones
+ * NOTE: Does NOT include sensors/hives in nested fields (broken - only returns 5 sensors)
+ * Use GET_ALL_SENSORS and GET_ALL_HIVES separately, then merge by floor_id/room_id
+ */
+export const GET_FULL_TOPOLOGY = gql `
+  query GetFullTopology {
+    sites {
+      data {
+        id
+        name
+        timezone
+        siteNumber
+        customID
+        org_id
+        buildings {
+          id
+          name
+          building_number
+          site_id
+          customID
+          capacity {
+            max
+            mid
+          }
+          address {
+            lines
+            country
+          }
+          floors {
+            id
+            name
+            floorNumber
+            building_id
+            timezone
+            installation_date
+            customID
+            capacity {
+              max
+              mid
+            }
+            area {
+              value
+              unit
+            }
+            rooms {
+              id
+              name
+              floor_id
+              roomType
+              customID
+              capacity {
+                max
+                mid
+              }
+              coordinates
+            }
+            zones {
+              id
+              name
+              floor_id
+              room_id
+              customID
+              coordinates
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Get all sensors for the organization
+ * Uses snake_case fields (floor_id, room_id) which work correctly
+ * CamelCase fields (floorID, roomID) have buggy resolvers that fail for NULL values
+ */
+export const GET_ALL_SENSORS = gql `
+  query GetAllSensors {
+    sensors {
+      data {
+        id
+        name
+        mac_address
+        mode
+        model
+        floor_id
+        room_id
+        hive_serial
+        is_entrance
+        is_online
+        is_streaming
+        power_type
+        last_battery_change_date
+        next_battery_change_date
+        battery_change_by_date
+        last_heartbeat
+        installation_status
+      }
+    }
+  }
+`;
+/**
+ * Get all hives for the organization
+ * Uses snake_case fields (floor_id, room_id) for consistency
+ */
+export const GET_ALL_HIVES = gql `
+  query GetAllHives {
+    hives {
+      data {
+        id
+        name
+        serialNumber
+        floor_id
+        room_id
+        isOnline
+        coordinates
+        isStreaming
+        hiveVersion
+        hiveType
+        note
+        lastHeartbeat
+        netPathStability
+        installed
+      }
+    }
+  }
+`;
+/**
+ * Lightweight topology without devices
+ * Faster when sensor/hive data isn't needed
+ */
+export const GET_TOPOLOGY_NO_DEVICES = gql `
+  query GetTopologyNoDevices {
+    sites {
+      data {
+        id
+        name
+        timezone
+        siteNumber
+        customID
+        org_id
+        buildings {
+          id
+          name
+          building_number
+          site_id
+          customID
+          capacity {
+            max
+            mid
+          }
+          address {
+            lines
+            country
+          }
+          floors {
+            id
+            name
+            floorNumber
+            building_id
+            timezone
+            installation_date
+            customID
+            capacity {
+              max
+              mid
+            }
+            area {
+              value
+              unit
+            }
+            rooms {
+              id
+              name
+              floor_id
+              customID
+              capacity {
+                max
+                mid
+              }
+              coordinates
+            }
+            zones {
+              id
+              name
+              floor_id
+              room_id
+              customID
+              coordinates
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+//# sourceMappingURL=topology.js.map

package/dist/clients/queries/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../../src/clients/queries/topology.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAErC;;;GAGG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;;;;;;;;;;;;CAYhC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BpC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEnC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;CAwBjC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;CAqB/B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEzC,CAAC"}

package/dist/clients/reporting-client.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Structured API error with status code for proper error translation
+ */
+export declare class ApiError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * v3 Reporting API Request Structure
+ * Based on butlr-api-container/pkg/reporting/models/request.go
+ */
+export interface ReportingRequest {
+    group_by?: {
+        order?: string[];
+        raw?: boolean;
+    };
+    window?: {
+        every: string;
+        function: string;
+        offset?: string;
+        timezone?: string;
+        create_empty?: boolean;
+        fill?: {
+            use_previous?: boolean;
+            value?: number;
+        };
+    };
+    filter: {
+        measurements: string[];
+        start: string;
+        stop?: string;
+        spaces?: {
+            eq: string[];
+        };
+        rooms?: {
+            eq: string[];
+        };
+        zones?: {
+            eq: string[];
+        };
+        tags?: {
+            eq: string[];
+        };
+        clients?: {
+            eq: string[];
+        };
+        buildings?: {
+            eq: string[];
+        };
+        value?: {
+            gte?: number;
+            lte?: number;
+            gt?: number;
+            lt?: number;
+        };
+        calibrated?: string;
+        time_constraints?: {
+            time_ranges?: Array<{
+                start: string;
+                stop: string;
+            }>;
+            exclude_days_of_week?: string[];
+        };
+    };
+    options?: {
+        format?: "json" | "csv";
+        precision?: "s" | "ms" | "us" | "ns";
+        timestamp?: "RFC3339";
+        includeCalibrationPoints?: boolean;
+    };
+    paginate?: {
+        page: number;
+        limit: number;
+    };
+    calibrationPoints?: Array<{
+        timestamp: string;
+        occupancy: number;
+        type: "user_provided" | "pir_zero";
+    }>;
+}
+/**
+ * v3 Reporting API Response Structure
+ */
+export interface ReportingResponse {
+    data: Array<{
+        field: string;
+        measurement: string;
+        time: string;
+        value: number;
+        timezone_offset?: string;
+        building_id?: string;
+        building_name?: string;
+        space_id?: string;
+        space_name?: string;
+        room_id?: string;
+        room_name?: string;
+        zone_id?: string;
+        hive_id?: string;
+        sensor_id?: string;
+        mac_address?: string;
+        [key: string]: unknown;
+    }>;
+    page_info?: {
+        page: number;
+        page_item_count: number;
+        total_item_count: number;
+        total_pages: number;
+    };
+    calibrationPoints?: unknown[];
+}
+/**
+ * Normalized data point (RFC3339 → ISO-8601)
+ */
+export interface NormalizedDataPoint {
+    start: string;
+    stop?: string;
+    measurement: string;
+    value: number;
+    asset_id?: string;
+    asset_name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Helper to get filter field name for asset type
+ */
+export declare function getFilterField(assetType: string): string;
+/**
+ * Helper to get measurement name for asset type
+ */
+export declare function getMeasurement(assetType: string): string;
+/**
+ * Normalize RFC3339 timestamp to ISO-8601
+ */
+export declare function normalizeTimestamp(rfc3339: string): string;
+/**
+ * Query v3 Reporting API
+ */
+export declare function queryReporting(requestBody: ReportingRequest): Promise<ReportingResponse>;
+/**
+ * Request builder for common occupancy queries
+ */
+export declare class ReportingRequestBuilder {
+    private request;
+    constructor();
+    /**
+     * Set asset IDs to query
+     */
+    assets(assetType: string, ids: string[]): this;
+    /**
+     * Set measurements (auto-mapped from asset type if not provided)
+     */
+    measurements(measurements: string[]): this;
+    /**
+     * Auto-set measurement based on asset type
+     */
+    measurementForAssetType(assetType: string): this;
+    /**
+     * Set time range (ISO-8601 or relative like '-24h')
+     */
+    timeRange(start: string, stop?: string): this;
+    /**
+     * Set window aggregation
+     */
+    window(every: string, func: "mean" | "max" | "min" | "sum" | "first" | "last" | "median", timezone?: string): this;
+    /**
+     * Set grouping
+     */
+    groupBy(order: string[], raw?: boolean): this;
+    /**
+     * Set pagination
+     */
+    paginate(page: number, limit: number): this;
+    /**
+     * Set tags filter
+     */
+    tags(tags: string[]): this;
+    /**
+     * Build and return the request
+     */
+    build(): ReportingRequest;
+    /**
+     * Build and execute the query
+     */
+    execute(): Promise<ReportingResponse>;
+}
+/**
+ * Convenience function: Get current occupancy for assets
+ * Implements fallback strategy: presence first, then traffic (matches dashboard behavior)
+ */
+export declare function getCurrentOccupancy(assetType: string, assetIds: string[]): Promise<NormalizedDataPoint[]>;
+//# sourceMappingURL=reporting-client.d.ts.map