@butlr/butlr-mcp-server 0.2.0 → 0.4.0

package/dist/utils/occupancy-helpers.js

@@ -8,7 +8,7 @@
 import { apolloClient } from "../clients/graphql-client.js";
 import { GET_ALL_SENSORS, GET_FULL_TOPOLOGY } from "../clients/queries/topology.js";
 import { detectAssetType } from "./asset-helpers.js";
-import { isProductionSensor } from "./graphql-helpers.js";
+import { isProductionSensor, throwIfGraphQLErrors } from "./graphql-helpers.js";
 import { getTimezoneForAsset, buildTimezoneMetadata } from "./timezone-helpers.js";
 import { rethrowIfGraphQLError } from "./graphql-helpers.js";
 /**
@@ -28,6 +28,8 @@ export async function fetchTopologyAndSensors() {
                 fetchPolicy: "network-only",
             }),
         ]);
+        throwIfGraphQLErrors(topoResult);
+        throwIfGraphQLErrors(sensorsResult);
     }
     catch (error) {
         rethrowIfGraphQLError(error);
@@ -58,7 +60,11 @@ export function resolveAssetContext(assetId, ctx) {
         : undefined;
     // Resolve asset name
     const assetName = findAssetName(assetId, typedAssetType, ctx.floors);
-    // Filter sensors for this asset
+    // Filter sensors for this asset. Zones have no direct sensor attribution —
+    // zone_occupancy is computed server-side and is not a roll-up of any
+    // single sensor we can identify client-side. The callers (current /
+    // timeseries occupancy tools) detect zones by asset_type and query
+    // anyway; the sensor count is correctly reported as 0 for zones.
     const assetSensors = ctx.productionSensors.filter((s) => {
         const sensorFloorId = s.floor_id || s.floorID;
         const sensorRoomId = s.room_id || s.roomID;
@@ -68,7 +74,7 @@ export function resolveAssetContext(assetId, ctx) {
             case "room":
                 return sensorRoomId === assetId;
             case "zone":
-                return false; // Zones don't have direct sensor assignments
+                return false; // Zones do not inherit room sensors — see comment above.
         }
     });
     // Partition sensors by mode
@@ -76,10 +82,18 @@ export function resolveAssetContext(assetId, ctx) {
     let trafficSensors;
     switch (typedAssetType) {
         case "floor":
+            // Floor-level traffic comes from the building/floor entrances.
             trafficSensors = assetSensors.filter((s) => s.mode === "traffic" && s.is_entrance === true);
             break;
         case "room":
-            trafficSensors = assetSensors.filter((s) => s.mode === "traffic" && s.is_entrance === false);
+            // Room-level traffic includes every traffic-mode sensor bound to the
+            // room. `is_entrance` is a semantic flag indicating the sensor sits at
+            // a building/floor entrance — it is not a routing flag. The Reporting
+            // API aggregates by `room_id` regardless, so filtering on
+            // `is_entrance === false` here would silently drop counts for rooms
+            // whose sensors are all entrances (e.g. a café occupying the floor's
+            // entry area).
+            trafficSensors = assetSensors.filter((s) => s.mode === "traffic");
             break;
         default:
             trafficSensors = [];

package/dist/utils/occupancy-helpers.js.map

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

package/dist/utils/tag-resolver.d.ts

@@ -0,0 +1,99 @@
+import { type TagId, type TagMatch, type TagName, type TaggedEntityRef } from "../clients/queries/tags.js";
+/**
+ * Pure tag-name → tag-row resolution shared by `butlr_available_rooms` and
+ * `butlr_list_topology`. Pure-function over an already-fetched row list so
+ * each caller can fetch the minimum tag shape it needs without the helper
+ * having to know about Apollo or GraphQL queries.
+ *
+ * The three-arm return contract (`ok` / `no_match` / `unsatisfiable`) is
+ * documented on `ResolveTagNamesResult` below — callers MUST switch on
+ * `kind` before touching the resolved arms.
+ */
+export interface ResolveTagNamesInput<Row extends {
+    id: string;
+    name: string;
+}> {
+    /** All tag rows fetched from the API (any shape that has at least id+name). */
+    allTags: Row[];
+    /** Names supplied by the caller (case-insensitive match against `allTags[].name`). */
+    requestedNames: string[];
+    /** Multi-tag semantics — only affects the `unsatisfiable` discriminant for unknown tags. */
+    match: TagMatch;
+}
+/**
+ * Discriminated union over the three terminal states.
+ *
+ * Callers branch on `kind` first; the type structurally prevents reading
+ * `resolvedRows` on a non-`ok` branch, where the resolved subset must NOT
+ * be used (it would silently broaden a `match='all'` query to `match='any'`
+ * semantics, or hide an all-unknown input behind a misleading "partial
+ * resolution" path).
+ *
+ * - `ok` — at least one requested name resolved; safe to continue with the
+ *   subset. Under `match='all'` this implies every name resolved.
+ * - `no_match` — every requested name was unknown. Distinct from
+ *   `unsatisfiable` because the right diagnostic is "no matching tags
+ *   found" rather than "cannot satisfy AND" (with one input there's no AND
+ *   to satisfy).
+ * - `unsatisfiable` — `match='all'` with at least one resolved AND at
+ *   least one unknown. Asking for the AND is impossible; the resolved
+ *   subset is intentionally hidden so a caller can't accidentally fall
+ *   back to `match='any'` semantics.
+ */
+export type ResolveTagNamesResult<Row extends {
+    id: string;
+    name: string;
+}> = {
+    kind: "ok";
+    /** Tag rows whose names matched — preserves the input row shape. */
+    resolvedRows: Row[];
+    /** Resolved tag IDs in the same order as `resolvedRows`. */
+    resolvedIds: TagId[];
+    /** Names from the input that did not match any tag. */
+    unknownNames: TagName[];
+    /**
+     * Number of malformed rows skipped by the defensive guard (missing or
+     * empty `id` / `name`, or canonical-name duplicates). Non-zero values
+     * indicate an upstream contract violation that callers should surface
+     * as a `malformed_tag_rows` diagnostic — silent filtering would
+     * otherwise hide the breakage.
+     */
+    droppedRowCount: number;
+    /**
+     * Up to ~5 representative names from the dropped rows (where the
+     * name was usable). Primarily useful for the duplicate-canonical
+     * case so operators can see which names collided.
+     */
+    droppedSampleNames: string[];
+} | {
+    kind: "no_match";
+    /** Every requested name, in input order. */
+    unknownNames: TagName[];
+    /** Same semantics as the `ok` variant — surface as a diagnostic if non-zero. */
+    droppedRowCount: number;
+    droppedSampleNames: string[];
+} | {
+    kind: "unsatisfiable";
+    /** The unknown subset that prevents satisfying `match='all'`. */
+    unknownNames: TagName[];
+    /** The resolved subset, hidden from callers so they can't broaden semantics. */
+    partialResolvedCount: number;
+    /** Same semantics as the `ok` variant — surface as a diagnostic if non-zero. */
+    droppedRowCount: number;
+    droppedSampleNames: string[];
+};
+export declare function resolveTagNames<Row extends {
+    id: string;
+    name: string;
+}>(input: ResolveTagNamesInput<Row>): ResolveTagNamesResult<Row>;
+/**
+ * Filter a tagged-entity ref list to only entries with a usable `id`, and
+ * drop the optional `name` when upstream omits it. Used by both
+ * `butlr_list_tags` (`applied_to_entities` projection) and
+ * `butlr_list_topology` (`collectDirectTaggedIds` + `collectMatchAwareClosure`) so the
+ * "what counts as a non-dangling ref" predicate lives in one place — they
+ * cannot drift apart, and the count + entity arrays produced from the same
+ * filtered list are guaranteed to agree.
+ */
+export declare function projectValidRefs(refs: ReadonlyArray<TaggedEntityRef> | null | undefined): TaggedEntityRef[];
+//# sourceMappingURL=tag-resolver.d.ts.map

