@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/services/view-service.d.ts

@@ -0,0 +1,46 @@
+import type { CubeView, NativeViewCreate, ViewDefinition, ViewResult } from "../../types.js";
+import type { RequestOptions, TM1HttpClient } from "../http.js";
+export declare class ViewService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * List public + private views on a cube. Each view's MDX is included if it
+     * is an MDXView; native views surface with mdx=undefined.
+     * GET /api/v1/Cubes('{c}')/Views + /PrivateViews
+     */
+    list(cubeName: string): Promise<CubeView[]>;
+    /**
+     * Execute a named view and return its cells + axes. Cells paginate
+     * server-side via $top/$skip (mirrors CellService.executeMdx) so wide/tall
+     * views don't dump their whole cellset; totalCellCount stays exact (product
+     * of axis tuple counts) regardless of the slice.
+     * POST /api/v1/Cubes('{c}')/Views('{v}')/tm1.Execute
+     */
+    getView(cubeName: string, viewName: string, top?: number, skip?: number, opts?: RequestOptions): Promise<ViewResult>;
+    /**
+     * Return the structural definition of a view (MDX expression OR native
+     * axes) WITHOUT executing it. Auto-falls back from public to private when
+     * isPrivate is undefined.
+     * GET /api/v1/Cubes('X')/Views('Y') with tm1.NativeView/* expands.
+     */
+    getDefinition(cubeName: string, viewName: string, isPrivate?: boolean): Promise<ViewDefinition>;
+    /**
+     * Create a public MDX-based view on a cube.
+     * POST /api/v1/Cubes('{c}')/Views with @odata.type = #ibm.tm1.api.v1.MDXView
+     */
+    createMdx(cubeName: string, viewName: string, mdx: string): Promise<void>;
+    /**
+     * Create a public native view on a cube. Each axis entry references exactly
+     * one subset source: a registered subset (`subset`), an MDX expression
+     * (`expression`), or an explicit element list (`elements`). The latter two
+     * create anonymous (view-private) subsets server-side.
+     * POST /api/v1/Cubes('{c}')/Views with @odata.type = #ibm.tm1.api.v1.NativeView
+     */
+    createNative(cubeName: string, viewName: string, spec: NativeViewCreate): Promise<void>;
+    /**
+     * Delete a public view from a cube.
+     * DELETE /api/v1/Cubes('{c}')/Views('{v}')
+     */
+    delete(cubeName: string, viewName: string): Promise<void>;
+}
+//# sourceMappingURL=view-service.d.ts.map

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

