@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tools/hierarchy.js

@@ -0,0 +1,27 @@
+// Optional `hierarchyName` that defaults to the dimension's same-named
+// hierarchy. Every TM1 dimension has one, and it is what callers mean in the
+// overwhelming majority of calls — omitting the field was the single most
+// common schema error (-32602) in recorded usage.
+//
+// Pattern in a tool registration:
+//
+//   input: { dimensionName: z.string(), ...HIERARCHY_NAME_OPTIONAL, ... },
+//   handler: async ({ dimensionName, hierarchyName }) => {
+//     const hierarchy = resolveHierarchy(dimensionName, hierarchyName);
+//     ...
+//   }
+//
+// Resolve before any confirm check or service call so both see the effective
+// name. Tools whose hierarchy is the subject of a create/delete keep the field
+// required: the default hierarchy cannot be created or deleted on its own.
+import { z } from "zod";
+export const HIERARCHY_NAME_OPTIONAL = {
+    hierarchyName: z
+        .string()
+        .optional()
+        .describe("Hierarchy within the dimension. Defaults to the dimension's same-named hierarchy."),
+};
+export function resolveHierarchy(dimensionName, hierarchyName) {
+    return hierarchyName ?? dimensionName;
+}
+//# sourceMappingURL=hierarchy.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TM1Client } from "../tm1-client.js";
+export declare function registerAllTools(server: McpServer, tm1Client: TM1Client): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,263 @@
+// Metadata tools
+import { registerListCubes } from "./metadata/list-cubes.js";
+import { registerListDimensions } from "./metadata/list-dimensions.js";
+import { registerGetHierarchy } from "./metadata/get-hierarchy.js";
+import { registerGetDescendants } from "./metadata/get-descendants.js";
+import { registerGetAncestors } from "./metadata/get-ancestors.js";
+import { registerResolveDefaultMembers } from "./metadata/resolve-default-members.js";
+import { registerListProcesses } from "./metadata/list-processes.js";
+import { registerListProcessesGrouped } from "./metadata/list-processes-grouped.js";
+import { registerListChores } from "./metadata/list-chores.js";
+// Cell data tools
+import { registerGetCellValue } from "./celldata/get-cell-value.js";
+import { registerExecuteMdx } from "./celldata/execute-mdx.js";
+import { registerGetView } from "./celldata/get-view.js";
+import { registerGetViewDefinition } from "./celldata/get-view-definition.js";
+import { registerSampleCells } from "./celldata/sample-cells.js";
+import { registerWriteCells } from "./celldata/write-cells.js";
+import { registerCheckFeeders } from "./celldata/check-feeders.js";
+import { registerTraceFeeders } from "./celldata/trace-feeders.js";
+import { registerTraceCellCalculation } from "./celldata/trace-cell-calculation.js";
+// TI development tools (process CRUD, execution, code, params, datasource)
+import { registerExecuteProcess } from "./ti-development/execute-process.js";
+import { registerGetProcessParameters } from "./ti-development/get-process-parameters.js";
+import { registerGetProcessCode } from "./ti-development/get-process-code.js";
+import { registerGetProcess } from "./ti-development/get-process.js";
+import { registerGetProcessDatasource } from "./ti-development/get-process-datasource.js";
+import { registerGetProcessVariables } from "./ti-development/get-process-variables.js";
+import { registerDeleteProcess } from "./ti-development/delete-process.js";
+import { registerCopyProcess } from "./ti-development/copy-process.js";
+import { registerCompileProcess } from "./ti-development/compile-process.js";
+import { registerCheckProcessCode } from "./ti-development/check-process-code.js";
+import { registerGetAllProcessesCode } from "./ti-development/get-all-processes-code.js";
+import { registerSearchCode } from "./ti-development/search-code.js";
+import { registerImportProFile } from "./ti-development/import-pro-file.js";
+import { registerExportProcessToPro } from "./ti-development/export-process-to-pro.js";
+import { registerDiffProcessWithFile } from "./ti-development/diff-process-with-file.js";
+import { registerDiffProcesses } from "./ti-development/diff-processes.js";
+import { registerValidateProcessRefs } from "./ti-development/validate-process-refs.js";
+import { registerUpsertProcess } from "./ti-development/upsert-process.js";
+import { registerInstallProBundle } from "./ti-development/install-pro-bundle.js";
+import { registerExportProcessToGit } from "./ti-development/export-process-to-git.js";
+import { registerImportProcessFromGit } from "./ti-development/import-process-from-git.js";
+import { registerCheckWritableCoords } from "./celldata/check-writable-coords.js";
+// Dimension management tools
+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";
+import { registerListElementAttributes } from "./dimension-management/list-element-attributes.js";
+import { registerCreateElementAttribute } from "./dimension-management/create-element-attribute.js";
+import { registerGetElementAttributeValues } from "./dimension-management/get-element-attribute-values.js";
+import { registerUpdateElementAttributeValue } from "./dimension-management/update-element-attribute-value.js";
+import { registerCreateHierarchy } from "./dimension-management/create-hierarchy.js";
+import { registerDeleteHierarchy } from "./dimension-management/delete-hierarchy.js";
+// Subset tools
+import { registerListSubsets } from "./subsets/list-subsets.js";
+import { registerGetSubset } from "./subsets/get-subset.js";
+import { registerCreateSubset } from "./subsets/create-subset.js";
+import { registerUpdateSubset } from "./subsets/update-subset.js";
+import { registerDeleteSubset } from "./subsets/delete-subset.js";
+// Model building tools
+import { registerCreateCube } from "./model-building/create-cube.js";
+import { registerDeleteCube } from "./model-building/delete-cube.js";
+import { registerGetCubeRules } from "./model-building/get-cube-rules.js";
+import { registerSetCubeRules } from "./model-building/set-cube-rules.js";
+import { registerClearCube } from "./model-building/clear-cube.js";
+import { registerUnloadCube } from "./model-building/unload-cube.js";
+import { registerGetAllCubeRules } from "./model-building/get-all-cube-rules.js";
+import { registerCheckCubeRule } from "./model-building/check-cube-rule.js";
+import { registerSearchRules } from "./model-building/search-rules.js";
+// View tools
+import { registerListViews } from "./views/list-views.js";
+import { registerCreateMdxView } from "./views/create-mdx-view.js";
+import { registerCreateNativeView } from "./views/create-native-view.js";
+import { registerDeleteView } from "./views/delete-view.js";
+// Scheduling tools
+import { registerToggleChore } from "./scheduling/toggle-chore.js";
+import { registerExecuteChore } from "./scheduling/execute-chore.js";
+import { registerCreateChore } from "./scheduling/create-chore.js";
+import { registerUpdateChore } from "./scheduling/update-chore.js";
+import { registerDeleteChore } from "./scheduling/delete-chore.js";
+// Operations tools
+import { registerGetMessageLog } from "./operations/get-message-log.js";
+import { registerGetThreads } from "./operations/get-threads.js";
+import { registerGetJobs } from "./operations/get-jobs.js";
+import { registerGetServerInfo } from "./operations/get-server-info.js";
+import { registerGetServerState } from "./operations/get-server-state.js";
+import { registerGetTransactionLog } from "./operations/get-transaction-log.js";
+import { registerGetAuditLog } from "./operations/get-audit-log.js";
+import { registerGetSessions } from "./operations/get-sessions.js";
+import { registerListErrorLogs } from "./operations/list-error-logs.js";
+import { registerGetErrorLogContent } from "./operations/get-error-log-content.js";
+import { registerDiagnoseProcessError } from "./operations/diagnose-process-error.js";
+import { registerGetCubeStats } from "./operations/get-cube-stats.js";
+import { registerSaveData } from "./operations/save-data.js";
+// File operations tools
+import { registerListFiles } from "./fileops/list-files.js";
+import { registerGetFileContent } from "./fileops/get-file-content.js";
+import { registerUploadFile } from "./fileops/upload-file.js";
+import { registerDeleteFile } from "./fileops/delete-file.js";
+import { registerSearchFiles } from "./fileops/search-files.js";
+// Analysis tools
+import { registerAnalyzeCallgraph } from "./analysis/analyze-callgraph.js";
+import { registerAnalyzeObjectUsage } from "./analysis/analyze-object-usage.js";
+import { registerTraceDataFlow } from "./analysis/trace-data-flow.js";
+import { registerAnalyzeChoreGraph } from "./analysis/analyze-chore-graph.js";
+import { registerInvalidateCallgraphCache } from "./analysis/invalidate-callgraph-cache.js";
+import { registerFindOrphanDimensions } from "./analysis/find-orphan-dimensions.js";
+import { registerCheckV12Readiness } from "./analysis/check-v12-readiness.js";
+import { registerAuditNaming } from "./analysis/audit-naming.js";
+import { registerAuditComplexity } from "./analysis/audit-complexity.js";
+import { registerAuditFeeders } from "./analysis/audit-feeders.js";
+// Security tools
+import { registerListClients } from "./security/list-clients.js";
+import { registerGetClient } from "./security/get-client.js";
+import { registerCreateClient } from "./security/create-client.js";
+import { registerUpdateClient } from "./security/update-client.js";
+import { registerDeleteClient } from "./security/delete-client.js";
+import { registerListGroups } from "./security/list-groups.js";
+import { registerAssignClientGroup } from "./security/assign-client-group.js";
+import { registerRemoveClientGroup } from "./security/remove-client-group.js";
+// Single registry of every tool registrar, grouped by category. Adding a tool
+// = add its import above and one entry here (adjacent edit, one PR hunk). The
+// previous design kept a second hand-ordered call block that drifted from the
+// import order; this array is the only call site. check-tool-registration.mjs
+// fails the build if a `register*` export under src/tools/ is missing here.
+const REGISTRARS = [
+    // Metadata
+    registerListCubes,
+    registerListDimensions,
+    registerGetHierarchy,
+    registerGetDescendants,
+    registerGetAncestors,
+    registerResolveDefaultMembers,
+    registerListProcesses,
+    registerListProcessesGrouped,
+    registerListChores,
+    // Cell data
+    registerGetCellValue,
+    registerExecuteMdx,
+    registerGetView,
+    registerGetViewDefinition,
+    registerSampleCells,
+    registerWriteCells,
+    registerCheckFeeders,
+    registerTraceFeeders,
+    registerTraceCellCalculation,
+    registerCheckWritableCoords,
+    // TI development — writes go through registerUpsertProcess (bundled),
+    // reads remain atomic for inspection without pulling full process code.
+    registerExecuteProcess,
+    registerGetProcessParameters,
+    registerGetProcessCode,
+    registerGetProcess,
+    registerGetProcessDatasource,
+    registerGetProcessVariables,
+    registerDeleteProcess,
+    registerCopyProcess,
+    registerCompileProcess,
+    registerCheckProcessCode,
+    registerGetAllProcessesCode,
+    registerSearchCode,
+    registerImportProFile,
+    registerExportProcessToPro,
+    registerDiffProcessWithFile,
+    registerDiffProcesses,
+    registerValidateProcessRefs,
+    registerUpsertProcess,
+    registerInstallProBundle,
+    registerExportProcessToGit,
+    registerImportProcessFromGit,
+    // Dimension management
+    registerCreateDimension,
+    registerDeleteDimension,
+    registerBulkUpsertElements,
+    registerCreateElement,
+    registerUpdateElement,
+    registerDeleteElement,
+    registerDeleteElements,
+    registerMoveElement,
+    registerListElementAttributes,
+    registerCreateElementAttribute,
+    registerGetElementAttributeValues,
+    registerUpdateElementAttributeValue,
+    registerCreateHierarchy,
+    registerDeleteHierarchy,
+    // Subsets
+    registerListSubsets,
+    registerGetSubset,
+    registerCreateSubset,
+    registerUpdateSubset,
+    registerDeleteSubset,
+    // Model building
+    registerCreateCube,
+    registerDeleteCube,
+    registerGetCubeRules,
+    registerSetCubeRules,
+    registerClearCube,
+    registerUnloadCube,
+    registerGetAllCubeRules,
+    registerCheckCubeRule,
+    registerSearchRules,
+    // Views
+    registerListViews,
+    registerCreateMdxView,
+    registerCreateNativeView,
+    registerDeleteView,
+    // Scheduling
+    registerToggleChore,
+    registerExecuteChore,
+    registerCreateChore,
+    registerUpdateChore,
+    registerDeleteChore,
+    // Operations
+    registerGetMessageLog,
+    registerGetThreads,
+    registerGetJobs,
+    registerGetServerInfo,
+    registerGetServerState,
+    registerGetTransactionLog,
+    registerGetAuditLog,
+    registerGetSessions,
+    registerListErrorLogs,
+    registerGetErrorLogContent,
+    registerDiagnoseProcessError,
+    registerGetCubeStats,
+    registerSaveData,
+    // File operations
+    registerListFiles,
+    registerGetFileContent,
+    registerUploadFile,
+    registerDeleteFile,
+    registerSearchFiles,
+    // Analysis
+    registerAnalyzeCallgraph,
+    registerAnalyzeObjectUsage,
+    registerTraceDataFlow,
+    registerAnalyzeChoreGraph,
+    registerInvalidateCallgraphCache,
+    registerFindOrphanDimensions,
+    registerCheckV12Readiness,
+    registerAuditNaming,
+    registerAuditComplexity,
+    registerAuditFeeders,
+    // Security
+    registerListClients,
+    registerGetClient,
+    registerCreateClient,
+    registerUpdateClient,
+    registerDeleteClient,
+    registerListGroups,
+    registerAssignClientGroup,
+    registerRemoveClientGroup,
+];
+export function registerAllTools(server, tm1Client) {
+    for (const register of REGISTRARS)
+        register(server, tm1Client);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/local-file.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Confine a caller-supplied host filesystem path to the directory configured via
+ * `TM1_LOCAL_FILE_ROOT`.
+ *
+ * Host-file access (the `filePath` / `writeToFile` / `directory` parameters on the
+ * `.pro` round-trip tools) is DISABLED by default: without the env var set, those
+ * tools only accept inline `content`. This keeps arbitrary host file read/write off
+ * the default (readonly) tool surface — a prompt-injected agent cannot coerce the
+ * server into reading `/proc/self/environ` (which would leak TM1 credentials),
+ * `~/.ssh/id_rsa`, or writing to arbitrary locations.
+ *
+ * When the root IS configured, the resolved absolute path must stay within it; any
+ * `..` traversal or absolute escape is rejected. Returns the resolved absolute path.
+ */
+export declare function resolveLocalPath(inputPath: string, paramName?: string): string;
+//# sourceMappingURL=local-file.d.ts.map

package/dist/tools/local-file.js

@@ -0,0 +1,88 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { TM1Error, TM1ErrorCode } from "../types.js";
+const ROOT_ENV = "TM1_LOCAL_FILE_ROOT";
+/**
+ * Resolve symlinks as deeply as the filesystem allows: realpath the nearest
+ * EXISTING ancestor (the target itself may not exist yet — write paths are
+ * confined before the file is created), then re-append the not-yet-existing
+ * tail lexically. Walks up one component at a time until realpathSync stops
+ * throwing; at worst it terminates at the filesystem root.
+ */
+function realpathNearestExisting(p) {
+    let current = p;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync(current);
+            return tail.length === 0 ? real : path.join(real, ...tail);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current) {
+                // Nothing on the path exists (not even "/", practically unreachable);
+                // fall back to the lexical path so the caller's check still runs.
+                return path.join(current, ...tail);
+            }
+            tail.unshift(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * Confine a caller-supplied host filesystem path to the directory configured via
+ * `TM1_LOCAL_FILE_ROOT`.
+ *
+ * Host-file access (the `filePath` / `writeToFile` / `directory` parameters on the
+ * `.pro` round-trip tools) is DISABLED by default: without the env var set, those
+ * tools only accept inline `content`. This keeps arbitrary host file read/write off
+ * the default (readonly) tool surface — a prompt-injected agent cannot coerce the
+ * server into reading `/proc/self/environ` (which would leak TM1 credentials),
+ * `~/.ssh/id_rsa`, or writing to arbitrary locations.
+ *
+ * When the root IS configured, the resolved absolute path must stay within it; any
+ * `..` traversal or absolute escape is rejected. Returns the resolved absolute path.
+ */
+export function resolveLocalPath(inputPath, paramName = "filePath") {
+    const root = process.env[ROOT_ENV]?.trim();
+    if (!root) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `Host-file access is disabled. Set ${ROOT_ENV} to an allowed directory to enable ` +
+                `'${paramName}', or pass the .pro content inline via the 'content' parameter instead.`,
+        });
+    }
+    if (!path.isAbsolute(inputPath)) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `${paramName} must be absolute: ${inputPath}`,
+        });
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(inputPath);
+    const rel = path.relative(resolvedRoot, resolved);
+    if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `${paramName} escapes the allowed ${ROOT_ENV} directory (${resolvedRoot}): ${inputPath}`,
+        });
+    }
+    // Symlink-safe second check: the lexical check above is bypassable by a
+    // symlink placed INSIDE the root that points outside it. Compare real paths
+    // instead — and realpath the root too, since the root itself may
+    // legitimately be a symlink (e.g. /tmp on some systems).
+    const realRoot = realpathNearestExisting(resolvedRoot);
+    const realResolved = realpathNearestExisting(resolved);
+    const relReal = path.relative(realRoot, realResolved);
+    if (relReal === ".." ||
+        relReal.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relReal)) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `${paramName} escapes the allowed ${ROOT_ENV} directory (${resolvedRoot}) ` +
+                `after resolving symlinks: ${inputPath}`,
+        });
+    }
+    return resolved;
+}
+//# sourceMappingURL=local-file.js.map

