@ffschrattenecker/tm1-mcp-server 7.0.2 → 8.0.0

package/dist/tm1-client/http.js

@@ -51,6 +51,24 @@ export class TM1HttpClient {
         this.logger = logger;
         this.profile = createConnectionProfile(config);
     }
+    mutationListeners = [];
+    /**
+     * @internal — subscribe to THIS connection's successful mutations. Unlike
+     * the process-global `tm1Events` bus, listeners die with the client, so a
+     * per-connection cache needs no unsubscribe and never sees another
+     * connection's writes.
+     */
+    onMutation(listener) {
+        this.mutationListeners.push(listener);
+    }
+    emitMutation(method, path) {
+        if (isSafeHttpMethod(method))
+            return;
+        const e = { method, path, connectionId: connectionIdOf(this.config) };
+        tm1Events.emit("mutation", e);
+        for (const listener of this.mutationListeners)
+            listener(e);
+    }
     /**
      * TM1 major version (11 | 12) — the single numeric source of truth for
      * version-conditional service code. Branch on this, never on the display
@@ -110,23 +128,11 @@ export class TM1HttpClient {
                         });
                     }
                     const retryResult = await this.handleResponse(retryResponse, path);
-                    if (!isSafeMethod) {
-                        tm1Events.emit("mutation", {
-                            method,
-                            path,
-                            connectionId: connectionIdOf(this.config),
-                        });
-                    }
+                    this.emitMutation(method, path);
                     return retryResult;
                 }
                 const result = await this.handleResponse(response, path);
-                if (!isSafeMethod) {
-                    tm1Events.emit("mutation", {
-                        method,
-                        path,
-                        connectionId: connectionIdOf(this.config),
-                    });
-                }
+                this.emitMutation(method, path);
                 return result;
             }
             catch (error) {
@@ -174,6 +180,22 @@ export class TM1HttpClient {
      */
     /** @internal — for Service-layer use; not part of the public consumer API. */
     async requestRaw(method, path, opts) {
+        return (await this.fetchRaw(method, path, opts)).text();
+    }
+    /**
+     * Same request as requestRaw, but hands back the bytes instead of a string.
+     *
+     * requestRaw decodes the body as UTF-8, which silently destroys anything
+     * that is not text — a spreadsheet read that way comes back as replacement
+     * characters. Callers that may face binary content use this and decide how
+     * to present it.
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    async requestRawBytes(method, path, opts) {
+        const res = await this.fetchRaw(method, path, opts);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async fetchRaw(method, path, opts) {
         const url = `${this.config.baseUrl}${this.profile.resolveApiPath(path)}`;
         const effectiveTimeout = opts?.timeoutMs ?? this.config.requestTimeoutMs;
         const cookie = await this.sessionManager.ensureSession();
@@ -198,15 +220,8 @@ export class TM1HttpClient {
             }
             throw this.classifyHttpError(response.status, path, body || undefined);
         }
-        const text = await response.text();
-        if (!isSafeHttpMethod(method)) {
-            tm1Events.emit("mutation", {
-                method,
-                path,
-                connectionId: connectionIdOf(this.config),
-            });
-        }
-        return text;
+        this.emitMutation(method, path);
+        return response;
     }
     /**
      * Make an authenticated HTTP request with a binary body (Buffer/Uint8Array).
@@ -237,13 +252,7 @@ export class TM1HttpClient {
             }
             throw this.classifyHttpError(response.status, path, errBody || undefined);
         }
-        if (!isSafeHttpMethod(method)) {
-            tm1Events.emit("mutation", {
-                method,
-                path,
-                connectionId: connectionIdOf(this.config),
-            });
-        }
+        this.emitMutation(method, path);
     }
     /**
      * Low-level single fetch with timeout + AbortSignal wiring.

package/dist/tm1-client/services/cell-service.d.ts

@@ -1,8 +1,10 @@
 import type { CalculationTraceNode, CellValue, FedCellDescriptor, FeederTraceResult, MdxResult } from "../../types.js";
 import type { RequestOptions, TM1HttpClient } from "../http.js";
+import { DimensionOrderCache } from "./dimension-order.js";
 export declare class CellService {
     private readonly http;
-    constructor(http: TM1HttpClient);
+    private readonly dimOrder;
+    constructor(http: TM1HttpClient, dimOrder?: DimensionOrderCache);
     /**
      * Get a single cell value via a 1-tuple MDX query.
      *
@@ -42,20 +44,20 @@ export declare class CellService {
     }>): Promise<void>;
     /**
      * Resolve the cube's dimension order and build Tuple@odata.bind paths for
-     * the cell-bound trace actions. Elements address the default hierarchy
-     * (same name as the dimension) — alternate hierarchies are not supported
-     * by these diagnostics tools.
+     * the cell-bound trace actions. Each entry addresses the dimension's default
+     * hierarchy, or an alternate one when written `Hier:Elem` — see
+     * splitHierarchyQualified().
      */
     private tupleBinds;
     /**
      * Check the feeders of a cell: returns the cells fed by this cell with a
-     * Fed flag per target — Fed=false marks a broken/missing feeder. v11 only.
+     * Fed flag per target — Fed=false marks a broken/missing feeder.
      * POST /api/v1/Cubes('{cube}')/tm1.CheckFeeders
      */
     checkFeeders(cubeName: string, elements: string[], opts?: RequestOptions): Promise<FedCellDescriptor[]>;
     /**
      * Trace the feeders of a cell: returns the cells this cell feeds plus the
-     * feeder statements involved. v11 only.
+     * feeder statements involved.
      * POST /api/v1/Cubes('{cube}')/tm1.TraceFeeders
      */
     traceFeeders(cubeName: string, elements: string[], opts?: RequestOptions): Promise<FeederTraceResult>;