@@ -0,0 +1,287 @@
+// View domain service. Owns the OData calls under
+// /api/v1/Cubes('{c}')/Views and /PrivateViews — list, create (MDX-based),
+// delete, execute (getView), and the structural definition (getDefinition)
+// that returns either MDX or NativeView (titles/columns/rows) without
+// executing.
+//
+// See docs/ARCHITECTURE.md for the layering.
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { freeCellset, transformCellsetResponse } from "./cellset-transform.js";
+import { rethrowIfSystemicOrDenied } from "./fallback.js";
+// OData key encoder: double ' per OData literal rules, then percent-encode.
+const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+export class ViewService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List public + private views on a cube. Each view's MDX is included if it
+     * is an MDXView; native views surface with mdx=undefined.
+     * GET /api/v1/Cubes('{c}')/Views + /PrivateViews
+     */
+    async list(cubeName) {
+        // Public and private scopes are independent collections — issue both at
+        // once instead of paying two serial round-trips. Each keeps its own
+        // rethrow/swallow behaviour, and the results are concatenated in the
+        // original order (public first), so callers see no change but the wait.
+        //
+        // MDX stays in the $select: tm1_list_views advertises it as part of the
+        // response, so dropping it to save bytes would be a breaking output change,
+        // not an optimisation.
+        const fetchScope = async (collection, isPrivate) => {
+            try {
+                const res = await this.http.request("GET", `/api/v1/Cubes('${enc(cubeName)}')/${collection}?$select=Name,MDX`);
+                return res.value.map((v) => ({
+                    name: v.Name,
+                    mdx: v.MDX,
+                    private: isPrivate,
+                }));
+            }
+            catch (e) {
+                // T-9: an empty list here is indistinguishable from "this cube has no
+                // views", so a denial must NOT be swallowed — "you may not see them" is
+                // a different answer and the caller has to be told. Same reasoning the
+                // transaction-log window already uses. What stays swallowed is the case
+                // the catch was written for: a scope this server does not expose at all
+                // (404 on /PrivateViews), which really is "not there".
+                rethrowIfSystemicOrDenied(e);
+                return [];
+            }
+        };
+        const [pub, priv] = await Promise.all([
+            fetchScope("Views", false),
+            fetchScope("PrivateViews", true),
+        ]);
+        return [...pub, ...priv];
+    }
+    /**
+     * Execute a named view and return its cells + axes. Cells paginate
+     * server-side via $top/$skip (mirrors CellService.executeMdx) so wide/tall
+     * views don't dump their whole cellset; totalCellCount stays exact (product
+     * of axis tuple counts) regardless of the slice.
+     * POST /api/v1/Cubes('{c}')/Views('{v}')/tm1.Execute
+     */
+    async getView(cubeName, viewName, top, skip, opts) {
+        let cellsExpand = "Cells($select=Value,FormattedValue";
+        if (top !== undefined)
+            cellsExpand += `;$top=${top}`;
+        if (skip !== undefined)
+            cellsExpand += `;$skip=${skip}`;
+        cellsExpand += ")";
+        const axesExpand = "Axes($expand=Tuples($expand=Members($select=Name;$expand=Hierarchy($select=Name))))";
+        const path = `/api/v1/Cubes('${enc(cubeName)}')/Views('${enc(viewName)}')/tm1.Execute?$expand=${cellsExpand},${axesExpand}`;
+        const response = await this.http.request("POST", path, undefined, opts);
+        try {
+            const mdxResult = transformCellsetResponse(response);
+            return {
+                cubeName,
+                viewName,
+                cells: mdxResult.cells,
+                axes: mdxResult.axes,
+                totalCellCount: mdxResult.totalCellCount,
+            };
+        }
+        finally {
+            // Cellsets are session-scoped and never auto-expire while keep-alive holds
+            // the session open; free the read-path cellset best-effort so it doesn't
+            // leak TM1 server memory indefinitely (mirrors TM1py's delete_cellset).
+            await freeCellset(this.http, response.ID, opts);
+        }
+    }
+    /**
+     * Return the structural definition of a view (MDX expression OR native
+     * axes) WITHOUT executing it. Auto-falls back from public to private when
+     * isPrivate is undefined.
+     * GET /api/v1/Cubes('X')/Views('Y') with tm1.NativeView/* expands.
+     */
+    async getDefinition(cubeName, viewName, isPrivate) {
+        const fetchBase = async (segment) => {
+            const path = `/api/v1/Cubes('${enc(cubeName)}')/${segment}('${enc(viewName)}')?$select=Name,MDX`;
+            return this.http.request("GET", path);
+        };
+        const order = isPrivate === true
+            ? [{ seg: "PrivateViews", priv: true }]
+            : isPrivate === false
+                ? [{ seg: "Views", priv: false }]
+                : [
+                    { seg: "Views", priv: false },
+                    { seg: "PrivateViews", priv: true },
+                ];
+        let base = null;
+        let resolvedSeg = "Views";
+        let resolvedPrivate = false;
+        let lastErr = null;
+        for (const { seg, priv } of order) {
+            try {
+                base = await fetchBase(seg);
+                resolvedSeg = seg;
+                resolvedPrivate = priv;
+                break;
+            }
+            catch (e) {
+                lastErr = e;
+            }
+        }
+        if (!base) {
+            if (lastErr instanceof TM1Error)
+                throw lastErr;
+            throw new TM1Error({
+                code: TM1ErrorCode.NOT_FOUND,
+                message: `View not found: ${cubeName}/${viewName}`,
+                endpoint: `/api/v1/Cubes('${cubeName}')/Views('${viewName}')`,
+            });
+        }
+        const isMdx = typeof base.MDX === "string" && base.MDX.length > 0;
+        if (isMdx) {
+            return {
+                cubeName,
+                viewName,
+                private: resolvedPrivate,
+                type: "MDX",
+                mdx: base.MDX,
+            };
+        }
+        // Titles/Columns/Rows are complex-type collections — TM1 11.8 rejects
+        // parenthesized expand options directly on them ("Expecting '/' after
+        // property of complex type in expand path") AND pure path form past the
+        // entity ("Expecting qualified entity type"). Working syntax
+        // (live-verified on 11.8): path through the complex part, parenthesized
+        // options from the first entity (Subset) on.
+        const subsetExpand = "Subset($expand=Hierarchy($expand=Dimension))";
+        const nativeExpand = [
+            `Titles/${subsetExpand}`,
+            "Titles/Selected",
+            `Columns/${subsetExpand}`,
+            `Rows/${subsetExpand}`,
+        ].join(",");
+        const nativePath = `/api/v1/Cubes('${enc(cubeName)}')/${resolvedSeg}('${enc(viewName)}')/tm1.NativeView?$expand=${nativeExpand}`;
+        let native;
+        try {
+            native = await this.http.request("GET", nativePath);
+        }
+        catch (e) {
+            if (e instanceof TM1Error && e.httpStatus === 404) {
+                return {
+                    cubeName,
+                    viewName,
+                    private: resolvedPrivate,
+                    type: "Native",
+                    native: { titles: [], columns: [], rows: [] },
+                };
+            }
+            throw e;
+        }
+        const mapAxis = (a) => {
+            const s = a.Subset ?? {};
+            return {
+                dimensionName: s.Hierarchy?.Dimension?.Name,
+                hierarchyName: s.Hierarchy?.Name,
+                subsetName: s.Name && s.Name.length > 0 ? s.Name : undefined,
+                expression: s.Expression && s.Expression.length > 0 ? s.Expression : undefined,
+            };
+        };
+        const mapTitle = (t) => ({
+            ...mapAxis(t),
+            selectedElement: t.Selected?.Name,
+        });
+        return {
+            cubeName,
+            viewName,
+            private: resolvedPrivate,
+            type: "Native",
+            native: {
+                titles: (native.Titles ?? []).map(mapTitle),
+                columns: (native.Columns ?? []).map(mapAxis),
+                rows: (native.Rows ?? []).map(mapAxis),
+            },
+        };
+    }
+    /**
+     * Create a public MDX-based view on a cube.
+     * POST /api/v1/Cubes('{c}')/Views with @odata.type = #ibm.tm1.api.v1.MDXView
+     */
+    async createMdx(cubeName, viewName, mdx) {
+        await this.http.request("POST", `/api/v1/Cubes('${enc(cubeName)}')/Views`, {
+            "@odata.type": "#ibm.tm1.api.v1.MDXView",
+            Name: viewName,
+            MDX: mdx,
+        });
+    }
+    /**
+     * Create a public native view on a cube. Each axis entry references exactly
+     * one subset source: a registered subset (`subset`), an MDX expression
+     * (`expression`), or an explicit element list (`elements`). The latter two
+     * create anonymous (view-private) subsets server-side.
+     * POST /api/v1/Cubes('{c}')/Views with @odata.type = #ibm.tm1.api.v1.NativeView
+     */
+    async createNative(cubeName, viewName, spec) {
+        const hierPath = (a) => `Dimensions('${enc(a.dimension)}')/Hierarchies('${enc(a.hierarchy ?? a.dimension)}')`;
+        const mapAxis = (a) => {
+            const sources = [a.subset, a.expression, a.elements].filter((s) => s !== undefined);
+            if (sources.length !== 1) {
+                throw new TM1Error({
+                    code: TM1ErrorCode.VALIDATION_ERROR,
+                    message: `Axis spec for dimension '${a.dimension}' must set exactly one of ` +
+                        `subset, expression, or elements.`,
+                    endpoint: `/api/v1/Cubes('${cubeName}')/Views`,
+                });
+            }
+            if (a.subset !== undefined) {
+                return {
+                    "Subset@odata.bind": `${hierPath(a)}/Subsets('${enc(a.subset)}')`,
+                };
+            }
+            if (a.expression !== undefined) {
+                return {
+                    Subset: {
+                        "Hierarchy@odata.bind": hierPath(a),
+                        Expression: a.expression,
+                    },
+                };
+            }
+            return {
+                Subset: {
+                    "Hierarchy@odata.bind": hierPath(a),
+                    "Elements@odata.bind": (a.elements ?? []).map((e) => `${hierPath(a)}/Elements('${enc(e)}')`),
+                },
+            };
+        };
+        const mapTitle = (t) => {
+            // TM1 rejects title subsets without a selected element (400: "Selected
+            // element was not specified on Title axis subset.") — fail fast here.
+            if (t.selected === undefined) {
+                throw new TM1Error({
+                    code: TM1ErrorCode.VALIDATION_ERROR,
+                    message: `Title spec for dimension '${t.dimension}' requires a selected element ` +
+                        `(TM1 rejects title subsets without one).`,
+                    endpoint: `/api/v1/Cubes('${cubeName}')/Views`,
+                });
+            }
+            const axis = mapAxis(t);
+            axis["Selected@odata.bind"] =
+                `${hierPath(t)}/Elements('${enc(t.selected)}')`;
+            return axis;
+        };
+        const body = {
+            "@odata.type": "#ibm.tm1.api.v1.NativeView",
+            Name: viewName,
+            Columns: spec.columns.map(mapAxis),
+            Rows: spec.rows.map(mapAxis),
+            Titles: (spec.titles ?? []).map(mapTitle),
+            SuppressEmptyColumns: spec.suppressEmptyColumns ?? false,
+            SuppressEmptyRows: spec.suppressEmptyRows ?? false,
+        };
+        if (spec.formatString !== undefined)
+            body.FormatString = spec.formatString;
+        await this.http.request("POST", `/api/v1/Cubes('${enc(cubeName)}')/Views`, body);
+    }
+    /**
+     * Delete a public view from a cube.
+     * DELETE /api/v1/Cubes('{c}')/Views('{v}')
+     */
+    async delete(cubeName, viewName) {
+        await this.http.request("DELETE", `/api/v1/Cubes('${enc(cubeName)}')/Views('${enc(viewName)}')`);
+    }
+}
+//# sourceMappingURL=view-service.js.map