package/dist/tools/metadata/get-ancestors.d.ts

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

package/dist/tools/metadata/get-ancestors.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { HIERARCHY_NAME_OPTIONAL, resolveHierarchy } from "../hierarchy.js";
+import { READ_ONLY } from "../annotations.js";
+import { AncestorsResultSchema } from "../schemas/items.js";
+import { FORMAT_SCHEMA, payloadResponse, renderTable, columnsOf, } from "../format.js";
+export const registerGetAncestors = defineTool({
+    name: "tm1_get_ancestors",
+    description: [
+        "Get all ancestors of an element via parent-walk. Multi-parent safe: returns the unique flat ancestor set AND every distinct root-to-element path.",
+        "Use to find roll-up paths or detect that an element rolls up to multiple consolidations (alternate hierarchies).",
+        "Output: { element, ancestors: [{ name, level }], paths: [[ root, ..., element ]] }.",
+    ],
+    annotations: READ_ONLY,
+    output: AncestorsResultSchema,
+    input: {
+        dimensionName: z.string().describe("Name of the TM1 dimension"),
+        ...HIERARCHY_NAME_OPTIONAL,
+        elementName: z
+            .string()
+            .describe("Element whose ancestors are requested. Root elements return empty ancestors and a single self-only path."),
+        ...FORMAT_SCHEMA,
+    },
+    handler: async ({ dimensionName, hierarchyName, elementName, format }, tm1Client) => {
+        const hierarchy = resolveHierarchy(dimensionName, hierarchyName);
+        const result = await tm1Client.hierarchies.getAncestors(dimensionName, hierarchy, elementName);
+        const columns = columnsOf(["name", "level"]);
+        return payloadResponse(result, format, (r) => {
+            const pathLines = r.paths
+                .map((p, i) => `${i + 1}. ${p.join(" → ")}`)
+                .join("\n");
+            return `## Ancestors of ${r.element}\n\n${renderTable(r.ancestors, columns)}\n\n### Paths\n\n${pathLines || "_(no paths)_"}`;
+        });
+    },
+});
+//# sourceMappingURL=get-ancestors.js.map

