@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tools/celldata/get-view.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { PAGINATION_SCHEMA } from "../pagination.js";
+import { FORMAT_SCHEMA, payloadResponse } from "../format.js";
+import { renderMdxMarkdown } from "./execute-mdx.js";
+import { clipAxesToWindow } from "../../tm1-client/services/cellset-transform.js";
+import { READ_ONLY } from "../annotations.js";
+import { ViewResultSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+export const registerGetView = defineTool({
+    name: "tm1_get_view",
+    description: [
+        "Execute a named cube view and return structured cell data with axes (page-envelope shape consistent with tm1_execute_mdx).",
+        "Cells paginate by default so wide/tall views don't flood context; fetchAll=true for the full cellset.",
+        "format='markdown' renders a pivot grid (2 axes, full result) or a flat coordinate table; 'json' (default) returns the structured envelope.",
+    ],
+    annotations: READ_ONLY,
+    output: ViewResultSchema,
+    input: {
+        cubeName: z.string().describe("Name of the TM1 cube"),
+        viewName: z.string().describe("Name of the view to execute"),
+        ...PAGINATION_SCHEMA,
+        ...FORMAT_SCHEMA,
+    },
+    handler: async ({ cubeName, viewName, limit, offset, fetchAll, format }, tm1Client, extra) => {
+        const all = fetchAll === true || limit === 0;
+        const top = all ? undefined : limit;
+        const skip = all ? undefined : offset;
+        const result = await tm1Client.views.getView(cubeName, viewName, top, skip, {
+            signal: extra?.signal,
+        });
+        const total = result.totalCellCount;
+        const count = result.cells.length;
+        const off = all ? 0 : offset;
+        const has_more = !all && off + count < total;
+        // Clip axes to the returned cell page so a capped read over a tall view
+        // doesn't ship the full tuple list. fetchAll keeps the whole cellset.
+        const { axes, clipped } = all
+            ? { axes: result.axes, clipped: false }
+            : clipAxesToWindow(result.axes, count, off);
+        const envelope = {
+            cubeName,
+            viewName,
+            axes,
+            total,
+            count,
+            offset: off,
+            has_more,
+            next_offset: has_more ? off + count : null,
+            ...(clipped ? { axes_clipped: true } : {}),
+            items: result.cells,
+        };
+        return payloadResponse(envelope, format, renderMdxMarkdown);
+    },
+});
+//# sourceMappingURL=get-view.js.map

package/dist/tools/celldata/sample-cells.d.ts

@@ -0,0 +1,2 @@
+export declare const registerSampleCells: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=sample-cells.d.ts.map

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

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { buildSampleCellsMdx, transformSampleCells, } from "../../lib/sample-cells.js";
+import { READ_ONLY } from "../annotations.js";
+import { SampleCellsResultSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+const FilterValueSchema = z.union([
+    z.string(),
+    z.array(z.string()).min(1),
+]);
+export const registerSampleCells = defineTool({
+    name: "tm1_sample_cells",
+    description: [
+        "Return up to maxCells populated cells from a cube without guessing coordinates — builds a NON EMPTY CROSSJOIN MDX over the cube's dimensions and HEAD-limits it.",
+        "For sanity-checks after a clone, finding non-zero cells, or debugging empty views. maxCells=0 means unlimited (WARNING: large cubes may return millions — filter first).",
+        "NON EMPTY targets numeric cells; set includeStrings=true for String value fields.",
+    ],
+    annotations: READ_ONLY,
+    output: SampleCellsResultSchema,
+    input: {
+        cubeName: z.string().describe("Cube to sample"),
+        maxCells: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .default(5)
+            .describe("Max cells to return (default 5). 0 = no limit (unbounded; combine with filters)."),
+        filters: z
+            .record(z.string(), FilterValueSchema)
+            .optional()
+            .describe("Per-dimension filters. Single string → WHERE pin. Array of strings → axis member set. Keys must match cube dimension names."),
+        axisDimension: z
+            .string()
+            .optional()
+            .describe("Dimension placed on COLUMNS (default: last dimension of the cube). Useful when the cube has a 'Measures'/'Account' dim that should drive columns."),
+        leavesOnly: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), unfiltered dims are restricted to leaf members via TM1FILTERBYLEVEL([dim],0). Set false to include consolidations."),
+        includeStrings: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Set true to sample String value fields. Swaps NON EMPTY for a `<> ""` FILTER and scans all members incl. consolidations (string values don\'t roll up, so they can sit on C). Requires the column/measure to resolve to a single element — pin it via filters or axisDimension.'),
+    },
+    handler: async ({ cubeName, maxCells, filters, axisDimension, leavesOnly, includeStrings }, tm1Client) => {
+        const startedAt = Date.now();
+        const dimensions = await tm1Client.cubes.getDimensionNames(cubeName);
+        // Sentinel row: ask TM1 for one cell MORE than requested, so `truncated`
+        // is decided by evidence instead of inferred from a full page.
+        // `cells.length >= maxCells` cannot tell "exactly maxCells cells exist"
+        // apart from "more exist" and reported truncation for both. The extra row
+        // is dropped below, so the response contract is unchanged.
+        // maxCells=0 means unlimited — no sentinel, nothing to truncate.
+        const requested = maxCells ?? 5;
+        const built = buildSampleCellsMdx({
+            cubeName,
+            dimensions,
+            maxCells: requested > 0 ? requested + 1 : 0,
+            filters,
+            axisDimension,
+            leavesOnly: leavesOnly ?? true,
+            includeStrings: includeStrings ?? false,
+        });
+        const result = await tm1Client.cells.executeMdx(built.mdx);
+        const whereCoords = {};
+        if (filters) {
+            for (const [dim, val] of Object.entries(filters)) {
+                if (typeof val === "string")
+                    whereCoords[dim] = val;
+            }
+        }
+        const sampled = transformSampleCells({ result, whereCoords });
+        const truncated = requested > 0 && sampled.length > requested;
+        const cells = truncated ? sampled.slice(0, requested) : sampled;
+        const hint = cells.length === 0
+            ? includeStrings
+                ? "No populated cells found — cube may be empty or current filters exclude data."
+                : "No populated cells found — cube may be empty, all-consolidated, or current filters exclude data. If the value field is a String type, NON EMPTY cannot detect it: retry with includeStrings=true."
+            : undefined;
+        const elapsedMs = Date.now() - startedAt;
+        const payload = {
+            cubeName,
+            count: cells.length,
+            truncated,
+            cells,
+            filtersApplied: filters ?? {},
+            axisDimension: built.columnDim,
+            rowDims: built.rowDims,
+            whereDims: built.whereDims,
+            mdxUsed: built.mdx,
+            elapsedMs,
+            ...(hint ? { hint } : {}),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+});
+//# sourceMappingURL=sample-cells.js.map

package/dist/tools/celldata/trace-cell-calculation.d.ts

@@ -0,0 +1,2 @@
+export declare const registerTraceCellCalculation: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=trace-cell-calculation.d.ts.map

package/dist/tools/celldata/trace-cell-calculation.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { withToolHint } from "../error-format.js";
+import { CalculationTraceResultSchema } from "../schemas/items.js";
+import { READ_ONLY, withVersion } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+export const registerTraceCellCalculation = defineTool({
+    name: "tm1_trace_cell_calculation",
+    description: [
+        "Trace how a cell value is calculated: recursive component tree with per-component type (Consolidation/Rule/Simple), status (Null/Data/Error), value, and the rule statements that populate it — answers 'why is this cell X / empty?'.",
+        "The tree is truncated client-side via maxDepth/maxComponents; truncated=true marks cut branches (re-run with the branch tuple as new start cell to drill deeper).",
+        "Elements address the default hierarchy, in cube dimension order (discover with tm1_list_cubes).",
+        "v11 only. Related: tm1_check_feeders / tm1_trace_feeders for feeder issues, tm1_get_cube_rules for the full rule text.",
+    ],
+    annotations: withVersion(READ_ONLY, "v11"),
+    output: CalculationTraceResultSchema,
+    input: {
+        cubeName: z.string().describe("Name of the TM1 cube"),
+        elements: z
+            .array(z.string())
+            .describe("Element names for each dimension of the cube, in cube dimension order"),
+        maxDepth: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe("Maximum component-tree depth to return (default 3). Deep consolidations explode quickly."),
+        maxComponents: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Maximum components per node (default 20). Excess children are dropped and the node marked truncated."),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1000)
+            .max(3600000)
+            .optional()
+            .describe("Override the default request timeout (ms, 1000–3600000). Traces over deep consolidations can be slow."),
+    },
+    handler: async ({ cubeName, elements, maxDepth, maxComponents, timeoutMs }, tm1Client, extra) => {
+        const tree = await withToolHint(tm1Client.cells.traceCellCalculation(cubeName, elements, maxDepth, maxComponents, {
+            signal: extra?.signal,
+            ...(timeoutMs ? { timeoutMs } : {}),
+        }), `TraceCellCalculation failed for cube '${cubeName}'. Verify dimension order/elements via tm1_list_cubes; alternate hierarchies are not supported. On v12 this action is unavailable.`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(tree) }],
+        };
+    },
+});
+//# sourceMappingURL=trace-cell-calculation.js.map

package/dist/tools/celldata/trace-feeders.d.ts

@@ -0,0 +1,2 @@
+export declare const registerTraceFeeders: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=trace-feeders.d.ts.map

package/dist/tools/celldata/trace-feeders.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { withToolHint } from "../error-format.js";
+import { READ_ONLY, withVersion } from "../annotations.js";
+import { TraceFeedersResultSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+export const registerTraceFeeders = defineTool({
+    name: "tm1_trace_feeders",
+    description: [
+        "Trace the feeders of a cell: returns the cells this cell feeds plus the feeder statements involved — answers 'which feeder statement fires from this cell, and where to'.",
+        "Use when a rule cell stays empty under SKIPCHECK: trace the source cell to see whether its feeder reaches the target.",
+        "Elements address the default hierarchy, in cube dimension order (discover with tm1_list_cubes).",
+        "v11 only. Related: tm1_check_feeders (fed/unfed flags), tm1_audit_feeders (static analysis).",
+    ],
+    annotations: withVersion(READ_ONLY, "v11"),
+    output: TraceFeedersResultSchema,
+    input: {
+        cubeName: z.string().describe("Name of the TM1 cube"),
+        elements: z
+            .array(z.string())
+            .describe("Element names for each dimension of the cube, in cube dimension order"),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1000)
+            .max(3600000)
+            .optional()
+            .describe("Override the default request timeout (ms, 1000–3600000). Traces over deep consolidations can be slow."),
+    },
+    handler: async ({ cubeName, elements, timeoutMs }, tm1Client, extra) => {
+        const result = await withToolHint(tm1Client.cells.traceFeeders(cubeName, elements, {
+            signal: extra?.signal,
+            ...(timeoutMs ? { timeoutMs } : {}),
+        }), `TraceFeeders failed for cube '${cubeName}'. Verify dimension order/elements via tm1_list_cubes; alternate hierarchies are not supported. On v12 this action is unavailable.`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ count: result.fedCells.length, ...result }),
+                },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=trace-feeders.js.map

package/dist/tools/celldata/write-cells.d.ts

@@ -0,0 +1,2 @@
+export declare const registerWriteCells: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=write-cells.d.ts.map

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+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 { dimensionCountMismatch } from "../../lib/coordinate-error.js";
+import { resolveCellAddress } from "../../lib/cell-address.js";
+export const registerWriteCells = defineTool({
+    name: "tm1_write_cells",
+    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.",
+        "Before: tm1_check_writable_coords to validate that target coordinates are leaf-level and addressable.",
+        "Related: tm1_clear_cube for bulk wipe, tm1_get_cell_value to read back, tm1_execute_process for production data loads.",
+    ],
+    annotations: DESTRUCTIVE,
+    output: MutationResultSchema,
+    input: {
+        cubeName: z.string().describe("Name of the TM1 cube"),
+        dimensions: z
+            .array(z.string())
+            .min(2)
+            .describe("Cube dimension names, any order; each cell's elements follow this order. Must cover every cube dimension except Sandboxes."),
+        cells: z
+            .array(z.object({
+            elements: z
+                .array(z.string())
+                .describe("Element names, one per entry in dimensions, in that order"),
+            value: z
+                .union([z.number(), z.string()])
+                .describe("Cell value (number for Numeric cubes, string for String cells)"),
+        }))
+            .min(1)
+            .describe("Cells to write"),
+        ...CONFIRM_SCHEMA,
+    },
+    handler: async ({ cubeName, dimensions, cells, 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 cells) {
+            if (c.elements.length !== dimensions.length) {
+                throw dimensionCountMismatch(cubeName, dimensions, c.elements);
+            }
+        }
+        // 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);
+        await tm1Client.cells.writeCells(cubeName, address.dimensions, cells.map((c) => ({ ...c, elements: address.toCubeOrder(c.elements) })));
+        return actionResponse({
+            success: true,
+            cellsWritten: cells.length,
+            ...(address.sandboxDefaulted
+                ? { sandboxDefaulted: address.sandboxDefaulted }
+                : {}),
+        });
+    },
+});
+//# sourceMappingURL=write-cells.js.map

package/dist/tools/confirm.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const CONFIRM_SCHEMA: {
+    confirm: z.ZodString;
+};
+export declare function requireConfirm(provided: string, target: string, kind: string): void;
+export declare const OVERWRITE_CONFIRM_SCHEMA: {
+    confirm: z.ZodOptional<z.ZodString>;
+};
+export declare function requireOverwriteConfirm(provided: string | undefined, target: string, kind: string): void;
+//# sourceMappingURL=confirm.d.ts.map

package/dist/tools/confirm.js

@@ -0,0 +1,64 @@
+// Confirmation guard for destructive tool calls (R2-10 from MCP best-
+// practices review). LLMs occasionally fire delete_* / clear_* tools
+// without sufficient evidence the action is intended. Requiring the
+// caller to repeat the target name as a second argument forces explicit
+// intent and makes "auto-approve all" clients safer.
+//
+// Pattern in a tool registration:
+//
+//   const CONFIRM_SCHEMA = {
+//     confirm: z
+//       .string()
+//       .describe(
+//         "Repeat the target name verbatim to confirm this irreversible action.",
+//       ),
+//   };
+//
+//   async ({ name, confirm }) => {
+//     requireConfirm(confirm, name, "cube");
+//     await tm1Client.cubes.delete(name);
+//     ...
+//   }
+//
+// requireConfirm throws TM1Error(VALIDATION_ERROR) on mismatch; the
+// Proxy in src/index.ts catches and reformats to the uniform error shape.
+import { z } from "zod";
+import { TM1Error, TM1ErrorCode } from "../types.js";
+export const CONFIRM_SCHEMA = {
+    confirm: z
+        .string()
+        .describe("Safety check: repeat the target identifier verbatim (e.g. cube/dimension/process name) to confirm this irreversible action. Mismatched values reject the call."),
+};
+export function requireConfirm(provided, target, kind) {
+    if (provided !== target) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `confirm mismatch — expected ${kind} name "${target}", got "${provided}".`,
+            hint: `Re-issue the call with confirm="${target}" verbatim. This safety check prevents accidental destructive operations.`,
+        });
+    }
+}
+// Overwrite guard for create-or-update tools (upsert_process, the import tools,
+// install_pro_bundle). Creating a new object needs no confirmation; replacing
+// an existing one does, because the previous version is not recoverable
+// through the API (the tools save a local backup, see process-backup.ts, but
+// that is a file on the MCP host, not an undo). Hence optional in the schema, required at runtime once the
+// target is known to exist.
+export const OVERWRITE_CONFIRM_SCHEMA = {
+    confirm: z
+        .string()
+        .optional()
+        .describe("Required only when the target already exists (an overwrite): repeat its name verbatim. Not needed to create. The replaced version is saved first; result.backup names the .json/.ti pair (restore: tm1_import_process_from_git)."),
+};
+export function requireOverwriteConfirm(provided, target, kind) {
+    if (provided === target)
+        return;
+    throw new TM1Error({
+        code: TM1ErrorCode.VALIDATION_ERROR,
+        message: provided === undefined
+            ? `${kind} "${target}" already exists; overwriting it needs confirm="${target}". Nothing was written.`
+            : `confirm mismatch — expected ${kind} name "${target}", got "${provided}". Nothing was written.`,
+        hint: `Show the user what will be replaced (e.g. tm1_diff_process_with_file), then re-issue with confirm="${target}" verbatim, or use mode="create" to refuse overwrites outright.`,
+    });
+}
+//# sourceMappingURL=confirm.js.map

