@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tools/views/create-native-view.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { actionResponse } from "../format.js";
+import { MutationResultSchema } from "../schemas/items.js";
+import { WRITE } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+const AXIS_SPEC = z.object({
+    dimension: z.string().describe("Dimension name"),
+    hierarchy: z
+        .string()
+        .optional()
+        .describe("Hierarchy name (default: same-named hierarchy as the dimension)"),
+    subset: z
+        .string()
+        .optional()
+        .describe("Registered subset name. Exactly one of subset/expression/elements per axis entry."),
+    expression: z
+        .string()
+        .optional()
+        .describe("MDX set expression for an anonymous subset, e.g. '{TM1SUBSETALL([Region])}'"),
+    elements: z
+        .array(z.string())
+        .optional()
+        .describe("Explicit element list for an anonymous subset"),
+});
+const TITLE_SPEC = AXIS_SPEC.extend({
+    selected: z
+        .string()
+        .describe("Element shown as the title's selection; must be in the subset. Required — TM1 rejects title subsets without a selected element."),
+});
+export const registerCreateNativeView = defineTool({
+    name: "tm1_create_native_view",
+    description: "Create a public native (subset-based) view on a cube — the classic view type used as TI process datasource " +
+        "(TM1CubeView) and for zero-suppressed exports. Every cube dimension must appear in exactly one of " +
+        "columns/rows/titles, each axis entry with exactly one subset source: a registered subset name, an MDX " +
+        "expression, or an explicit element list (the latter two create anonymous subsets). " +
+        "For MDX-defined views use tm1_create_mdx_view instead.",
+    annotations: WRITE,
+    output: MutationResultSchema,
+    input: {
+        cubeName: z.string().describe("Cube the view belongs to"),
+        viewName: z.string().describe("New view name"),
+        columns: z
+            .array(AXIS_SPEC)
+            .min(1)
+            .describe("Column axis, one entry per dimension"),
+        rows: z
+            .array(AXIS_SPEC)
+            .min(1)
+            .describe("Row axis, one entry per dimension"),
+        titles: z
+            .array(TITLE_SPEC)
+            .optional()
+            .describe("Title (context) dimensions, each with a required selected element"),
+        suppressEmptyColumns: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Suppress columns where all cells are empty/zero"),
+        suppressEmptyRows: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Suppress rows where all cells are empty/zero"),
+        formatString: z
+            .string()
+            .optional()
+            .describe("Cell format string, e.g. '0.#########'"),
+    },
+    handler: async ({ cubeName, viewName, columns, rows, titles, suppressEmptyColumns, suppressEmptyRows, formatString, }, tm1Client) => {
+        await tm1Client.views.createNative(cubeName, viewName, {
+            columns,
+            rows,
+            titles,
+            suppressEmptyColumns,
+            suppressEmptyRows,
+            formatString,
+        });
+        return actionResponse({ success: true, cubeName, viewName });
+    },
+});
+//# sourceMappingURL=create-native-view.js.map

package/dist/tools/views/delete-view.d.ts

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

