@butlr/butlr-mcp-server 0.2.0 → 0.5.0

package/dist/cache/topology-cache.d.ts

@@ -9,15 +9,30 @@ interface CacheEntry {
  */
 export declare const topologyCache: LRUCache<string, CacheEntry, unknown>;
 /**
- * Generate cache key for topology queries
+ * Generate cache key for topology queries.
+ *
+ * `devicesMerged` is part of the key because two consumers prime this cache
+ * with different shapes: `butlr_list_topology` runs sensors/hives through
+ * `mergeSensorsAndHivesIntoTopology` (so every floor carries `sensors` and
+ * `hives` arrays); `butlr_search_assets` writes the raw `sites` tree
+ * unmodified. A device-aware reader cannot trust an unmerged entry, so the
+ * two shapes must live under separate keys.
  */
-export declare function generateTopologyCacheKey(orgId: string, includeDevices: boolean, includeZones: boolean, siteIds?: string[]): string;
+export declare function generateTopologyCacheKey(orgId: string, includeDevices: boolean, includeZones: boolean, devicesMerged: boolean, siteIds?: string[]): string;
 /**
  * Get cached topology data
  */
 export declare function getCachedTopology(key: string): CacheEntry | undefined;
 /**
- * Store topology data in cache
+ * Store topology data in cache.
+ *
+ * INVARIANT: callers MUST only cache COMPLETE topology. A partial fetch
+ * (Apollo `result.error` set, GraphQL returned errors alongside data) will
+ * silently launder its partiality through the cache otherwise — every
+ * subsequent cache-hit reader would treat the truncated tree as
+ * authoritative without seeing `partial_topology`. `butlr-list-topology`
+ * gates its `setCachedTopology` call on `!partialData`; any new caller
+ * must do the same.
  */
 export declare function setCachedTopology(key: string, data: Record<string, unknown>): void;
 /**

package/dist/cache/topology-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topology-cache.d.ts","sourceRoot":"","sources":["../../src/cache/topology-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,uCAKxB,CAAC;AAEH;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAUrE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED;;GAEG;AACH,wBAAgB,aAAa;;;;EAM5B"}
+{"version":3,"file":"topology-cache.d.ts","sourceRoot":"","sources":["../../src/cache/topology-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,uCAKxB,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,OAAO,EACvB,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAUrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED;;GAEG;AACH,wBAAgB,aAAa;;;;EAM5B"}

package/dist/cache/topology-cache.js

@@ -16,15 +16,23 @@ export const topologyCache = new LRUCache({
     updateAgeOnHas: false,
 });
 /**
- * Generate cache key for topology queries
+ * Generate cache key for topology queries.
+ *
+ * `devicesMerged` is part of the key because two consumers prime this cache
+ * with different shapes: `butlr_list_topology` runs sensors/hives through
+ * `mergeSensorsAndHivesIntoTopology` (so every floor carries `sensors` and
+ * `hives` arrays); `butlr_search_assets` writes the raw `sites` tree
+ * unmodified. A device-aware reader cannot trust an unmerged entry, so the
+ * two shapes must live under separate keys.
  */
-export function generateTopologyCacheKey(orgId, includeDevices, includeZones, siteIds) {
+export function generateTopologyCacheKey(orgId, includeDevices, includeZones, devicesMerged, siteIds) {
     const parts = ["topo", orgId];
     if (siteIds && siteIds.length > 0) {
         parts.push(`sites:${siteIds.sort().join(",")}`);
     }
     parts.push(`devices:${includeDevices}`);
     parts.push(`zones:${includeZones}`);
+    parts.push(`merged:${devicesMerged}`);
     return parts.join(":");
 }
 /**
@@ -41,7 +49,15 @@ export function getCachedTopology(key) {
     return cached;
 }
 /**
- * Store topology data in cache
+ * Store topology data in cache.
+ *
+ * INVARIANT: callers MUST only cache COMPLETE topology. A partial fetch
+ * (Apollo `result.error` set, GraphQL returned errors alongside data) will
+ * silently launder its partiality through the cache otherwise — every
+ * subsequent cache-hit reader would treat the truncated tree as
+ * authoritative without seeing `partial_topology`. `butlr-list-topology`
+ * gates its `setCachedTopology` call on `!partialData`; any new caller
+ * must do the same.
  */
 export function setCachedTopology(key, data) {
     const entry = {

package/dist/cache/topology-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"topology-cache.js","sourceRoot":"","sources":["../../src/cache/topology-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C;;GAEG;AACH,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,0BAA0B;AAClH,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAO9B;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,QAAQ,CAAqB;IAC5D,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,iBAAiB;IACtB,cAAc,EAAE,IAAI,EAAE,yBAAyB;IAC/C,cAAc,EAAE,KAAK;CACtB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,cAAuB,EACvB,YAAqB,EACrB,OAAkB;IAElB,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAAW,cAAc,EAAE,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAEpC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEtC,IAAI,MAAM,EAAE,CAAC;QACX,KAAK,CAAC,gBAAgB,EAAE,sBAAsB,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,gBAAgB,EAAE,uBAAuB,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAA6B;IAC1E,MAAM,KAAK,GAAe;QACxB,IAAI;QACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAE9B,KAAK,CAAC,gBAAgB,EAAE,wBAAwB,GAAG,UAAU,iBAAiB,GAAG,IAAI,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,aAAa,CAAC,KAAK,EAAE,CAAC;IAEtB,KAAK,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,aAAa,CAAC,IAAI;QACxB,OAAO,EAAE,iBAAiB;QAC1B,GAAG,EAAE,iBAAiB,GAAG,IAAI,EAAE,sCAAsC;KACtE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"topology-cache.js","sourceRoot":"","sources":["../../src/cache/topology-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C;;GAEG;AACH,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,0BAA0B;AAClH,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAO9B;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,QAAQ,CAAqB;IAC5D,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,iBAAiB;IACtB,cAAc,EAAE,IAAI,EAAE,yBAAyB;IAC/C,cAAc,EAAE,KAAK;CACtB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,cAAuB,EACvB,YAAqB,EACrB,aAAsB,EACtB,OAAkB;IAElB,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAAW,cAAc,EAAE,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,UAAU,aAAa,EAAE,CAAC,CAAC;IAEtC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEtC,IAAI,MAAM,EAAE,CAAC;QACX,KAAK,CAAC,gBAAgB,EAAE,sBAAsB,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,gBAAgB,EAAE,uBAAuB,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAA6B;IAC1E,MAAM,KAAK,GAAe;QACxB,IAAI;QACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAE9B,KAAK,CAAC,gBAAgB,EAAE,wBAAwB,GAAG,UAAU,iBAAiB,GAAG,IAAI,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,aAAa,CAAC,KAAK,EAAE,CAAC;IAEtB,KAAK,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,aAAa,CAAC,IAAI;QACxB,OAAO,EAAE,iBAAiB;QAC1B,GAAG,EAAE,iBAAiB,GAAG,IAAI,EAAE,sCAAsC;KACtE,CAAC;AACJ,CAAC"}

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

@@ -9,10 +9,10 @@
  * Branded string types for tag identifiers.
  *
  * The Butlr API filter `roomsByTag` accepts tag *IDs*, not tag *names*.
- * These two are both `string` at runtime, which previously led to silent
- * filter failures when names were sent in the IDs slot. Branding them keeps
- * the distinction visible at the type level so the wrong one cannot be
- * passed by accident.
+ * Both are `string` at runtime, which previously led to silent filter
+ * failures when names were sent in the IDs slot. Branding them keeps the
+ * distinction visible at the type level so the wrong one cannot be passed
+ * by accident.
  */
 export type TagId = string & {
     readonly __brand: "TagId";
@@ -20,13 +20,70 @@ export type TagId = string & {
 export type TagName = string & {
     readonly __brand: "TagName";
 };
+/** Multi-tag composition mode shared across every tag-aware tool surface. */
+export type TagMatch = "all" | "any";
+/**
+ * Brand a string as a tag id. Throws on empty/whitespace-only input — the
+ * brand exists to catch "wrong slot" mistakes at compile time, but a blank
+ * value would brand cleanly and slip through. Constructors that accept
+ * arbitrary strings need a runtime check too.
+ */
 export declare const asTagId: (value: string) => TagId;
+/** Brand a string as a tag name. Same empty-input guard as `asTagId`. */
 export declare const asTagName: (value: string) => TagName;
+/**
+ * Shape of each tagged-entity reference returned by `GET_TAGS_WITH_USAGE`.
+ * `name` is best-effort: older API responses or partial entity records may
+ * omit it, so consumers must treat it as optional.
+ *
+ * Both `id` and `name` are runtime-guarded against partial GraphQL
+ * responses by `projectValidRefs` (src/utils/tag-resolver.ts) — refs with
+ * a missing/null/empty `id` are dropped, and a missing `name` is elided
+ * from the projection. Consumers should route through `projectValidRefs`
+ * rather than reading the fields directly, even though the type declares
+ * `id` as required.
+ */
+export interface TaggedEntityRef {
+    id: string;
+    name?: string;
+}
+/**
+ * Raw `tags` row returned by `GET_TAGS_WITH_USAGE`. Used by `butlr_list_tags`
+ * and the shared tag resolver — kept here so the GraphQL shape lives next
+ * to the query that produces it.
+ */
+export interface RawTagWithUsage {
+    id: string;
+    name: string;
+    organization_id?: string;
+    rooms?: TaggedEntityRef[] | null;
+    zones?: TaggedEntityRef[] | null;
+    floors?: TaggedEntityRef[] | null;
+}
+/**
+ * Inline tag projection returned when a Room/Zone/Floor query selects
+ * `tags { id name }` directly (e.g. `butlr_get_asset_details`).
+ *
+ * Lightweight `{id, name}` projection — both fields are required by
+ * the GraphQL schema and surfaced unchanged. Structurally similar to
+ * but intentionally distinct from `TaggedEntityRef`: `TaggedEntityRef`
+ * is best-effort (name optional) and represents the reverse direction
+ * (entities under a tag); `TagRef` represents tags applied to an
+ * entity. The bare name `Tag` is reserved for the full GraphQL Tag
+ * entity (with organization_id, associations, etc.); callers needing
+ * that shape go through `GET_TAGS_WITH_USAGE` instead.
+ */
+export interface TagRef {
+    id: string;
+    name: string;
+}
 /**
  * List every tag in the org along with its application footprint.
  *
- * Each tag's `rooms`, `zones`, and `floors` arrays are returned with
- * id-only payloads so the response stays bounded by tag count.
+ * Each tag's `rooms`, `zones`, and `floors` arrays carry both `id` and
+ * `name` so callers (e.g. `butlr_list_tags { include_entities: true }`,
+ * `butlr_list_topology { tag_names: [...] }`) can render the tagged
+ * entities without an extra resolution step.
  */
 export declare const GET_TAGS_WITH_USAGE: import("@apollo/client").DocumentNode;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../../src/clients/queries/tags.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAE/D,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,KAAuB,CAAC;AAChE,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,OAA2B,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,uCAiB/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,uCAO5B,CAAC"}
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../../src/clients/queries/tags.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAE/D,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,KAKvC,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,OAKzC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,uCAoB/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,uCAO5B,CAAC"}

package/dist/clients/queries/tags.js

@@ -1,11 +1,30 @@
 import { gql } from "@apollo/client";
-export const asTagId = (value) => value;
-export const asTagName = (value) => value;
+/**
+ * Brand a string as a tag id. Throws on empty/whitespace-only input — the
+ * brand exists to catch "wrong slot" mistakes at compile time, but a blank
+ * value would brand cleanly and slip through. Constructors that accept
+ * arbitrary strings need a runtime check too.
+ */
+export const asTagId = (value) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Invalid TagId: expected a non-empty string, got ${JSON.stringify(value)}`);
+    }
+    return value;
+};
+/** Brand a string as a tag name. Same empty-input guard as `asTagId`. */
+export const asTagName = (value) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Invalid TagName: expected a non-empty string, got ${JSON.stringify(value)}`);
+    }
+    return value;
+};
 /**
  * List every tag in the org along with its application footprint.
  *
- * Each tag's `rooms`, `zones`, and `floors` arrays are returned with
- * id-only payloads so the response stays bounded by tag count.
+ * Each tag's `rooms`, `zones`, and `floors` arrays carry both `id` and
+ * `name` so callers (e.g. `butlr_list_tags { include_entities: true }`,
+ * `butlr_list_topology { tag_names: [...] }`) can render the tagged
+ * entities without an extra resolution step.
  */
 export const GET_TAGS_WITH_USAGE = gql `
   query GetTagsWithUsage {
@@ -15,12 +34,15 @@ export const GET_TAGS_WITH_USAGE = gql `
       organization_id
       rooms {
         id
+        name
       }
       zones {
         id
+        name
       }
       floors {
         id
+        name
       }
     }
   }

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

@@ -1 +1 @@
-{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../src/clients/queries/tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAsBrC,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAS,EAAE,CAAC,KAAc,CAAC;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAW,EAAE,CAAC,KAAgB,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;CAiBrC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;;;;;;;CAOlC,CAAC"}
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../src/clients/queries/tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAyBrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAS,EAAE;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,mDAAmD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,KAAc,CAAC;AACxB,CAAC,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAW,EAAE;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,qDAAqD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,KAAgB,CAAC;AAC1B,CAAC,CAAC;AAmDF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;CAoBrC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;;;;;;;CAOlC,CAAC"}

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

@@ -12,8 +12,14 @@ export declare const GET_SITES_LIST: import("@apollo/client").DocumentNode;
 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
+ * Zones include a nested `sensors` selection — the only way to attribute sensors
+ * to zones, since GET_ALL_SENSORS selects no zone linkage. Verified live against
+ * the API: nested sensor selections are NOT truncated (an earlier note here
+ * claimed nested fields returned only 5 sensors; that does not reproduce — zone
+ * and floor nested counts match the flat sensors list exactly, and introspection
+ * shows no pagination args on the nested `sensors` field).
+ * Still use GET_ALL_SENSORS and GET_ALL_HIVES for full device detail (model,
+ * battery, heartbeat, ...), merged by floor_id/room_id.
  */
 export declare const GET_FULL_TOPOLOGY: import("@apollo/client").DocumentNode;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/clients/queries/topology.ts"],"names":[],"mappings":"AAEA;;GAEG;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"}
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/clients/queries/topology.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,uCAY1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,uCA6B9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,uCA4E7B,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

@@ -54,8 +54,14 @@ export const GET_SITE_STRUCTURE = gql `
 `;
 /**
  * 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
+ * Zones include a nested `sensors` selection — the only way to attribute sensors
+ * to zones, since GET_ALL_SENSORS selects no zone linkage. Verified live against
+ * the API: nested sensor selections are NOT truncated (an earlier note here
+ * claimed nested fields returned only 5 sensors; that does not reproduce — zone
+ * and floor nested counts match the flat sensors list exactly, and introspection
+ * shows no pagination args on the nested `sensors` field).
+ * Still use GET_ALL_SENSORS and GET_ALL_HIVES for full device detail (model,
+ * battery, heartbeat, ...), merged by floor_id/room_id.
  */
 export const GET_FULL_TOPOLOGY = gql `
   query GetFullTopology {
@@ -116,6 +122,17 @@ export const GET_FULL_TOPOLOGY = gql `
               room_id
               customID
               coordinates
+              sensors {
+                id
+                name
+                mac_address
+                mode
+                floor_id
+                room_id
+                hive_serial
+                is_entrance
+                is_online
+              }
             }
           }
         }

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

