@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tools/analysis/trace-data-flow.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { buildIndexFromTM1 } from "../../lib/callgraph/tm1-adapter.js";
+import { traceDataFlow } from "../../lib/callgraph/dataFlow.js";
+import { buildDatasourceMembership, } from "../../lib/callgraph/datasourceMembership.js";
+import { membersFromAxis } from "../../lib/callgraph/mdxMembers.js";
+import { DataFlowResultSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+// Per-direction ceiling. Flow rows carry a process name plus cube/element
+// arrays, so they are heavier than a list row — this sits well below the
+// list-tool cap on purpose.
+const FLOW_MAX_ITEMS = 500;
+export const registerTraceDataFlow = defineTool({
+    name: "tm1_trace_data_flow",
+    description: [
+        "Trace data flow into and out of a cube in one call, instead of analyze_object_usage + N× get_process_code.",
+        "downstream: processes that READ the cube and which cubes they WRITE to (where the data flows next).",
+        "upstream: processes that WRITE the cube and where they SOURCE data (read cubes + datasource).",
+        "Combines code-level CellGet/CellPut/DB access with each process's datasource, so view-sourced reads",
+        "(a TM1CubeView datasource with no CellGet in the code) are caught too. Read-only.",
+        "Pass element+dimension to also get which processes touch that element via in-code subset-membership calls.",
+        "Each touching process is tagged access=source|write|zero-out|indeterminate so a zero-out is not mistaken for a read-source.",
+        "Element tracing also resolves stored view/subset datasources (native-view titles + static subsets exactly; MDX views/subsets by literal member; computed selectors are flagged, not resolved).",
+        "With resolveComputed=true, computed native-view axis selectors are resolved to exact members (via 'view-native-computed'); otherwise they stay flagged in computedInProcesses.",
+    ],
+    annotations: READ_ONLY,
+    output: DataFlowResultSchema,
+    input: {
+        cubeName: z.string().describe("Cube to trace (case-insensitive)"),
+        direction: z
+            .enum(["upstream", "downstream", "both"])
+            .optional()
+            .default("both")
+            .describe("'downstream': readers → their write targets. 'upstream': writers → their data sources. 'both' (default)."),
+        includeControl: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include control processes (names starting with '}') when building the index. Default: false."),
+        element: z
+            .string()
+            .optional()
+            .describe("Element name to trace. With 'dimension', results add which processes touch this element via in-code subset-membership calls (SubsetElementInsert/Add/Delete)."),
+        dimension: z
+            .string()
+            .optional()
+            .describe("Owning dimension of 'element' (required when 'element' is set)."),
+        resolveDatasourceMembership: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When tracing an element, also resolve server-side view/subset datasources (extra fetches). Default true; set false to skip for speed."),
+        resolveComputed: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When tracing an element, additionally RESOLVE computed native-view axis selectors (e.g. TM1FILTERBYLEVEL/DESCENDANTS) by live-evaluating just that dimension's set against the view's cube (read-only). Off by default (extra queries). Only affects native-view axis expressions; stored subsets are already resolved exactly."),
+        elementAccess: z
+            .array(z.enum(["source", "write", "zero-out", "indeterminate"]))
+            .optional()
+            .describe("Element roles to include (default source+write+zero-out). Add 'indeterminate' to also list processes that build the subset but whose use we could not classify (NOT proof of no use)."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .max(FLOW_MAX_ITEMS)
+            .optional()
+            .default(FLOW_MAX_ITEMS)
+            .describe(`Max entries per direction (default ${FLOW_MAX_ITEMS}). counts stay unclipped; truncated=true says the cap bit.`),
+    },
+    handler: async ({ cubeName, direction, includeControl, element, dimension, resolveDatasourceMembership, resolveComputed, elementAccess, limit, }, tm1Client) => {
+        if (element && !dimension) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "When 'element' is set, 'dimension' is required (element names are only unique within a dimension).",
+                    },
+                ],
+            };
+        }
+        const [index, dsList] = await Promise.all([
+            buildIndexFromTM1(tm1Client, { includeControl }),
+            tm1Client.processes.listDataSources(includeControl),
+        ]);
+        let datasourceMembership;
+        if (element && dimension && resolveDatasourceMembership) {
+            datasourceMembership = await buildDatasourceMembership({
+                getViewDefinition: (cube, view) => tm1Client.views.getDefinition(cube, view),
+                getSubset: (dim, hier, sub) => tm1Client.subsets.get(dim, hier, sub),
+                ...(resolveComputed
+                    ? {
+                        evaluateSetExpression: async (cube, dim, mdxSet) => {
+                            const res = await tm1Client.cells.executeMdx(`SELECT {${mdxSet}} ON 0 FROM [${cube.replace(/\]/g, "]]")}]`, 1);
+                            return membersFromAxis(res, dim);
+                        },
+                    }
+                    : {}),
+            }, dsList);
+        }
+        const flow = traceDataFlow(index, dsList, cubeName, direction, element && dimension
+            ? {
+                element: { dimension, name: element },
+                ...(elementAccess ? { elementAccess } : {}),
+                ...(datasourceMembership ? { datasourceMembership } : {}),
+            }
+            : undefined);
+        // An element filter that found hits is meaningful output on its own — don't let
+        // a cube with no up/downstream flow overwrite it with a contradictory "not found" hint.
+        const elementHasHits = (flow.element?.processes.length ?? 0) > 0;
+        const empty = !elementHasHits &&
+            (flow.counts.upstream ?? 0) === 0 &&
+            (flow.counts.downstream ?? 0) === 0;
+        const hint = empty
+            ? `No data flow found for '${cubeName}'. Check the cube name, or set includeControl=true if it is touched only by control (}) processes.`
+            : undefined;
+        // This tool had no limit, offset or summary mode at all — on a large
+        // model it returned every reader and every writer of a cube in one
+        // response. Clip the two arrays but leave `counts` alone: the caller
+        // still sees the true totals, so a clipped answer is visibly partial
+        // rather than quietly wrong.
+        const clip = (rows) => rows && rows.length > limit ? rows.slice(0, limit) : rows;
+        const truncated = (flow.upstream?.length ?? 0) > limit ||
+            (flow.downstream?.length ?? 0) > limit;
+        const payload = {
+            ...flow,
+            ...(flow.upstream ? { upstream: clip(flow.upstream) } : {}),
+            ...(flow.downstream ? { downstream: clip(flow.downstream) } : {}),
+            ...(truncated ? { truncated } : {}),
+            ...(hint ? { hint } : {}),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+});
+//# sourceMappingURL=trace-data-flow.js.map

