@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tools/error-format.js

@@ -0,0 +1,130 @@
+// Centralized MCP error result formatting. Closes audit gaps 5 (actionable
+// hints) and 6 (uniform error shape) without per-tool edits — the index.ts
+// Proxy invokes these helpers so every tool emits the same JSON shape:
+//
+//   { code, message, httpStatus?, endpoint?, details?, hint }
+//
+// formatTm1ErrorResult: wrap a thrown error into the MCP result envelope.
+// normalizeErrorResult: rewrite an already-emitted isError result to the
+// uniform shape, parsing existing JSON when present and falling back to
+// treating plain-text bodies as TM1_ERROR messages.
+import { TM1Error, TM1ErrorCode, hintForCode } from "../types.js";
+import { maskSecretValues } from "../lib/mask-secrets.js";
+const DEFAULT_CODE = TM1ErrorCode.TM1_ERROR;
+// Second net on the error path. classifyHttpError already sanitizes whatever
+// TM1 said, but this envelope also carries errors that never went through it —
+// a driver message rethrown by a service, a third-party library's text. Those
+// reach the client here, so they get the same value-oriented masking.
+// Idempotent: masking an already-masked string is a no-op.
+function sanitize(payload) {
+    return {
+        ...payload,
+        message: maskSecretValues(payload.message),
+        ...(payload.details !== undefined
+            ? { details: maskSecretValues(payload.details) }
+            : {}),
+    };
+}
+function payloadFromUnknown(err) {
+    if (err instanceof TM1Error) {
+        return sanitize(err.toErrorPayload());
+    }
+    if (err instanceof Error) {
+        return sanitize({
+            code: DEFAULT_CODE,
+            message: err.message,
+            hint: hintForCode(DEFAULT_CODE),
+        });
+    }
+    return sanitize({
+        code: DEFAULT_CODE,
+        message: String(err),
+        hint: hintForCode(DEFAULT_CODE),
+    });
+}
+export function formatTm1ErrorResult(err) {
+    const payload = payloadFromUnknown(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+// Re-shape an isError result that came back from a tool's own try/catch.
+// Returns the original result unchanged when it's not safe to rewrite
+// (no content, non-text content, etc.) so we never mangle good data.
+export function normalizeErrorResult(result) {
+    const first = result.content?.[0];
+    if (!first || first.type !== "text" || typeof first.text !== "string") {
+        return result;
+    }
+    const raw = first.text.trim();
+    let parsed = null;
+    if (raw.startsWith("{")) {
+        try {
+            const candidate = JSON.parse(raw);
+            if (candidate &&
+                typeof candidate === "object" &&
+                !Array.isArray(candidate)) {
+                parsed = candidate;
+            }
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    if (parsed) {
+        // Already JSON. Add hint if missing; preserve any extra fields the tool
+        // attached (e.g. upsert_process attaches partialApply/failedStep).
+        const code = parsed.code ?? DEFAULT_CODE;
+        const enriched = {
+            ...parsed,
+            code,
+            // Payload fields are preserved via the spread — falling back to `raw`
+            // here would duplicate the entire JSON body inside `message`.
+            message: parsed.message ??
+                "Tool reported an error — see the payload fields for detail.",
+            hint: parsed.hint ?? hintForCode(code),
+        };
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(enriched) }],
+        };
+    }
+    // Plain-text error body — wrap into uniform shape.
+    const stripped = raw.replace(/^TM1 error:\s*/i, "");
+    const payload = {
+        code: DEFAULT_CODE,
+        message: stripped,
+        hint: hintForCode(DEFAULT_CODE),
+    };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+// Attach a tool-context hint to any thrown error and rethrow.
+// Use to wrap an awaited TM1 call so failures carry a tool-specific
+// follow-up suggestion instead of just the generic code-derived hint.
+//
+// Example:
+//   await withToolHint(
+//     tm1Client.cubes.setRules(cube, rules),
+//     "Validate first with tm1_check_cube_rule before tm1_set_cube_rules.",
+//   );
+export async function withToolHint(p, hint) {
+    try {
+        return await p;
+    }
+    catch (err) {
+        if (err instanceof TM1Error) {
+            err.hintOverride = hint;
+            throw err;
+        }
+        throw new TM1Error({
+            code: DEFAULT_CODE,
+            message: err instanceof Error ? err.message : String(err),
+            hint,
+        });
+    }
+}
+//# sourceMappingURL=error-format.js.map

package/dist/tools/fileops/delete-file.d.ts

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

package/dist/tools/fileops/delete-file.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { withToolHint } from "../error-format.js";
+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 registerDeleteFile = defineTool({
+    name: "tm1_delete_file",
+    description: [
+        "Delete a file from the TM1 server's blob/file storage.",
+        "Irreversible — file is removed from Files/Blobs container.",
+        "Auto-falls back from v12 (Files) to v11 (Blobs).",
+        "Returns NOT_FOUND if file is missing in both containers.",
+        "Safety: pass confirm=<file name verbatim>.",
+    ],
+    annotations: DESTRUCTIVE,
+    output: MutationResultSchema,
+    input: {
+        fileName: z
+            .string()
+            .min(1)
+            .describe("File name or path (e.g. 'data.csv' or 'imports/old.csv')."),
+        ...CONFIRM_SCHEMA,
+    },
+    handler: async ({ fileName, confirm }, tm1Client) => {
+        requireConfirm(confirm, fileName, "file");
+        await withToolHint(tm1Client.files.delete(fileName), "Verify exact name with tm1_list_files or tm1_search_files. Names are case-sensitive.");
+        return actionResponse({ success: true, fileName, deleted: true });
+    },
+});
+//# sourceMappingURL=delete-file.js.map

package/dist/tools/fileops/get-file-content.d.ts

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

package/dist/tools/fileops/get-file-content.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { FileContentResultSchema } from "../schemas/items.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+// Below the server's 80k-character response limit (TM1_MAX_RESPONSE_CHARS)
+// once JSON escaping is added; the old 256 KB default could never be returned.
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const HARD_MAX_BYTES = 4 * 1024 * 1024;
+export const registerGetFileContent = defineTool({
+    name: "tm1_get_file_content",
+    description: [
+        "Read the content of a file from the TM1 server's data directory.",
+        "Use to inspect CSV, TXT, or other text files before building import processes.",
+        "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
+        "Response is truncated to maxBytes (default 64 KB) to keep MCP messages small.",
+    ],
+    annotations: READ_ONLY,
+    output: FileContentResultSchema,
+    input: {
+        fileName: z
+            .string()
+            .describe("File name or path (e.g. 'data.csv' or 'imports/sales_2024.csv')"),
+        maxBytes: z
+            .number()
+            .int()
+            .positive()
+            .max(HARD_MAX_BYTES)
+            .optional()
+            .default(DEFAULT_MAX_BYTES)
+            .describe(`Truncate response after N bytes (default ${DEFAULT_MAX_BYTES}, hard max ${HARD_MAX_BYTES}).`),
+        headLines: z
+            .number()
+            .int()
+            .positive()
+            .max(10000)
+            .optional()
+            .describe("If set, only return the first N lines (overrides byte truncation)."),
+    },
+    handler: async ({ fileName, maxBytes, headLines }, tm1Client) => {
+        const content = await tm1Client.files.getContent(fileName);
+        const totalBytes = Buffer.byteLength(content, "utf8");
+        let body;
+        let truncated = false;
+        let truncationReason;
+        if (headLines !== undefined) {
+            const allLines = content.split("\n");
+            body = allLines.slice(0, headLines).join("\n");
+            if (allLines.length > headLines) {
+                truncated = true;
+                truncationReason = `headLines=${headLines} (of ${allLines.length})`;
+            }
+        }
+        else if (totalBytes > maxBytes) {
+            body = Buffer.from(content, "utf8")
+                .subarray(0, maxBytes)
+                .toString("utf8");
+            truncated = true;
+            truncationReason = `maxBytes=${maxBytes}`;
+        }
+        else {
+            body = content;
+        }
+        const payload = {
+            fileName,
+            totalBytes,
+            returnedBytes: Buffer.byteLength(body, "utf8"),
+            truncated,
+            ...(truncationReason ? { truncationReason } : {}),
+            content: body,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+});
+//# sourceMappingURL=get-file-content.js.map

package/dist/tools/fileops/list-files.d.ts

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

package/dist/tools/fileops/list-files.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { PAGINATION_SCHEMA, paginate } from "../pagination.js";
+import { FORMAT_SCHEMA, wrappedPageResponse, columnsOf } from "../format.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+import { FilenameItemSchema } from "../schemas/items.js";
+import { pageShapeFor } from "../schemas/common.js";
+// tm1_list_files prefixes a `path` field on top of the page envelope.
+const filePageShape = {
+    path: z.string().describe("Path that was listed (echoes the input)"),
+    ...pageShapeFor(FilenameItemSchema),
+};
+export const registerListFiles = defineTool({
+    name: "tm1_list_files",
+    description: [
+        "List files in the TM1 server's data directory (blob/file storage).",
+        "Use to browse available CSV, TXT, or other files before building import processes.",
+        "Supports subfolder navigation via the path parameter.",
+        "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
+        "Paginated (default 50/page).",
+    ],
+    annotations: READ_ONLY,
+    output: filePageShape,
+    input: {
+        path: z
+            .string()
+            .optional()
+            .describe("Subfolder path (e.g. 'imports' or 'imports/2024'). Empty = root."),
+        ...PAGINATION_SCHEMA,
+        ...FORMAT_SCHEMA,
+    },
+    handler: async ({ path, limit, offset, fetchAll, format }, tm1Client) => {
+        const files = await tm1Client.files.list(path);
+        const page = paginate(files, limit, offset, fetchAll);
+        const wrapper = { path: path ?? "", ...page };
+        const columns = columnsOf([{ header: "filename", get: (f) => f }]);
+        return wrappedPageResponse(wrapper, page, format, {
+            title: `Files in /${path ?? ""}`,
+            columns,
+        });
+    },
+});
+//# sourceMappingURL=list-files.js.map

package/dist/tools/fileops/search-files.d.ts

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

package/dist/tools/fileops/search-files.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { PAGINATION_SCHEMA, paginate } from "../pagination.js";
+import { FORMAT_SCHEMA, wrappedPageResponse, columnsOf } from "../format.js";
+import { READ_ONLY } from "../annotations.js";
+import { defineTool } from "../define-tool.js";
+import { FilenameItemSchema } from "../schemas/items.js";
+import { pageShapeFor } from "../schemas/common.js";
+// tm1_search_files echoes the search filters alongside the page envelope so
+// callers can correlate matches with the request that produced them.
+const searchFilePageShape = {
+    path: z.string().describe("Folder that was searched (echoes the input)"),
+    startswith: z.string().nullable().describe("Prefix filter applied, or null"),
+    contains: z
+        .array(z.string())
+        .nullable()
+        .describe("Substring filters applied, or null"),
+    operator: z
+        .enum(["and", "or"])
+        .describe("How `contains` substrings were joined"),
+    ...pageShapeFor(FilenameItemSchema),
+};
+export const registerSearchFiles = defineTool({
+    name: "tm1_search_files",
+    description: [
+        "Search file names in the TM1 server's blob/file storage by prefix and/or substring.",
+        "Use to find files when you only know part of the name (case-insensitive).",
+        "Combines startswith and contains filters via the `operator` (and/or).",
+        "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
+        "Paginated (default 50/page).",
+    ],
+    annotations: READ_ONLY,
+    output: searchFilePageShape,
+    input: {
+        startswith: z
+            .string()
+            .optional()
+            .describe("Case-insensitive prefix match on the file name (e.g. 'sales_')."),
+        contains: z
+            .array(z.string())
+            .optional()
+            .describe("List of case-insensitive substrings the name must contain (joined by `operator`)."),
+        operator: z
+            .enum(["and", "or"])
+            .optional()
+            .default("and")
+            .describe("How to join multiple `contains` substrings. Default 'and'."),
+        path: z
+            .string()
+            .optional()
+            .describe("Subfolder to search in (v12 only). Empty = root."),
+        ...PAGINATION_SCHEMA,
+        ...FORMAT_SCHEMA,
+    },
+    handler: async ({ startswith, contains, operator, path, limit, offset, fetchAll, format }, tm1Client) => {
+        const names = await tm1Client.files.search({
+            startswith,
+            contains,
+            operator,
+            path,
+        });
+        const page = paginate(names, limit, offset, fetchAll);
+        const wrapper = {
+            path: path ?? "",
+            startswith: startswith ?? null,
+            contains: contains ?? null,
+            operator,
+            ...page,
+        };
+        const columns = columnsOf([{ header: "filename", get: (f) => f }]);
+        return wrappedPageResponse(wrapper, page, format, {
+            title: `File search results in /${path ?? ""}`,
+            columns,
+        });
+    },
+});
+//# sourceMappingURL=search-files.js.map

package/dist/tools/fileops/upload-file.d.ts

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

package/dist/tools/fileops/upload-file.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { withToolHint } from "../error-format.js";
+import { actionResponse } from "../format.js";
+import { CONFIRM_SCHEMA, requireConfirm } from "../confirm.js";
+import { IDEMPOTENT_WRITE } from "../annotations.js";
+import { MutationResultSchema } from "../schemas/items.js";
+import { defineTool } from "../define-tool.js";
+const HARD_MAX_BYTES = 32 * 1024 * 1024;
+export const registerUploadFile = defineTool({
+    name: "tm1_upload_file",
+    description: [
+        "Upload (create or update) a file in the TM1 server's blob/file storage.",
+        "Use to push CSV, TXT, or other data files that import processes will read.",
+        "Provide content as plain text OR base64 (set encoding='base64' for binary).",
+        "Auto-falls back from v12 (Files) to v11 (Blobs) container.",
+        "v11: subfolders not supported — use a flat file name. v12: nested paths OK if folders exist.",
+        `Hard max size: ${HARD_MAX_BYTES} bytes (32 MB).`,
+    ],
+    annotations: IDEMPOTENT_WRITE,
+    output: MutationResultSchema,
+    input: {
+        fileName: z
+            .string()
+            .min(1)
+            .describe("File name or path (e.g. 'data.csv' or 'imports/sales_2024.csv'). v11 = flat only."),
+        content: z
+            .string()
+            .describe("File content. Plain text by default, or base64 string when encoding='base64'."),
+        encoding: z
+            .enum(["text", "base64"])
+            .optional()
+            .default("text")
+            .describe("Encoding of the `content` field. 'text' (default) for UTF-8 text, 'base64' for binary."),
+        ...CONFIRM_SCHEMA,
+    },
+    handler: async ({ fileName, content, encoding, confirm }, tm1Client) => {
+        // Silently replaces an existing server file of the same name. Guards
+        // against accidental invocation — not a security control.
+        requireConfirm(confirm, fileName, "file");
+        const bytes = encoding === "base64"
+            ? Buffer.from(content, "base64")
+            : Buffer.from(content, "utf8");
+        if (bytes.byteLength > HARD_MAX_BYTES) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            code: "VALIDATION_ERROR",
+                            message: `File too large: ${bytes.byteLength} bytes (hard max ${HARD_MAX_BYTES})`,
+                            hint: "Split the file or upload a smaller subset. Multipart upload is not yet supported.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const result = await withToolHint(tm1Client.files.upload(fileName, bytes), "If parent folder is missing, create it on TM1 v12 before retrying. v11 supports root only.");
+        return actionResponse({
+            success: true,
+            fileName,
+            bytesUploaded: bytes.byteLength,
+            created: result.created,
+            updated: !result.created,
+            container: result.root,
+        });
+    },
+});
+//# sourceMappingURL=upload-file.js.map

package/dist/tools/format.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import type { Page } from "./pagination.js";
+export declare const FORMAT_SCHEMA: {
+    format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        markdown: "markdown";
+        json: "json";
+    }>>>;
+};
+export type ResponseFormat = "json" | "markdown";
+export interface Column<T> {
+    header: string;
+    get: (row: T) => unknown;
+}
+/**
+ * A column is either a field name — rendered as itself, under its own name —
+ * or a full {header, get} pair for the cases that need one (a header that
+ * differs from the field, a projection, a computed value).
+ */
+export type ColumnSpec<T> = (keyof T & string) | Column<T>;
+/**
+ * Build the column list for a Markdown table.
+ *
+ * Most columns just print a field, and writing that out per column meant ~100
+ * `{ header: "name", get: (r) => r.name }` literals across the tool files, none
+ * of which the compiler could tie back to the row type — a renamed field left a
+ * table quietly printing empty cells. Naming the field instead makes the key
+ * `keyof Row`, so the rename becomes a compile error.
+ *
+ * `(r) => r.field ?? ""` is deliberately NOT needed: renderTable's escaper
+ * already prints null/undefined as an empty cell, and `??` leaves 0/false
+ * untouched, so the plain field name renders identically.
+ */
+export declare function columnsOf<T>(specs: readonly ColumnSpec<T>[]): Column<T>[];
+export declare function renderKV(obj: Record<string, unknown>, title?: string): string;
+export declare function renderTable<T>(rows: readonly T[], columns: Column<T>[]): string;
+export interface PageRenderOpts<T> {
+    title: string;
+    columns: Column<T>[];
+}
+export declare function renderPage<T>(page: Page<T>, opts: PageRenderOpts<T>): string;
+interface TextResult {
+    [x: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: {
+        [k: string]: unknown;
+    };
+}
+export declare function markdownResult(markdown: string): TextResult;
+export declare function pageResponse<T>(page: Page<T>, format: ResponseFormat, opts: PageRenderOpts<T>): TextResult;
+export declare function wrappedPageResponse<T>(wrapper: object, page: Page<T>, format: ResponseFormat, opts: PageRenderOpts<T>): TextResult;
+export declare function payloadResponse<T>(payload: T, format: ResponseFormat, renderMarkdown: (p: T) => string): TextResult;
+export declare function actionResponse<T extends object>(payload: T): TextResult;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/dist/tools/format.js

@@ -0,0 +1,157 @@
+// Shared response-format helper for list_* tools (G1 from MCP best-practices
+// review). Adds a `format: "json"|"markdown"` param so agents get structured
+// JSON (default, parsed by Proxy into structuredContent) while humans get a
+// readable Markdown table when piped to chat output.
+//
+// The markdown payload travels BOTH ways: as the text block (read by clients
+// like Kiro) and as `structuredContent: { markdown }` (read by clients like
+// Claude Code, which discard `content` whenever structuredContent is present).
+// Shipping it only one way makes format:"markdown" a no-op on one of them.
+// defineTool() applies `markdownCapable()` automatically to any tool whose
+// input shape carries `format` — see ./schemas/markdown-capable.ts for the why.
+import { z } from "zod";
+// Terse by design — see the byte-cost note on PAGINATION_SCHEMA. The enum
+// members and the "json" default are emitted structurally by JSON Schema, so
+// the description only carries what they cannot: what picking "markdown" does.
+export const FORMAT_SCHEMA = {
+    format: z
+        .enum(["json", "markdown"])
+        .optional()
+        .default("json")
+        .describe("'markdown' = human-readable table."),
+};
+/**
+ * Build the column list for a Markdown table.
+ *
+ * Most columns just print a field, and writing that out per column meant ~100
+ * `{ header: "name", get: (r) => r.name }` literals across the tool files, none
+ * of which the compiler could tie back to the row type — a renamed field left a
+ * table quietly printing empty cells. Naming the field instead makes the key
+ * `keyof Row`, so the rename becomes a compile error.
+ *
+ * `(r) => r.field ?? ""` is deliberately NOT needed: renderTable's escaper
+ * already prints null/undefined as an empty cell, and `??` leaves 0/false
+ * untouched, so the plain field name renders identically.
+ */
+export function columnsOf(specs) {
+    return specs.map((spec) => typeof spec === "string"
+        ? { header: spec, get: (row) => row[spec] }
+        : spec);
+}
+function mdEscape(v) {
+    if (v === null || v === undefined)
+        return "";
+    const s = typeof v === "string"
+        ? v
+        : Array.isArray(v)
+            ? v.join(", ")
+            : typeof v === "object"
+                ? JSON.stringify(v)
+                : String(v);
+    return s.replace(/\|/g, "\\|").replace(/\n/g, " ").replace(/\r/g, "");
+}
+// Render an object as a 2-column key/value Markdown table.
+// Nested objects become indented sub-tables; scalars stringify directly.
+export function renderKV(obj, title) {
+    const lines = [];
+    if (title)
+        lines.push(`## ${title}`, "");
+    lines.push("| key | value |", "| --- | --- |");
+    for (const [k, v] of Object.entries(obj)) {
+        if (v === null || v === undefined) {
+            lines.push(`| ${k} | _(none)_ |`);
+        }
+        else if (Array.isArray(v)) {
+            lines.push(`| ${k} | ${mdEscape(v)} |`);
+        }
+        else if (typeof v === "object") {
+            lines.push(`| **${k}** | _(see below)_ |`);
+        }
+        else {
+            lines.push(`| ${k} | ${mdEscape(v)} |`);
+        }
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+            lines.push("", `### ${k}`, "");
+            lines.push("| key | value |", "| --- | --- |");
+            for (const [k2, v2] of Object.entries(v)) {
+                lines.push(`| ${k2} | ${mdEscape(v2)} |`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export function renderTable(rows, columns) {
+    if (rows.length === 0)
+        return "_(no rows)_";
+    const headers = columns.map((c) => c.header);
+    const lines = [
+        `| ${headers.join(" | ")} |`,
+        `| ${headers.map(() => "---").join(" | ")} |`,
+        ...rows.map((row) => `| ${columns.map((c) => mdEscape(c.get(row))).join(" | ")} |`),
+    ];
+    return lines.join("\n");
+}
+export function renderPage(page, opts) {
+    const meta = `${page.total} total · ${page.count} shown · offset ${page.offset}${page.has_more ? ` · next_offset ${page.next_offset}` : ""}`;
+    const table = renderTable(page.items, opts.columns);
+    return `## ${opts.title}\n\n${meta}\n\n${table}`;
+}
+// The rendered table goes out twice on purpose: once as the text block, once
+// as structuredContent. Which of the two a client reads is not negotiable from
+// here — Kiro renders `content` and ignores structuredContent, Claude Code
+// does the reverse — so a markdown response that fills only one of them is
+// invisible on the other client. The JSON payload is deliberately NOT included
+// alongside: a client that reads structuredContent would then be shown the
+// JSON it asked not to get, which is exactly the bug this replaces.
+export function markdownResult(markdown) {
+    return {
+        content: [{ type: "text", text: markdown }],
+        structuredContent: { markdown },
+    };
+}
+// Page payload as either JSON (default, Proxy → structuredContent) or
+// Markdown table (for human display).
+export function pageResponse(page, format, opts) {
+    if (format === "markdown") {
+        return markdownResult(renderPage(page, opts));
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(page) }],
+    };
+}
+// Same as pageResponse but for tools that wrap the page envelope with extra
+// top-level fields (e.g. list_files prepends `path`). The wrapper object is
+// only used for the JSON path; the Markdown table is rendered from the inner
+// page so the metadata line stays consistent.
+export function wrappedPageResponse(wrapper, page, format, opts) {
+    if (format === "markdown") {
+        return markdownResult(renderPage(page, opts));
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(wrapper) }],
+    };
+}
+// Generic JSON-or-Markdown response for non-paginated payloads.
+// Caller supplies a markdown renderer that gets the typed payload.
+export function payloadResponse(payload, format, renderMarkdown) {
+    if (format === "markdown") {
+        return markdownResult(renderMarkdown(payload));
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+// Action-result helper for non-paginated mutation tools (delete/clear/
+// toggle/etc.) that return a flat {success, ...meta} payload. JSON-only;
+// no markdown variant since one-liner action results don't benefit from a
+// table view. structuredContent is attached so the declared-schema roundtrip
+// is satisfied without the Proxy re-parsing the JSON body.
+export function actionResponse(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        structuredContent: payload,
+    };
+}
+//# sourceMappingURL=format.js.map

package/dist/tools/hierarchy.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare const HIERARCHY_NAME_OPTIONAL: {
+    hierarchyName: z.ZodOptional<z.ZodString>;
+};
+export declare function resolveHierarchy(dimensionName: string, hierarchyName: string | undefined): string;
+//# sourceMappingURL=hierarchy.d.ts.map