@ffschrattenecker/tm1-mcp-server 6.0.0

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

@@ -0,0 +1,333 @@
+// 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.
+//
+// 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 { 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, "''"));
+// 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
+// through unchanged (caller owns escaping). A bare element defaults the
+// hierarchy to the dimension name (`[Dim].[Dim].[Elem]`); every bare name
+// component is `]`-escaped so a `]` in a name cannot mis-address the cell.
+function qualifyWriteMember(dim, element) {
+    const d = escapeMdxName(dim);
+    if (element.startsWith("[") && element.includes("].["))
+        return element;
+    if (element.startsWith("[") && element.endsWith("]"))
+        return `[${d}].[${d}].${element}`;
+    return `[${d}].[${d}].[${escapeMdxName(element)}]`;
+}
+export class CellService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Get a single cell value via a 1-tuple MDX query.
+     *
+     * TM1 11.8 returns 0 cells for `SELECT {} ON COLUMNS WHERE (...)` — the
+     * empty axis collapses the cellset. Put the first element on COLUMNS and
+     * the rest in WHERE to force a 1-cell cellset. Each element is qualified
+     * with its dimension to avoid name collisions in control cubes.
+     */
+    async getValue(cubeName, elements) {
+        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);
+        if (elements.length !== dims.length) {
+            throw dimensionCountMismatch(cubeName, dims, elements);
+        }
+        const qualify = (dim, element) => {
+            const d = escapeMdxName(dim);
+            // Pre-qualified MDX member reference — pass through (caller owns escaping).
+            if (element.startsWith("[") && element.includes("].["))
+                return element;
+            // Single bracketed member like `[Foo]` — prepend dimension.
+            if (element.startsWith("[") && element.endsWith("]"))
+                return `[${d}].${element}`;
+            return `[${d}].[${escapeMdxName(element)}]`;
+        };
+        const qualified = dims.map((d, i) => qualify(d, elements[i]));
+        const cube = escapeMdxName(cubeName);
+        const colMember = qualified[0];
+        const whereParts = qualified.slice(1);
+        const mdx = whereParts.length === 0
+            ? `SELECT {${colMember}} ON COLUMNS FROM [${cube}]`
+            : `SELECT {${colMember}} ON COLUMNS FROM [${cube}] WHERE (${whereParts.join(",")})`;
+        const cellsetResponse = await this.http.request("POST", "/api/v1/ExecuteMDX?$expand=Cells($select=Value,FormattedValue)", { MDX: mdx });
+        try {
+            if (cellsetResponse.Cells && cellsetResponse.Cells.length > 0) {
+                return cellsetResponse.Cells[0].Value;
+            }
+            // The MDX selects exactly one member, so a resolvable coordinate always
+            // yields one cell — an empty one comes back as a cell with a null Value.
+            // No cell at all means a member did not resolve. v11 refuses that MDX
+            // outright ("member not found (rte 81)"); v12 answers 200 with an empty
+            // cellset, and returning null there reported "this cell is empty" for a
+            // coordinate that does not exist. Both versions now fail the same way.
+            throw new TM1Error({
+                code: TM1ErrorCode.NOT_FOUND,
+                message: `No cell resolved for cube '${cubeName}' at (${elements.join(", ")}). At least one element name does not exist in its dimension — check spelling and case with tm1_get_descendants or tm1_list_element_attributes.`,
+                endpoint: "/api/v1/ExecuteMDX",
+            });
+        }
+        finally {
+            // Free the session-scoped cellset best-effort so single-value reads don't
+            // leak TM1 server memory while keep-alive holds the session open.
+            await freeCellset(this.http, cellsetResponse.ID);
+        }
+    }
+    /**
+     * Execute an MDX query and return structured cells + axes. Supports
+     * pagination via top/skip on the Cells expand. opts.timeoutMs overrides the
+     * 30s default for heavy queries.
+     * POST /api/v1/ExecuteMDX
+     */
+    async executeMdx(mdx, top, skip, opts) {
+        let cellsExpand = "Cells($select=Value,FormattedValue";
+        if (top !== undefined) {
+            cellsExpand += `;$top=${top}`;
+        }
+        if (skip !== undefined) {
+            cellsExpand += `;$skip=${skip}`;
+        }
+        cellsExpand += ")";
+        const axesExpand = "Axes($expand=Tuples($expand=Members($select=Name;$expand=Hierarchy($select=Name))))";
+        const path = `/api/v1/ExecuteMDX?$expand=${cellsExpand},${axesExpand}`;
+        const response = await this.http.request("POST", path, { MDX: mdx }, opts);
+        try {
+            return transformCellsetResponse(response);
+        }
+        finally {
+            // Cellsets are session-scoped and never auto-expire while keep-alive holds
+            // the session open, so a read that leaves them behind leaks TM1 server
+            // memory indefinitely. Free it best-effort (mirrors TM1py's delete_cellset).
+            await freeCellset(this.http, response.ID, opts);
+        }
+    }
+    /**
+     * Write multiple cells via the cellset PATCH path.
+     *
+     * TM1 11.8's Cube /tm1.Update action rejects every documented payload
+     * variant ("Invalid CellDescriptor property" / "Unexpected entity reference
+     * type" / "Expecting Object or EntityBind"). The cellset PATCH path is the
+     * supported route in 11.8:
+     *   1. POST /api/v1/ExecuteMDX with a slice MDX over the target cell
+     *   2. PATCH /api/v1/Cellsets('{id}')/Cells(0) with {Value}
+     *   3. DELETE /api/v1/Cellsets('{id}')
+     *
+     * Values can be numeric (for N-cubes) or strings (for string cells). Writes
+     * to consolidated cells are rejected by TM1.
+     *
+     * Prefer TI processes for reproducible data loads. Use this REST path only
+     * for ad-hoc / debugging writes.
+     */
+    async writeCells(cubeName, dimensions, cells) {
+        if (cells.length === 0)
+            return;
+        for (const c of cells) {
+            if (c.elements.length !== dimensions.length) {
+                throw dimensionCountMismatch(cubeName, dimensions, c.elements);
+            }
+        }
+        const cube = escapeMdxName(cubeName);
+        const tupleOf = (c) => {
+            const refs = c.elements.map((e, idx) => qualifyWriteMember(dimensions[idx], e));
+            return refs.length === 1 ? refs[0] : `(${refs.join(",")})`;
+        };
+        // One cell at a time cost three requests each — cellset, PATCH, delete —
+        // which measured 120 requests for 40 cells. TM1py (and tm1npm, which ports
+        // it) build ONE cellset over every target coordinate and PATCH the whole
+        // cell array once; verified against 11.8 at 40 cells in 3 requests, 9 ms.
+        //
+        // The array goes out BARE. `{Cells: [...]}` — what tm1npm sends — is
+        // refused with "Invalid CellsetCell property encountered in payload".
+        //
+        // Ordinals are positional, and TM1 does not collapse a repeated tuple in a
+        // set (verified), so cells[i] stays ordinal i even when a caller sends the
+        // same coordinate twice.
+        const writeOne = async (c) => {
+            const mdx = `SELECT {${tupleOf(c)}} ON COLUMNS FROM [${cube}]`;
+            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 });
+            }
+            finally {
+                try {
+                    await this.http.request("DELETE", `/api/v1/Cellsets('${enc(id)}')`);
+                }
+                catch {
+                    // cleanup best-effort
+                }
+            }
+        };
+        // Chunked because the MDX carries one tuple per cell: 2000 tuples measured
+        // at 194 KB and 90 ms, so this stays far inside what the server and any
+        // proxy in front of it accept.
+        const CHUNK = 500;
+        let written = 0;
+        for (let i = 0; i < cells.length; i += CHUNK) {
+            const chunk = cells.slice(i, i + CHUNK);
+            const mdx = `SELECT {${chunk.map(tupleOf).join(",")}} ON COLUMNS FROM [${cube}]`;
+            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 })));
+                written += chunk.length;
+            }
+            catch {
+                // A chunk holding one non-writable cell is refused WHOLE — nothing
+                // lands, not even the writable cells (measured:
+                // CubeCellWriteStatusElementIsConsolidated). The error names the
+                // status, never the coordinate, so the only way to tell the caller
+                // WHICH cell was refused is to re-walk this chunk one cell at a time.
+                // That is the old cost, paid only on the failing path.
+                bulkFailed = true;
+            }
+            finally {
+                try {
+                    await this.http.request("DELETE", `/api/v1/Cellsets('${enc(cellset.ID)}')`);
+                }
+                catch {
+                    // cleanup best-effort
+                }
+            }
+            if (!bulkFailed)
+                continue;
+            const results = await Promise.allSettled(chunk.map(writeOne));
+            const failed = [];
+            results.forEach((r, j) => {
+                if (r.status === "fulfilled") {
+                    written++;
+                }
+                else {
+                    failed.push({
+                        elements: chunk[j].elements,
+                        error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+                    });
+                }
+            });
+            if (failed.length > 0) {
+                const notAttempted = cells.length - (i + chunk.length);
+                throw new TM1Error({
+                    code: TM1ErrorCode.TM1_ERROR,
+                    message: `write_cells partially applied to '${cubeName}': ${written} written, ` +
+                        `${failed.length} failed, ${notAttempted} not attempted. ` +
+                        `Earlier writes are committed and will NOT be rolled back.`,
+                    details: JSON.stringify({ written, failed, notAttempted }),
+                    hint: "Inspect `details` for the failed coordinates. Successful cells are already committed — " +
+                        "retry ONLY the failed + notAttempted coords (re-sending written cells is harmless but wasteful). " +
+                        "Validate targets first with tm1_check_writable_coords.",
+                });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    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);
+        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])}')`);
+    }
+    /**
+     * 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.
+     * 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);
+        return (response.value ?? []).map(mapFedCell);
+    }
+    /**
+     * Trace the feeders of a cell: returns the cells this cell feeds plus the
+     * feeder statements involved. v11 only.
+     * 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);
+        return {
+            fedCells: (response.FedCells ?? []).map(mapFedCell),
+            statements: response.Statements ?? [],
+        };
+    }
+    /**
+     * 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.
+     * POST /api/v1/Cubes('{cube}')/tm1.TraceCellCalculation
+     */
+    async traceCellCalculation(cubeName, elements, maxDepth = 3, maxComponents = 20, opts) {
+        const binds = await this.tupleBinds(cubeName, elements);
+        // Components is a complex-type collection — nested nav-prop expand uses
+        // the path form (Components/Tuple); ($levels=...) is rejected by 11.8.
+        // Each path segment covers exactly one tree level, so emit one
+        // Components/.../{Tuple,Cube} pair per requested depth — without them,
+        // deeper nodes carry values but no coordinates (and no cube for
+        // cross-cube DB() components), making drill-down impossible.
+        const expandParts = ["Tuple($select=Name)"];
+        for (let level = 1; level <= maxDepth; level++) {
+            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);
+        return mapCalcComponent(response, maxDepth, maxComponents);
+    }
+}
+function mapFedCell(raw) {
+    return {
+        cube: raw.Cube?.Name ?? "",
+        tuple: (raw.Tuple ?? []).map((t) => t.Name ?? ""),
+        fed: raw.Fed === true,
+    };
+}
+function mapCalcComponent(raw, depthLeft, maxComponents) {
+    const node = { value: raw.Value ?? null };
+    if (raw.Type !== undefined)
+        node.type = raw.Type;
+    if (raw.Status !== undefined)
+        node.status = raw.Status;
+    if (raw.Cube?.Name !== undefined)
+        node.cube = raw.Cube.Name;
+    if (raw.Tuple !== undefined)
+        node.tuple = raw.Tuple.map((t) => t.Name ?? "");
+    if (raw.Statements !== undefined && raw.Statements.length > 0)
+        node.statements = raw.Statements;
+    const children = raw.Components ?? [];
+    if (children.length > 0) {
+        if (depthLeft <= 0) {
+            node.truncated = true;
+        }
+        else {
+            const kept = children.slice(0, maxComponents);
+            node.components = kept.map((c) => mapCalcComponent(c, depthLeft - 1, maxComponents));
+            if (children.length > maxComponents)
+                node.truncated = true;
+        }
+    }
+    return node;
+}
+//# sourceMappingURL=cell-service.js.map

