@node-i3x/mcp 0.11.0 → 0.12.0

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+// src/cli.ts
+import { createRequire as createRequire2 } from "module";
+
 // src/utils/similarity.ts
 function computeSimilarity(a, b) {
   const s1 = a.toLowerCase().trim();
@@ -27,25 +30,50 @@ function computeSimilarity(a, b) {
   const maxLen = Math.max(m, n);
   return Math.max(0, 1 - distance / maxLen);
 }
-function rankSuggestions(query, candidates, topN = 5, minScore = 0.4) {
-  return candidates.map((candidate) => ({
-    candidate,
-    score: computeSimilarity(query, candidate)
-  })).filter((item) => item.score >= minScore).sort((a, b) => b.score - a.score).slice(0, topN).map((item) => item.candidate);
+var MAX_FUZZY_QUERY_LENGTH = 128;
+function boundedSimilarity(query, candidate, minScore) {
+  const q = query.toLowerCase().trim();
+  const c = candidate.toLowerCase().trim();
+  if (!q || !c) return 0;
+  if (q.includes(c) || c.includes(q)) return computeSimilarity(q, c);
+  const lengthBound = 1 - Math.abs(q.length - c.length) / Math.max(q.length, c.length);
+  return lengthBound < minScore ? 0 : computeSimilarity(q, c);
+}
+function rankObjectSuggestions(query, objects, topN = 5, minScore = 0.4) {
+  if (query.trim().length > MAX_FUZZY_QUERY_LENGTH) return [];
+  return objects.map(({ elementId, displayName }) => ({
+    elementId,
+    displayName,
+    score: Math.max(
+      boundedSimilarity(query, elementId, minScore),
+      displayName ? boundedSimilarity(query, displayName, minScore) : 0
+    )
+  })).filter((item) => item.score >= minScore).sort((a, b) => b.score - a.score).slice(0, topN).map(({ elementId, displayName }) => ({ elementId, displayName }));
 }
 
 // src/bindings/rest-binding.ts
-var RestClientBinding = class {
+var OBJECT_CACHE_TTL_MS = 6e4;
+var RestClientBinding = class _RestClientBinding {
   baseUrl;
   headers;
   requestTimeoutMs;
-  constructor(baseUrl = "http://localhost:3000", token, timeoutMs = 15e3) {
+  fetchImpl;
+  token;
+  objectCache;
+  /**
+   * @param fetchImpl - replaces the global fetch, e.g. to route requests into an
+   *   in-process server (see InProcessConnectorBinding).
+   */
+  constructor(baseUrl = "http://localhost:3000", token, timeoutMs = 15e3, fetchImpl) {
     let cleanUrl = baseUrl.trim().replace(/\/+$/, "");
     if (!cleanUrl.startsWith("http://") && !cleanUrl.startsWith("https://")) {
       cleanUrl = `http://${cleanUrl}`;
     }
+    cleanUrl = cleanUrl.replace(/\/v1$/i, "");
     this.baseUrl = cleanUrl;
     this.requestTimeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+    this.token = token;
     this.headers = {
       "Content-Type": "application/json",
       Accept: "application/json"
@@ -54,11 +82,27 @@ var RestClientBinding = class {
       this.headers.Authorization = `Bearer ${token}`;
     }
   }
+  /** Normalized base URL, without a trailing /v1. */
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  get hasToken() {
+    return Boolean(this.token);
+  }
+  /**
+   * A binding to `baseUrl`. Without `token`, the current token is kept when the URL
+   * is this binding's own (re-connecting must not silently drop the configured token).
+   */
+  connectTo(baseUrl, token) {
+    const next = new _RestClientBinding(baseUrl, token, this.requestTimeoutMs);
+    if (token !== void 0 || next.baseUrl !== this.baseUrl || !this.token) return next;
+    return new _RestClientBinding(baseUrl, this.token, this.requestTimeoutMs);
+  }
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
     const signal = options.signal || AbortSignal.timeout(this.requestTimeoutMs);
     try {
-      const response = await fetch(url, {
+      const response = await (this.fetchImpl ?? fetch)(url, {
         ...options,
         signal,
         headers: {
@@ -81,98 +125,134 @@ var RestClientBinding = class {
       throw err;
     }
   }
+  /** Unwrap a `{ success, result }` envelope; a `success: false` envelope becomes an error. */
+  async get(path) {
+    const res = await this.request(path);
+    if (res?.success !== true || !("result" in res)) {
+      throw new Error(`i3X request ${path} failed: ${describeFailure(res)}`);
+    }
+    return res.result;
+  }
+  /**
+   * POST a bulk request and return its `results` items, one per requested elementId.
+   * `success` is false on the envelope as soon as one item failed, so items are
+   * returned as they are; only a body without `results` is an error here.
+   */
+  async postBulk(path, body) {
+    const res = await this.request(path, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (!Array.isArray(res?.results)) {
+      throw new Error(`i3X request ${path} failed: ${describeFailure(res)}`);
+    }
+    return res.results;
+  }
+  /** Bulk items as per-element results: a failed item keeps its elementId and error. */
+  async postBulkPerElement(path, elementIds, body) {
+    const items = await this.postBulk(path, { elementIds, ...body });
+    return items.map((item, idx) => {
+      const elementId = item.elementId ?? elementIds[idx] ?? `element_${idx}`;
+      if (!item.success) return { elementId, error: describeFailure(item) };
+      if (item.result == null) return { elementId, error: "Server returned no result" };
+      return { elementId, result: item.result };
+    });
+  }
+  /** The single item of a one-element bulk request. */
+  async postBulkOne(path, body) {
+    const [item] = await this.postBulk(path, body);
+    if (!item) throw new Error(`i3X request ${path} returned no result`);
+    return item;
+  }
   async getInfo() {
-    return this.request("/v1/info");
+    return this.get("/v1/info");
   }
   async getNamespaces() {
-    const res = await this.request("/v1/namespaces");
-    return res.namespaces || [];
+    return this.get("/v1/namespaces");
   }
   async getObjectTypes(namespaceUri) {
     const query = namespaceUri ? `?namespaceUri=${encodeURIComponent(namespaceUri)}` : "";
-    const res = await this.request(
-      `/v1/objecttypes${query}`
-    );
-    return res.objectTypes || [];
+    return this.get(`/v1/objecttypes${query}`);
   }
   async getRelationshipTypes() {
-    const res = await this.request(
-      "/v1/relationshiptypes"
-    );
-    return res.relationshipTypes || [];
+    return this.get("/v1/relationshiptypes");
   }
   async getObjects(options) {
     const params = new URLSearchParams();
     if (options?.rootOnly) params.set("root", "true");
     if (options?.typeElementId) params.set("typeElementId", options.typeElementId);
     const query = params.toString() ? `?${params.toString()}` : "";
-    const res = await this.request(
-      `/v1/objects${query}`
-    );
-    return res.objects || [];
+    return this.get(`/v1/objects${query}`);
   }
+  /** `null` only when the server reports the element as not found (404). */
   async getObjectById(elementId) {
-    try {
-      const res = await this.request(
-        "/v1/objects/list",
-        {
-          method: "POST",
-          body: JSON.stringify({ elementIds: [elementId] })
-        }
-      );
-      if (res.objects && res.objects.length > 0) {
-        return res.objects[0] ?? null;
-      }
-      return null;
-    } catch {
-      return null;
-    }
+    const path = "/v1/objects/list";
+    const item = await this.postBulkOne(path, {
+      elementIds: [elementId]
+    });
+    if (item.success) return item.result ?? null;
+    if (item.responseDetail?.status === 404) return null;
+    throw new Error(
+      `i3X request ${path} failed for '${elementId}': ${describeFailure(item)}`
+    );
   }
   async getRelatedObjects(elementId, relationshipType) {
-    try {
-      const body = { elementId };
-      if (relationshipType) body.relationshipType = relationshipType;
-      const res = await this.request("/v1/objects/related", {
-        method: "POST",
-        body: JSON.stringify(body)
-      });
-      return (res.relatedObjects || []).map((r) => r.targetObject);
-    } catch {
-      return [];
+    const path = "/v1/objects/related";
+    const body = {
+      elementIds: [elementId]
+    };
+    if (relationshipType) body.relationshipType = relationshipType;
+    const item = await this.postBulkOne(path, body);
+    if (!item.success) {
+      throw new Error(
+        `i3X request ${path} failed for '${elementId}': ${describeFailure(item)}`
+      );
     }
+    return (item.result ?? []).filter(
+      (r) => !relationshipType || r.sourceRelationship === relationshipType
+    );
   }
-  async getObjectValues(elementIds, maxDepth = 1) {
-    const res = await this.request(
-      "/v1/objects/value",
-      {
-        method: "POST",
-        body: JSON.stringify({ elementIds, maxDepth })
-      }
+  async getRelatedObjectsBulk(elementIds) {
+    return this.postBulkPerElement(
+      "/v1/objects/related",
+      elementIds,
+      {}
     );
-    return res.values || [];
+  }
+  async getObjectValues(elementIds, maxDepth = 1) {
+    return this.postBulkPerElement("/v1/objects/value", elementIds, {
+      maxDepth
+    });
   }
   async getHistoricalValues(elementIds, startTime, endTime, maxDepth = 1) {
-    const res = await this.request(
+    return this.postBulkPerElement(
       "/v1/objects/history",
-      {
-        method: "POST",
-        body: JSON.stringify({ elementIds, startTime, endTime, maxDepth })
-      }
+      elementIds,
+      { startTime, endTime, maxDepth }
     );
-    return res.history || [];
   }
-  async findSuggestions(unknownId) {
-    try {
-      const allObjects = await this.getObjects();
-      const candidates = allObjects.map((o) => o.elementId);
-      return rankSuggestions(unknownId, candidates, 5, 0.4);
-    } catch {
-      return [];
+  /** Closest objects by elementId or displayName; a failure to list objects propagates. */
+  async findSuggestions(query) {
+    if (query.trim().length > MAX_FUZZY_QUERY_LENGTH) return [];
+    const now = Date.now();
+    if (!this.objectCache || now - this.objectCache.at > OBJECT_CACHE_TTL_MS) {
+      const objects = this.getObjects();
+      this.objectCache = { at: now, objects };
+      objects.catch(() => {
+        if (this.objectCache?.objects === objects) this.objectCache = void 0;
+      });
     }
+    return rankObjectSuggestions(query, await this.objectCache.objects);
   }
 };
+function describeFailure(res) {
+  const d = res?.responseDetail;
+  if (d) return [d.status, d.title, d.detail].filter(Boolean).join(" ");
+  return `unexpected response ${JSON.stringify(res)?.slice(0, 200)}`;
+}
 
 // src/server.ts
+import { createRequire } from "module";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -188,12 +268,18 @@ var connectSchema = z.object({
   serverUrl: z.string().describe(
     "The base URL of the i3X Gateway (e.g. 'http://192.168.1.50:8000' or 'https://i3x-portal.sterfive.io/instance/SESSION_ID')"
   ),
-  authToken: z.string().optional().describe("Optional Bearer authentication token for secured endpoints"),
-  verifyConnection: z.boolean().optional().default(true).describe("Whether to immediately verify connectivity by querying server /v1/info")
+  authToken: z.string().optional().describe(
+    "Optional Bearer authentication token. Omitted when re-connecting to the current URL: the current token is kept."
+  ),
+  verifyConnection: z.boolean().optional().default(true).describe(
+    "Whether to verify connectivity and credentials before switching (reads /v1/info and /v1/namespaces)"
+  )
 });
-async function handleConnect(args2, onBindingSwitch) {
+async function handleConnect(args2, onBindingSwitch, current) {
   const { serverUrl, authToken: authToken2, verifyConnection } = args2;
-  const newBinding = new RestClientBinding(serverUrl, authToken2);
+  const newBinding = current instanceof RestClientBinding ? current.connectTo(serverUrl, authToken2) : new RestClientBinding(serverUrl, authToken2);
+  const tokenKept = authToken2 === void 0 && newBinding.hasToken;
+  const url = newBinding.getBaseUrl();
   let serverInfo;
   if (verifyConnection) {
     try {
@@ -201,19 +287,39 @@ async function handleConnect(args2, onBindingSwitch) {
     } catch (err) {
       return {
         status: "connection_failed",
-        serverUrl,
+        serverUrl: url,
         error: err.message,
-        tip: "Please check that the server URL is reachable and the authentication token (if required) is valid."
+        tip: "Please check that the server URL is reachable."
+      };
+    }
+    try {
+      await newBinding.getNamespaces();
+    } catch (err) {
+      const message = err.message;
+      if (/^HTTP 40[13]\b/.test(message)) {
+        return {
+          status: "auth_failed",
+          serverUrl: url,
+          error: message,
+          tip: "The server rejected the credentials. Pass a valid authToken; the previous connection is still active."
+        };
+      }
+      return {
+        status: "connection_failed",
+        serverUrl: url,
+        error: message,
+        tip: "The server answered /v1/info but not /v1/namespaces; the previous connection is still active."
       };
     }
   }
   onBindingSwitch(newBinding);
   return {
     status: "connected",
-    serverUrl,
-    authenticated: Boolean(authToken2),
+    serverUrl: url,
+    authenticated: newBinding.hasToken,
+    ...tokenKept ? { note: "No authToken given: kept the token already in use for this URL." } : {},
     serverInfo: serverInfo || "Connection established without verification.",
-    message: `Successfully connected to ${serverUrl}. All subsequent i3X tool calls will query this endpoint.`
+    message: `Successfully connected to ${url}. All subsequent i3X tool calls will query this endpoint.`
   };
 }
 
@@ -265,14 +371,30 @@ async function handleDiscoverTypes(binding2, args2) {
 
 // src/tools/explore-hierarchy.ts
 import { z as z3 } from "zod";
+
+// src/utils/relationships.ts
+var PARENT_RELATIONSHIPS = /* @__PURE__ */ new Set(["IsComponentOf", "ComponentOf", "HasParent"]);
+function isParentRelationship(sourceRelationship) {
+  return PARENT_RELATIONSHIPS.has(sourceRelationship);
+}
+
+// src/tools/explore-hierarchy.ts
+var RELATED_BATCH_SIZE = 100;
+var RELATED_CONCURRENCY = 4;
 var exploreHierarchySchema = z3.object({
   rootElementId: z3.string().optional().describe(
     "Optional specific root asset elementId. If omitted, explores all root assets."
   ),
-  maxDepth: z3.number().optional().default(2).describe("Maximum depth to traverse child components (1 to 5, default: 2)")
+  maxDepth: z3.number().int().min(0).optional().default(2).describe(
+    "Levels to show: 1 = roots only, 2 = roots and their children (default), 0 = unlimited (bounded by maxNodes)"
+  ),
+  maxNodes: z3.number().int().min(1).max(5e3).optional().default(500).describe(
+    "Node budget for the whole tree (default 500, max 5000); the tree is marked truncated when reached"
+  )
 });
 async function handleExploreHierarchy(binding2, args2) {
-  const maxDepth = Math.min(Math.max(args2.maxDepth || 2, 1), 5);
+  const maxDepth = args2.maxDepth ?? 2;
+  const maxNodes = args2.maxNodes ?? 500;
   let roots;
   if (args2.rootElementId) {
     const root = await binding2.getObjectById(args2.rootElementId);
@@ -287,34 +409,93 @@ async function handleExploreHierarchy(binding2, args2) {
   } else {
     roots = await binding2.getObjects({ rootOnly: true });
   }
-  async function buildNode(asset, currentDepth, visited) {
-    const node = {
-      elementId: asset.elementId,
-      displayName: asset.displayName || asset.elementId,
-      typeElementId: asset.typeElementId
-    };
-    visited.add(asset.elementId);
-    if (currentDepth < maxDepth) {
-      const children = await binding2.getRelatedObjects(asset.elementId);
-      const unvisitedChildren = children.filter((c) => !visited.has(c.elementId));
-      if (unvisitedChildren.length > 0) {
-        node.children = await Promise.all(
-          unvisitedChildren.map(
-            (child) => buildNode(child, currentDepth + 1, new Set(visited))
-          )
-        );
+  const toNode = (asset) => ({
+    elementId: asset.elementId,
+    displayName: asset.displayName || asset.elementId,
+    typeElementId: asset.typeElementId
+  });
+  let nodeCount = 0;
+  let truncated = false;
+  const expanded = /* @__PURE__ */ new Set();
+  const tree = [];
+  for (const root of roots) {
+    if (nodeCount >= maxNodes) {
+      truncated = true;
+      break;
+    }
+    tree.push(toNode(root));
+    nodeCount++;
+  }
+  let level = tree;
+  for (let depth = 1; level.length > 0 && (maxDepth === 0 || depth < maxDepth); depth++) {
+    const toExpand = [];
+    for (const node of level) {
+      if (expanded.has(node.elementId)) node.repeated = true;
+      else {
+        expanded.add(node.elementId);
+        toExpand.push(node);
       }
     }
-    return node;
+    const related = await readRelatedInBatches(
+      binding2,
+      toExpand.map((n) => n.elementId)
+    );
+    const next = [];
+    toExpand.forEach((node, idx) => {
+      const entry = related[idx];
+      if (entry?.error) {
+        node.error = entry.error;
+        return;
+      }
+      const children = (entry?.result ?? []).filter((r) => !isParentRelationship(r.sourceRelationship)).map((r) => r.object);
+      if (children.length === 0) return;
+      if (nodeCount + children.length > maxNodes) {
+        truncated = true;
+        node.truncated = true;
+        return;
+      }
+      node.children = children.map(toNode);
+      nodeCount += children.length;
+      next.push(...node.children);
+    });
+    level = next;
   }
-  const hierarchyTree = await Promise.all(
-    roots.map((root) => buildNode(root, 1, /* @__PURE__ */ new Set()))
-  );
   return {
     totalRoots: roots.length,
-    traversalDepth: maxDepth,
-    plantTopology: hierarchyTree
+    traversalDepth: maxDepth === 0 ? "unlimited" : maxDepth,
+    nodeCount,
+    ...truncated ? {
+      truncated: {
+        maxNodes,
+        hint: "Node budget reached; nodes marked truncated were not expanded. Use rootElementId on one of them, a smaller maxDepth, or a larger maxNodes."
+      }
+    } : {},
+    plantTopology: tree
+  };
+}
+async function readRelatedInBatches(binding2, elementIds) {
+  const batches = [];
+  for (let i = 0; i < elementIds.length; i += RELATED_BATCH_SIZE) {
+    batches.push(elementIds.slice(i, i + RELATED_BATCH_SIZE));
+  }
+  const results = new Array(batches.length);
+  let nextBatch = 0;
+  const worker = async () => {
+    while (nextBatch < batches.length) {
+      const idx = nextBatch++;
+      const batch = batches[idx];
+      try {
+        results[idx] = await binding2.getRelatedObjectsBulk(batch);
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        results[idx] = batch.map((elementId) => ({ elementId, error }));
+      }
+    }
   };
+  await Promise.all(
+    Array.from({ length: Math.min(RELATED_CONCURRENCY, batches.length) }, worker)
+  );
+  return results.flat();
 }
 
 // src/tools/inspect-asset.ts
@@ -322,10 +503,13 @@ import { z as z4 } from "zod";
 var inspectAssetSchema = z4.object({
   elementId: z4.string().describe("The elementId of the asset to inspect (e.g. 'Pump_101', 'Boiler_101')"),
   includeValues: z4.boolean().optional().default(true).describe("Whether to include live VQT (Value, Quality, Timestamp) telemetry values"),
-  includeSchema: z4.boolean().optional().default(true).describe("Whether to include the ObjectType JSON Schema definition")
+  includeSchema: z4.boolean().optional().default(true).describe("Whether to include the ObjectType JSON Schema definition"),
+  maxDepth: z4.number().int().min(0).optional().default(2).describe(
+    "Value read depth through components: 1 = the asset only (an Object usually has no value of its own), 2 = with its components (default), 0 = unlimited"
+  )
 });
 async function handleInspectAsset(binding2, args2) {
-  const { elementId, includeValues, includeSchema } = args2;
+  const { elementId, includeValues, includeSchema, maxDepth } = args2;
   const asset = await binding2.getObjectById(elementId);
   if (!asset) {
     const suggestions = await binding2.findSuggestions(elementId);
@@ -340,25 +524,35 @@ async function handleInspectAsset(binding2, args2) {
     displayName: asset.displayName || asset.elementId,
     description: asset.metadata?.description || void 0,
     typeElementId: asset.typeElementId,
+    parentId: asset.parentId ?? null,
     isRoot: !asset.parentId
   };
+  const warnings = [];
   const relatedPromise = binding2.getRelatedObjects(elementId);
   const schemaPromise = includeSchema && asset.typeElementId ? binding2.getObjectTypes() : Promise.resolve(null);
-  const valuesPromise = includeValues ? binding2.getObjectValues([elementId]) : Promise.resolve(null);
+  const valuesPromise = includeValues ? binding2.getObjectValues([elementId], maxDepth) : Promise.resolve(null);
   const [relatedResult, schemaResult, valuesResult] = await Promise.allSettled([
     relatedPromise,
     schemaPromise,
     valuesPromise
   ]);
-  if (relatedResult.status === "fulfilled" && Array.isArray(relatedResult.value) && relatedResult.value.length > 0) {
-    result.subComponents = relatedResult.value.map((r) => ({
-      elementId: r.elementId,
-      displayName: r.displayName || r.elementId,
-      typeElementId: r.typeElementId
-    }));
+  if (relatedResult.status === "fulfilled") {
+    const subComponents = relatedResult.value.filter(
+      (r) => !isParentRelationship(r.sourceRelationship)
+    );
+    if (subComponents.length > 0) {
+      result.subComponents = subComponents.map((r) => ({
+        elementId: r.object.elementId,
+        displayName: r.object.displayName || r.object.elementId,
+        typeElementId: r.object.typeElementId,
+        relationship: r.sourceRelationship
+      }));
+    }
+  } else {
+    warnings.push(`Sub-components unavailable: ${errorMessage(relatedResult.reason)}`);
   }
-  if (schemaResult.status === "fulfilled" && Array.isArray(schemaResult.value)) {
-    const targetType = schemaResult.value.find(
+  if (schemaResult.status === "fulfilled") {
+    const targetType = schemaResult.value?.find(
       (t) => t.elementId === asset.typeElementId
     );
     if (targetType) {
@@ -368,101 +562,177 @@ async function handleInspectAsset(binding2, args2) {
         schema: targetType.schema
       };
     }
+  } else {
+    warnings.push(`Type schema unavailable: ${errorMessage(schemaResult.reason)}`);
   }
-  if (valuesResult.status === "fulfilled" && Array.isArray(valuesResult.value) && valuesResult.value.length > 0) {
-    result.currentValues = valuesResult.value[0];
-  } else if (valuesResult.status === "rejected") {
-    result.currentValuesWarning = "Telemetry data temporarily unavailable";
+  if (valuesResult.status === "fulfilled") {
+    const entry = valuesResult.value?.[0];
+    if (entry?.result) result.currentValues = entry.result;
+    else if (entry?.error) warnings.push(`Telemetry unavailable: ${entry.error}`);
+  } else {
+    warnings.push(`Telemetry unavailable: ${errorMessage(valuesResult.reason)}`);
   }
+  if (warnings.length > 0) result.warnings = warnings;
   return result;
 }
+function errorMessage(reason) {
+  return reason instanceof Error ? reason.message : String(reason);
+}
 
 // src/tools/monitor-events.ts
+import { z as z6 } from "zod";
+
+// src/utils/element-ids.ts
 import { z as z5 } from "zod";
-var monitorEventsSchema = z5.object({
-  elementIds: z5.array(z5.string()).min(1).describe("Array of asset elementIds to monitor (e.g. ['Boiler_101', 'Pump_101'])"),
-  condition: z5.string().optional().describe(
-    "Optional monitoring alert condition filter (e.g. 'temperature > 85 || quality != Good')"
+var MAX_ELEMENT_IDS = 100;
+function elementIdsSchema(description) {
+  return z5.array(z5.string()).min(1).transform((ids) => [...new Set(ids)]).refine((ids) => ids.length <= MAX_ELEMENT_IDS, {
+    message: `At most ${MAX_ELEMENT_IDS} distinct elementIds per call.`
+  }).describe(`${description}; duplicates are ignored, at most ${MAX_ELEMENT_IDS}`);
+}
+
+// src/tools/monitor-events.ts
+var MAX_LISTED_ALERTS = 50;
+var monitorEventsSchema = z6.object({
+  elementIds: elementIdsSchema(
+    "Array of asset elementIds to check (e.g. ['Boiler_101', 'Pump_101'])"
+  ),
+  maxDepth: z6.number().int().min(0).optional().default(2).describe(
+    "Read depth through components: 1 = the element only, 2 = with its components (default), 0 = unlimited"
   )
 });
 async function handleMonitorEvents(binding2, args2) {
-  const { elementIds, condition } = args2;
-  const currentValues = await binding2.getObjectValues(elementIds);
+  const { elementIds, maxDepth } = args2;
+  const snapshot = await binding2.getObjectValues(elementIds, maxDepth);
+  const alerts = [];
+  for (const { elementId, result, error } of snapshot) {
+    if (error) {
+      alerts.push({ elementId, error });
+      continue;
+    }
+    if (result && !isGood(result.quality)) {
+      alerts.push({ elementId, quality: result.quality });
+    }
+    for (const [componentId, vqt] of Object.entries(result?.components ?? {})) {
+      if (!isGood(vqt.quality))
+        alerts.push({ elementId: componentId, quality: vqt.quality });
+    }
+  }
+  const summary = {
+    bad: alerts.filter((a) => a.quality && /^bad/i.test(a.quality)).length,
+    uncertain: alerts.filter((a) => a.quality && /^uncertain/i.test(a.quality)).length,
+    readErrors: alerts.filter((a) => a.error).length
+  };
   return {
-    status: "monitoring_active",
-    monitoredAssets: elementIds,
-    alertCondition: condition || "All value or quality changes",
-    initialSnapshot: currentValues,
-    instructions: "Subscription stream registered. The MCP server will emit notification events on matching VQT telemetry updates or threshold breaches."
+    status: "snapshot",
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary,
+    alerts: alerts.slice(0, MAX_LISTED_ALERTS),
+    ...alerts.length > MAX_LISTED_ALERTS ? { alertsOmitted: alerts.length - MAX_LISTED_ALERTS } : {},
+    snapshot,
+    note: "Point-in-time read; no subscription is created. Call again to re-check."
   };
 }
+function isGood(quality) {
+  return String(quality).toLowerCase().startsWith("good");
+}
 
 // src/tools/query-telemetry.ts
-import { z as z6 } from "zod";
-var queryTelemetrySchema = z6.object({
-  elementIds: z6.array(z6.string()).min(1).describe("Array of asset elementIds to query (e.g. ['Pump_101', 'Boiler_101'])"),
-  mode: z6.enum(["current", "history"]).optional().default("current").describe(
+import { z as z7 } from "zod";
+var queryTelemetrySchema = z7.object({
+  elementIds: elementIdsSchema(
+    "Array of asset elementIds to query (e.g. ['Pump_101', 'Boiler_101'])"
+  ),
+  mode: z7.enum(["current", "history"]).optional().default("current").describe(
     "Query mode: 'current' for live VQT telemetry, 'history' for time-series trend analysis"
   ),
-  startTime: z6.string().optional().describe(
-    "ISO 8601 start time or relative time string (e.g. '-2h', '-30m', '-1d') for history mode"
+  startTime: z7.string().optional().describe(
+    "ISO 8601 start time or relative time string (e.g. '-2h', '-30m', '-1d') for history mode (default: -1h)"
+  ),
+  endTime: z7.string().optional().describe(
+    "ISO 8601 end time or relative time string (e.g. '-10m') for history mode (default: now)"
   ),
-  endTime: z6.string().optional().describe("ISO 8601 end time (defaults to now) for history mode"),
-  aggregateStats: z6.boolean().optional().default(true).describe(
+  maxDepth: z7.number().int().min(0).optional().default(2).describe(
+    "Read depth through components: 1 = the element only, 2 = with its components (default), 0 = unlimited"
+  ),
+  aggregateStats: z7.boolean().optional().default(true).describe(
     "Whether to pre-compute min/max/mean statistical summaries for numeric sensor streams"
   )
 });
-function parseStartTime(input) {
-  if (!input) {
-    const d = /* @__PURE__ */ new Date();
-    d.setHours(d.getHours() - 1);
-    return d.toISOString();
-  }
-  const match = input.match(/^-(\d+)([smhdw])$/i);
+var RELATIVE_TIME = /^-(\d+)([smhdw])$/i;
+var UNIT_MS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5,
+  w: 6048e5
+};
+function parseTime(input, fallback, name) {
+  if (!input) return fallback.toISOString();
+  const match = input.match(RELATIVE_TIME);
   if (match) {
-    const amount = parseInt(match[1], 10);
-    const unit = match[2].toLowerCase();
-    const d = /* @__PURE__ */ new Date();
-    switch (unit) {
-      case "s":
-        d.setSeconds(d.getSeconds() - amount);
-        break;
-      case "m":
-        d.setMinutes(d.getMinutes() - amount);
-        break;
-      case "h":
-        d.setHours(d.getHours() - amount);
-        break;
-      case "d":
-        d.setDate(d.getDate() - amount);
-        break;
-      case "w":
-        d.setDate(d.getDate() - amount * 7);
-        break;
-    }
-    return d.toISOString();
+    const amount = Number.parseInt(match[1], 10);
+    return new Date(
+      Date.now() - amount * UNIT_MS[match[2].toLowerCase()]
+    ).toISOString();
   }
   const parsed = new Date(input);
   if (Number.isNaN(parsed.getTime())) {
-    const defaultDate = /* @__PURE__ */ new Date();
-    defaultDate.setHours(defaultDate.getHours() - 1);
-    return defaultDate.toISOString();
+    throw new Error(
+      `Invalid ${name} '${input}': expected ISO 8601 (e.g. '2026-10-25T10:00:00Z') or a relative time (e.g. '-2h').`
+    );
   }
   return parsed.toISOString();
 }
+function describeDetail(d) {
+  return [d.status, d.title, d.detail].filter(Boolean).join(" ");
+}
+function isBadQuality(quality) {
+  return quality != null && !String(quality).toLowerCase().startsWith("good");
+}
+function seriesStatistics(values) {
+  const numericValues = [];
+  let badQualityCount = 0;
+  for (const v of values) {
+    if (isBadQuality(v.quality)) badQualityCount++;
+    if (typeof v.value === "number" && !Number.isNaN(v.value))
+      numericValues.push(v.value);
+  }
+  if (numericValues.length === 0) return { count: values.length, badQualityCount };
+  const sum = numericValues.reduce((a, b) => a + b, 0);
+  return {
+    min: Math.min(...numericValues),
+    max: Math.max(...numericValues),
+    mean: Math.round(sum / numericValues.length * 100) / 100,
+    count: numericValues.length,
+    badQualityCount
+  };
+}
 async function handleQueryTelemetry(binding2, args2) {
-  const { elementIds, mode, aggregateStats } = args2;
+  const { elementIds, mode, aggregateStats, maxDepth } = args2;
   if (mode === "current") {
-    const values = await binding2.getObjectValues(elementIds);
+    const values = await binding2.getObjectValues(elementIds, maxDepth);
     return {
       mode: "current",
       telemetry: values
     };
   }
-  const startTime = parseStartTime(args2.startTime);
-  const endTimeDate = args2.endTime ? new Date(args2.endTime) : /* @__PURE__ */ new Date();
-  const endTime = Number.isNaN(endTimeDate.getTime()) ? (/* @__PURE__ */ new Date()).toISOString() : endTimeDate.toISOString();
-  const history = await binding2.getHistoricalValues(elementIds, startTime, endTime);
+  const now = /* @__PURE__ */ new Date();
+  const startTime = parseTime(
+    args2.startTime,
+    new Date(now.getTime() - UNIT_MS.h),
+    "startTime"
+  );
+  const endTime = parseTime(args2.endTime, now, "endTime");
+  if (startTime > endTime) {
+    throw new Error(`startTime ${startTime} is after endTime ${endTime}.`);
+  }
+  const history = await binding2.getHistoricalValues(
+    elementIds,
+    startTime,
+    endTime,
+    maxDepth
+  );
   if (!aggregateStats) {
     return {
       mode: "history",
@@ -470,41 +740,27 @@ async function handleQueryTelemetry(binding2, args2) {
       history
     };
   }
-  const reports = history.map((record, idx) => {
-    const elementId = elementIds[idx] || `element_${idx}`;
+  const reports = history.map(({ elementId, result, error }) => {
+    if (error || !result) return { elementId, error: error ?? "No history returned" };
     const report = {
       elementId,
-      timeRange: { startTime, endTime },
-      dataPoints: record.values || []
+      dataPoints: result.values ?? [],
+      statistics: seriesStatistics(result.values ?? [])
     };
-    const numericValues = [];
-    let badQualityCount = 0;
-    for (const v of record.values || []) {
-      if (v.quality && String(v.quality).toUpperCase() !== "GOOD") {
-        badQualityCount++;
-      }
-      if (typeof v.value === "number" && !Number.isNaN(v.value)) {
-        numericValues.push(v.value);
+    if (result.components) {
+      const entries = Object.entries(result.components);
+      report.components = Object.fromEntries(
+        entries.map(([componentId, { values, responseDetail }]) => [
+          componentId,
+          // A failed component read is not an empty time range: report why.
+          responseDetail ? { error: describeDetail(responseDetail) } : { dataPoints: values ?? [], statistics: seriesStatistics(values ?? []) }
+        ])
+      );
+      const failed = entries.filter(([, c]) => c.responseDetail);
+      if (failed.length > 0 && failed.length === entries.length && !result.values?.length) {
+        report.note = `No component history could be read (${describeDetail(failed[0][1].responseDetail)}): the server keeps no history for this asset's variables.`;
       }
     }
-    if (numericValues.length > 0) {
-      const min = Math.min(...numericValues);
-      const max = Math.max(...numericValues);
-      const sum = numericValues.reduce((a, b) => a + b, 0);
-      const mean = Math.round(sum / numericValues.length * 100) / 100;
-      report.statistics = {
-        min,
-        max,
-        mean,
-        count: numericValues.length,
-        badQualityCount
-      };
-    } else {
-      report.statistics = {
-        count: (record.values || []).length,
-        badQualityCount
-      };
-    }
     return report;
   });
   return {
@@ -514,16 +770,41 @@ async function handleQueryTelemetry(binding2, args2) {
   };
 }
 
+// src/utils/output-limit.ts
+var DEFAULT_MAX_RESULT_CHARS = 1e5;
+var NARROWING_HINTS = {
+  i3x_explore_plant_hierarchy: "pass rootElementId, or lower maxDepth or maxNodes",
+  i3x_inspect_asset: "lower maxDepth, or set includeSchema to false",
+  i3x_query_telemetry: "pass fewer elementIds, lower maxDepth, or shorten the time range",
+  i3x_discover_types_and_schemas: "pass typeElementId or namespaceUri",
+  i3x_monitor_asset_events: "pass fewer elementIds or lower maxDepth"
+};
+function serializeToolResult(tool, result, maxChars) {
+  const text = JSON.stringify(result, null, 2);
+  if (text.length <= maxChars) return text;
+  const hint = NARROWING_HINTS[tool] ?? "narrow the query";
+  return `${text.slice(0, maxChars)}
+
+[Result truncated: showing the first ${maxChars} of ${text.length} characters, so the JSON above is incomplete. To see everything, ${hint}.]`;
+}
+
 // src/server.ts
+var { version } = createRequire(import.meta.url)("../package.json");
 var NodeI3xMcpServer = class {
   server;
   binding;
-  constructor(binding2) {
+  maxResultChars;
+  /**
+   * @param options.maxResultChars - cap on a serialized tool result (default
+   *   I3X_MCP_MAX_RESULT_CHARS, else 100 000 characters).
+   */
+  constructor(binding2, options = {}) {
     this.binding = binding2 || new RestClientBinding();
+    this.maxResultChars = options.maxResultChars ?? (Number(process.env.I3X_MCP_MAX_RESULT_CHARS) || DEFAULT_MAX_RESULT_CHARS);
     this.server = new Server(
       {
         name: "@node-i3x/mcp",
-        version: "0.10.0"
+        version
       },
       {
         capabilities: {
@@ -555,11 +836,11 @@ var NodeI3xMcpServer = class {
               },
               authToken: {
                 type: "string",
-                description: "Optional Bearer authentication token for secured endpoints"
+                description: "Optional Bearer authentication token. Omit it to keep the current token when re-connecting to the same URL."
               },
               verifyConnection: {
                 type: "boolean",
-                description: "Whether to verify connectivity by querying server /v1/info (default: true)"
+                description: "Whether to verify connectivity and credentials before switching (default: true); a rejected token returns status auth_failed"
               }
             },
             required: ["serverUrl"]
@@ -582,6 +863,10 @@ var NodeI3xMcpServer = class {
               includeSchema: {
                 type: "boolean",
                 description: "Whether to include the ObjectType JSON Schema definition (default: true)"
+              },
+              maxDepth: {
+                type: "number",
+                description: "Value read depth through components: 1 = the element only, 2 = with its components (default), 0 = unlimited"
               }
             },
             required: ["elementId"]
@@ -599,7 +884,11 @@ var NodeI3xMcpServer = class {
               },
               maxDepth: {
                 type: "number",
-                description: "Maximum depth to traverse child components (1 to 5, default: 2)"
+                description: "Levels to show: 1 = roots only, 2 = roots and their children (default), 0 = unlimited (bounded by maxNodes)"
+              },
+              maxNodes: {
+                type: "number",
+                description: "Node budget for the whole tree (default 500, max 5000); the result is marked truncated when reached"
               }
             }
           }
@@ -613,7 +902,7 @@ var NodeI3xMcpServer = class {
               elementIds: {
                 type: "array",
                 items: { type: "string" },
-                description: "Array of asset elementIds to query (e.g. ['Pump_101', 'Boiler_101'])"
+                description: "Array of asset elementIds to query (e.g. ['Pump_101', 'Boiler_101']); duplicates are ignored, at most 100"
               },
               mode: {
                 type: "string",
@@ -626,7 +915,11 @@ var NodeI3xMcpServer = class {
               },
               endTime: {
                 type: "string",
-                description: "ISO 8601 end time (defaults to now) for history mode"
+                description: "ISO 8601 or relative duration (e.g. '-10m') end time (defaults to now) for history mode"
+              },
+              maxDepth: {
+                type: "number",
+                description: "Value read depth through components: 1 = the element only, 2 = with its components (default), 0 = unlimited"
               },
               aggregateStats: {
                 type: "boolean",
@@ -655,18 +948,18 @@ var NodeI3xMcpServer = class {
         },
         {
           name: "i3x_monitor_asset_events",
-          description: "Create an i3X subscription stream to monitor real-time VQT value changes or threshold alert conditions.",
+          description: "One-shot health check of assets: current VQT values plus an alert list of every series whose quality is not Good. Does not subscribe; call again to re-check.",
           inputSchema: {
             type: "object",
             properties: {
               elementIds: {
                 type: "array",
                 items: { type: "string" },
-                description: "Array of asset elementIds to monitor"
+                description: "Array of asset elementIds to check; duplicates are ignored, at most 100"
               },
-              condition: {
-                type: "string",
-                description: "Optional alert condition filter (e.g. 'temperature > 85 || quality != Good')"
+              maxDepth: {
+                type: "number",
+                description: "Value read depth through components: 1 = the element only, 2 = with its components (default), 0 = unlimited"
               }
             },
             required: ["elementIds"]
@@ -681,9 +974,13 @@ var NodeI3xMcpServer = class {
         switch (name) {
           case "i3x_connect": {
             const parsed = connectSchema.parse(rawArgs);
-            result = await handleConnect(parsed, (newBinding) => {
-              this.binding = newBinding;
-            });
+            result = await handleConnect(
+              parsed,
+              (newBinding) => {
+                this.binding = newBinding;
+              },
+              this.binding
+            );
             break;
           }
           case "i3x_inspect_asset": {
@@ -718,7 +1015,7 @@ var NodeI3xMcpServer = class {
           content: [
             {
               type: "text",
-              text: JSON.stringify(result, null, 2)
+              text: serializeToolResult(name, result, this.maxResultChars)
             }
           ]
         };
@@ -813,7 +1110,8 @@ Environment Variables:
   process.exit(0);
 }
 if (args.includes("--version") || args.includes("-v")) {
-  console.error("0.10.0");
+  const { version: version2 } = createRequire2(import.meta.url)("../package.json");
+  console.log(version2);
   process.exit(0);
 }
 function getArgValue(flag) {