package/dist/tools/views/delete-view.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { CONFIRM_SCHEMA, requireConfirm } from "../confirm.js";
+import { actionResponse } from "../format.js";
+import { DESTRUCTIVE } from "../annotations.js";
+import { MutationResultSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+export const registerDeleteView = defineTool({
+    name: "tm1_delete_view",
+    description: "Delete a public view from a cube. Irreversible — pass confirm=<view name verbatim>.",
+    annotations: DESTRUCTIVE,
+    output: MutationResultSchema,
+    input: {
+        cubeName: z.string().describe("Cube name"),
+        viewName: z.string().describe("View name to delete"),
+        ...CONFIRM_SCHEMA,
+    },
+    handler: async ({ cubeName, viewName, confirm }, tm1Client) => {
+        requireConfirm(confirm, viewName, "view");
+        await tm1Client.views.delete(cubeName, viewName);
+        return actionResponse({ success: true, cubeName, viewName });
+    },
+});
+//# sourceMappingURL=delete-view.js.map

package/dist/tools/views/list-views.d.ts

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

package/dist/tools/views/list-views.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { PAGINATION_SCHEMA, paginate } from "../pagination.js";
+import { FORMAT_SCHEMA, pageResponse, columnsOf } from "../format.js";
+import { READ_ONLY } from "../annotations.js";
+import { ViewItemSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+import { pageShapeFor } from "../schemas/common.js";
+export const registerListViews = defineTool({
+    name: "tm1_list_views",
+    description: "List public and private views defined on a cube. Returns view name, visibility, and MDX (when available). Paginated (default 50/page).",
+    annotations: READ_ONLY,
+    output: pageShapeFor(ViewItemSchema),
+    input: {
+        cubeName: z.string().describe("Cube name"),
+        ...PAGINATION_SCHEMA,
+        ...FORMAT_SCHEMA,
+    },
+    handler: async ({ cubeName, limit, offset, fetchAll, format }, tm1Client) => {
+        const views = await tm1Client.views.list(cubeName);
+        const page = paginate(views, limit, offset, fetchAll);
+        const columns = columnsOf([
+            "name",
+            { header: "scope", get: (v) => (v.private ? "private" : "public") },
+            "mdx",
+        ]);
+        return pageResponse(page, format, {
+            title: `Views of ${cubeName}`,
+            columns,
+        });
+    },
+});
+//# sourceMappingURL=list-views.js.map

package/dist/tools/with-annotations.d.ts

@@ -0,0 +1,6 @@
+import type pino from "pino";
+import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function deriveTitle(toolName: string): string;
+export declare function narrowingHint(inputKeys: ReadonlySet<string>): string;
+export declare function withAnnotations(server: McpServer, logger: pino.Logger, mode: "readwrite" | "readonly", responseMode?: "legacy" | "structured", maxResponseChars?: number): McpServer;
+//# sourceMappingURL=with-annotations.d.ts.map

package/dist/tools/with-annotations.js

@@ -0,0 +1,339 @@
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { slimJsonSchema } from "../lib/slim-json-schema.js";
+import { specFor } from "./define-tool.js";
+import { DEFAULT_MAX_RESPONSE_CHARS } from "../config.js";
+import { TM1Error, TM1ErrorCode } from "../types.js";
+import { strictVariants } from "./schemas/markdown-capable.js";
+import { formatTm1ErrorResult, normalizeErrorResult, } from "./error-format.js";
+// Words whose display casing differs from simple capitalization.
+const TITLE_CASING = {
+    mdx: "MDX",
+    ti: "TI",
+    v12: "v12",
+    v11: "v11",
+};
+// Derive a human-readable title from a snake_case tool name:
+// "tm1_get_process_code" → "Get Process Code". Single point of derivation —
+// no per-tool overrides in ANNOTATION_MAP.
+export function deriveTitle(toolName) {
+    return toolName
+        .replace(/^tm1_/, "")
+        .split("_")
+        .filter((w) => w.length > 0)
+        .map((w) => TITLE_CASING[w] ?? w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+// OUTPUT_SCHEMA_MAP entries are either a raw shape or a full Zod schema
+// (passthrough/catchall). Normalize to a parseable schema.
+function isZodSchema(entry) {
+    return "_def" in entry;
+}
+function asZodSchema(entry) {
+    return isZodSchema(entry) ? entry : z.object(entry);
+}
+// A markdown response carries exactly one key. Anything else is the JSON path.
+function isMarkdownPayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const keys = Object.keys(value);
+    return (keys.length === 1 &&
+        keys[0] === "markdown" &&
+        typeof value.markdown === "string");
+}
+// Characters the client receives for a successful result: the text blocks, or
+// the serialized structuredContent when "structured" mode emptied content[].
+function responseChars(result) {
+    const text = (result.content ?? []).reduce((n, c) => n + (typeof c.text === "string" ? c.text.length : 0), 0);
+    if (text > 0 || result.structuredContent === undefined)
+        return text;
+    return JSON.stringify(result.structuredContent).length;
+}
+// How to narrow a call, derived from the tool's own input keys so a new tool
+// gets a correct hint without a per-tool table to keep in step.
+export function narrowingHint(inputKeys) {
+    const ways = [];
+    if (inputKeys.has("outline"))
+        ways.push("outline=true to see the sections, then lineRange for a slice");
+    else if (inputKeys.has("lineRange"))
+        ways.push("lineRange for a slice");
+    if (inputKeys.has("countOnly"))
+        ways.push("countOnly=true to size it first");
+    if (inputKeys.has("limit"))
+        ways.push("a smaller limit, walking on with offset/next_offset");
+    else if (inputKeys.has("topN"))
+        ways.push("a smaller topN, walking on with offset");
+    if (inputKeys.has("maxBytes") || inputKeys.has("headLines"))
+        ways.push("a smaller maxBytes or headLines");
+    if (inputKeys.has("summary"))
+        ways.push("summary=true");
+    if (inputKeys.has("compact"))
+        ways.push("compact=true");
+    const tail = ways.length > 0
+        ? `Use ${ways.join("; or ")}.`
+        : "Narrow the request (filters, fewer objects) and retry.";
+    return `${tail} Raise TM1_MAX_RESPONSE_CHARS only if the client can take the full payload.`;
+}
+// Rewrite a tools/list response so every advertised schema is slimmed.
+function slimToolsListResult(result) {
+    if (!result || typeof result !== "object")
+        return result;
+    const listing = result;
+    if (!Array.isArray(listing.tools))
+        return result;
+    // Array.isArray widens an `unknown` to `any[]`; name the element type so the
+    // map below stays checked.
+    const tools = listing.tools;
+    return {
+        ...listing,
+        tools: tools.map((entry) => {
+            if (!entry || typeof entry !== "object")
+                return entry;
+            const tool = {
+                ...entry,
+            };
+            if (tool.inputSchema !== undefined) {
+                tool.inputSchema = slimJsonSchema(tool.inputSchema);
+            }
+            if (tool.outputSchema !== undefined) {
+                tool.outputSchema = slimJsonSchema(tool.outputSchema);
+            }
+            return tool;
+        }),
+    };
+}
+// SDK REACH — isolated here on purpose.
+//
+// The zod→JSON-Schema conversion happens inside the SDK: McpServer's
+// setToolRequestHandlers() serializes tool.inputSchema/outputSchema at
+// tools/list time, and it is installed lazily on the FIRST registerTool call.
+// There is no public hook between that conversion and the wire, so the only
+// place to slim the payload is the tools/list handler itself.
+//
+// Rather than dig into the handler registry (a private Map), we intercept the
+// SDK's own `setRequestHandler` call on the low-level Server and wrap the
+// handler it is trying to install. Public method, public request schema
+// (imported from the SDK, matched by reference — same module instance the SDK
+// itself imports), no private state touched. Must be installed BEFORE the first
+// tool registration, which is why it runs inside withAnnotations().
+//
+// If a future SDK stops routing tools/list through setRequestHandler, or hands
+// it a different schema object, this becomes a silent no-op — the sentinels
+// would simply reappear on the wire. tests/unit/slim-json-schema.test.ts does a
+// real end-to-end tools/list over an in-memory transport and fails loudly in
+// that case.
+function installToolsListSlimming(server) {
+    const lowLevel = server.server;
+    const originalSetRequestHandler = lowLevel.setRequestHandler.bind(lowLevel);
+    lowLevel.setRequestHandler = (schema, handler) => {
+        if (schema !== ListToolsRequestSchema) {
+            originalSetRequestHandler(schema, handler);
+            return;
+        }
+        originalSetRequestHandler(schema, async (...args) => slimToolsListResult(await handler(...args)));
+    };
+}
+// Wrap McpServer so every server.tool(name, desc, schema, cb) call:
+//   1) injects the annotation declared in the tool's defineTool() spec
+//   2) wraps the callback so thrown errors become uniform JSON results
+//      and existing isError results get reshaped to include `hint`
+//   3) when the tool declares an outputSchema, attaches it
+//   4) when mode="readonly", silently skips tools without readOnlyHint
+// Also installs the tools/list schema slimmer (see installToolsListSlimming) —
+// it has to be in place before the first registration triggers the SDK's lazy
+// handler setup.
+export function withAnnotations(server, logger, mode, 
+// Matches the shipped default (config.responseMode, see config.ts), so direct
+// callers — the live harness and the unit tests, which read content[0].text —
+// exercise the same wire shape real clients get.
+responseMode = "legacy", maxResponseChars = DEFAULT_MAX_RESPONSE_CHARS) {
+    installToolsListSlimming(server);
+    const originalRegisterTool = server.registerTool.bind(server);
+    // Handlers return their payload as a JSON string in content[0].text. Parsing
+    // it into structuredContent is what satisfies the declared outputSchema — but
+    // leaving the text block in place means the identical JSON crosses the wire
+    // TWICE. Every tool declares an outputSchema, so in "legacy" mode that
+    // doubling applies to every successful response.
+    //
+    // In "structured" mode the now-redundant text block is dropped. That is
+    // spec-legal only because an outputSchema is declared: CallToolResult.content
+    // "may be empty" then (see CallToolResultSchema in the SDK). It is NOT the
+    // default, and must not become one — the spec says a tool returning
+    // structured content SHOULD also return the serialized JSON in a TextContent
+    // block, and clients take that literally. Kiro's MCP layer (bundled TS SDK,
+    // protocolVersion 2025-11-25, clientInfo {name:"kiro"}) parses results with
+    //   const items = Array.isArray(r.content) ? r.content : []
+    // and never reads structuredContent, so an empty content array renders as no
+    // output at all.
+    //
+    // Dropping the text block also buys nothing on the clients that do read
+    // structuredContent: Claude Code de-duplicates, so an identical payload sent
+    // both ways costs exactly one copy of context (measured byte-identical
+    // tool_result at 1 KB and at 23 KB, and the >25k-token offload-to-file path
+    // behaves the same either way). The saving is real only for clients that
+    // serialize the whole CallToolResult into the model prompt — Q DEV CLI /
+    // Kiro CLI do this — which is who this mode is still here for.
+    //
+    // A non-JSON text block (markdown mode, where the handler already attached
+    // structuredContent itself) is left alone in both modes: there the text is
+    // the point, not a duplicate.
+    const attachStructured = (result) => {
+        const first = result.content?.[0];
+        if (!first || first.type !== "text" || typeof first.text !== "string") {
+            return result;
+        }
+        const raw = first.text.trim();
+        if (!raw.startsWith("{") && !raw.startsWith("["))
+            return result;
+        try {
+            // Deliberately not narrowed to an object: a handler may serialize a
+            // top-level array, and this wrapper's job is to pass the payload
+            // through unchanged, not to re-decide its shape.
+            const parsed = JSON.parse(raw);
+            return responseMode === "structured"
+                ? { ...result, content: [], structuredContent: parsed }
+                : { ...result, structuredContent: parsed };
+        }
+        catch {
+            return result;
+        }
+    };
+    const SLOW_TOOL_MS = 5000;
+    // Replace an oversized success with an error that says how to narrow the
+    // call. Never truncate: a cut JSON payload is worse than none.
+    const guardSize = (toolName, result, hint) => {
+        const size = responseChars(result);
+        if (size <= maxResponseChars)
+            return result;
+        logger.warn({ tool: toolName, size, maxResponseChars }, "response too large");
+        return formatTm1ErrorResult(new TM1Error({
+            code: TM1ErrorCode.RESPONSE_TOO_LARGE,
+            message: `${toolName} produced ${size} characters, over the ${maxResponseChars}-character response limit. Nothing was returned.`,
+            hint,
+            details: JSON.stringify({ size, limit: maxResponseChars }),
+        }));
+    };
+    const wrapCb = (toolName, cb, outputSchema, sizeHint) => {
+        // Normalize once per tool, not per call.
+        const schema = outputSchema ? asZodSchema(outputSchema) : undefined;
+        // Tools offering format:"markdown" publish a loosened schema (top-level
+        // keys optional, plus `markdown`) because the SDK cannot express "either
+        // shape" — see ./schemas/markdown-capable.ts. Validating against that
+        // loosened schema would forfeit top-level drift detection on the JSON
+        // path, so we pick the matching strict variant per response instead.
+        const variants = strictVariants(outputSchema);
+        return async (...cbArgs) => {
+            const start = Date.now();
+            try {
+                const result = (await cb(...cbArgs));
+                const durationMs = Date.now() - start;
+                if (durationMs >= SLOW_TOOL_MS) {
+                    void server.server
+                        .sendLoggingMessage({
+                        level: "warning",
+                        logger: "tm1-mcp",
+                        data: {
+                            tool: toolName,
+                            durationMs,
+                            message: `slow tool call: ${toolName} took ${durationMs}ms`,
+                        },
+                    })
+                        .catch(() => undefined);
+                }
+                if (result && result.isError) {
+                    return normalizeErrorResult(result);
+                }
+                if (result && schema) {
+                    const withStructured = attachStructured(result);
+                    if (withStructured.structuredContent !== undefined) {
+                        // Pre-validate against the outputSchema HERE so drift surfaces as
+                        // a graceful isError result. The SDK validates structuredContent
+                        // AFTER the callback returns and turns a mismatch into a raw
+                        // JSON-RPC protocol error; it skips that validation for isError
+                        // results (validateToolOutput returns early on result.isError),
+                        // so the error envelope below — which carries no
+                        // structuredContent — passes through cleanly.
+                        //
+                        // COVERAGE BOUNDARY: this guard only bites schemas that can actually
+                        // fail safeParse. A `.passthrough()` object or a `z.unknown()` field
+                        // accepts anything, so tools whose OUTPUT_SCHEMA_MAP entry is
+                        // permissive (e.g. MutationResultSchema.passthrough(), audit/feeder
+                        // schemas) get no structural drift protection here — extra/renamed
+                        // fields slip through silently. Prefer a strict, fully-modelled
+                        // schema for any new output whose shape you want enforced (the
+                        // callgraph tree was tightened for exactly this reason).
+                        //
+                        // Variant pick is made from the RESPONSE, not from the requested
+                        // `format`: a handler may legitimately fall back to JSON while
+                        // format:"markdown" was asked for (unavailable stats, empty
+                        // result), and branching on the input would reject that. No JSON
+                        // payload in OUTPUT_SCHEMA_MAP carries a top-level `markdown`
+                        // string, so the discriminator is unambiguous.
+                        const effectiveSchema = variants
+                            ? isMarkdownPayload(withStructured.structuredContent)
+                                ? variants.markdown
+                                : variants.json
+                            : schema;
+                        const parsed = effectiveSchema.safeParse(withStructured.structuredContent);
+                        if (!parsed.success) {
+                            const issue = parsed.error.issues[0];
+                            const detail = issue
+                                ? `${issue.path.join(".") || "(root)"}: ${issue.message}`
+                                : "unknown issue";
+                            logger.warn({ tool: toolName, issues: parsed.error.issues.slice(0, 5) }, "output schema drift");
+                            return formatTm1ErrorResult(new Error(`output schema drift in ${toolName}: ${detail}`));
+                        }
+                    }
+                    return guardSize(toolName, withStructured, sizeHint);
+                }
+                return result ? guardSize(toolName, result, sizeHint) : result;
+            }
+            catch (err) {
+                logger.error({ err, tool: toolName }, "Tool handler threw");
+                return formatTm1ErrorResult(err);
+            }
+        };
+    };
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop !== "tool")
+                return Reflect.get(target, prop, receiver);
+            return (...args) => {
+                const isFourArg = args.length === 4 &&
+                    typeof args[0] === "string" &&
+                    typeof args[1] === "string" &&
+                    typeof args[3] === "function";
+                if (!isFourArg) {
+                    throw new Error("withAnnotations Proxy expects server.tool(name, description, inputSchema, cb). " +
+                        "Other tool() overloads are deprecated and not supported here.");
+                }
+                const name = args[0];
+                const description = args[1];
+                const inputSchema = args[2];
+                const spec = specFor(name);
+                const annot = spec?.annotations;
+                if (!annot) {
+                    throw new Error(`Tool "${name}" registered without a spec — build it with defineTool() (src/tools/define-tool.ts) instead of calling server.tool directly.`);
+                }
+                if (mode === "readonly" && !annot.readOnlyHint) {
+                    return;
+                }
+                const outputSchema = spec.outputSchema;
+                const inputKeys = new Set(inputSchema && typeof inputSchema === "object"
+                    ? Object.keys(inputSchema)
+                    : []);
+                const wrappedCb = wrapCb(name, args[3], outputSchema, narrowingHint(inputKeys));
+                const config = {
+                    title: deriveTitle(name),
+                    description,
+                    inputSchema,
+                    annotations: annot,
+                };
+                if (outputSchema)
+                    config.outputSchema = outputSchema;
+                return originalRegisterTool(name, config, wrappedCb);
+            };
+        },
+    });
+}
+//# sourceMappingURL=with-annotations.js.map