@butlr/butlr-mcp-server 0.1.0

package/dist/clients/stats-client.js

@@ -0,0 +1,238 @@
+import { request as httpRequest } from "undici";
+import { authClient } from "./auth-client.js";
+import { ApiError } from "./reporting-client.js";
+const BASE_URL = process.env.BUTLR_BASE_URL || "https://api.butlr.io";
+const STATS_ENDPOINT = `${BASE_URL}/api/v4/reporting/stats`;
+/**
+ * Query v4 Stats API
+ *
+ * Note: This endpoint is production-ready but may occasionally return 504 errors
+ * under heavy load. Implement fallback to client-side calculation if needed.
+ */
+export async function queryStats(statsRequest) {
+    if (process.env.DEBUG) {
+        console.error(`[stats-client] POST ${STATS_ENDPOINT}`, JSON.stringify(statsRequest, null, 2));
+    }
+    try {
+        // Get auth token
+        const token = await authClient.getToken();
+        // Make request
+        const response = await httpRequest(STATS_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(statsRequest),
+        });
+        if (response.statusCode !== 200) {
+            const errorBody = await response.body.text();
+            // Special handling for 504 Gateway Timeout
+            if (response.statusCode === 504) {
+                console.error(`[stats-client] 504 Gateway Timeout - stats service may be overloaded`);
+                throw new ApiError(504, "Stats service temporarily unavailable (504). Try reducing the time range or number of assets.");
+            }
+            if (process.env.DEBUG) {
+                console.error(`[stats-client] API error body: ${errorBody}`);
+            }
+            throw new ApiError(response.statusCode, `Butlr API error (${response.statusCode}). Enable DEBUG=butlr-mcp for details.`);
+        }
+        const data = (await response.body.json());
+        if (process.env.DEBUG) {
+            console.error(`[stats-client] Response: statistics for ${Object.keys(data.data || {}).length} assets`);
+        }
+        return data;
+    }
+    catch (error) {
+        console.error(`[stats-client] Request failed:`, error);
+        // Translate common errors using structured ApiError
+        if (error instanceof ApiError) {
+            if (error.statusCode === 401 || error.statusCode === 403) {
+                authClient.clearToken();
+                throw new ApiError(error.statusCode, "Authentication failed. Check BUTLR_CLIENT_ID and BUTLR_CLIENT_SECRET.");
+            }
+            if (error.statusCode === 429) {
+                throw new ApiError(429, "Rate limit exceeded. Please retry after a few seconds.");
+            }
+            if (error.statusCode === 400) {
+                throw new ApiError(400, "Invalid request parameters. Check measurements and items.");
+            }
+        }
+        throw error;
+    }
+}
+/**
+ * Convert relative time to ISO-8601 timestamp
+ * e.g., "-7d" → "2025-10-06T00:00:00Z"
+ */
+function parseRelativeTime(relativeTime) {
+    const match = relativeTime.match(/^-(\d+)([mhd])$/);
+    if (!match) {
+        // If not relative format, return as-is (assume ISO-8601)
+        return relativeTime;
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    const now = new Date();
+    switch (unit) {
+        case "m":
+            now.setMinutes(now.getMinutes() - value);
+            break;
+        case "h":
+            now.setHours(now.getHours() - value);
+            break;
+        case "d":
+            now.setDate(now.getDate() - value);
+            break;
+    }
+    return now.toISOString();
+}
+/**
+ * Request builder for stats queries
+ */
+export class StatsRequestBuilder {
+    request;
+    constructor() {
+        this.request = {
+            measurements: [],
+            items: [],
+        };
+    }
+    /**
+     * Set measurements to query
+     * Use v4-specific measurement names:
+     * - occupancy_avg_presence
+     * - occupancy_median_presence
+     * - occupancy_avg_traffic
+     * - occupancy_median_traffic
+     */
+    measurements(measurements) {
+        this.request.measurements = measurements;
+        return this;
+    }
+    /**
+     * Set asset IDs to query
+     */
+    assets(assetIds) {
+        this.request.items = assetIds;
+        return this;
+    }
+    /**
+     * Set time range (ISO-8601 timestamp or relative like '-7d')
+     * Relative times will be converted to ISO-8601
+     */
+    timeRange(start, stop) {
+        // Convert start time
+        this.request.start = parseRelativeTime(start);
+        // Convert stop time - if not provided or "now", use current time
+        if (!stop || stop === "now") {
+            this.request.stop = new Date().toISOString();
+        }
+        else {
+            this.request.stop = parseRelativeTime(stop);
+        }
+        return this;
+    }
+    /**
+     * Set time-of-day filters
+     */
+    timeOfDayFilter(ranges) {
+        if (!this.request.filters) {
+            this.request.filters = {};
+        }
+        this.request.filters.time_ranges = ranges;
+        return this;
+    }
+    /**
+     * Exclude specific days of week
+     */
+    excludeDays(days) {
+        if (!this.request.filters) {
+            this.request.filters = {};
+        }
+        this.request.filters.exclude_days_of_week = days;
+        return this;
+    }
+    /**
+     * Build and return the request
+     */
+    build() {
+        // Validation
+        if (!this.request.measurements.length) {
+            throw new Error("At least one measurement is required");
+        }
+        if (!this.request.items.length) {
+            throw new Error("At least one asset ID is required");
+        }
+        return this.request;
+    }
+    /**
+     * Build and execute the query
+     */
+    async execute() {
+        return queryStats(this.build());
+    }
+}
+/**
+ * Convenience function: Get statistics for multiple assets
+ * @param measurement - Use v4 format: 'occupancy_avg_presence', 'occupancy_median_presence', etc.
+ * @param assetIds - Array of asset IDs (rooms, floors, zones)
+ * @param start - ISO-8601 or relative time (will be converted)
+ * @param stop - ISO-8601 timestamp (optional)
+ */
+export async function getAssetStatistics(measurement, assetIds, start = "-7d", stop) {
+    return new StatsRequestBuilder()
+        .measurements([measurement])
+        .assets(assetIds)
+        .timeRange(start, stop)
+        .execute();
+}
+/**
+ * Convenience function: Get statistics for a single asset
+ * @param measurement - Use v4 format: 'occupancy_avg_presence', 'occupancy_median_presence', etc.
+ */
+export async function getSingleAssetStats(measurement, assetId, start = "-7d", stop) {
+    const response = await getAssetStatistics(measurement, [assetId], start, stop);
+    return response.data[assetId] || null;
+}
+/**
+ * Calculate client-side statistics as fallback
+ * Useful if v4/stats returns 504 error
+ */
+export function calculateStatistics(values) {
+    if (values.length === 0) {
+        return {
+            count: 0,
+            first: 0,
+            last: 0,
+            max: 0,
+            mean: 0,
+            median: 0,
+            min: 0,
+            stdev: 0,
+            sum: 0,
+        };
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const sum = values.reduce((a, b) => a + b, 0);
+    const mean = sum / values.length;
+    // Calculate standard deviation
+    const squaredDiffs = values.map((v) => Math.pow(v - mean, 2));
+    const variance = squaredDiffs.reduce((a, b) => a + b, 0) / values.length;
+    const stdev = Math.sqrt(variance);
+    // Calculate median
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+    return {
+        count: values.length,
+        first: values[0],
+        last: values[values.length - 1],
+        max: values.reduce((a, b) => (b > a ? b : a), values[0]),
+        mean: parseFloat(mean.toFixed(2)),
+        median: parseFloat(median.toFixed(2)),
+        min: values.reduce((a, b) => (b < a ? b : a), values[0]),
+        stdev: parseFloat(stdev.toFixed(2)),
+        sum,
+    };
+}
+//# sourceMappingURL=stats-client.js.map

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

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

package/dist/clients/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * TypeScript type definitions for Butlr GraphQL API
+ * Based on GraphQL schemas from butlr-api-container
+ */
+export interface Capacity {
+    max?: number;
+    mid?: number;
+}
+export interface Address {
+    lines?: string[];
+    country?: string;
+}
+export interface MetaData {
+    created_at?: number;
+    updated_at?: number;
+    deleted_at?: number;
+}
+export interface Area {
+    value?: number;
+    unit?: string;
+}
+/**
+ * Site - Top level organizational unit (campus)
+ */
+export interface Site {
+    id: string;
+    name: string;
+    timezone: string;
+    org_id: string;
+    siteNumber?: number;
+    customID?: string;
+    butlrCode?: string;
+    buildings: Building[];
+}
+/**
+ * Building - Physical structure containing floors
+ */
+export interface Building {
+    id: string;
+    name: string;
+    site_id: string;
+    building_number?: number;
+    buildingNumber?: number;
+    butlr_code?: string;
+    capacity: Capacity;
+    address?: Address;
+    customID?: string;
+    floors: Floor[];
+    site: Site;
+}
+/**
+ * Floor - Level within a building
+ */
+export interface Floor {
+    id: string;
+    name: string;
+    building_id: string;
+    floorNumber?: number;
+    timezone: string;
+    installation_date: number;
+    installation_status?: string;
+    service_status?: string;
+    capacity: Capacity;
+    area: Area;
+    metadata: MetaData;
+    customID?: string;
+    butlrCode?: string;
+    rooms?: Room[];
+    zones?: Zone[];
+    sensors?: Sensor[];
+    hives?: Hive[];
+    floor_plans?: FloorPlan[];
+    building: Building;
+}
+/**
+ * Room - Defined space within a floor
+ */
+export interface Room {
+    id: string;
+    name: string;
+    floorID?: string;
+    floor_id?: string;
+    roomType?: string;
+    capacity: Capacity;
+    area: Area;
+    coordinates?: number[][];
+    rotation?: number;
+    metadata: MetaData;
+    customID?: string;
+    note?: string;
+    pir_zero_enable?: boolean;
+    pir_zero_threshold?: number;
+    pir_zero_window?: number;
+    sensors?: Sensor[];
+    floor: Floor;
+}
+/**
+ * Zone - Sub-area within a floor or room
+ */
+export interface Zone {
+    id: string;
+    name: string;
+    floorID?: string;
+    floor_id?: string;
+    roomID?: string;
+    room_id?: string;
+    capacity: Capacity;
+    area: Area;
+    coordinates?: number[][];
+    rotation?: number;
+    metadata: MetaData;
+    customID?: string;
+    note?: string;
+    sensors?: Sensor[];
+}
+/**
+ * Sensor - Individual detection device
+ */
+export interface Sensor {
+    id: string;
+    name: string;
+    mac_address: string;
+    mode: "presence" | "traffic";
+    model: string;
+    floorID?: string;
+    floor_id?: string;
+    roomID?: string;
+    room_id?: string;
+    hiveID?: string;
+    hive_id?: string;
+    hive_serial: string;
+    is_online: boolean;
+    is_streaming?: boolean;
+    height: number;
+    center: number[];
+    orientation: number[];
+    field_of_view: number;
+    door_line: number;
+    in_direction: number;
+    is_entrance: boolean;
+    parallel_to_door: boolean;
+    sensitivity: number;
+    metadata: MetaData;
+    note?: string;
+    last_heartbeat?: number;
+    last_raw_message?: number;
+    last_occupancy_message?: number;
+    power_type?: "Wired" | "Battery";
+    sensor_serial?: string;
+    installation_status?: "INSTALLED" | "UNINSTALLED";
+    last_battery_change_date?: string;
+    next_battery_change_date?: string;
+    battery_change_by_date?: string;
+}
+/**
+ * Hive - Gateway device managing sensors
+ */
+export interface Hive {
+    id: string;
+    name: string;
+    serialNumber: string;
+    floor_id: string;
+    floorID: string;
+    room_id?: string;
+    roomID?: string;
+    coordinates?: number[];
+    is_online: boolean;
+    isOnline: boolean;
+    is_streaming?: boolean;
+    isStreaming?: boolean;
+    hiveVersion?: string;
+    hiveType?: string;
+    metadata: MetaData;
+    note?: string;
+    last_heartbeat?: number;
+    lastHeartbeat?: number;
+    net_path_stability?: number;
+    netPathStability?: number;
+    installed: boolean;
+    sensors?: Sensor[];
+}
+/**
+ * FloorPlan - Visual layout of a floor
+ */
+export interface FloorPlan {
+    floor_plan_id: string;
+    name: string;
+    url?: string;
+    coordinates?: number[][];
+}
+/**
+ * GraphQL response wrapper types
+ */
+export interface SitesResponse {
+    data: Site[];
+}
+export interface BuildingsResponse {
+    data: Building[];
+}
+export interface FloorsResponse {
+    data: Floor[];
+}
+export interface RoomsResponse {
+    data: Room[];
+}
+export interface ZonesResponse {
+    data: Zone[];
+}
+export interface SensorsResponse {
+    data: Sensor[];
+}
+export interface HivesResponse {
+    data: Hive[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/clients/types.js

@@ -0,0 +1,6 @@
+/**
+ * TypeScript type definitions for Butlr GraphQL API
+ * Based on GraphQL schemas from butlr-api-container
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/clients/types.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+/** Maximum response size in characters. Responses exceeding this are truncated. */
+export declare const CHARACTER_LIMIT = 25000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,eAAO,MAAM,eAAe,QAAS,CAAC"}

package/dist/constants.js

@@ -0,0 +1,3 @@
+/** Maximum response size in characters. Responses exceeding this are truncated. */
+export const CHARACTER_LIMIT = 25_000;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC"}

package/dist/errors/mcp-errors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Structural type for Apollo-like errors (ApolloError was removed in Apollo Client 4.0)
+ * Narrowed from `any` to `unknown` with runtime property checks inside translateGraphQLError.
+ */
+interface GraphQLClientError {
+    networkError?: {
+        statusCode?: number;
+        message?: string;
+        result?: unknown;
+        response?: {
+            headers?: {
+                get(name: string): string | null;
+            };
+        };
+    };
+    graphQLErrors?: Array<{
+        message: string;
+        extensions?: Record<string, unknown>;
+    }>;
+    message?: string;
+}
+/**
+ * MCP Error Codes
+ * Standard error codes for Model Context Protocol
+ */
+export declare enum MCPErrorCode {
+    AUTH_EXPIRED = "AUTH_EXPIRED",
+    RATE_LIMITED = "RATE_LIMITED",
+    VALIDATION_FAILED = "VALIDATION_FAILED",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    NOT_FOUND = "NOT_FOUND",
+    NETWORK_ERROR = "NETWORK_ERROR"
+}
+export interface MCPError {
+    code: MCPErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+    retryAfter?: number;
+}
+/**
+ * Translate GraphQL/Apollo errors to MCP error format
+ */
+export declare function translateGraphQLError(error: GraphQLClientError): MCPError;
+/**
+ * Format MCP error for user-friendly display
+ */
+export declare function formatMCPError(error: MCPError): string;
+/**
+ * Error subclass for MCP errors — provides stack traces and works with instanceof checks.
+ */
+export declare class MCPValidationError extends Error {
+    code: MCPErrorCode;
+    details?: Record<string, unknown>;
+    retryable: boolean;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Create a validation error (throws a proper Error subclass with stack trace)
+ */
+export declare function createValidationError(message: string, details?: Record<string, unknown>): MCPValidationError;
+export {};
+//# sourceMappingURL=mcp-errors.d.ts.map

package/dist/errors/mcp-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-errors.d.ts","sourceRoot":"","sources":["../../src/errors/mcp-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,UAAU,kBAAkB;IAC1B,YAAY,CAAC,EAAE;QACb,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE;gBAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;aAAE,CAAA;SAAE,CAAC;KAC/D,CAAC;IACF,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,oBAAY,YAAY;IACtB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,iBAAiB,sBAAsB;IACvC,cAAc,mBAAmB;IACjC,SAAS,cAAc;IACvB,aAAa,kBAAkB;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,QAAQ,CAmGzE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAgBtD;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,OAAO,CAAC;gBAEP,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAO/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,kBAAkB,CAEpB"}