package/dist/tools/define-tool.d.ts

@@ -0,0 +1,51 @@
+import type { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodObject, ZodRawShape, ZodTypeAny } from "zod";
+import type { TM1Client } from "../tm1-client.js";
+import type { Tm1ToolAnnotations } from "./annotations.js";
+/** Registrar shape expected by the REGISTRARS array in ./index.ts. */
+export type ToolRegistrar = (server: McpServer, tm1Client: TM1Client) => void;
+export interface ToolSpec<I extends ZodRawShape> {
+    /** Wire name, `tm1_*`. */
+    name: string;
+    /**
+     * Tool description. An array is joined with a single space — the same shape
+     * the hand-written registrations use, and what scripts/lib/scan-tools.mjs
+     * parses for docs/TOOLS.md.
+     */
+    description: string | readonly string[];
+    /** Zod raw shape for the tool's arguments. */
+    input: I;
+    /**
+     * Output payload schema, pre-widening. Pass the plain schema or raw shape;
+     * `asOutputSchema()` and `markdownCapable()` are applied here as needed.
+     * Omit for tools that answer with unstructured text.
+     */
+    output?: ZodObject<ZodRawShape> | ZodRawShape;
+    /** MCP behavior hints — one of the presets in ./annotations.js. */
+    annotations: Tm1ToolAnnotations;
+    /**
+     * Registration gate for tools that exist on one TM1 generation only (v11
+     * threads vs v12 jobs, v11-only save_data). Returning false skips the tool
+     * entirely — it never appears in tools/list. This is deliberately separate
+     * from the `requiresVersion` annotation, which is a client-facing HINT and
+     * is also carried by tools that stay registered on both generations.
+     */
+    enabled?: (tm1Client: TM1Client) => boolean;
+    /**
+     * Handler. Receives the parsed args, the shared TM1 client, and the SDK's
+     * per-call extra (abort signal, request metadata).
+     */
+    handler: (args: Parameters<ToolCallback<I>>[0], tm1Client: TM1Client, extra: Parameters<ToolCallback<I>>[1]) => ReturnType<ToolCallback<I>>;
+}
+/** What ./with-annotations.ts needs at registration time. */
+export interface ResolvedSpec {
+    name: string;
+    annotations: Tm1ToolAnnotations;
+    /** Already widened — hand straight to the SDK. */
+    outputSchema?: ZodRawShape | ZodTypeAny;
+}
+export declare function specFor(name: string): ResolvedSpec | undefined;
+/** Every spec defined so far. Used by the lint gates and by tests. */
+export declare function allSpecs(): ReadonlyMap<string, ResolvedSpec>;
+export declare function defineTool<I extends ZodRawShape>(spec: ToolSpec<I>): ToolRegistrar;
+//# sourceMappingURL=define-tool.d.ts.map