package/dist/utils/tag-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/tag-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,KAAK,EACV,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;GASG;AAEH,MAAM,WAAW,oBAAoB,CAAC,GAAG,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;IAC5E,+EAA+E;IAC/E,OAAO,EAAE,GAAG,EAAE,CAAC;IACf,sFAAsF;IACtF,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,4FAA4F;IAC5F,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,qBAAqB,CAAC,GAAG,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,IACtE;IACE,IAAI,EAAE,IAAI,CAAC;IACX,oEAAoE;IACpE,YAAY,EAAE,GAAG,EAAE,CAAC;IACpB,4DAA4D;IAC5D,WAAW,EAAE,KAAK,EAAE,CAAC;IACrB,uDAAuD;IACvD,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,4CAA4C;IAC5C,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,iEAAiE;IACjE,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,gFAAgF;IAChF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEN,wBAAgB,eAAe,CAAC,GAAG,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACtE,KAAK,EAAE,oBAAoB,CAAC,GAAG,CAAC,GAC/B,qBAAqB,CAAC,GAAG,CAAC,CA8F5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,GAAG,SAAS,GACtD,eAAe,EAAE,CAOnB"}

package/dist/utils/tag-resolver.js

@@ -0,0 +1,108 @@
+import { asTagId, asTagName, } from "../clients/queries/tags.js";
+export function resolveTagNames(input) {
+    const { allTags, requestedNames, match } = input;
+    // Defensively skip rows whose `name` or `id` is not a usable string. The
+    // type contract says both are required, but a missing field on a partial
+    // GraphQL response would otherwise throw on `.toLowerCase()` (name) or
+    // surface a null branded TagId downstream (id), crashing every tag-using
+    // tool. Empty strings are rejected too — they can never match a
+    // Zod-validated request and would sit as dead weight in the lookup.
+    // The dropped count is returned to the caller so the upstream contract
+    // violation is visible (rather than silently masking it as "unknown tag").
+    const lookup = new Map();
+    let droppedRowCount = 0;
+    const droppedSampleNames = [];
+    const SAMPLE_LIMIT = 5;
+    const noteDroppedName = (name) => {
+        if (typeof name === "string" &&
+            name.trim().length > 0 &&
+            droppedSampleNames.length < SAMPLE_LIMIT) {
+            droppedSampleNames.push(name);
+        }
+    };
+    for (const t of allTags) {
+        // Whitespace-only counts as "missing" — asTagId / asTagName would
+        // reject it later, but the boundary check is the right place for
+        // the user-facing diagnostic to fire from.
+        if (typeof t.name !== "string" || t.name.trim().length === 0) {
+            droppedRowCount++;
+            // No usable name to sample — diagnostic carries count only.
+            continue;
+        }
+        if (typeof t.id !== "string" || t.id.trim().length === 0) {
+            droppedRowCount++;
+            noteDroppedName(t.name);
+            continue;
+        }
+        const key = t.name.toLowerCase();
+        // First-write-wins on duplicate canonical names. If upstream returns
+        // two rows with case-insensitively equal names (e.g. "Huddle" and
+        // "huddle"), last-write would non-deterministically depend on
+        // upstream order and silently mask the upstream-contract violation.
+        // Treating the dup as a malformed row keeps resolution deterministic
+        // and surfaces the issue via the same droppedRowCount → malformed_tag_rows
+        // diagnostic that catches null/empty rows.
+        if (lookup.has(key)) {
+            droppedRowCount++;
+            noteDroppedName(t.name);
+            continue;
+        }
+        lookup.set(key, t);
+    }
+    const resolvedRows = [];
+    const resolvedIds = [];
+    const unknownNames = [];
+    for (const rawName of requestedNames) {
+        const name = asTagName(rawName);
+        const row = lookup.get(name.toLowerCase());
+        if (row) {
+            resolvedRows.push(row);
+            resolvedIds.push(asTagId(row.id));
+        }
+        else {
+            unknownNames.push(name);
+        }
+    }
+    if (resolvedRows.length === 0 && unknownNames.length > 0) {
+        // At least one name was requested and nothing matched — distinct from
+        // `unsatisfiable` so callers can emit "no matching tags found" rather
+        // than the misleading "cannot satisfy AND" (when only one input was
+        // sent there's no AND to fail). Empty `requestedNames` falls through
+        // to the `ok` branch as a trivially-empty resolution.
+        return { kind: "no_match", unknownNames, droppedRowCount, droppedSampleNames };
+    }
+    if (match === "all" && unknownNames.length > 0) {
+        return {
+            kind: "unsatisfiable",
+            unknownNames,
+            partialResolvedCount: resolvedRows.length,
+            droppedRowCount,
+            droppedSampleNames,
+        };
+    }
+    return {
+        kind: "ok",
+        resolvedRows,
+        resolvedIds,
+        unknownNames,
+        droppedRowCount,
+        droppedSampleNames,
+    };
+}
+/**
+ * Filter a tagged-entity ref list to only entries with a usable `id`, and
+ * drop the optional `name` when upstream omits it. Used by both
+ * `butlr_list_tags` (`applied_to_entities` projection) and
+ * `butlr_list_topology` (`collectDirectTaggedIds` + `collectMatchAwareClosure`) so the
+ * "what counts as a non-dangling ref" predicate lives in one place — they
+ * cannot drift apart, and the count + entity arrays produced from the same
+ * filtered list are guaranteed to agree.
+ */
+export function projectValidRefs(refs) {
+    if (!refs)
+        return [];
+    return refs.flatMap((ref) => typeof ref.id === "string" && ref.id.trim().length > 0
+        ? [typeof ref.name === "string" ? { id: ref.id, name: ref.name } : { id: ref.id }]
+        : []);
+}
+//# sourceMappingURL=tag-resolver.js.map

package/dist/utils/tag-resolver.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@butlr/butlr-mcp-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Model Context Protocol server providing secure, read-only access to Butlr occupancy and asset data",
   "type": "module",
   "main": "dist/index.js",