@butlr/butlr-mcp-server 0.1.0

package/dist/errors/mcp-errors.js

@@ -0,0 +1,144 @@
+/**
+ * MCP Error Codes
+ * Standard error codes for Model Context Protocol
+ */
+export var MCPErrorCode;
+(function (MCPErrorCode) {
+    MCPErrorCode["AUTH_EXPIRED"] = "AUTH_EXPIRED";
+    MCPErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    MCPErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    MCPErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    MCPErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    MCPErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+})(MCPErrorCode || (MCPErrorCode = {}));
+/**
+ * Translate GraphQL/Apollo errors to MCP error format
+ */
+export function translateGraphQLError(error) {
+    // Check for network errors
+    if (error.networkError) {
+        const networkError = error.networkError;
+        // Authentication errors
+        if (networkError.statusCode === 401 || networkError.statusCode === 403) {
+            return {
+                code: MCPErrorCode.AUTH_EXPIRED,
+                message: "Authentication failed. Please check BUTLR_CLIENT_ID and BUTLR_CLIENT_SECRET.",
+                details: {
+                    statusCode: networkError.statusCode,
+                },
+                retryable: false,
+            };
+        }
+        // Rate limiting
+        if (networkError.statusCode === 429) {
+            const retryAfter = parseInt(networkError.response?.headers?.get("retry-after") || "60", 10);
+            return {
+                code: MCPErrorCode.RATE_LIMITED,
+                message: `API rate limit exceeded. Please retry after ${retryAfter} seconds.`,
+                retryable: true,
+                retryAfter,
+            };
+        }
+        // Bad request / validation
+        if (networkError.statusCode === 400) {
+            return {
+                code: MCPErrorCode.VALIDATION_FAILED,
+                message: "Invalid request parameters.",
+                details: {
+                    statusCode: 400,
+                    body: networkError.result,
+                },
+                retryable: false,
+            };
+        }
+        // Not found
+        if (networkError.statusCode === 404) {
+            return {
+                code: MCPErrorCode.NOT_FOUND,
+                message: "Resource not found.",
+                retryable: false,
+            };
+        }
+        // Generic network error
+        return {
+            code: MCPErrorCode.NETWORK_ERROR,
+            message: `Network error: ${networkError.message}`,
+            details: {
+                statusCode: networkError.statusCode,
+            },
+            retryable: true,
+        };
+    }
+    // Check for GraphQL errors
+    if (error.graphQLErrors && error.graphQLErrors.length > 0) {
+        const firstError = error.graphQLErrors[0];
+        // Authentication errors
+        if (firstError.extensions?.code === "UNAUTHENTICATED") {
+            return {
+                code: MCPErrorCode.AUTH_EXPIRED,
+                message: "JWT token expired or invalid. Re-authenticating...",
+                retryable: true,
+            };
+        }
+        // Validation errors
+        if (firstError.extensions?.code === "BAD_USER_INPUT") {
+            return {
+                code: MCPErrorCode.VALIDATION_FAILED,
+                message: `Invalid input: ${firstError.message}`,
+                details: firstError.extensions,
+                retryable: false,
+            };
+        }
+        // Generic GraphQL error
+        return {
+            code: MCPErrorCode.INTERNAL_ERROR,
+            message: firstError.message,
+            details: firstError.extensions,
+            retryable: false,
+        };
+    }
+    // Fallback: unknown error
+    return {
+        code: MCPErrorCode.INTERNAL_ERROR,
+        message: error.message || "An unknown error occurred",
+        retryable: false,
+    };
+}
+/**
+ * Format MCP error for user-friendly display
+ */
+export function formatMCPError(error) {
+    let message = `[${error.code}] ${error.message}`;
+    if (error.retryable) {
+        message += " (retryable)";
+    }
+    if (error.retryAfter) {
+        message += ` - retry after ${error.retryAfter}s`;
+    }
+    if (error.details && process.env.DEBUG) {
+        message += `\nDetails: ${JSON.stringify(error.details, null, 2)}`;
+    }
+    return message;
+}
+/**
+ * Error subclass for MCP errors — provides stack traces and works with instanceof checks.
+ */
+export class MCPValidationError extends Error {
+    code;
+    details;
+    retryable;
+    constructor(message, details) {
+        super(message);
+        this.name = "MCPValidationError";
+        this.code = MCPErrorCode.VALIDATION_FAILED;
+        this.details = details;
+        this.retryable = false;
+    }
+}
+/**
+ * Create a validation error (throws a proper Error subclass with stack trace)
+ */
+export function createValidationError(message, details) {
+    return new MCPValidationError(message, details);
+}
+//# sourceMappingURL=mcp-errors.js.map