@@ -63,7 +65,7 @@ export declare class CellService {
      * Trace how a cell value is calculated: recursive component tree with
      * per-component type (consolidation/rule), status, value, and rule
      * statements. The server returns the full tree; maxDepth/maxComponents
-     * truncate client-side to keep responses bounded. v11 only.
+     * truncate client-side to keep responses bounded.
      * POST /api/v1/Cubes('{cube}')/tm1.TraceCellCalculation
      */
     traceCellCalculation(cubeName: string, elements: string[], maxDepth?: number, maxComponents?: number, opts?: RequestOptions): Promise<CalculationTraceNode>;

package/dist/tm1-client/services/cell-service.js

@@ -1,16 +1,38 @@
 // Cell domain service. Owns single-cell reads, MDX cellset execution, and
 // cell writes via the cellset PATCH path. Cube-shape lookups (resolving
-// dimension order for getValue) go through the request layer directly rather
-// than CubeService to avoid a CubeService → CellService cycle later.
+// dimension order for getValue) go through the shared DimensionOrderCache
+// rather than CubeService to avoid a CubeService → CellService cycle later.
 //
 // See docs/ARCHITECTURE.md for the layering.
 import { TM1Error, TM1ErrorCode } from "../../types.js";
 import { escapeMdxName } from "../../lib/mdx.js";
 import { dimensionCountMismatch } from "../../lib/coordinate-error.js";
 import { bindLeftOutSandbox } from "../../lib/cell-address.js";
+import { mapSettledWithConcurrency } from "../../lib/concurrency.js";
 import { freeCellset, transformCellsetResponse } from "./cellset-transform.js";
-// OData key encoder: double ' per OData literal rules, then percent-encode.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { odataKey } from "./odata-page.js";
+import { DimensionOrderCache } from "./dimension-order.js";
+// In-flight cap for the per-cell re-walk after a refused bulk write.
+const FALLBACK_CONCURRENCY = 8;
+/**
+ * Split one entry of a cell coordinate into (hierarchy, element).
+ *
+ * A bare name addresses the dimension's DEFAULT hierarchy, which carries the
+ * dimension's own name. `Hier:Elem` addresses an alternate hierarchy — the
+ * same `Dim:Hier` idiom TM1 rules use, one slot down.
+ *
+ * The split takes the FIRST colon, and the dimension's default hierarchy can
+ * always be named explicitly, so an element whose own name contains a colon
+ * stays reachable: in dimension `Region`, `Region:A:B` is element `A:B` in
+ * the default hierarchy. A leading or trailing colon cannot separate anything,
+ * so such an entry is taken as a plain element name.
+ */
+function splitHierarchyQualified(entry, dimension) {
+    const i = entry.indexOf(":");
+    if (i <= 0 || i === entry.length - 1)
+        return { hierarchy: dimension, element: entry };
+    return { hierarchy: entry.slice(0, i), element: entry.slice(i + 1) };
+}
 // Build a fully-qualified MDX member reference for a write coordinate.
 // A caller may pass a pre-qualified ref to target an ALTERNATE hierarchy
 // (`[Dim].[AltHier].[Elem]`, or `[Dim].[Elem]` for the default) — passed
@@ -27,8 +49,10 @@ function qualifyWriteMember(dim, element) {
 }
 export class CellService {
     http;
-    constructor(http) {
+    dimOrder;
+    constructor(http, dimOrder = new DimensionOrderCache(http)) {
         this.http = http;
+        this.dimOrder = dimOrder;
     }
     /**
      * Get a single cell value via a 1-tuple MDX query.
@@ -42,9 +66,7 @@ export class CellService {
         if (elements.length === 0) {
             return null;
         }
-        const cubePath = `/api/v1/Cubes('${enc(cubeName)}')?$expand=Dimensions($select=Name)`;
-        const cubeMeta = await this.http.request("GET", cubePath);
-        const dims = cubeMeta.Dimensions.map((d) => d.Name);
+        const dims = await this.dimOrder.get(cubeName);
         // Sandboxes left out → Base, as tm1_write_cells does.
         elements = bindLeftOutSandbox(dims, elements) ?? elements;
         if (elements.length !== dims.length) {
@@ -164,11 +186,11 @@ export class CellService {
             const cellset = await this.http.request("POST", "/api/v1/ExecuteMDX", { MDX: mdx });
             const id = cellset.ID;
             try {
-                await this.http.request("PATCH", `/api/v1/Cellsets('${enc(id)}')/Cells(0)`, { Value: c.value });
+                await this.http.request("PATCH", `/api/v1/Cellsets('${odataKey(id)}')/Cells(0)`, { Value: c.value });
             }
             finally {
                 try {
-                    await this.http.request("DELETE", `/api/v1/Cellsets('${enc(id)}')`);
+                    await this.http.request("DELETE", `/api/v1/Cellsets('${odataKey(id)}')`);
                 }
                 catch {
                     // cleanup best-effort
@@ -186,7 +208,7 @@ export class CellService {
             let bulkFailed = false;
             const cellset = await this.http.request("POST", "/api/v1/ExecuteMDX", { MDX: mdx });
             try {
-                await this.http.request("PATCH", `/api/v1/Cellsets('${enc(cellset.ID)}')/Cells`, chunk.map((c, ordinal) => ({ Ordinal: ordinal, Value: c.value })));
+                await this.http.request("PATCH", `/api/v1/Cellsets('${odataKey(cellset.ID)}')/Cells`, chunk.map((c, ordinal) => ({ Ordinal: ordinal, Value: c.value })));
                 written += chunk.length;
             }
             catch {
@@ -200,7 +222,7 @@ export class CellService {
             }
             finally {
                 try {
-                    await this.http.request("DELETE", `/api/v1/Cellsets('${enc(cellset.ID)}')`);
+                    await this.http.request("DELETE", `/api/v1/Cellsets('${odataKey(cellset.ID)}')`);
                 }
                 catch {
                     // cleanup best-effort
@@ -208,7 +230,9 @@ export class CellService {
             }
             if (!bulkFailed)
                 continue;
-            const results = await Promise.allSettled(chunk.map(writeOne));
+            // Bounded: re-walking a 500-cell chunk unbounded put ~1500 requests
+            // (cellset, PATCH, delete per cell) in flight against the worker pool.
+            const results = await mapSettledWithConcurrency(chunk, FALLBACK_CONCURRENCY, (c) => writeOne(c));
             const failed = [];
             results.forEach((r, j) => {
                 if (r.status === "fulfilled") {
@@ -238,39 +262,41 @@ export class CellService {
     }
     /**
      * Resolve the cube's dimension order and build Tuple@odata.bind paths for
-     * the cell-bound trace actions. Elements address the default hierarchy
-     * (same name as the dimension) — alternate hierarchies are not supported
-     * by these diagnostics tools.
+     * the cell-bound trace actions. Each entry addresses the dimension's default
+     * hierarchy, or an alternate one when written `Hier:Elem` — see
+     * splitHierarchyQualified().
      */
     async tupleBinds(cubeName, elements) {
-        const cubeMeta = await this.http.request("GET", `/api/v1/Cubes('${enc(cubeName)}')?$expand=Dimensions($select=Name)`);
-        const dims = cubeMeta.Dimensions.map((d) => d.Name);
+        const dims = await this.dimOrder.get(cubeName);
         if (elements.length !== dims.length) {
             throw new TM1Error({
                 code: TM1ErrorCode.VALIDATION_ERROR,
                 message: `Cube '${cubeName}' has ${dims.length} dimension(s) (${dims.join(", ")}) but ${elements.length} element(s) were given`,
             });
         }
-        return dims.map((d, i) => `Dimensions('${enc(d)}')/Hierarchies('${enc(d)}')/Elements('${enc(elements[i])}')`);
+        return dims.map((d, i) => {
+            const { hierarchy, element } = splitHierarchyQualified(elements[i], d);
+            return `Dimensions('${odataKey(d)}')/Hierarchies('${odataKey(hierarchy)}')/Elements('${odataKey(element)}')`;
+        });
     }
     /**
      * Check the feeders of a cell: returns the cells fed by this cell with a
-     * Fed flag per target — Fed=false marks a broken/missing feeder. v11 only.
+     * Fed flag per target — Fed=false marks a broken/missing feeder.
      * POST /api/v1/Cubes('{cube}')/tm1.CheckFeeders
      */
     async checkFeeders(cubeName, elements, opts) {
         const binds = await this.tupleBinds(cubeName, elements);
-        const response = await this.http.request("POST", `/api/v1/Cubes('${enc(cubeName)}')/tm1.CheckFeeders?$expand=Cube($select=Name),Tuple($select=Name)`, { "Tuple@odata.bind": binds }, opts);
+        const response = await this.http.request("POST", `/api/v1/Cubes('${odataKey(cubeName)}')/tm1.CheckFeeders?$expand=Cube($select=Name),Tuple($select=Name)`, { "Tuple@odata.bind": binds }, opts);
         return (response.value ?? []).map(mapFedCell);
     }
     /**
      * Trace the feeders of a cell: returns the cells this cell feeds plus the
-     * feeder statements involved. v11 only.
+     * feeder statements involved.
      * POST /api/v1/Cubes('{cube}')/tm1.TraceFeeders
      */
     async traceFeeders(cubeName, elements, opts) {
         const binds = await this.tupleBinds(cubeName, elements);
-        const response = await this.http.request("POST", `/api/v1/Cubes('${enc(cubeName)}')/tm1.TraceFeeders?$expand=FedCells/Cube($select=Name),FedCells/Tuple($select=Name)`, { "Tuple@odata.bind": binds }, opts);
+        const response = await this.http.request("POST", `/api/v1/Cubes('${odataKey(cubeName)}')/tm1.TraceFeeders?$expand=FedCells/Cube($select=Name),FedCells/Tuple($select=Name)`, { "Tuple@odata.bind": binds }, opts);
         return {
             fedCells: (response.FedCells ?? []).map(mapFedCell),
             statements: response.Statements ?? [],
@@ -280,7 +306,7 @@ export class CellService {
      * Trace how a cell value is calculated: recursive component tree with
      * per-component type (consolidation/rule), status, value, and rule
      * statements. The server returns the full tree; maxDepth/maxComponents
-     * truncate client-side to keep responses bounded. v11 only.
+     * truncate client-side to keep responses bounded.
      * POST /api/v1/Cubes('{cube}')/tm1.TraceCellCalculation
      */
     async traceCellCalculation(cubeName, elements, maxDepth = 3, maxComponents = 20, opts) {
@@ -296,7 +322,7 @@ export class CellService {
             const prefix = "Components/".repeat(level);
             expandParts.push(`${prefix}Tuple($select=Name)`, `${prefix}Cube($select=Name)`);
         }
-        const response = await this.http.request("POST", `/api/v1/Cubes('${enc(cubeName)}')/tm1.TraceCellCalculation?$expand=${expandParts.join(",")}`, { "Tuple@odata.bind": binds }, opts);
+        const response = await this.http.request("POST", `/api/v1/Cubes('${odataKey(cubeName)}')/tm1.TraceCellCalculation?$expand=${expandParts.join(",")}`, { "Tuple@odata.bind": binds }, opts);
         return mapCalcComponent(response, maxDepth, maxComponents);
     }
 }

package/dist/tm1-client/services/chore-service.js

@@ -5,8 +5,7 @@
 import { CHORE_STATUS_UNAVAILABLE, TM1Error, TM1ErrorCode, } from "../../types.js";
 import { classifyChoreExecution } from "./chore-status.js";
 import { rethrowIfSystemic } from "./fallback.js";
-// OData key encoder: double ' per OData literal rules, then percent-encode.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { odataKey } from "./odata-page.js";
 function frequencyDuration(f) {
     return `P${f.days}DT${String(f.hours).padStart(2, "0")}H${String(f.minutes).padStart(2, "0")}M${String(f.seconds).padStart(2, "0")}S`;
 }
@@ -45,7 +44,7 @@ export class ChoreService {
      * PATCH /api/v1/Chores('{name}') with { Active: bool }
      */
     async toggleActive(choreName, active) {
-        const path = `/api/v1/Chores('${enc(choreName)}')`;
+        const path = `/api/v1/Chores('${odataKey(choreName)}')`;
         await this.http.request("PATCH", path, { Active: active });
     }
     /**
@@ -65,11 +64,11 @@ export class ChoreService {
      *   — everywhere else. Returns 204, so no status exists to report.
      */
     async execute(choreName, opts) {
-        const plain = `/api/v1/Chores('${enc(choreName)}')/tm1.Execute`;
+        const plain = `/api/v1/Chores('${odataKey(choreName)}')/tm1.Execute`;
         if (this.withReturnSupported === false) {
             return this.executeWithoutStatus(plain, opts);
         }
-        const withReturn = `/api/v1/Chores('${enc(choreName)}')/tm1.ExecuteWithReturn?$expand=ErrorLogFile`;
+        const withReturn = `/api/v1/Chores('${odataKey(choreName)}')/tm1.ExecuteWithReturn?$expand=ErrorLogFile`;
         try {
             const response = await this.http.request("POST", withReturn, {}, opts);
             this.withReturnSupported = true;
@@ -129,7 +128,7 @@ export class ChoreService {
             Frequency: frequencyDuration(chore.frequency),
             Tasks: chore.steps.map((step, idx) => ({
                 Step: idx,
-                "Process@odata.bind": `Processes('${enc(step.process)}')`,
+                "Process@odata.bind": `Processes('${odataKey(step.process)}')`,
                 Parameters: step.parameters.map((p) => ({
                     Name: p.name,
                     Value: p.value,
@@ -143,7 +142,7 @@ export class ChoreService {
      * PATCH /api/v1/Chores('{name}')
      */
     async update(choreName, updates) {
-        const path = `/api/v1/Chores('${enc(choreName)}')`;
+        const path = `/api/v1/Chores('${odataKey(choreName)}')`;
         const body = {};
         if (updates.startTime !== undefined)
             body.StartTime = updates.startTime;
@@ -159,7 +158,7 @@ export class ChoreService {
         if (updates.steps !== undefined) {
             body.Tasks = updates.steps.map((step, idx) => ({
                 Step: idx,
-                "Process@odata.bind": `Processes('${enc(step.process)}')`,
+                "Process@odata.bind": `Processes('${odataKey(step.process)}')`,
                 Parameters: step.parameters.map((p) => ({
                     Name: p.name,
                     Value: p.value,
@@ -173,7 +172,7 @@ export class ChoreService {
      * DELETE /api/v1/Chores('{name}')
      */
     async delete(choreName) {
-        await this.http.request("DELETE", `/api/v1/Chores('${enc(choreName)}')`);
+        await this.http.request("DELETE", `/api/v1/Chores('${odataKey(choreName)}')`);
     }
 }
 //# sourceMappingURL=chore-service.js.map

package/dist/tm1-client/services/cube-service.d.ts

@@ -1,6 +1,7 @@
 import type { Cube, CubeRules, RuleSyntaxError } from "../../types.js";
-import type { TM1HttpClient } from "../http.js";
+import type { RequestOptions, TM1HttpClient } from "../http.js";
 import { type NameFilterOpts, type Paged, type PageOpts } from "./odata-page.js";
+import { DimensionOrderCache } from "./dimension-order.js";
 export interface AllRulesOpts {
     /** Include control cubes (`}`-prefixed). Default false. */
     includeControl?: boolean;
@@ -14,7 +15,8 @@ export interface CubeListOpts extends NameFilterOpts {
 }
 export declare class CubeService {
     private readonly http;
-    constructor(http: TM1HttpClient);
+    private readonly dimOrder;
+    constructor(http: TM1HttpClient, dimOrder?: DimensionOrderCache);
     /**
      * List all cubes with their dimension names.
      * GET /api/v1/Cubes?$expand=Dimensions($select=Name)
@@ -36,7 +38,8 @@ export declare class CubeService {
         page: PageOpts;
     }): Promise<Paged<Cube>>;
     /**
-     * Return ordered dimension-name list of a cube.
+     * Return ordered dimension-name list of a cube. Cached per connection —
+     * see dimension-order.ts.
      * GET /api/v1/Cubes('{name}')?$expand=Dimensions($select=Name)
      */
     getDimensionNames(cubeName: string): Promise<string[]>;
@@ -104,23 +107,16 @@ export declare class CubeService {
      */
     checkRule(cubeName: string, ruleText: string): Promise<RuleSyntaxError[]>;
     /**
-     * Clear cube cells.
+     * Clear every cell in a cube.
      *
-     * A **full** clear runs an ephemeral TI with CubeClearData(). tm1.Clear is
-     * not an alternative on either build: 11.8 and 12.5 both answer
-     * "'tm1.Clear' resource can not be resolved on type 'Cube'" for a cube that
-     * exists, and neither declares a clear action anywhere in $metadata — Cube
-     * carries only Lock and Unlock. CubeClearData() is the only route measured
-     * to work.
-     *
-     * A **partial** clear would need tuple selectors, which only tm1.Clear
-     * offers, so no server reachable here can do one. Callers get
-     * UNSUPPORTED_OPERATION pointing at bedrock `}bedrock.cube.data.clear`
-     * rather than a request that is known to 404.
+     * The clear runs an ephemeral TI with CubeClearData(). tm1.Clear is not an
+     * alternative on either build: 11.8 and 12.5 both answer "'tm1.Clear'
+     * resource can not be resolved on type 'Cube'" for a cube that exists, and
+     * neither declares a clear action anywhere in $metadata — Cube carries only
+     * Lock and Unlock. CubeClearData() is the only route measured to work, and
+     * it takes a cube name and nothing else, so there is no region to scope.
      */
-    clear(cubeName: string, dimensions: string[], tuples: string[][]): Promise<void>;
-    /** Same verdict for both versions: no tuple-selective clear on this server. */
-    private partialClearUnsupported;
+    clear(cubeName: string, opts?: Pick<RequestOptions, "timeoutMs">): Promise<void>;
     /**
      * Unload a cube from memory. Forces TM1 to discard the in-memory fed-cell
      * index and reload from disk on next access. Required for feeder corrections