@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/http-transport.js

@@ -0,0 +1,132 @@
+import { createServer, } from "node:http";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+// Streamable HTTP transport (stateless JSON, single /mcp endpoint).
+//
+// Stateless mode (sessionIdGenerator omitted) means each StreamableHTTPServerTransport
+// is single-use: the SDK throws "Stateless transport cannot be reused across requests"
+// on the second handleRequest. So we build a *fresh* McpServer + transport per request
+// and tear both down when the response closes — the SDK-documented stateless pattern.
+// This is cheap: registration is pure in-memory wiring with no I/O, and the shared
+// TM1 client (captured by the buildServer closure) is not rebuilt.
+//
+// Consequence: there is no standing server->client stream, so subscribe/logging
+// notifications are not delivered over HTTP. That is acceptable for the intended
+// deployment (one process per TM1 identity; stdio remains the push-capable default).
+//
+// Per MCP best practices: bind 127.0.0.1 by default and enable DNS-rebinding
+// protection. allowedHosts/Origins narrow what the transport accepts.
+export async function startHttpTransport(buildServer, config, logger) {
+    const allowedHost = `${config.httpHost}:${config.httpPort}`;
+    if (!config.httpToken) {
+        logger.warn("HTTP transport has no TM1_MCP_HTTP_TOKEN set — /mcp requests are unauthenticated. " +
+            "Bind loopback only, or front the server with an authenticating reverse proxy.");
+    }
+    const httpServer = createServer(
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- async request handler intentional; errors are caught internally
+    async (req, res) => {
+        // Match the exact /mcp endpoint (optionally with a query string) or a real
+        // subpath under /mcp/. A loose startsWith("/mcp") would also accept
+        // /mcpFoo, routing an unrelated path into the MCP transport.
+        const path = (req.url ?? "").split(/[?#]/, 1)[0] ?? "";
+        if (path !== "/mcp" && !path.startsWith("/mcp/")) {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ error: "Not found. Use POST /mcp." }));
+            return;
+        }
+        if (config.httpToken) {
+            // Constant-time comparison: hashing both sides to fixed-length digests avoids
+            // both the length-mismatch throw and the per-character timing oracle that `!==`
+            // would leak, so the token can't be brute-forced via response-timing analysis.
+            const expected = createHash("sha256")
+                .update(`Bearer ${config.httpToken}`)
+                .digest();
+            const provided = createHash("sha256")
+                .update(req.headers.authorization ?? "")
+                .digest();
+            if (!timingSafeEqual(expected, provided)) {
+                res.statusCode = 401;
+                res.setHeader("Content-Type", "application/json");
+                res.setHeader("WWW-Authenticate", "Bearer");
+                res.end(JSON.stringify({ error: "Unauthorized" }));
+                return;
+            }
+        }
+        let body;
+        if (req.method === "POST") {
+            try {
+                const chunks = [];
+                for await (const chunk of req) {
+                    chunks.push(typeof chunk === "string"
+                        ? Buffer.from(chunk)
+                        : chunk);
+                }
+                const raw = Buffer.concat(chunks).toString("utf8");
+                body = raw ? JSON.parse(raw) : undefined;
+            }
+            catch (err) {
+                logger.warn({ err }, "Bad JSON in /mcp body");
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: "Invalid JSON" }));
+                return;
+            }
+        }
+        // Fresh server + transport per request (stateless single-use); tear both down
+        // once the response is fully written so nothing leaks between requests.
+        const { server, dispose } = buildServer();
+        const transport = new StreamableHTTPServerTransport({
+            // sessionIdGenerator omitted → stateless mode (single-use per request)
+            enableJsonResponse: true,
+            enableDnsRebindingProtection: true,
+            allowedHosts: [allowedHost, "127.0.0.1", "localhost"],
+            allowedOrigins: config.httpAllowedOrigins,
+        });
+        res.on("close", () => {
+            // dispose() FIRST and synchronously: it detaches the per-build listener
+            // from the process-global tm1Events emitter, which server.close() has no
+            // knowledge of. Skipping it leaks one listener plus the server graph it
+            // retains on every request — the transport builds a fresh server each
+            // time, so the leak is unbounded, not one-off.
+            dispose();
+            void transport.close();
+            void server.close();
+        });
+        try {
+            // Cast: StreamableHTTPServerTransport.onclose is `(() => void) | undefined`
+            // while Transport expects `() => void`; the cast papers over that library-
+            // internal signature mismatch without changing behaviour. Cast to the
+            // parameter's own type rather than `any`, so only this mismatch is
+            // waived and the argument stays checked against the real signature.
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            logger.error({ err }, "Transport handleRequest threw");
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: "Internal transport error" }));
+            }
+        }
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(config.httpPort, config.httpHost, () => {
+            httpServer.off("error", reject);
+            resolve();
+        });
+    });
+    logger.info({
+        host: config.httpHost,
+        port: config.httpPort,
+        endpoint: "/mcp",
+        allowedOrigins: config.httpAllowedOrigins,
+        dnsRebindingProtection: true,
+    }, "MCP server listening on HTTP (Streamable, stateless, per-request)");
+    return async () => {
+        await new Promise((resolve) => httpServer.close(() => resolve()));
+    };
+}
+//# sourceMappingURL=http-transport.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import "./load-env.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface BuiltMcpServer {
+    server: McpServer;
+    /**
+     * Detach everything this build attached to PROCESS-GLOBAL state — today the
+     * SubscriptionRegistry's `tm1Events` listener. `server.close()` does NOT do
+     * this: the registry holds its listener on an emitter the server knows
+     * nothing about, so closing the server leaves it subscribed forever.
+     *
+     * The stateless HTTP transport builds one server per request, so skipping
+     * this leaks a listener (and the whole server object graph it closes over)
+     * on every single call. Must be invoked by every transport teardown path.
+     */
+    dispose: () => void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import "./load-env.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createLogger } from "./logger.js";
+import { SessionManager } from "./session-manager.js";
+import { TM1Client } from "./tm1-client.js";
+import { registerAllPrompts } from "./prompts/index.js";
+import { registerAllResources } from "./resources/index.js";
+import { SubscriptionRegistry } from "./resources/subscriptions.js";
+import { installPaginatedListHandler } from "./resources/list-handler.js";
+import { registerAllTools } from "./tools/index.js";
+import { withAnnotations } from "./tools/with-annotations.js";
+import { startHttpTransport } from "./http-transport.js";
+import { NAME, VERSION } from "./version.js";
+// stdio transport: existing Claude-Code/Desktop entry path.
+async function startStdioTransport(server, logger) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP server listening on stdio");
+    return async () => {
+        await transport.close();
+    };
+}
+function buildMcpServer(tm1Client, config, logger) {
+    const server = new McpServer({
+        name: NAME,
+        version: VERSION,
+    }, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { listChanged: true, subscribe: true },
+            prompts: { listChanged: true },
+            logging: {},
+        },
+    });
+    // Register all tools — wrap the server so each registration receives the
+    // annotation hint from ANNOTATION_MAP without editing call sites. In readonly
+    // mode the proxy silently drops write/destructive tools so they never appear
+    // in the tool listing — no autoApprove lists needed.
+    registerAllTools(withAnnotations(server, logger, config.mode, config.responseMode, config.maxResponseChars), tm1Client);
+    logger.debug(`All MCP tools registered (mode: ${config.mode})`);
+    // Register MCP Resources (URI-addressable read-only views over TM1 objects).
+    const resourceCatalog = registerAllResources(server, tm1Client);
+    // R2-07: replace the SDK's default ListResourcesRequestSchema handler with a
+    // cursor-aware override that paginates the combined static + template list.
+    installPaginatedListHandler(server, resourceCatalog, logger);
+    // R2-05: install subscribe/unsubscribe handlers and bridge HTTP-layer mutation
+    // events to notifications/resources/updated for subscribers of tm1://server/state.
+    const subscriptions = new SubscriptionRegistry(server, logger);
+    subscriptions.install();
+    // Register MCP Prompts (parameterised workflow templates surfaced as slash-commands).
+    registerAllPrompts(server);
+    logger.debug("All MCP resources and prompts registered");
+    return {
+        server,
+        dispose: () => {
+            subscriptions.dispose();
+        },
+    };
+}
+async function main() {
+    const config = loadConfig();
+    const logger = createLogger(config);
+    logger.info("Starting TM1 MCP Server");
+    const sessionManager = new SessionManager(config, logger);
+    const tm1Client = new TM1Client(config, sessionManager, logger);
+    // Try to connect to TM1, but don't block MCP server startup.
+    // request() calls ensureSession() on every tool invocation, so a tool call
+    // will retry auth if the initial connect failed. Keeps Claude able to list
+    // tools and report a meaningful error instead of crashing the whole process.
+    try {
+        await tm1Client.connect();
+        logger.info("TM1 client connected");
+    }
+    catch (err) {
+        logger.warn({ err }, "Initial TM1 connection failed — server will retry on first tool call");
+    }
+    if (config.mode === "readonly") {
+        logger.info("TM1_MODE=readonly — write and destructive tools will not be registered");
+    }
+    // Branch on transport. stdio is the default for local MCP-client setups
+    // (Claude Code, Claude Desktop) and gets one long-lived server. http
+    // (Streamable HTTP, stateless) is for remote/multi-client deploys and builds a
+    // fresh server per request (single-use transport); binds to 127.0.0.1 by
+    // default with DNS-rebinding protection per MCP spec recommendation.
+    // stdio builds exactly one server for the process lifetime, so its disposer
+    // runs in shutdown(). http builds one per request and disposes each in the
+    // transport's own teardown — nothing process-scoped is left for us here.
+    let stdioDispose;
+    const httpCloser = config.transport === "http"
+        ? await startHttpTransport(() => buildMcpServer(tm1Client, config, logger), config, logger)
+        : await (async () => {
+            const built = buildMcpServer(tm1Client, config, logger);
+            stdioDispose = built.dispose;
+            return startStdioTransport(built.server, logger);
+        })();
+    logger.info(`MCP server configured (mode: ${config.mode}, transport: ${config.transport})`);
+    // Graceful shutdown — ensure TM1 session is always cleaned up.
+    let shuttingDown = false;
+    const shutdown = async (signal, exitCode = 0) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info({ signal }, "Shutting down TM1 MCP Server");
+        try {
+            stdioDispose?.();
+        }
+        catch (err) {
+            logger.error({ err }, "Error disposing server subscriptions");
+        }
+        try {
+            await httpCloser?.();
+        }
+        catch (err) {
+            logger.error({ err }, "Error closing transport");
+        }
+        try {
+            await tm1Client.disconnect();
+        }
+        catch (err) {
+            logger.error({ err }, "Error during disconnect");
+        }
+        process.exit(exitCode);
+    };
+    process.on("SIGINT", () => {
+        void shutdown("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+        void shutdown("SIGTERM");
+    });
+    process.on("SIGHUP", () => {
+        void shutdown("SIGHUP");
+    });
+    // Parent process death — only meaningful on stdio (Claude spawns us as a
+    // child). For http we ignore stdin events since the process lifecycle is
+    // independent.
+    if (config.transport === "stdio") {
+        process.stdin.on("end", () => {
+            logger.info("stdin ended (parent process gone), shutting down");
+            void shutdown("stdin-end");
+        });
+        process.stdin.on("close", () => {
+            logger.info("stdin closed, shutting down");
+            void shutdown("stdin-close");
+        });
+    }
+    // Last resort — try to clean up the TM1 session on uncaught errors.
+    process.on("uncaughtException", (err) => {
+        logger.error({ err }, "Uncaught exception, attempting cleanup");
+        // Exit non-zero: a crash must not look like a clean shutdown to a
+        // supervisor/systemd, which would otherwise not restart or would mask it.
+        void shutdown("uncaughtException", 1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        logger.error({ reason }, "Unhandled rejection");
+    });
+}
+main().catch((err) => {
+    console.error("Fatal error starting TM1 MCP Server:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/lib/callgraph/callGraph.d.ts

@@ -0,0 +1,124 @@
+import type { ReferenceIndex, CallParam, CallParamResolution, UnresolvedCall } from "./referenceIndex.js";
+/**
+ * Effective parameter value in the context of a specific graph node.
+ * - literal: fully resolved value (from explicit literal, propagated literal, or process default)
+ * - unknown: value would need to flow in from an upstream param we cannot see (root input)
+ *            `viaParam` is the name of the originating root-level param (for display: pX=«pX»)
+ * - dynamic: resolution is known to be impossible (CellGet, concat, IF, loops, …)
+ */
+export type EffectiveValue = {
+    kind: "literal";
+    value: string;
+} | {
+    kind: "unknown";
+    viaParam: string;
+} | {
+    kind: "dynamic";
+};
+/**
+ * One edge in the call graph = one ExecuteProcess/RunProcess call site.
+ * Each call site has its own params (same caller→callee pair can appear
+ * multiple times with different params).
+ */
+export interface CallEdge {
+    caller: string;
+    callee: string;
+    section: string;
+    line: number;
+    funcName: string;
+    snippet: string;
+    params: CallParam[];
+    /**
+     * Effective value per call-param at THIS edge (parent env applied).
+     * Only populated for downstream direction. Index matches `params`.
+     */
+    effectiveParams?: Array<{
+        name: string;
+        effective: EffectiveValue;
+        valueRaw: string;
+    }>;
+}
+/**
+ * A node in the call graph tree. Parent→child edge is described by `incomingEdge`
+ * (the call that reached this node). The root node has incomingEdge = null.
+ */
+export interface CallGraphNode {
+    process: string;
+    incomingEdge: CallEdge | null;
+    /**
+     * Effective parameter environment AT this node (after call-site resolution).
+     * Keys are lowercased param names. Only populated for downstream direction.
+     */
+    env?: Map<string, EffectiveValue> | undefined;
+    children: CallGraphNode[];
+    cycle: boolean;
+    depthLimitReached?: boolean | undefined;
+    /** Outgoing calls whose target could not be statically resolved (downstream only). */
+    unresolvedCalls?: UnresolvedCall[] | undefined;
+}
+export type Direction = "downstream" | "upstream";
+export interface BuildCallGraphOptions {
+    direction: Direction;
+    maxDepth?: number;
+    /**
+     * Include system objects (names starting with `}`) as children/ancestors.
+     * The root node is always shown regardless of this flag.
+     * Default: true.
+     */
+    includeSystem?: boolean;
+}
+/**
+ * Resolve one call-site CallParamResolution against the parent node's env.
+ * - literal stays literal
+ * - passthrough → look up the named caller-param in parent env:
+ *     known literal → propagate; unknown → mark unknown; dynamic → dynamic
+ * - dynamic stays dynamic
+ */
+export declare function resolveEdgeParam(res: CallParamResolution, parentEnv: Map<string, EffectiveValue>): EffectiveValue;
+/**
+ * Recursively build the call graph starting from `start`.
+ *
+ * downstream: children = processes that THIS process calls (with env-propagation)
+ * upstream:   children = processes that CALL this process (no env-propagation)
+ *
+ * Cycle detection uses the ancestor chain: if a candidate child is already
+ * on the path from the root, `cycle = true` and children are empty.
+ *
+ * Duplicate edges (same caller→callee, different lines/sections) are kept
+ * as separate nodes — each represents a distinct call site.
+ */
+export declare function buildCallGraph(index: ReferenceIndex, start: string, opts: BuildCallGraphOptions): CallGraphNode;
+export declare function classifyAccess(funcName: string | undefined, sourceKind: "process" | "rule"): "read" | "write" | "other";
+/** Flat usage reference — one occurrence where a cube/dimension is referenced. */
+export interface UsageRef {
+    sourceKind: "process" | "rule";
+    sourceName: string;
+    section: string;
+    line: number;
+    funcName?: string | undefined;
+    snippet: string;
+    /** Classified access type: 'read' (CellGetN/S, DB), 'write' (CellPutN/S, ViewZeroOut, …), 'other' (structural). */
+    accessType: "read" | "write" | "other";
+}
+/**
+ * Collect all references to a cube or dimension as a flat list, sorted by
+ * source name and line. Self-references (a cube's own rules reading from the
+ * cube itself via DB()/`[...]`) are filtered out to avoid noise — the rule
+ * editor already shows them inline.
+ */
+export declare function buildCubeOrDimUsages(index: ReferenceIndex, kind: "cube" | "dimension", name: string, opts?: {
+    includeSystem?: boolean;
+    accessMode?: "read" | "write" | "all";
+}): UsageRef[];
+/** Flattens the tree depth-first for simple list rendering. */
+export declare function flattenCallGraph(root: CallGraphNode): Array<{
+    node: CallGraphNode;
+    depth: number;
+}>;
+/**
+ * Human-readable param summary using effective values (env-propagated).
+ * Falls back to raw resolution if no effective values are available (upstream mode).
+ *   pRegion='UK', pYear=2026, pSource=«pCaller», pDate=?
+ */
+export declare function formatEdgeParams(edge: CallEdge): string;
+//# sourceMappingURL=callGraph.d.ts.map