package/dist/tm1-client/services/cellset-transform.d.ts

@@ -0,0 +1,26 @@
+import type { CellValue, MdxAxis, MdxResult } from "../../types.js";
+import type { RequestOptions, TM1HttpClient } from "../http.js";
+export declare function freeCellset(http: TM1HttpClient, id: string | undefined, opts?: RequestOptions): Promise<void>;
+interface RawCellsetResponse {
+    Cells: Array<{
+        Value: CellValue;
+        FormattedValue: string;
+    }>;
+    Axes: Array<{
+        Tuples: Array<{
+            Members: Array<{
+                Name: string;
+                Hierarchy: {
+                    Name: string;
+                };
+            }>;
+        }>;
+    }>;
+}
+export declare function clipAxesToWindow(axes: MdxAxis[], cellCount: number, skip: number): {
+    axes: MdxAxis[];
+    clipped: boolean;
+};
+export declare function transformCellsetResponse(response: RawCellsetResponse): MdxResult;
+export {};
+//# sourceMappingURL=cellset-transform.d.ts.map

package/dist/tm1-client/services/cellset-transform.js

@@ -0,0 +1,80 @@
+// TM1 escaping: `]` inside a bracketed identifier is doubled. Cellset IDs are
+// server-generated GUIDs so this is defensive, but keeps the pattern uniform.
+function encId(id) {
+    return id.replace(/]/g, "]]");
+}
+// Best-effort DELETE of a read-path cellset. Cellsets are session-scoped and
+// never auto-expire while keep-alive holds the session open, so a read that
+// leaves one behind leaks TM1 server memory indefinitely (mirrors TM1py's
+// delete_cellset). Never throws: cleanup failure must not turn a successful
+// read into an error.
+export async function freeCellset(http, id, opts) {
+    if (!id)
+        return;
+    try {
+        await http.request("DELETE", `/api/v1/Cellsets('${encId(id)}')`, undefined, opts);
+    }
+    catch {
+        // cleanup best-effort
+    }
+}
+// Clip each axis to just the tuples the returned cell window actually
+// addresses, so a paginated read over a huge view doesn't ship the whole
+// (e.g. 200k-row) tuple list alongside its capped cells.
+//
+// TM1 orders cells so axis 0 varies fastest: cell ordinal `ord` decomposes as
+// idx_k = floor(ord / stride_k) mod L_k, stride_0 = 1, stride_k = product of
+// lower axis lengths. The returned cells span the contiguous ordinal range
+// [skip, skip+count). An axis is safe to shrink to `maxIdx+1` tuples ONLY when
+// its quotient never wraps past its length within that range
+// (qmax = floor(maxOrd/stride) < L) — that holds exactly for the slowest
+// partially-referenced axis and every axis above it, never for a fully-cycled
+// fast axis whose stride the higher axes decode through. Because those fast
+// axes stay at full length, stride_k is preserved for every clipped axis and
+// the consumer's positional decode (offset+i over the returned tuple counts)
+// stays valid; axes above the pivot collapse to a single tuple (idx always 0,
+// decoded via `mod 1`). totalCellCount is computed from the FULL axes, so the
+// caller still sees the true cell total.
+export function clipAxesToWindow(axes, cellCount, skip) {
+    if (axes.length === 0 || cellCount === 0)
+        return { axes, clipped: false };
+    const maxOrd = skip + cellCount - 1;
+    let stride = 1;
+    let clipped = false;
+    const out = axes.map((axis) => {
+        const len = axis.tuples.length;
+        const qmax = len > 0 ? Math.floor(maxOrd / stride) : 0;
+        stride *= len; // next axis's stride uses this axis's ORIGINAL length
+        if (len > 0 && qmax < len) {
+            const keep = qmax + 1;
+            if (keep < len) {
+                clipped = true;
+                return { tuples: axis.tuples.slice(0, keep) };
+            }
+        }
+        return axis;
+    });
+    return { axes: out, clipped };
+}
+export function transformCellsetResponse(response) {
+    const cells = (response.Cells ?? []).map((c) => ({
+        value: c.Value,
+        formattedValue: c.FormattedValue,
+    }));
+    const axes = (response.Axes ?? []).map((axis) => ({
+        tuples: axis.Tuples.map((tuple) => ({
+            members: tuple.Members.map((m) => ({
+                name: m.Name,
+                hierarchyName: m.Hierarchy.Name,
+            })),
+        })),
+    }));
+    // totalCellCount: product of tuple counts across all axes, or cell count if
+    // no axes. Always the FULL count; axis clipping (clipAxesToWindow) is applied
+    // by the paginating tool layer, which keeps totalCellCount intact.
+    const totalCellCount = axes.length > 0
+        ? axes.reduce((acc, axis) => acc * axis.tuples.length, 1)
+        : cells.length;
+    return { cells, axes, totalCellCount };
+}
+//# sourceMappingURL=cellset-transform.js.map

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