package/dist/tools/define-tool.js

@@ -0,0 +1,49 @@
+import { asOutputSchema } from "./schemas/output-schema.js";
+import { markdownCapable } from "./schemas/markdown-capable.js";
+// Populated at module-load time, when a tool file's top-level defineTool()
+// call runs. That is strictly before registerAllTools() executes, because the
+// import graph resolves first — so the Proxy always finds the spec.
+const SPECS = new Map();
+export function specFor(name) {
+    return SPECS.get(name);
+}
+/** Every spec defined so far. Used by the lint gates and by tests. */
+export function allSpecs() {
+    return SPECS;
+}
+function isZodObject(output) {
+    return "_def" in output;
+}
+function resolveOutput(output, formatCapable) {
+    if (output === undefined)
+        return undefined;
+    const normalized = isZodObject(output) ? asOutputSchema(output) : output;
+    return formatCapable ? markdownCapable(normalized) : normalized;
+}
+export function defineTool(spec) {
+    const description = Array.isArray(spec.description)
+        ? spec.description.join(" ")
+        : spec.description;
+    const existing = SPECS.get(spec.name);
+    if (existing) {
+        throw new Error(`defineTool: duplicate tool name "${spec.name}" — each tool may be defined once.`);
+    }
+    const outputSchema = resolveOutput(spec.output, "format" in spec.input);
+    SPECS.set(spec.name, {
+        name: spec.name,
+        annotations: spec.annotations,
+        // Built conditionally: exactOptionalPropertyTypes rejects an explicit
+        // `outputSchema: undefined` for an optional property.
+        ...(outputSchema === undefined ? {} : { outputSchema }),
+    });
+    return (server, tm1Client) => {
+        if (spec.enabled && !spec.enabled(tm1Client))
+            return;
+        // ToolCallback<I> is a conditional type over an unresolved generic, so TS
+        // cannot check the lambda against it — the cast asserts what the
+        // ToolSpec.handler signature already pins down (same args, same return).
+        const cb = ((args, extra) => spec.handler(args, tm1Client, extra));
+        server.tool(spec.name, description, spec.input, cb);
+    };
+}
+//# sourceMappingURL=define-tool.js.map