@@ -1 +1 @@
-{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../../src/clients/queries/topology.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAErC;;GAEG;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"}
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../../src/clients/queries/topology.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAErC;;GAEG;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;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EnC,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/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * TypeScript type definitions for Butlr GraphQL API
  */
+import type { TagRef } from "./queries/tags.js";
 export interface Capacity {
     max?: number;
     mid?: number;
@@ -70,6 +71,7 @@ export interface Floor {
     hives?: Hive[];
     floor_plans?: FloorPlan[];
     building: Building;
+    tags: TagRef[];
 }
 /**
  * Room - Defined space within a floor
@@ -92,6 +94,7 @@ export interface Room {
     pir_zero_window?: number;
     sensors?: Sensor[];
     floor: Floor;
+    tags: TagRef[];
 }
 /**
  * Zone - Sub-area within a floor or room
@@ -111,6 +114,7 @@ export interface Zone {
     customID?: string;
     note?: string;
     sensors?: Sensor[];
+    tags: TagRef[];
 }
 /**
  * Sensor - Individual detection device

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/clients/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IAEd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IAElD,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,EAAE,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,EAAE,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,EAAE,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,EAAE,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,EAAE,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/clients/types.ts"],"names":[],"mappings":"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"}

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

@@ -2,6 +2,13 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 /**
  * Wraps a tool handler to catch errors and return them as MCP tool errors
  * with isError: true, so the LLM can see and handle the error.
+ *
+ * If the underlying error message already carries a `[CODE]` prefix
+ * (added by `formatMCPError` upstream), the message passes through. If
+ * it doesn't — non-Apollo Error classes, unrelated `throw new Error(...)`
+ * sites, ServerParseError, etc. — we wrap with an INTERNAL_ERROR prefix
+ * so consumers branching on `[XXX]` still see a structured code. Stack
+ * traces survive in the `debug` log but never reach the response body.
  */
 export declare function withToolErrorHandling(handler: (args: Record<string, unknown>) => Promise<CallToolResult>): (args: Record<string, unknown>) => Promise<CallToolResult>;
 /**
@@ -52,6 +59,33 @@ export declare function translateGraphQLError(error: GraphQLClientError): MCPErr
  * Format MCP error for user-friendly display
  */
 export declare function formatMCPError(error: MCPError): string;
+/**
+ * Validate that an upstream-supplied value is array-shaped, returning the
+ * array (treating `null`/`undefined` as a legitimately-empty signal) or
+ * throwing INTERNAL_ERROR for any other shape. Centralizes the pattern
+ * that callers like `butlr_list_topology` / `butlr_list_tags` /
+ * `butlr_available_rooms` use on nested response fields where a
+ * `value || []` would otherwise launder a contract regression into
+ * silently-empty results.
+ *
+ * Pass `fieldName` for a useful error message; the lenient null/undefined
+ * branch reflects that legitimately-empty lists arrive as
+ * `[]`/`null`/missing depending on upstream resolver.
+ */
+export declare function ensureArrayOrEmpty<T>(value: ReadonlyArray<T> | null | undefined | unknown, fieldName: string): ReadonlyArray<T>;
+/**
+ * Throw a properly MCP-formatted INTERNAL_ERROR. Use for upstream contract
+ * violations (unexpected response shape, missing data envelope, etc.) so
+ * the failure surfaces with a structured `[INTERNAL_ERROR]` prefix that
+ * `withToolErrorHandling` translates uniformly. Without this, every tool
+ * would have a different error-shape contract for the same class of bug.
+ *
+ * `retryable: false` — contract violations are not transient. If the
+ * upstream returned a non-array where an array was contracted, retrying
+ * will yield the same broken response. MCP clients that auto-retry
+ * `retryable: true` errors would spin against this signal otherwise.
+ */
+export declare function throwInternalError(message: string): never;
 /**
  * Error subclass for MCP errors — provides stack traces and works with instanceof checks.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-errors.d.ts","sourceRoot":"","sources":["../../src/errors/mcp-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,GAClE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAa5D;AAED;;;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"}
+{"version":3,"file":"mcp-errors.d.ts","sourceRoot":"","sources":["../../src/errors/mcp-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,GAClE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAsB5D;AAED;;;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,CA6GzE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAgBtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EACpD,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC,CAAC,CAAC,CAOlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAOzD;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"}

package/dist/errors/mcp-errors.js

@@ -2,6 +2,13 @@ import { debug } from "../utils/debug.js";
 /**
  * Wraps a tool handler to catch errors and return them as MCP tool errors
  * with isError: true, so the LLM can see and handle the error.
+ *
+ * If the underlying error message already carries a `[CODE]` prefix
+ * (added by `formatMCPError` upstream), the message passes through. If
+ * it doesn't — non-Apollo Error classes, unrelated `throw new Error(...)`
+ * sites, ServerParseError, etc. — we wrap with an INTERNAL_ERROR prefix
+ * so consumers branching on `[XXX]` still see a structured code. Stack
+ * traces survive in the `debug` log but never reach the response body.
  */
 export function withToolErrorHandling(handler) {
     return async (args) => {
@@ -9,10 +16,19 @@ export function withToolErrorHandling(handler) {
             return await handler(args);
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            debug("tool-error", message, error);
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            const stack = error instanceof Error ? error.stack : undefined;
+            debug("tool-error", rawMessage, stack ?? error);
+            // Already-translated errors carry the `[CODE]` prefix; preserve them.
+            const text = /^\[[A-Z_]+\]/.test(rawMessage)
+                ? rawMessage
+                : formatMCPError({
+                    code: MCPErrorCode.INTERNAL_ERROR,
+                    message: rawMessage || "Unknown internal error",
+                    retryable: false,
+                });
             return {
-                content: [{ type: "text", text: message }],
+                content: [{ type: "text", text }],
                 isError: true,
             };
         }
@@ -59,11 +75,20 @@ export function translateGraphQLError(error) {
                 retryAfter,
             };
         }
-        // Bad request / validation
+        // Bad request / validation. Surface the upstream message in the
+        // user-visible string so an LLM caller debugging a 400 doesn't have
+        // to wait for DEBUG=butlr-mcp to see "Unknown tag id: foo_bar". Fall
+        // back to the generic phrasing only when no message can be extracted.
         if (networkError.statusCode === 400) {
+            const body = networkError.result;
+            const upstreamMessage = body?.errors?.find((e) => typeof e?.message === "string")?.message ??
+                (typeof networkError.message === "string" ? networkError.message : undefined);
+            const truncate = (s) => (s.length > 240 ? `${s.slice(0, 240)}…` : s);
             return {
                 code: MCPErrorCode.VALIDATION_FAILED,
-                message: "Invalid request parameters.",
+                message: upstreamMessage
+                    ? `Invalid request: ${truncate(String(upstreamMessage))}`
+                    : "Invalid request parameters.",
                 details: {
                     statusCode: 400,
                     body: networkError.result,
@@ -140,6 +165,47 @@ export function formatMCPError(error) {
     }
     return message;
 }
+/**
+ * Validate that an upstream-supplied value is array-shaped, returning the
+ * array (treating `null`/`undefined` as a legitimately-empty signal) or
+ * throwing INTERNAL_ERROR for any other shape. Centralizes the pattern
+ * that callers like `butlr_list_topology` / `butlr_list_tags` /
+ * `butlr_available_rooms` use on nested response fields where a
+ * `value || []` would otherwise launder a contract regression into
+ * silently-empty results.
+ *
+ * Pass `fieldName` for a useful error message; the lenient null/undefined
+ * branch reflects that legitimately-empty lists arrive as
+ * `[]`/`null`/missing depending on upstream resolver.
+ */
+export function ensureArrayOrEmpty(value, fieldName) {
+    if (value === null || value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    throwInternalError(`Unexpected response shape from ${fieldName} (expected array, got ${typeof value}). ` +
+        "Please retry; if persistent, the upstream API contract may have changed.");
+}
+/**
+ * Throw a properly MCP-formatted INTERNAL_ERROR. Use for upstream contract
+ * violations (unexpected response shape, missing data envelope, etc.) so
+ * the failure surfaces with a structured `[INTERNAL_ERROR]` prefix that
+ * `withToolErrorHandling` translates uniformly. Without this, every tool
+ * would have a different error-shape contract for the same class of bug.
+ *
+ * `retryable: false` — contract violations are not transient. If the
+ * upstream returned a non-array where an array was contracted, retrying
+ * will yield the same broken response. MCP clients that auto-retry
+ * `retryable: true` errors would spin against this signal otherwise.
+ */
+export function throwInternalError(message) {
+    const mcpError = {
+        code: MCPErrorCode.INTERNAL_ERROR,
+        message,
+        retryable: false,
+    };
+    throw new Error(formatMCPError(mcpError));
+}
 /**
  * Error subclass for MCP errors — provides stack traces and works with instanceof checks.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-errors.js","sourceRoot":"","sources":["../../src/errors/mcp-errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-errors.js","sourceRoot":"","sources":["../../src/errors/mcp-errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAmE;IAEnE,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,UAAU,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1E,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YAC/D,KAAK,CAAC,YAAY,EAAE,UAAU,EAAE,KAAK,IAAI,KAAK,CAAC,CAAC;YAChD,sEAAsE;YACtE,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC;gBAC1C,CAAC,CAAC,UAAU;gBACZ,CAAC,CAAC,cAAc,CAAC;oBACb,IAAI,EAAE,YAAY,CAAC,cAAc;oBACjC,OAAO,EAAE,UAAU,IAAI,wBAAwB;oBAC/C,SAAS,EAAE,KAAK;iBACjB,CAAC,CAAC;YACP,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;gBAC1C,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAoBD;;;GAGG;AACH,MAAM,CAAN,IAAY,YAOX;AAPD,WAAY,YAAY;IACtB,6CAA6B,CAAA;IAC7B,6CAA6B,CAAA;IAC7B,uDAAuC,CAAA;IACvC,iDAAiC,CAAA;IACjC,uCAAuB,CAAA;IACvB,+CAA+B,CAAA;AACjC,CAAC,EAPW,YAAY,KAAZ,YAAY,QAOvB;AAUD;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAyB;IAC7D,2BAA2B;IAC3B,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACvB,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QAExC,wBAAwB;QACxB,IAAI,YAAY,CAAC,UAAU,KAAK,GAAG,IAAI,YAAY,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;YACvE,OAAO;gBACL,IAAI,EAAE,YAAY,CAAC,YAAY;gBAC/B,OAAO,EAAE,8EAA8E;gBACvF,OAAO,EAAE;oBACP,UAAU,EAAE,YAAY,CAAC,UAAU;iBACpC;gBACD,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QAED,gBAAgB;QAChB,IAAI,YAAY,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;YACpC,MAAM,UAAU,GAAG,QAAQ,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;YAC5F,OAAO;gBACL,IAAI,EAAE,YAAY,CAAC,YAAY;gBAC/B,OAAO,EAAE,+CAA+C,UAAU,WAAW;gBAC7E,SAAS,EAAE,IAAI;gBACf,UAAU;aACX,CAAC;QACJ,CAAC;QAED,gEAAgE;QAChE,oEAAoE;QACpE,qEAAqE;QACrE,sEAAsE;QACtE,IAAI,YAAY,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,YAAY,CAAC,MAA+D,CAAC;YAC1F,MAAM,eAAe,GACnB,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,QAAQ,CAAC,EAAE,OAAO;gBAClE,CAAC,OAAO,YAAY,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAChF,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrF,OAAO;gBACL,IAAI,EAAE,YAAY,CAAC,iBAAiB;gBACpC,OAAO,EAAE,eAAe;oBACtB,CAAC,CAAC,oBAAoB,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE;oBACzD,CAAC,CAAC,6BAA6B;gBACjC,OAAO,EAAE;oBACP,UAAU,EAAE,GAAG;oBACf,IAAI,EAAE,YAAY,CAAC,MAAM;iBAC1B;gBACD,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QAED,YAAY;QACZ,IAAI,YAAY,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;YACpC,OAAO;gBACL,IAAI,EAAE,YAAY,CAAC,SAAS;gBAC5B,OAAO,EAAE,qBAAqB;gBAC9B,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,OAAO;YACL,IAAI,EAAE,YAAY,CAAC,aAAa;YAChC,OAAO,EAAE,kBAAkB,YAAY,CAAC,OAAO,EAAE;YACjD,OAAO,EAAE;gBACP,UAAU,EAAE,YAAY,CAAC,UAAU;aACpC;YACD,SAAS,EAAE,IAAI;SAChB,CAAC;IACJ,CAAC;IAED,2BAA2B;IAC3B,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QAE1C,wBAAwB;QACxB,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,KAAK,iBAAiB,EAAE,CAAC;YACtD,OAAO;gBACL,IAAI,EAAE,YAAY,CAAC,YAAY;gBAC/B,OAAO,EAAE,oDAAoD;gBAC7D,SAAS,EAAE,IAAI;aAChB,CAAC;QACJ,CAAC;QAED,oBAAoB;QACpB,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACrD,OAAO;gBACL,IAAI,EAAE,YAAY,CAAC,iBAAiB;gBACpC,OAAO,EAAE,kBAAkB,UAAU,CAAC,OAAO,EAAE;gBAC/C,OAAO,EAAE,UAAU,CAAC,UAAU;gBAC9B,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,OAAO;YACL,IAAI,EAAE,YAAY,CAAC,cAAc;YACjC,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,OAAO,EAAE,UAAU,CAAC,UAAU;YAC9B,SAAS,EAAE,KAAK;SACjB,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,OAAO;QACL,IAAI,EAAE,YAAY,CAAC,cAAc;QACjC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,2BAA2B;QACrD,SAAS,EAAE,KAAK;KACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,IAAI,OAAO,GAAG,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAEjD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,IAAI,cAAc,CAAC;IAC5B,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,OAAO,IAAI,kBAAkB,KAAK,CAAC,UAAU,GAAG,CAAC;IACnD,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,CAAC,EAAE,CAAC;QACtF,OAAO,IAAI,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IACpE,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAoD,EACpD,SAAiB;IAEjB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAyB,CAAC;IAC3D,kBAAkB,CAChB,kCAAkC,SAAS,yBAAyB,OAAO,KAAK,KAAK;QACnF,0EAA0E,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,QAAQ,GAAa;QACzB,IAAI,EAAE,YAAY,CAAC,cAAc;QACjC,OAAO;QACP,SAAS,EAAE,KAAK;KACjB,CAAC;IACF,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,IAAI,CAAe;IACnB,OAAO,CAA2B;IAClC,SAAS,CAAU;IAEnB,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,iBAAiB,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IACzB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,OAAiC;IAEjC,OAAO,IAAI,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}

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

@@ -1,6 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { type TagName } from "../clients/queries/tags.js";
 import type { AvailableRoomsResponse } from "../types/responses.js";
 export declare const AvailableRoomsArgsSchema: z.ZodEffects<z.ZodObject<{
     min_capacity: z.ZodOptional<z.ZodNumber>;
@@ -13,15 +12,15 @@ export declare const AvailableRoomsArgsSchema: z.ZodEffects<z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     max_results: number;
     tag_match: "all" | "any";
-    building_id?: string | undefined;
     tags?: string[] | undefined;
+    building_id?: 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;
+    building_id?: string | undefined;
     min_capacity?: number | undefined;
     max_capacity?: number | undefined;
     tag_match?: "all" | "any" | undefined;
@@ -29,15 +28,15 @@ export declare const AvailableRoomsArgsSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     max_results: number;
     tag_match: "all" | "any";
-    building_id?: string | undefined;
     tags?: string[] | undefined;
+    building_id?: 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;
+    building_id?: string | undefined;
     min_capacity?: number | undefined;
     max_capacity?: number | undefined;
     tag_match?: "all" | "any" | undefined;
@@ -48,24 +47,7 @@ export declare const GET_ROOMS_BY_TAG: import("@apollo/client").DocumentNode;
 /**
  * Execute available rooms tool
  */
-export declare function executeAvailableRooms(args: AvailableRoomsArgs): Promise<AvailableRoomsResponse | {
-    summary: string;
-    available_rooms: never[];
-    total_available: number;
-    showing: number;
-    timestamp: string;
-    filtered_by: {
-        max_results: number;
-        tag_match: "all" | "any";
-        building_id?: string | undefined;
-        tags?: string[] | undefined;
-        min_capacity?: number | undefined;
-        max_capacity?: number | undefined;
-        floor_id?: string | undefined;
-    };
-    unknown_tags: TagName[];
-    warning: string;
-}>;
+export declare function executeAvailableRooms(args: AvailableRoomsArgs): Promise<AvailableRoomsResponse>;
 /**
  * Register butlr_available_rooms with an McpServer instance
  */