package/dist/errors/mcp-errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerSearchAssets } from "./tools/butlr-search-assets.js";
+import { registerGetAssetDetails } from "./tools/butlr-get-asset-details.js";
+import { registerHardwareSnapshot } from "./tools/butlr-hardware-snapshot.js";
+import { registerAvailableRooms } from "./tools/butlr-available-rooms.js";
+import { registerSpaceBusyness } from "./tools/butlr-space-busyness.js";
+import { registerTrafficFlow } from "./tools/butlr-traffic-flow.js";
+import { registerListTopology } from "./tools/butlr-list-topology.js";
+import { registerFetchEntityDetails } from "./tools/butlr-fetch-entity-details.js";
+import { registerGetOccupancyTimeseries } from "./tools/butlr-get-occupancy-timeseries.js";
+import { registerGetCurrentOccupancy } from "./tools/butlr-get-current-occupancy.js";
+const SERVER_NAME = "butlr-mcp-server";
+const SERVER_VERSION = "0.1.0";
+const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+});
+// Register all tools
+registerSearchAssets(server);
+registerGetAssetDetails(server);
+registerHardwareSnapshot(server);
+registerAvailableRooms(server);
+registerSpaceBusyness(server);
+registerTrafficFlow(server);
+registerListTopology(server);
+registerFetchEntityDetails(server);
+registerGetOccupancyTimeseries(server);
+registerGetCurrentOccupancy(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (process.env.DEBUG === "butlr-mcp" || process.env.DEBUG === "*") {
+        console.error(`[${SERVER_NAME}] Server started on stdio transport`);
+        console.error(`[${SERVER_NAME}] Version: ${SERVER_VERSION}`);
+    }
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EAAE,8BAA8B,EAAE,MAAM,2CAA2C,CAAC;AAC3F,OAAO,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAErF,MAAM,WAAW,GAAG,kBAAkB,CAAC;AACvC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;CACxB,CAAC,CAAC;AAEH,qBAAqB;AACrB,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACnC,8BAA8B,CAAC,MAAM,CAAC,CAAC;AACvC,2BAA2B,CAAC,MAAM,CAAC,CAAC;AAEpC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,EAAE,CAAC;QACnE,OAAO,CAAC,KAAK,CAAC,IAAI,WAAW,qCAAqC,CAAC,CAAC;QACpE,OAAO,CAAC,KAAK,CAAC,IAAI,WAAW,cAAc,cAAc,EAAE,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/butlr-available-rooms.d.ts

@@ -0,0 +1,49 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { AvailableRoomsResponse } from "../types/responses.js";
+export declare const AvailableRoomsArgsSchema: z.ZodEffects<z.ZodObject<{
+    min_capacity: z.ZodOptional<z.ZodNumber>;
+    max_capacity: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    building_id: z.ZodOptional<z.ZodString>;
+    floor_id: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    max_results: number;
+    building_id?: string | undefined;
+    tags?: string[] | undefined;
+    min_capacity?: number | undefined;
+    max_capacity?: number | undefined;
+    floor_id?: string | undefined;
+}, {
+    max_results?: number | undefined;
+    building_id?: string | undefined;
+    tags?: string[] | undefined;
+    min_capacity?: number | undefined;
+    max_capacity?: number | undefined;
+    floor_id?: string | undefined;
+}>, {
+    max_results: number;
+    building_id?: string | undefined;
+    tags?: string[] | undefined;
+    min_capacity?: number | undefined;
+    max_capacity?: number | undefined;
+    floor_id?: string | undefined;
+}, {
+    max_results?: number | undefined;
+    building_id?: string | undefined;
+    tags?: string[] | undefined;
+    min_capacity?: number | undefined;
+    max_capacity?: number | undefined;
+    floor_id?: string | undefined;
+}>;
+export type AvailableRoomsArgs = z.output<typeof AvailableRoomsArgsSchema>;
+/**
+ * Execute available rooms tool
+ */
+export declare function executeAvailableRooms(args: AvailableRoomsArgs): Promise<AvailableRoomsResponse>;
+/**
+ * Register butlr_available_rooms with an McpServer instance
+ */
+export declare function registerAvailableRooms(server: McpServer): void;
+//# sourceMappingURL=butlr-available-rooms.d.ts.map

package/dist/tools/butlr-available-rooms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"butlr-available-rooms.d.ts","sourceRoot":"","sources":["../../src/tools/butlr-available-rooms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,OAAO,KAAK,EAAiB,sBAAsB,EAAmB,MAAM,uBAAuB,CAAC;AAkDpG,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAclC,CAAC;AAgCJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAoI3E;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,mCAwTnE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsB9D"}