@ffschrattenecker/tm1-mcp-server 7.0.1 → 7.0.2

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.2] - 2026-09-27
+
+### Fixed
+
+- On servers with `EnableSandboxDimension=true`, `tm1_get_cell_value` and `tm1_check_writable_coords`
+  (without `dimensions`) accept a coordinate that leaves out `Sandboxes` and bind it to `Base`, as
+  `tm1_write_cells` already did. Before, they refused it as one element short.
+- `tm1_sample_cells` found no cells in any cube with a `Sandboxes` dimension: TM1's `NONEMPTY()`
+  returns an empty set whenever Sandboxes is part of the row set. An unfiltered Sandboxes is now
+  pinned to `Base` in WHERE.
+- Markdown tables (`format: "markdown"`) now escape backslashes, so a value ending in `\` no
+  longer breaks the table at the next `|`. In `tm1_execute_mdx`, raw cell values are no longer
+  escaped twice.
+
+### Changed
+
+- Dependencies: undici 8, dotenv 18, zod 4.6, and minor/patch bumps. Dev: vitest 5.
+
 ## [7.0.1] - 2026-09-27
 
 ### Fixed
@@ -1306,7 +1324,8 @@ Initial public release.
 - Quality gates: strict typecheck, ESLint, `lint:no-flat-api`,
   annotation-coverage, and tool-registration wiring.
 
-[Unreleased]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.1...HEAD
+[Unreleased]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.2...HEAD
+[7.0.2]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.1...v7.0.2
 [7.0.1]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v7.0.0...v7.0.1
 [7.0.0]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v6.1.1...v7.0.0
 [6.1.1]: https://github.com/ffschrattenecker/tm1-mcp-server/compare/v6.1.0...v6.1.1

package/dist/lib/cell-address.d.ts

@@ -1,5 +1,15 @@
 export declare const SANDBOX_DIMENSION = "Sandboxes";
 export declare const BASE_SANDBOX = "Base";
+/** Index of the cube's `Sandboxes` dimension, or -1. */
+export declare function sandboxPosition(cubeDimensions: readonly string[]): number;
+/**
+ * Positional counterpart of resolveCellAddress, for tools that take one
+ * element per cube dimension (get_cell_value, check_writable_coords without
+ * `dimensions`). A coordinate exactly one short on a cube with `Sandboxes`
+ * is read as "Sandboxes left out" and gets `Base` at its position; anything
+ * else returns undefined and the caller's count check refuses it as before.
+ */
+export declare function bindLeftOutSandbox(cubeDimensions: readonly string[], elements: readonly string[]): string[] | undefined;
 export interface ResolvedAddress {
     /** The cube's dimensions, in cube order. */
     dimensions: string[];

package/dist/lib/cell-address.js

@@ -20,6 +20,25 @@
 import { TM1Error, TM1ErrorCode } from "../types.js";
 export const SANDBOX_DIMENSION = "Sandboxes";
 export const BASE_SANDBOX = "Base";
+/** Index of the cube's `Sandboxes` dimension, or -1. */
+export function sandboxPosition(cubeDimensions) {
+    return cubeDimensions.findIndex((d) => d.toLowerCase() === SANDBOX_DIMENSION.toLowerCase());
+}
+/**
+ * Positional counterpart of resolveCellAddress, for tools that take one
+ * element per cube dimension (get_cell_value, check_writable_coords without
+ * `dimensions`). A coordinate exactly one short on a cube with `Sandboxes`
+ * is read as "Sandboxes left out" and gets `Base` at its position; anything
+ * else returns undefined and the caller's count check refuses it as before.
+ */
+export function bindLeftOutSandbox(cubeDimensions, elements) {
+    if (elements.length !== cubeDimensions.length - 1)
+        return undefined;
+    const pos = sandboxPosition(cubeDimensions);
+    if (pos < 0)
+        return undefined;
+    return [...elements.slice(0, pos), BASE_SANDBOX, ...elements.slice(pos)];
+}
 export function resolveCellAddress(cubeName, cubeDimensions, given) {
     const byLower = new Map(cubeDimensions.map((d, i) => [d.toLowerCase(), i]));
     const positions = [];
@@ -37,7 +56,7 @@ export function resolveCellAddress(cubeName, cubeDimensions, given) {
         positions.push(pos ?? -1);
     }
     const missing = cubeDimensions.filter((_, i) => !seen.has(i));
-    const sandboxPos = cubeDimensions.findIndex((d) => d.toLowerCase() === SANDBOX_DIMENSION.toLowerCase());
+    const sandboxPos = sandboxPosition(cubeDimensions);
     const onlySandboxMissing = missing.length === 1 && sandboxPos >= 0 && !seen.has(sandboxPos);
     const problems = [];
     if (unknown.length > 0)

package/dist/lib/coordinate-error.js

@@ -9,6 +9,7 @@
 // cube's dimension order, names the uncovered positions, and `details` pairs
 // every dimension with the element that landed on it.
 import { TM1Error, TM1ErrorCode } from "../types.js";
+import { BASE_SANDBOX, SANDBOX_DIMENSION, sandboxPosition, } from "./cell-address.js";
 export function dimensionCountMismatch(cubeName, dimensions, elements) {
     const missing = dimensions.slice(elements.length);
     const extra = elements.slice(dimensions.length);
@@ -19,7 +20,10 @@ export function dimensionCountMismatch(cubeName, dimensions, elements) {
         code: TM1ErrorCode.VALIDATION_ERROR,
         message: `Cube '${cubeName}' has ${dimensions.length} dimensions but ${elements.length} element(s) were given.` +
             gap,
-        hint: `Pass exactly one element per dimension, in this order: ${dimensions.join(", ")}. A forgotten dimension anywhere in the list shifts every later element onto the wrong one — check the pairing in details.`,
+        hint: `Pass exactly one element per dimension, in this order: ${dimensions.join(", ")}. A forgotten dimension anywhere in the list shifts every later element onto the wrong one — check the pairing in details.` +
+            (sandboxPosition(dimensions) >= 0
+                ? ` Only ${SANDBOX_DIMENSION} may be left out; it is then bound to ${BASE_SANDBOX}.`
+                : ""),
         details: JSON.stringify(dimensions.map((dimension, i) => ({
             dimension,
             element: elements[i] ?? null,

package/dist/lib/sample-cells.d.ts

@@ -1,4 +1,5 @@
 import type { MdxResult, CellValue } from "../types.js";
+import { BASE_SANDBOX } from "./cell-address.js";
 export type SampleCellFilter = string | string[];
 export interface SampleCellsBuildArgs {
     cubeName: string;
@@ -29,6 +30,11 @@ export interface SampleCellsBuildResult {
     rowDims: string[];
     /** Dimension placed on COLUMNS. */
     columnDim: string;
+    /** Set when an unfiltered `Sandboxes` was pinned to `Base` in WHERE. */
+    sandboxPin?: {
+        dimension: string;
+        element: typeof BASE_SANDBOX;
+    };
 }
 export interface SampleCell {
     coordinates: Record<string, string>;

package/dist/lib/sample-cells.js

@@ -2,6 +2,7 @@
 // No I/O — kept pure for unit-testability.
 import { TM1Error, TM1ErrorCode } from "../types.js";
 import { escapeMdxName } from "./mdx.js";
+import { BASE_SANDBOX, SANDBOX_DIMENSION } from "./cell-address.js";
 const memberRef = (dim, elem) => {
     // Pre-qualified pass-through (e.g. caller passes "[Dim].[Elem]").
     if (elem.startsWith("[") && elem.includes("].["))
@@ -36,10 +37,21 @@ export function buildSampleCellsMdx(args) {
     const whereParts = [];
     const rowDims = [];
     const rowSets = [];
+    // An unfiltered Sandboxes is pinned to Base instead of crossjoined: TM1's
+    // NONEMPTY() returns an empty set whenever Sandboxes is part of the row set,
+    // even as {[Sandboxes].[Base]} alone, so every sample of a sandboxed cube
+    // came back empty. Measured on plapp-franz (EnableSandboxDimension=true).
+    // Base is also what every other read through this server sees.
+    let sandboxPin;
     for (const dim of dimensions) {
         if (dim === columnDim)
             continue;
-        const f = filters[dim];
+        let f = filters[dim];
+        if (f === undefined &&
+            dim.toLowerCase() === SANDBOX_DIMENSION.toLowerCase()) {
+            f = BASE_SANDBOX;
+            sandboxPin = { dimension: dim, element: BASE_SANDBOX };
+        }
         if (typeof f === "string") {
             whereDims.push(dim);
             whereParts.push(memberRef(dim, f));
@@ -103,7 +115,13 @@ export function buildSampleCellsMdx(args) {
     }
     const whereClause = whereParts.length > 0 ? ` WHERE (${whereParts.join(",")})` : "";
     const mdx = `SELECT ${columnSet} ON COLUMNS, ${rowAxisExpr} ON ROWS FROM [${escapeMdxName(cubeName)}]${whereClause}`;
-    return { mdx, whereDims, rowDims, columnDim };
+    return {
+        mdx,
+        whereDims,
+        rowDims,
+        columnDim,
+        ...(sandboxPin ? { sandboxPin } : {}),
+    };
 }
 /**
  * Convert flat MdxResult cells into self-describing {coordinates,value,formattedValue}.

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

@@ -7,6 +7,7 @@
 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 { 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, "''"));
@@ -44,6 +45,8 @@ export class CellService {
         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);
+        // Sandboxes left out → Base, as tm1_write_cells does.
+        elements = bindLeftOutSandbox(dims, elements) ?? elements;
         if (elements.length !== dims.length) {
             throw dimensionCountMismatch(cubeName, dims, elements);
         }

package/dist/tools/celldata/check-writable-coords.js

@@ -5,7 +5,7 @@ import { READ_ONLY } from "../annotations.js";
 import { WritableCoordsResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
 import { dimensionCountMismatch } from "../../lib/coordinate-error.js";
-import { resolveCellAddress } from "../../lib/cell-address.js";
+import { bindLeftOutSandbox, resolveCellAddress, } from "../../lib/cell-address.js";
 export const registerCheckWritableCoords = defineTool({
     name: "tm1_check_writable_coords",
     description: "Pre-flight check before CellPutN/CellPutS. Verifies (1) every coord element exists, (2) every element is N-Level (writes to Consolidated elements silent-fail), and (3) whether the target cube has rules that may overlap the coord. Returns per-coord status + a rule-overlap warning. Use before writing cells in a TI process or via tm1_write_cells; pass the same dimensions list as the write to check exactly the cell it will address.",
@@ -15,7 +15,7 @@ export const registerCheckWritableCoords = defineTool({
         cubeName: z.string().describe("Target cube name"),
         coords: z
             .array(z.string())
-            .describe("Element name per dimension: in cube dimension order, or in the order of dimensions when given."),
+            .describe("Element name per dimension: in cube dimension order, or in the order of dimensions when given. Sandboxes may be left out (bound to Base)."),
         dimensions: z
             .array(z.string())
             .optional()
@@ -41,8 +41,15 @@ export const registerCheckWritableCoords = defineTool({
             coords = address.toCubeOrder(given);
             sandboxDefaulted = address.sandboxDefaulted;
         }
-        else if (coords.length !== dims.length) {
-            throw dimensionCountMismatch(cubeName, dims, coords);
+        else {
+            const bound = bindLeftOutSandbox(dims, coords);
+            if (bound) {
+                coords = bound;
+                sandboxDefaulted = "Base";
+            }
+            else if (coords.length !== dims.length) {
+                throw dimensionCountMismatch(cubeName, dims, coords);
+            }
         }
         const checks = await Promise.all(dims.map(async (dim, idx) => {
             // coords.length === dims.length is guarded above

package/dist/tools/celldata/execute-mdx.js

@@ -1,19 +1,14 @@
 import { z } from "zod";
 import { PAGINATION_SCHEMA } from "../pagination.js";
-import { FORMAT_SCHEMA, payloadResponse } from "../format.js";
+import { FORMAT_SCHEMA, mdEscape, payloadResponse } from "../format.js";
 import { withToolHint } from "../error-format.js";
 import { clipAxesToWindow } from "../../tm1-client/services/cellset-transform.js";
 import { MdxResultSchema } from "../schemas/items.js";
 import { READ_ONLY } from "../annotations.js";
 import { defineTool } from "../define-tool.js";
-function mdCell(v) {
-    if (v === null || v === undefined)
-        return "";
-    return String(v).replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
 const tupleLabel = (tuple) => tuple.members.map((m) => m.name).join(" / ");
 const axisHeader = (axis) => axis.tuples[0]?.members.map((m) => m.hierarchyName).join(" / ") || "Axis";
-const cellText = (c) => c.formattedValue !== "" ? c.formattedValue : mdCell(c.value);
+const cellText = (c) => c.formattedValue !== "" ? c.formattedValue : (c.value ?? "").toString();
 // Render an MDX cellset envelope as Markdown.
 //
 // Pivot grid when axis[0] (ON COLUMNS) and axis[1] (ON ROWS) drive the result
@@ -45,30 +40,30 @@ export function renderMdxMarkdown(env) {
         const rows = axes[1].tuples;
         const colCount = cols.length;
         const context = contextAxes
-            .map((ax) => mdCell(tupleLabel(ax.tuples[0])))
+            .map((ax) => mdEscape(tupleLabel(ax.tuples[0])))
             .filter((s) => s.length > 0)
             .join(" · ");
         const head = context ? [meta, "", `**Context:** ${context}`] : [meta];
-        const header = `| ${mdCell(axisHeader(axes[1]))} | ${cols.map((t) => mdCell(tupleLabel(t))).join(" | ")} |`;
+        const header = `| ${mdEscape(axisHeader(axes[1]))} | ${cols.map((t) => mdEscape(tupleLabel(t))).join(" | ")} |`;
         const sep = `| ${["---", ...cols.map(() => "---")].join(" | ")} |`;
         const body = rows.map((rt, r) => {
-            const vals = cols.map((_, c) => mdCell(cellText(items[r * colCount + c])));
-            return `| ${mdCell(tupleLabel(rt))} | ${vals.join(" | ")} |`;
+            const vals = cols.map((_, c) => mdEscape(cellText(items[r * colCount + c])));
+            return `| ${mdEscape(tupleLabel(rt))} | ${vals.join(" | ")} |`;
         });
         return [...head, "", header, sep, ...body].join("\n");
     }
     // Flat fallback: decode each cell's coordinate from its global ordinal.
     const radices = axes.map((a) => a.tuples.length);
-    const header = `| ${[...axes.map((a) => mdCell(axisHeader(a))), "Value"].join(" | ")} |`;
+    const header = `| ${[...axes.map((a) => mdEscape(axisHeader(a))), "Value"].join(" | ")} |`;
     const sep = `| ${[...axes.map(() => "---"), "---"].join(" | ")} |`;
     const body = items.map((cell, i) => {
         let ord = offset + i;
         const coords = radices.map((n, k) => {
             const idx = ord % n;
             ord = Math.floor(ord / n);
-            return mdCell(tupleLabel(axes[k].tuples[idx]));
+            return mdEscape(tupleLabel(axes[k].tuples[idx]));
         });
-        return `| ${[...coords, mdCell(cellText(cell))].join(" | ")} |`;
+        return `| ${[...coords, mdEscape(cellText(cell))].join(" | ")} |`;
     });
     return [meta, "", header, sep, ...body].join("\n");
 }

package/dist/tools/celldata/get-cell-value.js

@@ -18,7 +18,7 @@ export const registerGetCellValue = defineTool({
         cubeName: z.string().describe("Name of the TM1 cube"),
         elements: z
             .array(z.string())
-            .describe("Element names for each dimension of the cube"),
+            .describe("One element per cube dimension, in cube order. Sandboxes may be left out (bound to Base)."),
     },
     handler: async ({ cubeName, elements }, tm1Client) => {
         const value = await tm1Client.cells.getValue(cubeName, elements);

package/dist/tools/celldata/sample-cells.js

@@ -71,6 +71,9 @@ export const registerSampleCells = defineTool({
                     whereCoords[dim] = val;
             }
         }
+        if (built.sandboxPin) {
+            whereCoords[built.sandboxPin.dimension] = built.sandboxPin.element;
+        }
         const sampled = transformSampleCells({ result, whereCoords });
         const truncated = requested > 0 && sampled.length > requested;
         const cells = truncated ? sampled.slice(0, requested) : sampled;

package/dist/tools/format.d.ts

@@ -31,6 +31,7 @@ export type ColumnSpec<T> = (keyof T & string) | Column<T>;
  * untouched, so the plain field name renders identically.
  */
 export declare function columnsOf<T>(specs: readonly ColumnSpec<T>[]): Column<T>[];
+export declare function mdEscape(v: unknown): string;
 export declare function renderKV(obj: Record<string, unknown>, title?: string): string;
 export declare function renderTable<T>(rows: readonly T[], columns: Column<T>[]): string;
 export interface PageRenderOpts<T> {

package/dist/tools/format.js

@@ -38,7 +38,7 @@ export function columnsOf(specs) {
         ? { header: spec, get: (row) => row[spec] }
         : spec);
 }
-function mdEscape(v) {
+export function mdEscape(v) {
     if (v === null || v === undefined)
         return "";
     const s = typeof v === "string"
@@ -48,7 +48,12 @@ function mdEscape(v) {
             : typeof v === "object"
                 ? JSON.stringify(v)
                 : String(v);
-    return s.replace(/\|/g, "\\|").replace(/\n/g, " ").replace(/\r/g, "");
+    // Backslashes first, so an escaped pipe can't be undone by a preceding `\`.
+    return s
+        .replace(/\\/g, "\\\\")
+        .replace(/\|/g, "\\|")
+        .replace(/\n/g, " ")
+        .replace(/\r/g, "");
 }
 // Render an object as a 2-column key/value Markdown table.
 // Nested objects become indented sub-tables; scalars stringify directly.