package/dist/tools/annotations.d.ts

@@ -0,0 +1,12 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+export type Tm1RequiresVersion = "v11" | "v12" | "v11+" | "v12+";
+export interface Tm1ToolAnnotations extends ToolAnnotations {
+    requiresVersion?: Tm1RequiresVersion;
+}
+export declare function withVersion(base: ToolAnnotations, version: Tm1RequiresVersion): Tm1ToolAnnotations;
+export declare const READ_ONLY: ToolAnnotations;
+export declare const IDEMPOTENT_WRITE: ToolAnnotations;
+export declare const WRITE: ToolAnnotations;
+export declare const IDEMPOTENT_DESTRUCTIVE: ToolAnnotations;
+export declare const DESTRUCTIVE: ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/tools/annotations.js

@@ -0,0 +1,61 @@
+// Apply requiresVersion to a base annotation preset without mutating it.
+export function withVersion(base, version) {
+    return { ...base, requiresVersion: version };
+}
+// GET / list / search / analyze / validate / compile / diff — no server-side state change.
+// No idempotentHint: per MCP spec it is only meaningful when readOnlyHint=false.
+export const READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+};
+// PUT-style updates: same input -> same end state. update_*, upsert_*, bulk_upsert_*.
+export const IDEMPOTENT_WRITE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+// POST-style creates / non-idempotent writes: create_*, copy_*, toggle_*, write_cells.
+export const WRITE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+// Idempotent, but overwrites something that re-running the call cannot bring
+// back: set_cube_rules replaces the whole rule file, write_cells replaces the
+// prior cell values, bulk_upsert_elements' component lists replace a
+// consolidation's entire child set.
+//
+// Splitting this out closes a real taxonomy hole: "destructive" had come to mean
+// "deletes an object", so full-replacement writes advertised
+// destructiveHint:false and a client's confirm-before-destructive prompt never
+// fired for them. Per MCP spec destructiveHint asks whether the tool "may
+// perform destructive updates to its environment" — an irreversible overwrite
+// qualifies. Idempotence is orthogonal (same input, same end state; it says
+// nothing about what the first call overwrote).
+export const IDEMPOTENT_DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+// delete_*, clear_*, unload_*, cancel_*, remove_*, execute_* (TI side effects).
+// Note: "destructive" per MCP spec = "may perform destructive updates to its
+// environment". This covers two distinct shapes in TM1:
+//   1. Irreversible object/data removal (delete_*, clear_*) — true destructive
+//   2. Irreversible data mutation via side-effects (execute_process,
+//      execute_chore) — process runs and writes through to cubes; output is
+//      not recoverable by undoing the tool call.
+// Both surface to the client as a single destructiveHint=true so prompts
+// before invocation warn either way. tm1_invalidate_callgraph_cache was
+// previously here but is in fact recoverable (cache rebuilds on next read)
+// and is now classified IDEMPOTENT_WRITE.
+export const DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+//# sourceMappingURL=annotations.js.map

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

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

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { withToolHint } from "../error-format.js";
+import { CheckFeedersResultSchema } from "../schemas/items.js";
+import { READ_ONLY, withVersion } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+export const registerCheckFeeders = defineTool({
+    name: "tm1_check_feeders",
+    description: [
+        "Check the feeders of a cell: verifies feeder coverage for the cells underlying this cell and returns the problematic ones with a fed flag — fed=false marks a broken or missing feeder (the classic cause of empty consolidated/rule cells). An empty result means no feeder problems were detected (live-verified on 11.8: fully-fed areas return []).",
+        "Per-cell runtime check; complements tm1_audit_feeders (static rule analysis).",
+        "Elements address the default hierarchy, in cube dimension order (discover with tm1_list_cubes).",
+        "v11 only. Related: tm1_trace_feeders (statements involved), tm1_trace_cell_calculation (why has this cell value X).",
+    ],
+    annotations: withVersion(READ_ONLY, "v11"),
+    output: CheckFeedersResultSchema,
+    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). Checks over deep consolidations can be slow."),
+    },
+    handler: async ({ cubeName, elements, timeoutMs }, tm1Client, extra) => {
+        const fedCells = await withToolHint(tm1Client.cells.checkFeeders(cubeName, elements, {
+            signal: extra?.signal,
+            ...(timeoutMs ? { timeoutMs } : {}),
+        }), `CheckFeeders 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: fedCells.length,
+                        unfedCount: fedCells.filter((c) => !c.fed).length,
+                        fedCells,
+                    }, null, 2),
+                },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=check-feeders.js.map

package/dist/tools/celldata/check-writable-coords.d.ts

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

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

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { rethrowIfSystemic } from "../../tm1-client/services/fallback.js";
+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";
+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.",
+    annotations: READ_ONLY,
+    output: WritableCoordsResultSchema,
+    input: {
+        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."),
+        dimensions: z
+            .array(z.string())
+            .optional()
+            .describe("Dimension names for coords, any order — as passed to tm1_write_cells. Every cube dimension except Sandboxes (bound to Base) must be named."),
+    },
+    handler: async ({ cubeName, coords: given, dimensions }, tm1Client) => {
+        const cubes = await tm1Client.cubes.list();
+        const cubeMeta = cubes.find((c) => c.name.toLowerCase() === cubeName.toLowerCase());
+        if (!cubeMeta) {
+            throw new TM1Error({
+                code: TM1ErrorCode.NOT_FOUND,
+                message: `Cube '${cubeName}' not found`,
+            });
+        }
+        const dims = cubeMeta.dimensions;
+        let coords = given;
+        let sandboxDefaulted;
+        if (dimensions !== undefined) {
+            if (given.length !== dimensions.length) {
+                throw dimensionCountMismatch(cubeName, dimensions, given);
+            }
+            const address = resolveCellAddress(cubeName, dims, dimensions);
+            coords = address.toCubeOrder(given);
+            sandboxDefaulted = address.sandboxDefaulted;
+        }
+        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
+            const element = coords[idx];
+            try {
+                const hier = await tm1Client.hierarchies.get(dim, dim);
+                const el = hier.elements.find((e) => e.name.toLowerCase() === element.toLowerCase());
+                if (!el) {
+                    return {
+                        dimension: dim,
+                        element,
+                        exists: false,
+                        type: "(missing)",
+                        isNLevel: false,
+                    };
+                }
+                return {
+                    dimension: dim,
+                    element: el.name,
+                    exists: true,
+                    type: el.type,
+                    isNLevel: el.type !== "Consolidated",
+                };
+            }
+            catch (e) {
+                // A transport/auth outage must not masquerade as a missing element —
+                // that would tell the agent to "repair" coordinates that are actually
+                // fine. Only genuine lookup failures (NOT_FOUND) fall through.
+                rethrowIfSystemic(e);
+                return {
+                    dimension: dim,
+                    element,
+                    exists: false,
+                    type: "(missing)",
+                    isNLevel: false,
+                };
+            }
+        }));
+        let ruleOverlapWarn = {
+            hasRules: false,
+            ruleLines: 0,
+            note: "",
+        };
+        try {
+            const rules = await tm1Client.cubes.getRules(cubeName);
+            const ruleText = (rules.rulesText ?? "").trim();
+            if (ruleText) {
+                ruleOverlapWarn = {
+                    hasRules: true,
+                    ruleLines: ruleText.split(/\r?\n/).length,
+                    note: "Cube has rules. CellPutN/S to a coord that the rule computes will be silently overridden by the rule. Inspect the rules manually for LHS pattern overlap with this coord.",
+                };
+            }
+        }
+        catch (e) {
+            // A missing/rule-less cube legitimately leaves the default; a systemic
+            // outage must surface rather than silently claim the cube has no rules.
+            rethrowIfSystemic(e);
+        }
+        const allExist = checks.every((c) => c.exists);
+        const allNLevel = checks.every((c) => c.isNLevel);
+        const writable = allExist && allNLevel;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        cube: cubeName,
+                        writable,
+                        allElementsExist: allExist,
+                        allElementsNLevel: allNLevel,
+                        coords: checks,
+                        ruleOverlapWarn,
+                        ...(sandboxDefaulted ? { sandboxDefaulted } : {}),
+                    }, null, 2),
+                },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=check-writable-coords.js.map

package/dist/tools/celldata/execute-mdx.d.ts

@@ -0,0 +1,17 @@
+import type { MdxAxis, CellValue } from "../../types.js";
+export interface MdxEnvelope {
+    axes: MdxAxis[];
+    total: number | null;
+    count: number;
+    offset: number;
+    has_more: boolean;
+    next_offset: number | null;
+    axes_clipped?: boolean;
+    items: Array<{
+        value: CellValue;
+        formattedValue: string;
+    }>;
+}
+export declare function renderMdxMarkdown(env: MdxEnvelope): string;
+export declare const registerExecuteMdx: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=execute-mdx.d.ts.map

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

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { PAGINATION_SCHEMA } from "../pagination.js";
+import { FORMAT_SCHEMA, 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);
+// Render an MDX cellset envelope as Markdown.
+//
+// Pivot grid when axis[0] (ON COLUMNS) and axis[1] (ON ROWS) drive the result
+// and every remaining axis is a single-tuple slicer/context (TM1 surfaces the
+// WHERE clause as a trailing single-tuple axis). Requires the full result
+// (offset 0, all cells). TM1 orders cells with axis[0] varying fastest and the
+// single-tuple context axes contribute index 0 (×1), so cell(r,c) still maps
+// to items[r*colCount + c]. Context tuples are noted above the grid.
+//
+// Anything else (0/1 axis, a genuine 3-D result, or a paginated slice where the
+// grid can't be reconstructed) → a flat table: one row per cell, coordinates
+// decoded from the global ordinal (offset + i), value last.
+export function renderMdxMarkdown(env) {
+    const { axes, items, total, count, offset, has_more } = env;
+    const meta = `_MDX cellset — ${count}${total !== null ? ` of ${total}` : ""} cells` +
+        `${offset > 0 ? `, offset ${offset}` : ""}${has_more ? ", more available" : ""}._`;
+    if (axes.length === 0 || items.length === 0) {
+        const scalar = items.length > 0 ? cellText(items[0]) : "(no cells)";
+        return `${meta}\n\n**Value:** ${scalar}`;
+    }
+    const contextAxes = axes.slice(2);
+    const fullSet = items.length === axes.reduce((a, ax) => a * ax.tuples.length, 1);
+    const isGrid = axes.length >= 2 &&
+        offset === 0 &&
+        fullSet &&
+        contextAxes.every((ax) => ax.tuples.length === 1);
+    if (isGrid) {
+        const cols = axes[0].tuples;
+        const rows = axes[1].tuples;
+        const colCount = cols.length;
+        const context = contextAxes
+            .map((ax) => mdCell(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 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(" | ")} |`;
+        });
+        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 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 `| ${[...coords, mdCell(cellText(cell))].join(" | ")} |`;
+    });
+    return [meta, "", header, sep, ...body].join("\n");
+}
+export const registerExecuteMdx = defineTool({
+    name: "tm1_execute_mdx",
+    description: [
+        "Execute an MDX query against the TM1 server and return structured cell data with axes (page-envelope shape consistent with list_*).",
+        "format='markdown' renders a pivot grid (2 axes, full result — set fetchAll=true to avoid a partial grid) or a flat coordinate table; 'json' (default) returns the structured envelope.",
+        "Related: tm1_create_mdx_view to persist a query as a public view, tm1_sample_cells for cheap sparsity probe, tm1_get_cell_value for a single coordinate.",
+    ],
+    annotations: READ_ONLY,
+    output: MdxResultSchema,
+    input: {
+        mdx: z.string().describe("The MDX query string to execute"),
+        ...PAGINATION_SCHEMA,
+        ...FORMAT_SCHEMA,
+        timeoutMs: z
+            .number()
+            .int()
+            .min(1000)
+            .max(3600000)
+            .optional()
+            .describe("Override the default 30s request timeout for this call (ms, 1000–3600000). Use for heavy MDX over wide views."),
+    },
+    handler: async ({ mdx, limit, offset, fetchAll, format, timeoutMs }, tm1Client, extra) => {
+        const all = fetchAll === true || limit === 0;
+        const top = all ? undefined : limit;
+        const skip = all ? undefined : offset;
+        const result = await withToolHint(tm1Client.cells.executeMdx(mdx, top, skip, {
+            signal: extra?.signal,
+            ...(timeoutMs ? { timeoutMs } : {}),
+        }), "MDX execution failed. Common causes: missing brackets around member names ([Dim].[Hier].[Member]), unbalanced FROM/SELECT, unknown cube. Inspect details; cross-check member names with tm1_get_hierarchy or tm1_list_cubes.");
+        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 huge 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 = {
+            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=execute-mdx.js.map

package/dist/tools/celldata/get-cell-value.d.ts

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

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

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { CellValueSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+export const registerGetCellValue = defineTool({
+    name: "tm1_get_cell_value",
+    description: [
+        "Get a single cell value from a TM1 cube by specifying element coordinates.",
+        "Discover dimension order with tm1_list_cubes (cube.dimensions).",
+        "Reading more than a few cells? One tm1_execute_mdx (slices/grids) or tm1_sample_cells (populated cells) call replaces a loop of get_cell_value calls.",
+        "Related: tm1_write_cells for the inverse operation.",
+    ],
+    annotations: READ_ONLY,
+    output: {
+        value: CellValueSchema.describe("Cell value (string, number, or null)"),
+    },
+    input: {
+        cubeName: z.string().describe("Name of the TM1 cube"),
+        elements: z
+            .array(z.string())
+            .describe("Element names for each dimension of the cube"),
+    },
+    handler: async ({ cubeName, elements }, tm1Client) => {
+        const value = await tm1Client.cells.getValue(cubeName, elements);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ value }) }],
+        };
+    },
+});
+//# sourceMappingURL=get-cell-value.js.map

package/dist/tools/celldata/get-view-definition.d.ts

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

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { READ_ONLY } from "../annotations.js";
+import { ViewDefinitionResultSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+export const registerGetViewDefinition = defineTool({
+    name: "tm1_get_view_definition",
+    description: [
+        "Return the structural definition of a cube view (MDX expression OR NativeView axes)",
+        "WITHOUT executing it. Use tm1_get_view to execute and read cells.",
+        "Auto-detects public vs private when isPrivate is omitted (public tried first).",
+    ],
+    annotations: READ_ONLY,
+    output: ViewDefinitionResultSchema,
+    input: {
+        cubeName: z.string().describe("Name of the TM1 cube"),
+        viewName: z.string().describe("Name of the view"),
+        isPrivate: z
+            .boolean()
+            .optional()
+            .describe("If true, look only in PrivateViews. If false, only in Views. If omitted, public is tried first then private."),
+    },
+    handler: async ({ cubeName, viewName, isPrivate }, tm1Client) => {
+        const result = await tm1Client.views.getDefinition(cubeName, viewName, isPrivate);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+        };
+    },
+});
+//# sourceMappingURL=get-view-definition.js.map

package/dist/tools/celldata/get-view.d.ts

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