@butlr/butlr-mcp-server 0.2.0 → 0.5.0

package/dist/utils/field-validator.js

@@ -32,8 +32,9 @@ function normalizeFieldName(field) {
 /**
  * Valid fields for each entity type
  * Based on GraphQL schema (mix of snake_case and camelCase)
+ * Exported for unit testing (FIELD_SELECTIONS sync invariant)
  */
-const VALID_FIELDS = {
+export const VALID_FIELDS = {
     site: ["id", "name", "timezone", "siteNumber", "customID", "org_id", "buildings"],
     building: [
         "id",
@@ -62,6 +63,7 @@ const VALID_FIELDS = {
         "sensors",
         "hives",
         "building",
+        "tags",
     ],
     room: [
         "id",
@@ -76,6 +78,7 @@ const VALID_FIELDS = {
         "note",
         "sensors",
         "floor",
+        "tags",
     ],
     zone: [
         "id",
@@ -89,6 +92,7 @@ const VALID_FIELDS = {
         "rotation",
         "note",
         "sensors",
+        "tags",
     ],
     sensor: [
         "id",

package/dist/utils/field-validator.js.map

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

package/dist/utils/occupancy-helpers.d.ts

@@ -55,11 +55,24 @@ export declare function getPresenceCoverageNote(assetType: "floor" | "room" | "z
  * Build coverage note for traffic measurement.
  */
 export declare function getTrafficCoverageNote(assetType: "floor" | "room" | "zone", sensorCount: number): string;
+/**
+ * Caller context threaded through recommendation building. `assetType` decides
+ * structural applicability (zones don't support traffic); `windowLabel` is a
+ * human-readable description of the query window so failure copy doesn't claim
+ * a window the caller never queried (the current-occupancy tool uses a fixed
+ * 5-minute snapshot; the timeseries tool uses a caller-supplied range).
+ */
+export interface RecommendationContext {
+    assetType: "floor" | "room" | "zone";
+    windowLabel: string;
+}
 /**
  * Build measurement recommendation based on data availability AND query success.
  *
  * Unlike the previous implementation, this checks whether data was actually retrieved,
- * not just whether sensors exist.
+ * not just whether sensors exist. When both measurement types fail, the reason
+ * distinguishes three sub-cases (no sensors / sensors-but-quiet / call errored)
+ * so downstream LLMs don't conflate "uninstrumented space" with "no recent reads."
  */
-export declare function buildRecommendation(presence: BaseMeasurementData, traffic: BaseMeasurementData, presenceHasData: boolean, trafficHasData: boolean): MeasurementRecommendation;
+export declare function buildRecommendation(presence: BaseMeasurementData, traffic: BaseMeasurementData, presenceHasData: boolean, trafficHasData: boolean, ctx: RecommendationContext): MeasurementRecommendation;
 //# sourceMappingURL=occupancy-helpers.d.ts.map

package/dist/utils/occupancy-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"occupancy-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/occupancy-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAM5F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,eAAe,CAAC,CA0BxE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,YAAY,CAmEvF;AA4BD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CASnF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAOzE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,mBAAmB,EAC5B,eAAe,EAAE,OAAO,EACxB,cAAc,EAAE,OAAO,GACtB,yBAAyB,CA6B3B"}
+{"version":3,"file":"occupancy-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/occupancy-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAQ,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAM5F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,eAAe,CAAC,CA4BxE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,YAAY,CA8EvF;AAwCD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CASnF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAOzE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,mBAAmB,EAC5B,eAAe,EAAE,OAAO,EACxB,cAAc,EAAE,OAAO,EACvB,GAAG,EAAE,qBAAqB,GACzB,yBAAyB,CA4B3B"}

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,28 +60,41 @@ export function resolveAssetContext(assetId, ctx) {
         : undefined;
     // Resolve asset name
     const assetName = findAssetName(assetId, typedAssetType, ctx.floors);
-    // Filter sensors for this asset
-    const assetSensors = ctx.productionSensors.filter((s) => {
-        const sensorFloorId = s.floor_id || s.floorID;
-        const sensorRoomId = s.room_id || s.roomID;
-        switch (typedAssetType) {
-            case "floor":
-                return sensorFloorId === assetId;
-            case "room":
-                return sensorRoomId === assetId;
-            case "zone":
-                return false; // Zones don't have direct sensor assignments
-        }
-    });
+    // Filter sensors for this asset. Rooms get sensors via the flat
+    // productionSensors list (joined by sensor.room_id). Zones get them
+    // via the topology's floor.zones[i].sensors relation — they have
+    // their own directly-attributed sensors, NOT inherited from any
+    // notional "parent room" (zones and rooms are siblings under a
+    // floor; the legacy zone.room_id field is decorative).
+    let assetSensors;
+    if (typedAssetType === "zone") {
+        const zone = findZone(assetId, ctx.floors);
+        assetSensors = (zone?.sensors ?? []).filter(isProductionSensor);
+    }
+    else {
+        assetSensors = ctx.productionSensors.filter((s) => {
+            const sensorFloorId = s.floor_id || s.floorID;
+            const sensorRoomId = s.room_id || s.roomID;
+            return typedAssetType === "floor" ? sensorFloorId === assetId : sensorRoomId === assetId;
+        });
+    }
     // Partition sensors by mode
     const presenceSensors = assetSensors.filter((s) => s.mode === "presence");
     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 = [];
@@ -118,6 +133,18 @@ function findAssetName(assetId, assetType, floors) {
             return undefined;
     }
 }
+/**
+ * Find a zone object in the topology by id. Returns undefined if the zone
+ * isn't present (e.g. stale id or topology that didn't include zones).
+ */
+function findZone(zoneId, floors) {
+    for (const floor of floors) {
+        const zone = floor.zones?.find((z) => z.id === zoneId);
+        if (zone)
+            return zone;
+    }
+    return undefined;
+}
 /**
  * Get the measurement name for presence data based on asset type.
  */
@@ -174,9 +201,11 @@ export function getTrafficCoverageNote(assetType, sensorCount) {
  * Build measurement recommendation based on data availability AND query success.
  *
  * Unlike the previous implementation, this checks whether data was actually retrieved,
- * not just whether sensors exist.
+ * not just whether sensors exist. When both measurement types fail, the reason
+ * distinguishes three sub-cases (no sensors / sensors-but-quiet / call errored)
+ * so downstream LLMs don't conflate "uninstrumented space" with "no recent reads."
  */
-export function buildRecommendation(presence, traffic, presenceHasData, trafficHasData) {
+export function buildRecommendation(presence, traffic, presenceHasData, trafficHasData, ctx) {
     const presenceSucceeded = presence.available && presenceHasData && !presence.warning;
     const trafficSucceeded = traffic.available && trafficHasData && !traffic.warning;
     if (presenceSucceeded && trafficSucceeded) {
@@ -197,10 +226,78 @@ export function buildRecommendation(presence, traffic, presenceHasData, trafficH
             recommendation_reason: "Traffic available (entry/exit counts).",
         };
     }
-    const failureReason = presence.warning || traffic.warning || "No occupancy data available.";
     return {
         recommended_measurement: "none",
-        recommendation_reason: failureReason,
+        recommendation_reason: buildFailureReason(presence, traffic, ctx),
     };
 }
+/**
+ * Number of sensors configured for a measurement, regardless of which field
+ * the caller populated: floors report traffic via `entrance_sensor_count`;
+ * rooms and zones use `sensor_count`.
+ */
+function configuredSensorCount(data) {
+    return data.sensor_count ?? data.entrance_sensor_count ?? 0;
+}
+/**
+ * Compose the recommendation_reason when neither presence nor traffic yielded a
+ * usable reading. Prefers the more actionable of the two measurement types,
+ * giving the customer something concrete to do next (instrument the space,
+ * wait for the next read, check sensor health, or retry the call).
+ *
+ * Avoids the literal phrase "no occupancy data" — downstream LLMs were quoting
+ * it verbatim and turning "quiet but instrumented" into "the space is
+ * unmonitored," which is the opposite of true.
+ */
+function buildFailureReason(presence, traffic, ctx) {
+    const presenceReason = describeMeasurementFailure("presence", presence, ctx);
+    const trafficReason = describeMeasurementFailure("traffic", traffic, ctx);
+    // Prefer the measurement type carrying real signal: one with sensors
+    // configured, or whose call errored mid-flight. Without this, a floor with
+    // working entrance sensors but zero presence sensors would surface
+    // presence's "no sensors configured" copy and read as uninstrumented.
+    // Presence wins ties — it's the more informative signal when both
+    // measurement types are instrumented but quiet.
+    const presenceHasSignal = configuredSensorCount(presence) > 0 || Boolean(presence.warning);
+    const trafficHasSignal = configuredSensorCount(traffic) > 0 || Boolean(traffic.warning);
+    if (presenceReason && presenceHasSignal)
+        return presenceReason;
+    if (trafficReason && trafficHasSignal)
+        return trafficReason;
+    // Neither measurement type has sensors: the space is uninstrumented.
+    // Presence first — it applies to every asset type.
+    if (presenceReason)
+        return presenceReason;
+    if (trafficReason)
+        return trafficReason;
+    // Defensive fallback for totality only. Unreachable today: presence is
+    // applicable to every asset type, so `presenceReason` is always set.
+    return "No recent occupancy reads. Check butlr_hardware_snapshot for sensor health.";
+}
+/**
+ * Returns a customer-facing explanation of why a measurement type produced no
+ * usable reading, or `undefined` if the measurement type is structurally
+ * inapplicable to this asset (traffic on a zone). Only called for measurements
+ * that yielded no usable reading, so "sensors configured" below means
+ * configured-but-quiet.
+ */
+function describeMeasurementFailure(kind, data, ctx) {
+    // Traffic on a zone is the only structurally-N/A combination. The caller's
+    // coverage_note already explains why; surfacing it here would be redundant.
+    if (kind === "traffic" && ctx.assetType === "zone")
+        return undefined;
+    // The call errored. Surface the warning verbatim so the customer (and any
+    // LLM reading the response) gets the actual failure mode.
+    if (data.warning) {
+        return `Tried to retrieve ${kind} occupancy but the request failed: ${data.warning}. Retry with a smaller asset set, or check butlr_hardware_snapshot for sensor health.`;
+    }
+    // Sensors are configured but the Reporting API had no reads in the query
+    // window. Honest: we don't know if the space is empty or if the sensors
+    // are stuck — point at hardware_snapshot for the health-check answer.
+    if (configuredSensorCount(data) > 0) {
+        return `Sensor(s) configured but no ${kind} reads in ${ctx.windowLabel}. The asset may currently be empty, or the sensor(s) may need a health check via butlr_hardware_snapshot.`;
+    }
+    // No sensors at all. The space is uninstrumented for this measurement type.
+    return `No ${kind} sensors configured for this asset. Contact facilities to instrument it before requesting ${kind} occupancy.`;
+}
 //# sourceMappingURL=occupancy-helpers.js.map

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.5.0",
   "description": "Model Context Protocol server providing secure, read-only access to Butlr occupancy and asset data",
   "type": "module",
   "main": "dist/index.js",