package/dist/tm1-client.d.ts

@@ -0,0 +1,56 @@
+import type pino from "pino";
+import type { TM1Config } from "./config.js";
+import type { SessionManager } from "./session-manager.js";
+import { BatchService } from "./tm1-client/services/batch-service.js";
+import { CubeService } from "./tm1-client/services/cube-service.js";
+import { DimensionService } from "./tm1-client/services/dimension-service.js";
+import { HierarchyService } from "./tm1-client/services/hierarchy-service.js";
+import { ElementService } from "./tm1-client/services/element-service.js";
+import { CellService } from "./tm1-client/services/cell-service.js";
+import { ViewService } from "./tm1-client/services/view-service.js";
+import { SubsetService } from "./tm1-client/services/subset-service.js";
+import { ProcessService } from "./tm1-client/services/process-service.js";
+import { ChoreService } from "./tm1-client/services/chore-service.js";
+import { SecurityService } from "./tm1-client/services/security-service.js";
+import { ServerService } from "./tm1-client/services/server-service.js";
+import { MonitoringService } from "./tm1-client/services/monitoring-service.js";
+import { FileService } from "./tm1-client/services/file-service.js";
+export declare class TM1Client {
+    private connected;
+    private readonly http;
+    private readonly sessionManager;
+    private readonly logger;
+    private readonly config;
+    readonly batch: BatchService;
+    readonly cubes: CubeService;
+    readonly dimensions: DimensionService;
+    readonly hierarchies: HierarchyService;
+    readonly cells: CellService;
+    readonly views: ViewService;
+    readonly subsets: SubsetService;
+    readonly elements: ElementService;
+    readonly processes: ProcessService;
+    readonly chores: ChoreService;
+    readonly security: SecurityService;
+    readonly server: ServerService;
+    readonly monitoring: MonitoringService;
+    readonly files: FileService;
+    constructor(config: TM1Config, sessionManager: SessionManager, logger: pino.Logger);
+    /** The configured TM1 major version (11 or 12). Fixed for this connection. */
+    get version(): 11 | 12;
+    /**
+     * Stable label for this connection, used to keep per-connection files (the
+     * process backups) apart: host and port, plus the v12 instance/database.
+     */
+    get connectionId(): string;
+    /**
+     * Authenticate and start the keep-alive timer.
+     */
+    connect(): Promise<void>;
+    /**
+     * Stop the keep-alive timer and mark as disconnected.
+     */
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+}
+//# sourceMappingURL=tm1-client.d.ts.map

