@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tools/analysis/analyze-callgraph.js

@@ -0,0 +1,350 @@
+import { z } from "zod";
+import { buildIndexFromTM1 } from "../../lib/callgraph/tm1-adapter.js";
+import { buildCallGraph, } from "../../lib/callgraph/callGraph.js";
+import { isSecretName, MASK, maskCodeLine, resolveMaskSecrets, } from "../../lib/mask-secrets.js";
+import { CallgraphResultSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+function maskParams(params) {
+    return params.map((p) => isSecretName(p.name)
+        ? {
+            ...p,
+            valueRaw: MASK,
+            resolution: p.resolution.kind === "literal"
+                ? { kind: "literal", value: MASK }
+                : p.resolution,
+        }
+        : p);
+}
+function maskEffective(eff) {
+    return eff.map((e) => isSecretName(e.name)
+        ? {
+            ...e,
+            valueRaw: MASK,
+            effective: e.effective.kind === "literal"
+                ? { kind: "literal", value: MASK }
+                : e.effective,
+        }
+        : e);
+}
+function maskEnv(env) {
+    const out = {};
+    for (const [k, v] of env.entries()) {
+        out[k] =
+            isSecretName(k) && v.kind === "literal"
+                ? { kind: "literal", value: MASK }
+                : v;
+    }
+    return out;
+}
+function serializeCompact(node) {
+    const out = {
+        process: node.process,
+        children: node.children.map(serializeCompact),
+    };
+    if (node.cycle)
+        out.cycle = true;
+    if (node.depthLimitReached)
+        out.depthLimitReached = true;
+    if (node.unresolvedCalls && node.unresolvedCalls.length > 0) {
+        out.unresolvedCalls = node.unresolvedCalls.map((u) => ({
+            section: u.section,
+            line: u.line,
+            funcName: u.funcName,
+            expr: u.expr,
+            reason: u.reason,
+        }));
+    }
+    return out;
+}
+function serializeNode(node, mask) {
+    return {
+        process: node.process,
+        cycle: node.cycle,
+        depthLimitReached: node.depthLimitReached,
+        incomingEdge: node.incomingEdge
+            ? {
+                caller: node.incomingEdge.caller,
+                callee: node.incomingEdge.callee,
+                section: node.incomingEdge.section,
+                line: node.incomingEdge.line,
+                funcName: node.incomingEdge.funcName,
+                snippet: mask
+                    ? maskCodeLine(node.incomingEdge.snippet)
+                    : node.incomingEdge.snippet,
+                params: mask
+                    ? maskParams(node.incomingEdge.params)
+                    : node.incomingEdge.params,
+                effectiveParams: node.incomingEdge.effectiveParams
+                    ? mask
+                        ? maskEffective(node.incomingEdge.effectiveParams)
+                        : node.incomingEdge.effectiveParams
+                    : undefined,
+            }
+            : null,
+        env: node.env
+            ? mask
+                ? maskEnv(node.env)
+                : Object.fromEntries(node.env.entries())
+            : undefined,
+        unresolvedCalls: node.unresolvedCalls
+            ? node.unresolvedCalls.map((u) => ({
+                section: u.section,
+                line: u.line,
+                funcName: u.funcName,
+                expr: u.expr,
+                snippet: mask ? maskCodeLine(u.snippet) : u.snippet,
+                reason: u.reason,
+            }))
+            : undefined,
+        children: node.children.map((c) => serializeNode(c, mask)),
+    };
+}
+function summarize(root) {
+    const map = new Map();
+    let totalNodes = 0;
+    let maxDepth = 0;
+    let cyclesDetected = 0;
+    let depthLimitsHit = 0;
+    function walk(node, depth) {
+        totalNodes++;
+        if (depth > maxDepth)
+            maxDepth = depth;
+        const isCycle = !!node.cycle;
+        const isDepthLimit = !!node.depthLimitReached;
+        if (isCycle)
+            cyclesDetected++;
+        if (isDepthLimit)
+            depthLimitsHit++;
+        const existing = map.get(node.process);
+        if (existing) {
+            existing.occurrences++;
+            if (depth < existing.depthMin)
+                existing.depthMin = depth;
+            if (depth > existing.depthMax)
+                existing.depthMax = depth;
+            existing.cycle = existing.cycle || isCycle;
+            existing.depthLimitReached = existing.depthLimitReached || isDepthLimit;
+        }
+        else {
+            map.set(node.process, {
+                process: node.process,
+                depthMin: depth,
+                depthMax: depth,
+                occurrences: 1,
+                cycle: isCycle,
+                depthLimitReached: isDepthLimit,
+                unresolvedCount: node.unresolvedCalls?.length ?? 0,
+            });
+        }
+        for (const child of node.children)
+            walk(child, depth + 1);
+    }
+    walk(root, 0);
+    const processes = Array.from(map.values()).sort((a, b) => {
+        if (a.depthMin !== b.depthMin)
+            return a.depthMin - b.depthMin;
+        return b.occurrences - a.occurrences;
+    });
+    return {
+        root: root.process,
+        totalNodes,
+        uniqueProcesses: map.size,
+        maxDepth,
+        cyclesDetected,
+        depthLimitsHit,
+        processes,
+    };
+}
+/**
+ * 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 function globalRanking(index, opts) {
+    const { rankBy, topN, includeSystem } = opts;
+    const isSystem = (name) => name.startsWith("}");
+    const acc = new Map();
+    const ensure = (name) => {
+        const key = name.toLowerCase();
+        let e = acc.get(key);
+        if (!e) {
+            e = {
+                process: name,
+                outgoingCalls: 0,
+                incomingCalls: 0,
+                callees: new Set(),
+                callers: new Set(),
+            };
+            acc.set(key, e);
+        }
+        return e;
+    };
+    let totalCallEdges = 0;
+    for (const ref of index.all) {
+        if (ref.targetKind !== "process")
+            continue;
+        const src = ref.sourceName;
+        const tgt = ref.targetName;
+        if (!includeSystem && (isSystem(src) || isSystem(tgt)))
+            continue;
+        totalCallEdges++;
+        const s = ensure(src);
+        const t = ensure(tgt);
+        s.outgoingCalls++;
+        s.callees.add(tgt.toLowerCase());
+        t.incomingCalls++;
+        t.callers.add(src.toLowerCase());
+    }
+    let totalProcessesIndexed = 0;
+    for (const lc of index.processParams.keys()) {
+        if (!includeSystem && isSystem(lc))
+            continue;
+        totalProcessesIndexed++;
+    }
+    const all = Array.from(acc.values()).map((e) => ({
+        process: e.process,
+        outgoingCalls: e.outgoingCalls,
+        outgoingDistinct: e.callees.size,
+        incomingCalls: e.incomingCalls,
+        incomingDistinct: e.callers.size,
+    }));
+    all.sort((a, b) => {
+        const primary = rankBy === "incoming"
+            ? b.incomingCalls - a.incomingCalls
+            : b.outgoingCalls - a.outgoingCalls;
+        if (primary !== 0)
+            return primary;
+        const secondary = rankBy === "incoming"
+            ? b.outgoingCalls - a.outgoingCalls
+            : b.incomingCalls - a.incomingCalls;
+        if (secondary !== 0)
+            return secondary;
+        return a.process.localeCompare(b.process);
+    });
+    const ranking = all.slice(0, topN);
+    return {
+        rankBy,
+        totalProcessesIndexed,
+        processesWithEdges: all.length,
+        totalCallEdges,
+        truncated: all.length > ranking.length,
+        ranking,
+    };
+}
+export const registerAnalyzeCallgraph = defineTool({
+    name: "tm1_analyze_callgraph",
+    description: "Build a process call graph (ExecuteProcess/RunProcess) for a TI process. direction='downstream' shows what `start` calls (with parameter env propagation: literal/passthrough/dynamic). direction='upstream' shows callers. Returns nested JSON tree. Omit `start` for a global ranking: every process ranked by outgoing (fan-out) or incoming (fan-in) call counts — answers 'which process triggers/is triggered by the most others' without a per-process traversal. ExecuteProcess/RunProcess calls whose target is a computed expression or process parameter (not statically resolvable) are surfaced per node via `unresolvedCalls` (full/compact) or `unresolvedCount` (summary) — flagged, not resolved.",
+    annotations: READ_ONLY,
+    output: CallgraphResultSchema,
+    input: {
+        start: z
+            .string()
+            .optional()
+            .describe("Process name to start traversal from. Omit for global ranking across all processes."),
+        direction: z.enum(["downstream", "upstream"]).default("downstream"),
+        maxDepth: z.number().int().min(1).max(50).optional().default(20),
+        includeSystem: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include TM1 control objects (names starting with '}') in graph. Default: false."),
+        includeControl: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Index control processes/cubes/chores (broader graph). Default: false."),
+        mode: z
+            .enum(["full", "summary", "compact"])
+            .optional()
+            .default("full")
+            .describe("Output mode. 'full' returns nested tree with incomingEdge/env/effectiveParams (large for deep graphs). 'summary' returns flat per-process aggregates (occurrences, depthMin/Max, cycle/depthLimit flags) for triage. 'compact' returns the nested tree but only {process, cycle?, depthLimitReached?, children[]} — drops params, env, snippets, effectiveParams. Use compact for structural overviews where call shape matters but param values do not."),
+        maskSecrets: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Redact param values whose name matches /pass|pwd|secret|token|key|credential|auth/i to '***'. Also masks the inline snippet. Default: true. Set false only when debugging credential propagation locally."),
+        rankBy: z
+            .enum(["outgoing", "incoming"])
+            .optional()
+            .default("outgoing")
+            .describe("Global-ranking mode only (when `start` is omitted). 'outgoing' ranks by fan-out (most ExecuteProcess call sites), 'incoming' by fan-in (most called). Default: outgoing."),
+        topN: z
+            .number()
+            .int()
+            .positive()
+            .max(1000)
+            .optional()
+            .default(50)
+            .describe("Global-ranking mode only: cap on ranked processes returned (default 50)."),
+    },
+    handler: async ({ start, direction, maxDepth, includeSystem, includeControl, mode, maskSecrets: maskSecretsRequested, rankBy, topN, }, tm1Client) => {
+        // A model-supplied `maskSecrets:false` only takes effect when the
+        // operator allowed it via TM1_ALLOW_UNMASKED_SECRETS.
+        const maskSecrets = resolveMaskSecrets(maskSecretsRequested);
+        const index = await buildIndexFromTM1(tm1Client, { includeControl });
+        if (start === undefined || start === "") {
+            const result = globalRanking(index, { rankBy, topN, includeSystem });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ mode: "globalRanking", ...result }),
+                    },
+                ],
+            };
+        }
+        const lc = start.toLowerCase();
+        if (!index.processParams.has(lc) &&
+            !index.bySourceProcess.has(lc) &&
+            !index.byProcess.has(lc)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            warning: `Process "${start}" not found in index.`,
+                            indexedProcessCount: index.processParams.size,
+                        }),
+                    },
+                ],
+            };
+        }
+        const tree = buildCallGraph(index, start, {
+            direction,
+            maxDepth,
+            includeSystem,
+        });
+        let payload;
+        if (mode === "summary") {
+            payload = {
+                start,
+                direction,
+                mode,
+                maskSecrets,
+                summary: summarize(tree),
+            };
+        }
+        else if (mode === "compact") {
+            payload = { start, direction, mode, tree: serializeCompact(tree) };
+        }
+        else {
+            payload = {
+                start,
+                direction,
+                mode,
+                maskSecrets,
+                tree: serializeNode(tree, maskSecrets),
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload),
+                },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=analyze-callgraph.js.map

package/dist/tools/analysis/analyze-chore-graph.d.ts

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

package/dist/tools/analysis/analyze-chore-graph.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { buildIndexFromTM1 } from "../../lib/callgraph/tm1-adapter.js";
+import { buildChoreGraph } from "../../lib/callgraph/choreGraph.js";
+import { isSecretName, MASK, maskCodeLine, resolveMaskSecrets, } from "../../lib/mask-secrets.js";
+import { ChoreGraphResultSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+function maskParams(params) {
+    return params.map((p) => isSecretName(p.name)
+        ? {
+            ...p,
+            valueRaw: MASK,
+            resolution: p.resolution.kind === "literal"
+                ? { kind: "literal", value: MASK }
+                : p.resolution,
+        }
+        : p);
+}
+function maskEffective(eff) {
+    return eff.map((e) => isSecretName(e.name)
+        ? {
+            ...e,
+            valueRaw: MASK,
+            effective: e.effective.kind === "literal"
+                ? { kind: "literal", value: MASK }
+                : e.effective,
+        }
+        : e);
+}
+function maskEnv(env) {
+    const out = {};
+    for (const [k, v] of env.entries()) {
+        out[k] =
+            isSecretName(k) && v.kind === "literal"
+                ? { kind: "literal", value: MASK }
+                : v;
+    }
+    return out;
+}
+function maskChoreParams(params) {
+    if (!params)
+        return params;
+    return params.map((p) => {
+        const name = (p.Name ?? p.name);
+        return name && isSecretName(name) ? { ...p, Value: MASK, value: MASK } : p;
+    });
+}
+function serializeNode(node, mask) {
+    return {
+        process: node.process,
+        cycle: node.cycle,
+        depthLimitReached: node.depthLimitReached,
+        incomingEdge: node.incomingEdge
+            ? {
+                caller: node.incomingEdge.caller,
+                callee: node.incomingEdge.callee,
+                section: node.incomingEdge.section,
+                line: node.incomingEdge.line,
+                funcName: node.incomingEdge.funcName,
+                snippet: mask
+                    ? maskCodeLine(node.incomingEdge.snippet)
+                    : node.incomingEdge.snippet,
+                params: mask
+                    ? maskParams(node.incomingEdge.params)
+                    : node.incomingEdge.params,
+                effectiveParams: node.incomingEdge.effectiveParams
+                    ? mask
+                        ? maskEffective(node.incomingEdge.effectiveParams)
+                        : node.incomingEdge.effectiveParams
+                    : undefined,
+            }
+            : null,
+        env: node.env
+            ? mask
+                ? maskEnv(node.env)
+                : Object.fromEntries(node.env.entries())
+            : undefined,
+        children: node.children.map((c) => serializeNode(c, mask)),
+    };
+}
+export const registerAnalyzeChoreGraph = defineTool({
+    name: "tm1_analyze_chore_graph",
+    description: "Build downstream call graphs for every task of a TM1 chore. Each task's tree is seeded with the chore's task params (literals) which propagate through ExecuteProcess calls. Returns one tree per task plus the chore's own params per task.",
+    annotations: READ_ONLY,
+    output: ChoreGraphResultSchema,
+    input: {
+        choreName: z.string().describe("Chore name (case-insensitive)"),
+        includeSystem: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include TM1 control objects in the graph. Default: false."),
+        includeControl: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Index control objects when building the index. Default: false."),
+        maskSecrets: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Redact param values whose name matches /pass|pwd|secret|token|key|credential|auth/i to '***'. Includes chore-task params, edge params, env, and snippet. Default: true."),
+    },
+    handler: async ({ choreName, includeSystem, includeControl, maskSecrets: maskSecretsRequested, }, tm1Client) => {
+        // A model-supplied `maskSecrets:false` only takes effect when the
+        // operator allowed it via TM1_ALLOW_UNMASKED_SECRETS.
+        const maskSecrets = resolveMaskSecrets(maskSecretsRequested);
+        const index = await buildIndexFromTM1(tm1Client, { includeControl });
+        const graph = buildChoreGraph(index, choreName, { includeSystem });
+        if (!graph) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            // Same top-level shape as the success branch so the strict
+                            // output schema accepts the not-found payload.
+                            choreName,
+                            tasks: [],
+                            warning: `Chore "${choreName}" not found.`,
+                            indexedChoreCount: index.choreTasks.size,
+                        }),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        choreName: graph.choreName,
+                        maskSecrets,
+                        tasks: graph.tasks.map((t) => ({
+                            step: t.step,
+                            processName: t.processName,
+                            choreParams: maskSecrets
+                                ? maskChoreParams(t.choreParams)
+                                : t.choreParams,
+                            tree: serializeNode(t.tree, maskSecrets),
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=analyze-chore-graph.js.map

package/dist/tools/analysis/analyze-object-usage.d.ts

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

package/dist/tools/analysis/analyze-object-usage.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { buildIndexFromTM1 } from "../../lib/callgraph/tm1-adapter.js";
+import { buildCubeOrDimUsages } from "../../lib/callgraph/callGraph.js";
+import { ObjectUsageResultSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+// Backstop for the bulk/audit path, mirroring UNBOUNDED_MAX_ITEMS in
+// pagination.ts. Usage rows are small, so this sits higher than the list-tool
+// cap — but it is a bound, which "omit limit for everything" was not.
+const USAGE_MAX_ITEMS = 5000;
+export const registerAnalyzeObjectUsage = defineTool({
+    name: "tm1_analyze_object_usage",
+    description: [
+        "Find every reference to a cube or dimension across all TI processes (CellGet/Put, ViewExtract, ZeroOut, …) and cube rules (DB(), [dim].[el]).",
+        "Returns a flat list sorted by source; excludes a cube's self-references inside its own rules. accessMode picks read vs write (data-flow) analysis; mode='summary' collapses per-source and drops snippets.",
+    ],
+    annotations: READ_ONLY,
+    output: ObjectUsageResultSchema,
+    input: {
+        kind: z.enum(["cube", "dimension"]).describe("Object kind to look up"),
+        objectName: z
+            .string()
+            .describe("Cube or dimension name (case-insensitive)"),
+        accessMode: z
+            .enum(["all", "read", "write"])
+            .optional()
+            .default("all")
+            .describe("Filter by access type. 'write': CellPut*/ViewZeroOut/CubeClearData/… (data-flow analysis). " +
+            "'read': CellGet*/DB()-rules (consumption analysis). 'all' (default): every reference."),
+        includeSystem: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include sources whose names start with '}' (control objects). Default: false."),
+        includeControl: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Index control processes/cubes when building the index. Default: false."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .max(USAGE_MAX_ITEMS)
+            .optional()
+            .describe(`Cap the number of returned usages (or sources in summary mode). Omit for bulk load (audit use-case) — still bounded at ${USAGE_MAX_ITEMS}, truncated=true says the bound bit.`),
+        mode: z
+            .enum(["full", "summary"])
+            .optional()
+            .default("full")
+            .describe("'full' (default): individual usage lines with snippets. 'summary': aggregate per source " +
+            "({sourceKind, sourceName, accessTypes[], sections[], funcNames[], count}), sorted by count desc, " +
+            "snippets dropped. Use summary for compact data-flow overviews on heavily-referenced objects."),
+    },
+    handler: async ({ kind, objectName, accessMode, includeSystem, includeControl, limit, mode, }, tm1Client) => {
+        // An omitted `limit` used to mean "no limit at all" — on a large model
+        // that is a full-model dump into one response. It now means "as much as
+        // is still readable", and `truncated` says when that bound bit, so the
+        // audit use-case still gets bulk output without an unbounded worst case.
+        const effectiveLimit = limit ?? USAGE_MAX_ITEMS;
+        const index = await buildIndexFromTM1(tm1Client, { includeControl });
+        const all = buildCubeOrDimUsages(index, kind, objectName, {
+            includeSystem,
+            accessMode,
+        });
+        if (mode === "summary") {
+            // Aggregate per source (process or rule). Key by kind+name so a process
+            // and a cube-rule sharing a name don't collapse into one row.
+            const bySource = new Map();
+            for (const u of all) {
+                const key = `${u.sourceKind}\x00${u.sourceName}`;
+                let s = bySource.get(key);
+                if (!s) {
+                    s = {
+                        sourceKind: u.sourceKind,
+                        sourceName: u.sourceName,
+                        accessTypes: new Set(),
+                        sections: new Set(),
+                        funcNames: new Set(),
+                        count: 0,
+                    };
+                    bySource.set(key, s);
+                }
+                s.accessTypes.add(u.accessType);
+                s.sections.add(u.section);
+                if (u.funcName)
+                    s.funcNames.add(u.funcName);
+                s.count++;
+            }
+            const allSources = [...bySource.values()]
+                .map((s) => ({
+                sourceKind: s.sourceKind,
+                sourceName: s.sourceName,
+                accessTypes: [...s.accessTypes].sort(),
+                sections: [...s.sections].sort(),
+                funcNames: [...s.funcNames].sort(),
+                count: s.count,
+            }))
+                .sort((a, b) => b.count - a.count || a.sourceName.localeCompare(b.sourceName));
+            const sumTruncated = allSources.length > effectiveLimit;
+            const sources = sumTruncated
+                ? allSources.slice(0, effectiveLimit)
+                : allSources;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            kind,
+                            name: objectName,
+                            accessMode,
+                            mode,
+                            count: all.length,
+                            sourceCount: allSources.length,
+                            returned: sources.length,
+                            truncated: sumTruncated,
+                            sources,
+                        }),
+                    },
+                ],
+            };
+        }
+        const truncated = all.length > effectiveLimit;
+        const usages = truncated ? all.slice(0, effectiveLimit) : all;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        kind,
+                        name: objectName,
+                        accessMode,
+                        count: all.length,
+                        returned: usages.length,
+                        truncated,
+                        usages,
+                    }),
+                },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=analyze-object-usage.js.map

package/dist/tools/analysis/audit-complexity.d.ts

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