package/dist/tools/dimension-management/bulk-upsert-elements.d.ts

@@ -0,0 +1,2 @@
+export declare const registerBulkUpsertElements: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=bulk-upsert-elements.d.ts.map

package/dist/tools/dimension-management/bulk-upsert-elements.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { withToolHint } from "../error-format.js";
+import { actionResponse } from "../format.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";
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+const ElementSchema = z.object({
+    name: z.string().describe("Element name"),
+    type: z
+        .enum(["Numeric", "String", "Consolidated"])
+        .describe("N=numeric leaf, C=consolidated/parent, S=string"),
+    components: z
+        .array(z.object({
+        name: z.string().describe("Child element name"),
+        weight: z
+            .number()
+            .default(1)
+            .describe("Consolidation weight (default: 1)"),
+    }))
+        .optional()
+        .describe("Child elements for a Consolidated element. REPLACES the full existing child set (verified live: passing [X,Y] drops any current children not in the list — it does not append). Omit or pass an empty array to leave existing children unchanged. To add one child, list the complete intended set."),
+});
+export const registerBulkUpsertElements = defineTool({
+    name: "tm1_bulk_upsert_elements",
+    description: [
+        "Create or update multiple elements in a TM1 hierarchy in bulk (two-pass: leafs first, then consolidations).",
+        "Existing elements are updated; new elements are created.",
+        "IMPORTANT: List all Numeric/String leaf elements BEFORE Consolidated elements to avoid reference errors.",
+        "For a Consolidated element, a non-empty components list REPLACES its full child set (existing children not listed are dropped); omit components to leave children unchanged.",
+        "When that would drop existing children, the call needs confirm=<dimension name>; dryRun=true returns the plan (creates, updates, typeChanges, removals) without writing.",
+    ],
+    annotations: IDEMPOTENT_DESTRUCTIVE,
+    output: MutationResultSchema,
+    input: {
+        dimensionName: z.string().describe("Dimension name"),
+        ...HIERARCHY_NAME_OPTIONAL,
+        elements: z
+            .array(ElementSchema)
+            .min(1)
+            .describe("Elements to create or update"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return the plan (creates, updates, typeChanges, removals) and write nothing."),
+        confirm: z
+            .string()
+            .optional()
+            .describe("Required only when components would remove existing children: the dimension name verbatim."),
+    },
+    handler: async ({ dimensionName, hierarchyName, elements, dryRun, confirm }, tm1Client) => {
+        const hier = resolveHierarchy(dimensionName, hierarchyName);
+        // Only a components list can drop children, so only then (or for a
+        // dryRun) is the plan worth its read. It must run before bulkUpsert: the
+        // $batch create pass commits as it goes.
+        const replacesChildren = elements.some((e) => e.type === "Consolidated" && (e.components?.length ?? 0) > 0);
+        if (dryRun || replacesChildren) {
+            const plan = await tm1Client.elements.planBulkUpsert(dimensionName, hier, elements);
+            if (dryRun) {
+                return actionResponse({
+                    success: true,
+                    dryRun: true,
+                    dimensionName,
+                    hierarchyName: hier,
+                    ...plan,
+                });
+            }
+            if (plan.removals.length > 0 && confirm !== dimensionName) {
+                const dropped = plan.removals.reduce((n, r) => n + r.children.length, 0);
+                throw new TM1Error({
+                    code: TM1ErrorCode.VALIDATION_ERROR,
+                    message: `components would remove ${dropped} existing child link(s) under ${plan.removals.map((r) => r.parent).join(", ")}. Nothing was written.`,
+                    hint: `components REPLACE a consolidation's children. Show the user details.removals; to proceed re-issue with confirm="${dimensionName}", or list the complete intended child set.`,
+                    details: JSON.stringify({ removals: plan.removals }),
+                });
+            }
+        }
+        const { typeChanges } = await withToolHint(tm1Client.elements.bulkUpsert(dimensionName, hier, elements), "Bulk upsert failed. Common causes: Consolidated element references a child that is not in this batch and does not exist yet (list leafs first), dimension/hierarchy name mismatch (tm1_list_dimensions to verify), or attempt to change an element's type (delete + recreate instead).");
+        const counts = {
+            N: elements.filter((e) => e.type === "Numeric").length,
+            C: elements.filter((e) => e.type === "Consolidated").length,
+            S: elements.filter((e) => e.type === "String").length,
+        };
+        return actionResponse({
+            success: true,
+            dimensionName,
+            hierarchyName: hier,
+            total: elements.length,
+            counts,
+            // Existing elements whose Type was changed in place. A
+            // Numeric->Consolidated/String conversion discards the element's
+            // leaf cell values, so surface it instead of letting it happen
+            // silently.
+            typeChanges,
+            ...(typeChanges.length > 0 && {
+                warning: `${typeChanges.length} element(s) had their type changed in place; any existing leaf cell values for those elements were discarded.`,
+            }),
+        });
+    },
+});
+//# sourceMappingURL=bulk-upsert-elements.js.map

package/dist/tools/dimension-management/create-dimension.d.ts

@@ -0,0 +1,2 @@
+export declare const registerCreateDimension: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=create-dimension.d.ts.map

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

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { actionResponse } from "../format.js";
+import { MutationResultSchema } from "../schemas/items.js";
+import { WRITE } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+export const registerCreateDimension = defineTool({
+    name: "tm1_create_dimension",
+    description: [
+        "Create a new TM1 dimension with a default hierarchy of the same name.",
+        "Fails if the dimension already exists. After: tm1_create_element / tm1_bulk_upsert_elements to populate, tm1_create_hierarchy for alternate hierarchies.",
+    ],
+    annotations: WRITE,
+    output: MutationResultSchema,
+    input: {
+        dimensionName: z.string().describe("Dimension name"),
+    },
+    handler: async ({ dimensionName }, tm1Client) => {
+        await tm1Client.dimensions.create(dimensionName);
+        return actionResponse({ success: true, dimensionName });
+    },
+});
+//# sourceMappingURL=create-dimension.js.map

package/dist/tools/dimension-management/create-element-attribute.d.ts

@@ -0,0 +1,2 @@
+export declare const registerCreateElementAttribute: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=create-element-attribute.d.ts.map