package/dist/tm1-client.js

@@ -0,0 +1,126 @@
+import { TM1HttpClient } from "./tm1-client/http.js";
+import { BatchService } from "./tm1-client/services/batch-service.js";
+import { CubeService } from "./tm1-client/services/cube-service.js";
+import { DimensionService } from "./tm1-client/services/dimension-service.js";
+import { HierarchyService } from "./tm1-client/services/hierarchy-service.js";
+import { ElementService } from "./tm1-client/services/element-service.js";
+import { CellService } from "./tm1-client/services/cell-service.js";
+import { ViewService } from "./tm1-client/services/view-service.js";
+import { SubsetService } from "./tm1-client/services/subset-service.js";
+import { ProcessService } from "./tm1-client/services/process-service.js";
+import { ChoreService } from "./tm1-client/services/chore-service.js";
+import { SecurityService } from "./tm1-client/services/security-service.js";
+import { ServerService } from "./tm1-client/services/server-service.js";
+import { MonitoringService } from "./tm1-client/services/monitoring-service.js";
+import { FileService } from "./tm1-client/services/file-service.js";
+import { registerCallgraphCacheInvalidation } from "./lib/callgraph/tm1-adapter.js";
+export class TM1Client {
+    connected = false;
+    // Transport is HELD, not inherited. Because TM1Client no longer `extends`
+    // TM1HttpClient, its public type does not expose `request()/requestRaw()/
+    // requestBinary()`, so a tool typed on TM1Client cannot call raw REST — that
+    // is now a compile error (`tsc`), not just a `lint:no-flat-api` failure.
+    // Services that legitimately need transport receive `this.http` explicitly.
+    http;
+    sessionManager;
+    logger;
+    config;
+    // Domain services. Init order matters when services depend on each other —
+    // `cells` is created before `elements` because the latter holds a CellService
+    // ref for the element-attribute-value methods that route through MDX/cellset.
+    batch;
+    cubes;
+    dimensions;
+    hierarchies;
+    cells;
+    views;
+    subsets;
+    elements;
+    processes;
+    chores;
+    security;
+    server;
+    monitoring;
+    files;
+    constructor(config, sessionManager, logger) {
+        this.config = config;
+        this.http = new TM1HttpClient(config, sessionManager, logger);
+        this.sessionManager = sessionManager;
+        this.logger = logger;
+        // Explicitly wire the callgraph cache-invalidation listener to tm1Events
+        // "mutation" notifications. Replaces the former import-time side-effect in
+        // http.ts — now the coupling is a visible, idempotent call at construction.
+        registerCallgraphCacheInvalidation();
+        this.batch = new BatchService(this.http);
+        this.cubes = new CubeService(this.http);
+        this.dimensions = new DimensionService(this.http);
+        this.hierarchies = new HierarchyService(this.http);
+        this.cells = new CellService(this.http);
+        this.views = new ViewService(this.http);
+        this.subsets = new SubsetService(this.http);
+        // ElementService depends on CellService and BatchService — both MUST be
+        // constructed above. Enforced at runtime so a future reorder fails loudly
+        // instead of injecting `undefined` (TS types the fields as defined, so the
+        // compiler won't catch a move). `batch` is asserted too even though the
+        // constructor parameter is optional: an undefined batch degrades bulkUpsert
+        // silently back to N round-trips, with no error and no failing test.
+        if (!this.cells) {
+            throw new Error("TM1Client init order: CellService must be constructed before ElementService");
+        }
+        if (!this.batch) {
+            throw new Error("TM1Client init order: BatchService must be constructed before ElementService");
+        }
+        this.elements = new ElementService(this.http, this.cells, this.batch);
+        this.processes = new ProcessService(this.http);
+        this.chores = new ChoreService(this.http);
+        this.security = new SecurityService(this.http);
+        this.server = new ServerService(this.http);
+        this.monitoring = new MonitoringService(this.http);
+        this.files = new FileService(this.http);
+    }
+    /** The configured TM1 major version (11 or 12). Fixed for this connection. */
+    get version() {
+        return this.config.version;
+    }
+    /**
+     * Stable label for this connection, used to keep per-connection files (the
+     * process backups) apart: host and port, plus the v12 instance/database.
+     */
+    get connectionId() {
+        let host;
+        try {
+            const url = new URL(this.config.baseUrl);
+            host = url.port ? `${url.hostname}_${url.port}` : url.hostname;
+        }
+        catch {
+            host = this.config.baseUrl;
+        }
+        return [host, this.config.instance, this.config.database]
+            .filter((part) => Boolean(part))
+            .join("_");
+    }
+    /**
+     * Authenticate and start the keep-alive timer.
+     */
+    async connect() {
+        this.logger.info("Connecting to TM1 server");
+        await this.sessionManager.authenticate();
+        this.sessionManager.startKeepAlive();
+        this.connected = true;
+        this.logger.info("Connected to TM1 server");
+    }
+    /**
+     * Stop the keep-alive timer and mark as disconnected.
+     */
+    async disconnect() {
+        this.logger.info("Disconnecting from TM1 server");
+        this.sessionManager.stopKeepAlive();
+        await this.sessionManager.logout();
+        this.connected = false;
+        this.logger.info("Disconnected from TM1 server");
+    }
+    isConnected() {
+        return this.connected;
+    }
+}
+//# sourceMappingURL=tm1-client.js.map

package/dist/tools/analysis/analyze-callgraph.d.ts

@@ -0,0 +1,28 @@
+import type { ReferenceIndex } from "../../lib/callgraph/referenceIndex.js";
+export interface RankEntry {
+    process: string;
+    outgoingCalls: number;
+    outgoingDistinct: number;
+    incomingCalls: number;
+    incomingDistinct: number;
+}
+export interface GlobalRankingResult {
+    rankBy: "outgoing" | "incoming";
+    totalProcessesIndexed: number;
+    processesWithEdges: number;
+    totalCallEdges: number;
+    truncated: boolean;
+    ranking: RankEntry[];
+}
+/**
+ * Global fan-out/fan-in ranking across ALL processes — answers "which process
+ * triggers (or is triggered by) the most others" without a per-process traversal.
+ * Counts ExecuteProcess/RunProcess edges (targetKind='process') from the flat ref index.
+ */
+export declare function globalRanking(index: ReferenceIndex, opts: {
+    rankBy: "outgoing" | "incoming";
+    topN: number;
+    includeSystem: boolean;
+}): GlobalRankingResult;
+export declare const registerAnalyzeCallgraph: import("../define-tool.js").ToolRegistrar;
+//# sourceMappingURL=analyze-callgraph.d.ts.map