@ffschrattenecker/tm1-mcp-server 7.0.2 → 8.0.0

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

@@ -1,9 +1,11 @@
 import { z } from "zod";
+import { TM1Error } from "../../types.js";
 import { actionResponse } from "../format.js";
 import { CONFIRM_SCHEMA, requireConfirm } from "../confirm.js";
 import { DESTRUCTIVE } from "../annotations.js";
 import { MutationResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
+import { memberRef } from "./member-ref.js";
 import { dimensionCountMismatch } from "../../lib/coordinate-error.js";
 import { resolveCellAddress } from "../../lib/cell-address.js";
 const READ_BACK_LIMIT = 20;
@@ -17,8 +19,8 @@ export const registerWriteCells = defineTool({
     description: [
         "Write one or more cell values directly to a TM1 cube via REST.",
         "IMPORTANT: TI processes are the standard path for data loads — use this tool only for ad-hoc writes or when explicitly requested.",
-        "Writes to consolidated cells are rejected by TM1.",
-        "Every cube dimension must be named (any order) — a dimension left out would land on its default member, so the call is refused. Only Sandboxes may be left out: it is bound to Base and echoed as sandboxDefaulted. A named sandbox is addressable only once its IncludeInSandboxDimension is true.",
+        "Leaf (N-level) coordinates only. Every coordinate is checked before anything is sent and a consolidated one aborts the whole call: writing to a C element is not how TM1 data is loaded, and whether the server would even accept it depends on the account's rights. Aggregate values come from the consolidation, not from a write.",
+        "Name every cube dimension, in any order: a dimension left out would land on its default member, so the call is refused. Only Sandboxes may be left out; it is then bound to Base and reported as sandboxDefaulted. A named sandbox is addressable only once its IncludeInSandboxDimension is true.",
         "Before: tm1_check_writable_coords to validate that target coordinates are leaf-level and addressable.",
         "The written cells are read back (up to 20; verified.mismatches lists any that differ, e.g. a rule or spread overriding the value), so no separate tm1_get_cell_value is needed.",
         "Related: tm1_clear_cube for bulk wipe, tm1_execute_process for production data loads.",
@@ -44,29 +46,77 @@ export const registerWriteCells = defineTool({
             .describe("Cells to write"),
         ...CONFIRM_SCHEMA,
     },
-    handler: async ({ cubeName, dimensions, cells, confirm }, tm1Client) => {
+    handler: async ({ cubeName, dimensions: given, cells: givenCells, confirm }, tm1Client) => {
         // Overwrites prior cell values with no undo. Guards against an
         // auto-approve client firing this without intent — NOT a security
         // control: anything that can call the tool can also supply `confirm`.
         requireConfirm(confirm, cubeName, "cube");
+        for (const c of givenCells) {
+            if (c.elements.length !== given.length) {
+                throw dimensionCountMismatch(cubeName, given, c.elements);
+            }
+        }
+        // Everything below works in cube order over the cube's full dimension
+        // list, so a dimension the caller forgot can never reach the MDX tuple.
+        const address = resolveCellAddress(cubeName, await tm1Client.cubes.getDimensionNames(cubeName), given);
+        const dimensions = address.dimensions;
+        const cells = givenCells.map((c) => ({
+            ...c,
+            elements: address.toCubeOrder(c.elements),
+        }));
+        // One probe per distinct hierarchy, not per cell: a write typically
+        // reuses the same handful of elements across many coordinates.
+        const byHierarchy = new Map();
         for (const c of cells) {
-            if (c.elements.length !== dimensions.length) {
-                throw dimensionCountMismatch(cubeName, dimensions, c.elements);
+            c.elements.forEach((e, idx) => {
+                const ref = memberRef(dimensions[idx], e);
+                const key = `${ref.dimension}\u0000${ref.hierarchy}`;
+                const entry = byHierarchy.get(key) ?? {
+                    dimension: ref.dimension,
+                    hierarchy: ref.hierarchy,
+                    names: new Set(),
+                };
+                entry.names.add(ref.element);
+                byHierarchy.set(key, entry);
+            });
+        }
+        const consolidated = [];
+        for (const { dimension, hierarchy, names } of byHierarchy.values()) {
+            try {
+                const hits = await tm1Client.elements.consolidatedAmong(dimension, hierarchy, [...names]);
+                for (const hit of hits)
+                    consolidated.push(`${dimension}:${hit}`);
             }
+            catch (e) {
+                // Fail closed. A probe that did not answer is not evidence that the
+                // coordinates are leaves, and the tool promises every coordinate is
+                // checked before anything is sent — so an unanswered probe stops the
+                // write instead of reading as "no consolidations found".
+                throw new TM1Error({
+                    code: e instanceof TM1Error ? e.code : "TM1_ERROR",
+                    message: `Could not check the elements of ${dimension}:${hierarchy} for consolidations: ${e instanceof Error ? e.message : String(e)}. Nothing was sent.`,
+                    hint: "Verify the dimension and hierarchy names — in `dimensions` and in any qualified element reference — then retry. Use tm1_check_writable_coords to inspect the coordinates first.",
+                    ...(e instanceof TM1Error && e.httpStatus !== undefined
+                        ? { httpStatus: e.httpStatus }
+                        : {}),
+                });
+            }
+        }
+        if (consolidated.length > 0) {
+            throw new TM1Error({
+                code: "VALIDATION_ERROR",
+                message: `Consolidated coordinates in this write: ${consolidated.join(", ")}. Nothing was sent.`,
+                hint: "Write to N-level (leaf) elements instead — tm1_check_writable_coords reports the level of every coordinate. There is no override: an aggregate is computed from the leaves below it, so load those, or run a TI process via tm1_execute_process.",
+            });
         }
         // writeCells throws a TM1Error carrying its own partial-commit accounting
         // (written / failed / notAttempted) + a targeted hint, so we let it
         // propagate to the index.ts Proxy unwrapped — wrapping it here would
         // clobber that hint with a generic one.
-        const address = resolveCellAddress(cubeName, await tm1Client.cubes.getDimensionNames(cubeName), dimensions);
-        const ordered = cells.map((c) => ({
-            ...c,
-            elements: address.toCubeOrder(c.elements),
-        }));
-        await tm1Client.cells.writeCells(cubeName, address.dimensions, ordered);
+        await tm1Client.cells.writeCells(cubeName, dimensions, cells);
         // Read back a bounded sample: each read is its own MDX round trip. The
         // write has landed by now, so a failed read-back is reported, not thrown.
-        const sample = ordered.slice(0, READ_BACK_LIMIT);
+        const sample = cells.slice(0, READ_BACK_LIMIT);
         let verified;
         try {
             const readBack = await Promise.all(sample.map((c) => tm1Client.cells.getValue(cubeName, c.elements)));

package/dist/tools/dimension-management/create-element-attribute.js

@@ -6,7 +6,7 @@ import { defineTool } from "../define-tool.js";
 import { HIERARCHY_NAME_OPTIONAL, resolveHierarchy } from "../hierarchy.js";
 export const registerCreateElementAttribute = defineTool({
     name: "tm1_create_element_attribute",
-    description: "Create an element attribute definition (schema) on a TM1 hierarchy. For reproducible deployments prefer a TI process (DimensionElementInsert on the }ElementAttributes_{dim} control cube). Use this tool for ad-hoc / debugging scenarios or when explicitly requested.",
+    description: "Create an element attribute definition (schema) on a TM1 dimension. Attributes are dimension-wide: created through any hierarchy, the attribute exists on all of them. For reproducible deployments prefer a TI process (DimensionElementInsert on the }ElementAttributes_{dim} control cube). Use this tool for ad-hoc / debugging scenarios or when explicitly requested.",
     annotations: WRITE,
     output: MutationResultSchema,
     input: {

package/dist/tools/dimension-management/delete-hierarchy.js

@@ -5,11 +5,10 @@ import { DESTRUCTIVE } from "../annotations.js";
 import { MutationResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
 import { TM1Error, TM1ErrorCode } from "../../types.js";
-// TM1 names ignore case and spaces.
-const norm = (s) => s.toLowerCase().replace(/ /g, "");
+import { tm1NameEquals } from "../../lib/tm1-name.js";
 export const registerDeleteHierarchy = defineTool({
     name: "tm1_delete_hierarchy",
-    description: "Delete a hierarchy from a dimension. The default (dimension-named) hierarchy cannot be deleted — use tm1_delete_dimension for that. Irreversible — pass confirm=<hierarchy name verbatim>.",
+    description: "Delete a hierarchy from a dimension. Irreversible — pass confirm=<hierarchy name verbatim>. Deleting the same-named (default) hierarchy is allowed. The tools of this server still default an omitted hierarchyName to the dimension name, so after such a delete pass hierarchyName on every call.",
     annotations: DESTRUCTIVE,
     output: MutationResultSchema,
     input: {
@@ -21,7 +20,7 @@ export const registerDeleteHierarchy = defineTool({
         requireConfirm(confirm, hierarchyName, "hierarchy");
         // TM1 does NOT refuse this itself: 11.8 answers 204 and leaves a dimension
         // listed with no hierarchies at all (verified live). Refuse it here.
-        if (norm(hierarchyName) === norm(dimensionName)) {
+        if (tm1NameEquals(hierarchyName, dimensionName)) {
             throw new TM1Error({
                 code: TM1ErrorCode.VALIDATION_ERROR,
                 message: `'${hierarchyName}' is the default hierarchy of '${dimensionName}' and cannot be deleted on its own.`,

package/dist/tools/dimension-management/get-element-attribute-values.js

@@ -19,6 +19,7 @@ export const registerGetElementAttributeValues = defineTool({
     description: [
         "Read attribute values (Numeric/String/Alias) via MDX on the }ElementAttributes_{Dim} control cube. Use this to verify alias values, attribute lookups, or to debug rules referencing ATTRN/ATTRS.",
         "With elementName: that element's attributes. Without: every element of the dimension, name-sorted and paged (items[{elementName, values}]); narrow the columns with attributeNames.",
+        "Attribute definitions are dimension-wide. A leaf (N) element has one set of values across all hierarchies, but a consolidated (C) element has its own values per hierarchy, so pass hierarchyName for a consolidation or any element of an alternate hierarchy.",
     ],
     annotations: READ_ONLY,
     output: {
@@ -38,6 +39,10 @@ export const registerGetElementAttributeValues = defineTool({
             .string()
             .optional()
             .describe("Element whose attribute values should be read. Omit to page through all elements."),
+        hierarchyName: z
+            .string()
+            .optional()
+            .describe("Hierarchy of the element (default: the same-named one). Single-element mode only."),
         attributeNames: z
             .array(z.string())
             .optional()
@@ -45,7 +50,7 @@ export const registerGetElementAttributeValues = defineTool({
         ...PAGINATION_SCHEMA,
         ...FORMAT_SCHEMA,
     },
-    handler: async ({ dimensionName, elementName, attributeNames, limit, offset, fetchAll, format, }, tm1Client) => {
+    handler: async ({ dimensionName, elementName, hierarchyName, attributeNames, limit, offset, fetchAll, format, }, tm1Client) => {
         if (elementName === undefined) {
             const unbounded = fetchAll || limit === 0;
             const start = unbounded ? 0 : offset;
@@ -65,7 +70,7 @@ export const registerGetElementAttributeValues = defineTool({
             ]);
             return payloadResponse(payload, format, (p) => `## Attributes of ${p.dimensionName} (${p.offset + 1}–${p.offset + p.count} of ${p.total})\n\n${renderTable(p.items, columns)}`);
         }
-        const values = await tm1Client.elements.getAttributeValues(dimensionName, elementName);
+        const values = await tm1Client.elements.getAttributeValues(dimensionName, elementName, hierarchyName);
         const payload = { dimensionName, elementName, attributes: values };
         const columns = columnsOf([
             { header: "attribute", get: (a) => a.attributeName },

package/dist/tools/dimension-management/list-element-attributes.js

@@ -8,7 +8,7 @@ import { HIERARCHY_NAME_OPTIONAL, resolveHierarchy } from "../hierarchy.js";
 import { pageShapeFor } from "../schemas/common.js";
 export const registerListElementAttributes = defineTool({
     name: "tm1_list_element_attributes",
-    description: "List element attribute definitions of a TM1 hierarchy with their types (Numeric/String/Alias). Useful to verify attribute schema before writing values or referencing them in rules (ATTRN/ATTRS).",
+    description: "List element attribute definitions of a TM1 dimension with their types (Numeric/String/Alias); every hierarchy returns the same dimension-wide list. Useful to verify attribute schema before writing values or referencing them in rules (ATTRN/ATTRS).",
     annotations: READ_ONLY,
     output: pageShapeFor(ElementAttributeDefinitionSchema),
     input: {

package/dist/tools/dimension-management/update-element-attribute-value.js

@@ -13,6 +13,7 @@ export const registerUpdateElementAttributeValue = defineTool({
     description: [
         "Set attribute values on elements by writing to the }ElementAttributes_{Dim} control cube.",
         "One value (elementName + attributeName + value) or many in a single write (updates[]). Values are strings, coerced server-side for Numeric attributes.",
+        "Pass hierarchyName for an element of an alternate hierarchy. A leaf's value is shared by every hierarchy of the dimension; a consolidation's value is set for that hierarchy only.",
         "For reproducible deployments prefer a TI process (AttrPutS / AttrPutN); this REST-direct tool is for ad-hoc / debugging scenarios.",
     ],
     annotations: IDEMPOTENT_WRITE,
@@ -23,6 +24,10 @@ export const registerUpdateElementAttributeValue = defineTool({
             .string()
             .optional()
             .describe("Element whose attribute value should be set"),
+        hierarchyName: z
+            .string()
+            .optional()
+            .describe("Hierarchy of the element(s) (default: the same-named one)."),
         attributeName: z
             .string()
             .optional()
@@ -41,7 +46,7 @@ export const registerUpdateElementAttributeValue = defineTool({
             .optional()
             .describe("Batch form: many {elementName, attributeName, value} in one cellset write. Replaces elementName/attributeName/value."),
     },
-    handler: async ({ dimensionName, elementName, attributeName, value, updates }, tm1Client) => {
+    handler: async ({ dimensionName, elementName, hierarchyName, attributeName, value, updates, }, tm1Client) => {
         const single = elementName !== undefined ||
             attributeName !== undefined ||
             value !== undefined;
@@ -52,7 +57,7 @@ export const registerUpdateElementAttributeValue = defineTool({
             });
         }
         if (updates !== undefined) {
-            await tm1Client.elements.updateAttributeValues(dimensionName, updates);
+            await tm1Client.elements.updateAttributeValues(dimensionName, updates, hierarchyName);
             return actionResponse({
                 success: true,
                 dimensionName,
@@ -67,7 +72,7 @@ export const registerUpdateElementAttributeValue = defineTool({
                 message: "elementName, attributeName and value are all required (or pass updates[]).",
             });
         }
-        await tm1Client.elements.updateAttributeValue(dimensionName, elementName, attributeName, value);
+        await tm1Client.elements.updateAttributeValue(dimensionName, elementName, attributeName, value, hierarchyName);
         return actionResponse({
             success: true,
             dimensionName,

package/dist/tools/dimension-management/update-element.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { actionResponse } from "../format.js";
-import { IDEMPOTENT_WRITE } from "../annotations.js";
+import { IDEMPOTENT_DESTRUCTIVE } from "../annotations.js";
 import { MutationResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
 import { HIERARCHY_NAME_OPTIONAL, resolveHierarchy } from "../hierarchy.js";
@@ -9,16 +9,16 @@ const updateSchema = z.object({
     type: z
         .enum(["Numeric", "String", "Consolidated"])
         .optional()
-        .describe("New element type"),
+        .describe("New element type, changed in place. Numeric to Consolidated/String discards the element's leaf cell values; the result reports it as typeChange."),
     components: z
         .array(z.object({ name: z.string(), weight: z.number() }))
         .optional()
-        .describe("New child components for consolidated elements"),
+        .describe("Replaces the element's complete child list: children not listed are removed from this parent (they stay in the dimension with their data). [] removes all children. To move an element between parents, update both parents."),
 });
 export const registerUpdateElement = defineTool({
     name: "tm1_update_element",
-    description: "Update an existing element in a TM1 dimension hierarchy (name, type, or components)",
-    annotations: IDEMPOTENT_WRITE,
+    description: "Update an existing element in a TM1 dimension hierarchy (name, type, or components). components replaces the whole child list, it does not append.",
+    annotations: IDEMPOTENT_DESTRUCTIVE,
     output: MutationResultSchema,
     input: {
         dimensionName: z.string().describe("Name of the dimension"),
@@ -28,8 +28,15 @@ export const registerUpdateElement = defineTool({
     },
     handler: async ({ dimensionName, hierarchyName, elementName, update }, tm1Client) => {
         const hierarchy = resolveHierarchy(dimensionName, hierarchyName);
-        await tm1Client.elements.update(dimensionName, hierarchy, elementName, update);
-        return actionResponse({ success: true, elementName });
+        const { typeChange } = await tm1Client.elements.update(dimensionName, hierarchy, elementName, update);
+        return actionResponse({
+            success: true,
+            elementName,
+            ...(typeChange && {
+                typeChange,
+                warning: `Type changed in place from ${typeChange.from} to ${typeChange.to}; any existing leaf cell values for this element were discarded.`,
+            }),
+        });
     },
 });
 //# sourceMappingURL=update-element.js.map

package/dist/tools/fileops/container.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const CONTAINER_SCHEMA: {
+    container: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        files: "files";
+        applications: "applications";
+    }>>>;
+};
+//# sourceMappingURL=container.d.ts.map

package/dist/tools/fileops/container.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+// Which storage tree the file tools address. Shared by all five so the wording
+// a model reads is identical everywhere.
+export const CONTAINER_SCHEMA = {
+    container: z
+        .enum(["files", "applications"])
+        .optional()
+        .default("files")
+        .describe("'files' (default): the TI data directory (Files on v12, Blobs on v11). 'applications': the Applications tree of Architect/PAW; nests on both versions, only its documents carry content."),
+};
+//# sourceMappingURL=container.js.map

package/dist/tools/fileops/delete-file.js

@@ -5,6 +5,7 @@ import { actionResponse } from "../format.js";
 import { DESTRUCTIVE } from "../annotations.js";
 import { MutationResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
+import { CONTAINER_SCHEMA } from "./container.js";
 export const registerDeleteFile = defineTool({
     name: "tm1_delete_file",
     description: [
@@ -21,11 +22,12 @@ export const registerDeleteFile = defineTool({
             .string()
             .min(1)
             .describe("File name or path (e.g. 'data.csv' or 'imports/old.csv')."),
+        ...CONTAINER_SCHEMA,
         ...CONFIRM_SCHEMA,
     },
-    handler: async ({ fileName, confirm }, tm1Client) => {
+    handler: async ({ fileName, container, confirm }, tm1Client) => {
         requireConfirm(confirm, fileName, "file");
-        await withToolHint(tm1Client.files.delete(fileName), "Verify exact name with tm1_list_files or tm1_search_files. Names are case-sensitive.");
+        await withToolHint(tm1Client.files.delete(fileName, container), "Verify exact name with tm1_list_files or tm1_search_files. Names are case-sensitive.");
         return actionResponse({ success: true, fileName, deleted: true });
     },
 });

package/dist/tools/fileops/get-file-content.js

@@ -2,17 +2,22 @@ import { z } from "zod";
 import { FileContentResultSchema } from "../schemas/items.js";
 import { READ_ONLY } from "../annotations.js";
 import { defineTool } from "../define-tool.js";
+import { CONTAINER_SCHEMA } from "./container.js";
 // Below the server's 80k-character response limit (TM1_MAX_RESPONSE_CHARS)
 // once JSON escaping is added; the old 256 KB default could never be returned.
 const DEFAULT_MAX_BYTES = 64 * 1024;
+// base64 grows the body by 4/3: 48 KB comes out at 64k characters, where the
+// text default would come out at ~87k and be refused by the size guard.
+const DEFAULT_BASE64_MAX_BYTES = 48 * 1024;
 const HARD_MAX_BYTES = 4 * 1024 * 1024;
 export const registerGetFileContent = defineTool({
     name: "tm1_get_file_content",
     description: [
         "Read the content of a file from the TM1 server's data directory.",
         "Use to inspect CSV, TXT, or other text files before building import processes.",
-        "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
-        "Response is truncated to maxBytes (default 64 KB) to keep MCP messages small.",
+        "Auto-falls back from v12 (Files) to v11 (Blobs) container. Set container='applications' to read a document out of the Applications tree; a folder or a view reference there carries no content and is refused by name.",
+        "encoding='base64' returns the bytes untouched — use it for spreadsheets and other binaries, which a text read would corrupt.",
+        "Response is truncated to maxBytes (default 64 KB, 48 KB for base64) to keep MCP messages small.",
     ],
     annotations: READ_ONLY,
     output: FileContentResultSchema,
@@ -26,8 +31,13 @@ export const registerGetFileContent = defineTool({
             .positive()
             .max(HARD_MAX_BYTES)
             .optional()
-            .default(DEFAULT_MAX_BYTES)
-            .describe(`Truncate response after N bytes (default ${DEFAULT_MAX_BYTES}, hard max ${HARD_MAX_BYTES}).`),
+            .describe(`Truncate response after N bytes (default ${DEFAULT_MAX_BYTES}, ${DEFAULT_BASE64_MAX_BYTES} for base64; hard max ${HARD_MAX_BYTES}).`),
+        ...CONTAINER_SCHEMA,
+        encoding: z
+            .enum(["text", "base64"])
+            .optional()
+            .default("text")
+            .describe("How to return the body. 'text' (default) decodes as UTF-8; 'base64' hands back the raw bytes. headLines only applies to text."),
         headLines: z
             .number()
             .int()
@@ -36,12 +46,39 @@ export const registerGetFileContent = defineTool({
             .optional()
             .describe("If set, only return the first N lines (overrides byte truncation)."),
     },
-    handler: async ({ fileName, maxBytes, headLines }, tm1Client) => {
-        const content = await tm1Client.files.getContent(fileName);
-        const totalBytes = Buffer.byteLength(content, "utf8");
+    handler: async ({ fileName, maxBytes: requestedMaxBytes, headLines, container, encoding }, tm1Client) => {
+        const maxBytes = requestedMaxBytes ??
+            (encoding === "base64" ? DEFAULT_BASE64_MAX_BYTES : DEFAULT_MAX_BYTES);
+        const bytes = await tm1Client.files.getContentBytes(fileName, container);
+        const totalBytes = bytes.byteLength;
         let body;
         let truncated = false;
         let truncationReason;
+        if (encoding === "base64") {
+            const slice = bytes.subarray(0, maxBytes);
+            body = slice.toString("base64");
+            if (slice.byteLength < totalBytes) {
+                truncated = true;
+                truncationReason = `maxBytes=${maxBytes}`;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            fileName,
+                            totalBytes,
+                            returnedBytes: slice.byteLength,
+                            truncated,
+                            ...(truncationReason ? { truncationReason } : {}),
+                            encoding,
+                            content: body,
+                        }),
+                    },
+                ],
+            };
+        }
+        const content = bytes.toString("utf8");
         if (headLines !== undefined) {
             const allLines = content.split("\n");
             body = allLines.slice(0, headLines).join("\n");
@@ -66,6 +103,7 @@ export const registerGetFileContent = defineTool({
             returnedBytes: Buffer.byteLength(body, "utf8"),
             truncated,
             ...(truncationReason ? { truncationReason } : {}),
+            encoding,
             content: body,
         };
         return {

package/dist/tools/fileops/list-files.js

@@ -3,6 +3,7 @@ import { PAGINATION_SCHEMA, paginate } from "../pagination.js";
 import { FORMAT_SCHEMA, wrappedPageResponse, columnsOf } from "../format.js";
 import { READ_ONLY } from "../annotations.js";
 import { defineTool } from "../define-tool.js";
+import { CONTAINER_SCHEMA } from "./container.js";
 import { FilenameItemSchema } from "../schemas/items.js";
 import { pageShapeFor } from "../schemas/common.js";
 // tm1_list_files prefixes a `path` field on top of the page envelope.
@@ -17,6 +18,7 @@ export const registerListFiles = defineTool({
         "Use to browse available CSV, TXT, or other files before building import processes.",
         "Supports subfolder navigation via the path parameter.",
         "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
+        "Set container='applications' to browse the Applications tree instead.",
         "Paginated (default 50/page).",
     ],
     annotations: READ_ONLY,
@@ -26,11 +28,12 @@ export const registerListFiles = defineTool({
             .string()
             .optional()
             .describe("Subfolder path (e.g. 'imports' or 'imports/2024'). Empty = root."),
+        ...CONTAINER_SCHEMA,
         ...PAGINATION_SCHEMA,
         ...FORMAT_SCHEMA,
     },
-    handler: async ({ path, limit, offset, fetchAll, format }, tm1Client) => {
-        const files = await tm1Client.files.list(path);
+    handler: async ({ path, container, limit, offset, fetchAll, format }, tm1Client) => {
+        const files = await tm1Client.files.list(path, container);
         const page = paginate(files, limit, offset, fetchAll);
         const wrapper = { path: path ?? "", ...page };
         const columns = columnsOf([{ header: "filename", get: (f) => f }]);

package/dist/tools/fileops/search-files.js

@@ -3,6 +3,7 @@ import { PAGINATION_SCHEMA, paginate } from "../pagination.js";
 import { FORMAT_SCHEMA, wrappedPageResponse, columnsOf } from "../format.js";
 import { READ_ONLY } from "../annotations.js";
 import { defineTool } from "../define-tool.js";
+import { CONTAINER_SCHEMA } from "./container.js";
 import { FilenameItemSchema } from "../schemas/items.js";
 import { pageShapeFor } from "../schemas/common.js";
 // tm1_search_files echoes the search filters alongside the page envelope so
@@ -48,15 +49,17 @@ export const registerSearchFiles = defineTool({
             .string()
             .optional()
             .describe("Subfolder to search in (v12 only). Empty = root."),
+        ...CONTAINER_SCHEMA,
         ...PAGINATION_SCHEMA,
         ...FORMAT_SCHEMA,
     },
-    handler: async ({ startswith, contains, operator, path, limit, offset, fetchAll, format }, tm1Client) => {
+    handler: async ({ startswith, contains, operator, path, container, limit, offset, fetchAll, format, }, tm1Client) => {
         const names = await tm1Client.files.search({
             startswith,
             contains,
             operator,
             path,
+            container,
         });
         const page = paginate(names, limit, offset, fetchAll);
         const wrapper = {

package/dist/tools/fileops/upload-file.js

@@ -5,6 +5,7 @@ import { CONFIRM_SCHEMA, requireConfirm } from "../confirm.js";
 import { IDEMPOTENT_WRITE } from "../annotations.js";
 import { MutationResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
+import { CONTAINER_SCHEMA } from "./container.js";
 const HARD_MAX_BYTES = 32 * 1024 * 1024;
 export const registerUploadFile = defineTool({
     name: "tm1_upload_file",
@@ -14,6 +15,7 @@ export const registerUploadFile = defineTool({
         "Provide content as plain text OR base64 (set encoding='base64' for binary).",
         "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
         "v11: subfolders not supported — use a flat file name. v12: nested paths OK if folders exist.",
+        "container='applications' writes into the Applications tree instead, which nests on both versions. The parent folder must already exist there too.",
         `Hard max size: ${HARD_MAX_BYTES} bytes (32 MB).`,
     ],
     annotations: IDEMPOTENT_WRITE,
@@ -31,9 +33,10 @@ export const registerUploadFile = defineTool({
             .optional()
             .default("text")
             .describe("Encoding of the `content` field. 'text' (default) for UTF-8 text, 'base64' for binary."),
+        ...CONTAINER_SCHEMA,
         ...CONFIRM_SCHEMA,
     },
-    handler: async ({ fileName, content, encoding, confirm }, tm1Client) => {
+    handler: async ({ fileName, content, encoding, container, confirm }, tm1Client) => {
         // Silently replaces an existing server file of the same name. Guards
         // against accidental invocation — not a security control.
         requireConfirm(confirm, fileName, "file");
@@ -55,7 +58,7 @@ export const registerUploadFile = defineTool({
                 ],
             };
         }
-        const result = await withToolHint(tm1Client.files.upload(fileName, bytes), "If parent folder is missing, create it on TM1 v12 before retrying. v11 supports root only.");
+        const result = await withToolHint(tm1Client.files.upload(fileName, bytes, container), "If parent folder is missing, create it on TM1 v12 before retrying. v11 supports root only.");
         return actionResponse({
             success: true,
             fileName,

package/dist/tools/index.js

@@ -42,7 +42,6 @@ import { registerCreateElement } from "./dimension-management/create-element.js"
 import { registerUpdateElement } from "./dimension-management/update-element.js";
 import { registerDeleteElement } from "./dimension-management/delete-element.js";
 import { registerDeleteElements } from "./dimension-management/delete-elements.js";
-import { registerMoveElement } from "./dimension-management/move-element.js";
 import { registerCreateDimension } from "./dimension-management/create-dimension.js";
 import { registerDeleteDimension } from "./dimension-management/delete-dimension.js";
 import { registerBulkUpsertElements } from "./dimension-management/bulk-upsert-elements.js";
@@ -174,7 +173,6 @@ const REGISTRARS = [
     registerUpdateElement,
     registerDeleteElement,
     registerDeleteElements,
-    registerMoveElement,
     registerListElementAttributes,
     registerCreateElementAttribute,
     registerGetElementAttributeValues,

package/dist/tools/model-building/check-cube-rule.js

@@ -6,7 +6,7 @@ export const registerCheckCubeRule = defineTool({
     name: "tm1_check_cube_rule",
     description: [
         "Validate the syntax of a TM1 cube rule WITHOUT applying it.",
-        "Returns 'valid' or a list of syntax errors with line numbers.",
+        "Returns ok:true, or ok:false with the syntax errors and their line numbers; a rule with errors is a normal result, not a tool error.",
         "Takes the same sources as tm1_set_cube_rules — rules, edits or filePath — and checks the full resulting text, so an edits patch is validated exactly as it would be installed. tm1_set_cube_rules runs this check itself before writing.",
     ],
     annotations: READ_ONLY,
@@ -42,8 +42,9 @@ export const registerCheckCubeRule = defineTool({
                 message: e.message,
             })),
         };
+        // A rule with syntax errors is the answer to the question, not a failed
+        // call: flagging it isError would drop structuredContent for the payload.
         return {
-            isError: !ok || undefined,
             content: [{ type: "text", text: JSON.stringify(payload) }],
         };
     },