package/dist/tools/metadata/get-descendants.d.ts

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

package/dist/tools/metadata/get-descendants.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { FORMAT_SCHEMA, payloadResponse, renderTable, columnsOf, } from "../format.js";
+import { DescendantsResultSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+import { HIERARCHY_NAME_OPTIONAL, resolveHierarchy } from "../hierarchy.js";
+export const registerGetDescendants = defineTool({
+    name: "tm1_get_descendants",
+    description: [
+        "Get descendants of a consolidation element. Token-efficient alternative to tm1_get_hierarchy when you only need a subtree.",
+        "depth caps how many levels below the start element are returned (depth=1 = direct children).",
+        "leavesOnly=true keeps only N-elements (no consolidations). Multi-parent hierarchies: each unique element appears once.",
+        "Result capped to topN (default 1000) with truncated=true when the cap clips — raise topN for more.",
+        "Output: { element, descendants: [{ name, type, level, depth }], truncated }.",
+    ],
+    annotations: READ_ONLY,
+    output: DescendantsResultSchema,
+    input: {
+        dimensionName: z.string().describe("Name of the TM1 dimension"),
+        ...HIERARCHY_NAME_OPTIONAL,
+        elementName: z
+            .string()
+            .describe("Start element (typically a consolidation). Numeric/leaf elements return empty descendants."),
+        depth: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Max depth below the start element. Omit for unlimited."),
+        leavesOnly: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return only leaf elements (no consolidations)."),
+        topN: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .default(1000)
+            .describe("Max descendants returned (default 1000). Caps large subtrees; result sets truncated=true when the cap clipped the set. Raise to fetch more."),
+        ...FORMAT_SCHEMA,
+    },
+    handler: async ({ dimensionName, hierarchyName, elementName, depth, leavesOnly, topN, format, }, tm1Client) => {
+        const hierarchy = resolveHierarchy(dimensionName, hierarchyName);
+        const full = await tm1Client.hierarchies.getDescendants(dimensionName, hierarchy, elementName, {
+            ...(depth !== undefined ? { depth } : {}),
+            ...(leavesOnly !== undefined ? { leavesOnly } : {}),
+        });
+        // The traversal is client-side (BFS over the fetched hierarchy), so the
+        // full descendant set is known here — truncated is exact, not a heuristic.
+        const truncated = full.descendants.length > topN;
+        const result = {
+            element: full.element,
+            descendants: truncated
+                ? full.descendants.slice(0, topN)
+                : full.descendants,
+            truncated,
+        };
+        const columns = columnsOf(["name", "type", "level", "depth"]);
+        return payloadResponse(result, format, (r) => `## Descendants of ${r.element}\n\n${r.descendants.length} elements\n\n${renderTable(r.descendants, columns)}`);
+    },
+});
+//# sourceMappingURL=get-descendants.js.map

package/dist/tools/metadata/get-hierarchy.d.ts

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

package/dist/tools/metadata/get-hierarchy.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { HierarchySchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+import { HIERARCHY_NAME_OPTIONAL, resolveHierarchy } from "../hierarchy.js";
+export const registerGetHierarchy = defineTool({
+    name: "tm1_get_hierarchy",
+    description: [
+        "Get hierarchy elements with parent-child relationships for a dimension.",
+        "To size a dimension, pass countOnly=true (totals by type and level, no elements) or narrow with nameContains/nameStartsWith before paging — don't probe with growing topN.",
+        "Filters (level/levelMax/elementType, name filters, compact) reduce payload; capped to topN (default 1000) with truncated=true when the cap clips.",
+        "Elements are ordered by name; walk large dimensions with offset (total/has_more count the filtered element set) rather than raising topN.",
+        "Filtered-out parents/children are pruned from remaining elements to avoid dangling references.",
+    ],
+    annotations: READ_ONLY,
+    output: HierarchySchema,
+    input: {
+        dimensionName: z.string().describe("Name of the TM1 dimension"),
+        ...HIERARCHY_NAME_OPTIONAL,
+        level: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Exact level filter (0 = leaves, 1+ = consolidations). Combinable with levelMax."),
+        levelMax: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Keep elements with Level ≤ levelMax. Caps deep hierarchies."),
+        elementType: z
+            .enum(["Numeric", "String", "Consolidated", "All"])
+            .optional()
+            .describe("Filter by element type. Default: All."),
+        nameContains: z
+            .string()
+            .optional()
+            .describe("Server-side OData substring filter (contains). Case-sensitive. Combine with other filters via AND."),
+        nameStartsWith: z
+            .string()
+            .optional()
+            .describe("Server-side OData prefix filter (startswith). Case-sensitive."),
+        nameRegex: z
+            .string()
+            .optional()
+            .describe("Client-side regex filter on element name (JS RegExp). Use for patterns OData cannot express. Invalid regex throws VALIDATION_ERROR."),
+        topN: z
+            .number()
+            .int()
+            .positive()
+            // Ceiling, not a page size: without it a caller can ask for a whole
+            // 200k-element dimension in one response. `offset` exists precisely so
+            // large dimensions get walked rather than swallowed.
+            .max(10000)
+            .optional()
+            .default(1000)
+            .describe("Page size — max elements returned after filter (default 1000, max 10000). Combine with offset to walk past it; truncated/has_more say whether more remain."),
+        offset: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .default(0)
+            .describe("Elements to skip before topN (default 0). Use next page = offset + topN while has_more is true."),
+        countOnly: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return only totals of the filtered set (counts.byType, counts.byLevel, counts.maxLevel) with an empty elements array. Filters apply; topN/offset/compact are ignored."),
+        compact: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Drop parents[] and children[] arrays from each element. Use for hierarchy overviews."),
+    },
+    handler: async ({ dimensionName, hierarchyName, level, levelMax, elementType, nameContains, nameStartsWith, nameRegex, topN, offset, countOnly, compact, }, tm1Client) => {
+        const hierName = resolveHierarchy(dimensionName, hierarchyName);
+        const filterOpts = {
+            ...(level !== undefined ? { level } : {}),
+            ...(levelMax !== undefined ? { levelMax } : {}),
+            ...(elementType !== undefined ? { elementType } : {}),
+            ...(nameContains !== undefined ? { nameContains } : {}),
+            ...(nameStartsWith !== undefined ? { nameStartsWith } : {}),
+            ...(nameRegex !== undefined ? { nameRegex } : {}),
+        };
+        if (countOnly) {
+            const { total, ...counts } = await tm1Client.hierarchies.getCounts(dimensionName, hierName, filterOpts);
+            const output = {
+                name: hierName,
+                dimensionName,
+                elements: [],
+                truncated: false,
+                total,
+                offset: 0,
+                has_more: false,
+                counts,
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(output) }],
+            };
+        }
+        const { totalElements, ...hierarchy } = await tm1Client.hierarchies.get(dimensionName, hierName, { ...filterOpts, topN, skip: offset });
+        // `totalElements` counts the whole filtered set, so this is exact — the
+        // old `elements.length === topN` test cried truncation whenever the last
+        // page happened to be exactly topN long.
+        const has_more = offset + hierarchy.elements.length < totalElements;
+        const elements = compact
+            ? hierarchy.elements.map((e) => ({
+                name: e.name,
+                type: e.type,
+                level: e.level,
+            }))
+            : hierarchy.elements;
+        const output = {
+            ...hierarchy,
+            elements,
+            // Kept as the pre-paging name for `has_more`; both mean "elements the
+            // cap left behind".
+            truncated: has_more,
+            total: totalElements,
+            offset,
+            has_more,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output) }],
+        };
+    },
+});
+//# sourceMappingURL=get-hierarchy.js.map

package/dist/tools/metadata/list-chores.d.ts

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