@@ -0,0 +1,68 @@
+import type { Chore, ChoreCreate, ChoreResult } from "../../types.js";
+import type { RequestOptions, TM1HttpClient } from "../http.js";
+export declare class ChoreService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * Connection-scoped verdict on `tm1.ExecuteWithReturn` for chores: null until
+     * the first run has told us, then sticky. Only ever set to false by the
+     * proof described in `execute()` — never by a version guess.
+     */
+    private withReturnSupported;
+    /**
+     * List all chores with their tasks (process + parameters per step).
+     * GET /api/v1/Chores?$expand=Tasks($expand=Process($select=Name))
+     */
+    list(): Promise<Chore[]>;
+    /**
+     * Activate or deactivate a chore.
+     * PATCH /api/v1/Chores('{name}') with { Active: bool }
+     */
+    toggleActive(choreName: string, active: boolean): Promise<void>;
+    /**
+     * Execute a chore immediately (bypass its schedule), and report how it ended.
+     * opts.timeoutMs overrides the 30s default for chores that run long TI chains.
+     *
+     * Both actions here are SYNCHRONOUS — the POST returns when the chore is
+     * done, which is why the tool exposes a timeout ceiling of an hour. Using
+     * `tm1.ExecuteWithReturn` therefore costs no extra waiting; it only stops us
+     * throwing the status away.
+     *
+     * POST /api/v1/Chores('{name}')/tm1.ExecuteWithReturn?$expand=ErrorLogFile
+     *   — v12 12.5.0 and up. `$expand` is REQUIRED: ErrorLogFile is a navigation
+     *     property on ChoreExecuteResult, so without it the filename is silently
+     *     absent (the same trap as ProcessService.execute).
+     * POST /api/v1/Chores('{name}')/tm1.Execute
+     *   — everywhere else. Returns 204, so no status exists to report.
+     */
+    execute(choreName: string, opts?: RequestOptions): Promise<ChoreResult>;
+    /**
+     * The statusless path: run the chore, report that nothing is known about how
+     * it ended. Deliberately NOT `{success: true}` — that claim is what this
+     * whole change exists to remove.
+     */
+    private executeWithoutStatus;
+    /**
+     * Create a new chore.
+     * POST /api/v1/Chores
+     */
+    create(chore: ChoreCreate): Promise<void>;
+    /**
+     * Update an existing chore (partial update).
+     * PATCH /api/v1/Chores('{name}')
+     */
+    update(choreName: string, updates: {
+        startTime?: string | undefined;
+        active?: boolean | undefined;
+        dstSensitive?: boolean | undefined;
+        executionMode?: "SingleCommit" | "MultipleCommit" | undefined;
+        frequency?: ChoreCreate["frequency"] | undefined;
+        steps?: ChoreCreate["steps"] | undefined;
+    }): Promise<void>;
+    /**
+     * Delete a chore.
+     * DELETE /api/v1/Chores('{name}')
+     */
+    delete(choreName: string): Promise<void>;
+}
+//# sourceMappingURL=chore-service.d.ts.map