@ffschrattenecker/tm1-mcp-server 6.0.0 → 7.0.0

package/dist/tools/operations/get-server-state.js

@@ -47,7 +47,7 @@ export const registerGetServerState = defineTool({
             tm1Client.server.getInfo(),
             tm1Client.cubes.list(),
             tm1Client.dimensions.list(),
-            tm1Client.processes.list(),
+            tm1Client.processes.list({ namesOnly: true }),
             tm1Client.chores.list(),
             tm1Client.security.listClients(),
         ]);

package/dist/tools/operations/get-threads.js

@@ -9,7 +9,7 @@ const registerListThreads = defineTool({
     name: "tm1_list_threads",
     description: "List active threads on the TM1 server (running processes, chores, MDX queries, etc.). Paginated (default 50/page). (v11 only)",
     annotations: READ_ONLY,
-    enabled: (tm1Client) => tm1Client.version === 11,
+    version: 11,
     output: pageShapeFor(ThreadSchema),
     input: { ...PAGINATION_SCHEMA, ...FORMAT_SCHEMA },
     handler: async ({ limit, offset, fetchAll, format }, tm1Client) => {
@@ -33,7 +33,7 @@ const registerCancelThread = defineTool({
         "(v11 only)",
     ],
     annotations: DESTRUCTIVE,
-    enabled: (tm1Client) => tm1Client.version === 11,
+    version: 11,
     output: MutationResultSchema,
     input: {
         id: z.number().int().describe("Thread ID to cancel"),

package/dist/tools/operations/get-transaction-log.js

@@ -10,7 +10,7 @@ export const registerGetTransactionLog = defineTool({
     // v12 deprecated TransactionLogEntry/TransactionLogEntries (and the
     // TransactionLog / TailTransactionLog functions) in 12.0.0; all of them serve
     // empty with no successor endpoint.
-    enabled: (tm1Client) => tm1Client.version === 11,
+    version: 11,
     output: {
         count: z.number().int(),
         coverage: z

package/dist/tools/operations/list-connections.d.ts

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

package/dist/tools/operations/list-connections.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { READ_ONLY } from "../annotations.js";
+const ConnectionSchema = z.object({
+    name: z.string(),
+    mode: z.enum(["readwrite", "readonly"]).optional(),
+    tm1Version: z.string().optional(),
+    connected: z.boolean(),
+    error: z.string().optional(),
+});
+export const registerListConnections = defineTool({
+    name: "tm1_list_connections",
+    description: "List the TM1 connections this server can reach: name (the `connection` argument of every other tool), readonly/readwrite mode, TM1 version, and whether a session is open. Makes no TM1 call.",
+    annotations: READ_ONLY,
+    output: z.object({ connections: z.array(ConnectionSchema) }),
+    input: {},
+    connectionless: true,
+    handler: (_args, registry) => {
+        const connections = registry.status().map((c) => ({
+            name: c.name,
+            ...(c.mode && { mode: c.mode }),
+            ...(c.tm1Version && { tm1Version: c.tm1Version }),
+            connected: c.connected,
+            ...((c.configError ?? c.lastError) && {
+                error: c.configError ?? c.lastError,
+            }),
+        }));
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ connections }) },
+            ],
+        };
+    },
+});
+//# sourceMappingURL=list-connections.js.map

package/dist/tools/operations/save-data.js

@@ -13,7 +13,7 @@ export const registerSaveData = defineTool({
         "Executes as an unbound TI process via ExecuteProcessWithReturn; no process object is created on the server.",
     ],
     annotations: withVersion(IDEMPOTENT_WRITE, "v11"),
-    enabled: (tm1Client) => tm1Client.version === 11,
+    version: 11,
     output: MutationResultSchema,
     input: {
         cube: z

package/dist/tools/schemas/items-monitoring.d.ts

@@ -4,6 +4,17 @@ export declare const ServerInfoSchema: z.ZodObject<{
     mcpServer: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         version: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            readwrite: "readwrite";
+            readonly: "readonly";
+        }>>;
+        environment: z.ZodOptional<z.ZodEnum<{
+            dev: "dev";
+            test: "test";
+            prod: "prod";
+            unspecified: "unspecified";
+        }>>;
+        modeReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     serverName: z.ZodString;
     productVersion: z.ZodString;

package/dist/tools/schemas/items-monitoring.js

@@ -7,7 +7,15 @@ export { AuditLogDetailSchema, ErrorLogFileSchema, JobSchema, MessageLogEntrySch
 import { AuditLogDetailSchema } from "../../schemas/monitoring.js";
 export const ServerInfoSchema = z
     .object({
-    mcpServer: z.object({ name: z.string(), version: z.string() }).optional(),
+    mcpServer: z
+        .object({
+        name: z.string(),
+        version: z.string(),
+        mode: z.enum(["readwrite", "readonly"]).optional(),
+        environment: z.enum(["dev", "test", "prod", "unspecified"]).optional(),
+        modeReason: z.string().optional(),
+    })
+        .optional(),
     serverName: z.string(),
     productVersion: z.string(),
     productEdition: z.string().optional(),

package/dist/tools/schemas/items-processes.d.ts

@@ -154,12 +154,15 @@ export declare const UpsertProcessResultSchema: z.ZodObject<{
     action: z.ZodEnum<{
         created: "created";
         updated: "updated";
+        wouldCreate: "wouldCreate";
+        wouldUpdate: "wouldUpdate";
     }>;
     appliedSteps: z.ZodArray<z.ZodString>;
     backup: z.ZodOptional<z.ZodObject<{
         json: z.ZodString;
         ti: z.ZodString;
     }, z.core.$strip>>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export declare const InstallProBundleResultSchema: z.ZodObject<{
     directory: z.ZodString;

package/dist/tools/schemas/items-processes.js

@@ -102,9 +102,10 @@ const ProcessBackupSchema = z.object({ json: z.string(), ti: z.string() });
 export const UpsertProcessResultSchema = z
     .object({
     processName: z.string(),
-    action: z.enum(["created", "updated"]),
+    action: z.enum(["created", "updated", "wouldCreate", "wouldUpdate"]),
     appliedSteps: z.array(z.string()),
     backup: ProcessBackupSchema.optional(),
+    dryRun: z.boolean().optional(),
 })
     .passthrough();
 const InstallBundleEntrySchema = z

package/dist/tools/ti-development/diff-processes.d.ts

@@ -1,2 +1,44 @@
+import type { ProcessParameter, ProcessVariable, DataSource } from "../../types.js";
+interface DiffHunk {
+    startA: number;
+    countA: number;
+    startB: number;
+    countB: number;
+    lines: Array<{
+        type: " " | "+" | "-";
+        text: string;
+    }>;
+}
+export declare function tabCodeDiff(codeA: string, codeB: string, contextLines: number): {
+    identical: boolean;
+    linesA: number;
+    linesB: number;
+    hunks: DiffHunk[];
+};
+export declare function diffParams(a: ProcessParameter[], b: ProcessParameter[]): {
+    identical: boolean;
+    added: string[];
+    removed: string[];
+    changed: {
+        name: string;
+        a: ProcessParameter;
+        b: ProcessParameter;
+    }[];
+};
+export declare function diffVars(a: ProcessVariable[], b: ProcessVariable[]): {
+    identical: boolean;
+    added: string[];
+    removed: string[];
+    changed: {
+        name: string;
+        a: ProcessVariable;
+        b: ProcessVariable;
+    }[];
+};
+export declare function diffDs(a: DataSource, b: DataSource): {
+    identical: boolean;
+    differences: string[];
+};
 export declare const registerDiffProcesses: import("../define-tool.js").ToolRegistrar;
+export {};
 //# sourceMappingURL=diff-processes.d.ts.map

package/dist/tools/ti-development/diff-processes.js

@@ -105,7 +105,7 @@ function buildHunks(ops, contextLines) {
     });
 }
 const NORM = (s) => s.replace(/\r\n/g, "\n").trimEnd();
-function tabCodeDiff(codeA, codeB, contextLines) {
+export function tabCodeDiff(codeA, codeB, contextLines) {
     const na = NORM(codeA);
     const nb = NORM(codeB);
     if (na === nb) {
@@ -119,7 +119,7 @@ function tabCodeDiff(codeA, codeB, contextLines) {
     return { identical: false, linesA: a.length, linesB: b.length, hunks };
 }
 // ── param / var / datasource diff ────────────────────────────────────────────
-function diffParams(a, b) {
+export function diffParams(a, b) {
     const ma = new Map(a.map((p) => [p.name, p]));
     const mb = new Map(b.map((p) => [p.name, p]));
     const added = [];
@@ -147,7 +147,7 @@ function diffParams(a, b) {
         changed,
     };
 }
-function diffVars(a, b) {
+export function diffVars(a, b) {
     const ma = new Map(a.map((v) => [v.name, v]));
     const mb = new Map(b.map((v) => [v.name, v]));
     const added = [];
@@ -204,7 +204,7 @@ function diffIgnoredColumns(a, b) {
         renamed,
     };
 }
-function diffDs(a, b) {
+export function diffDs(a, b) {
     const diffs = [];
     const fields = [
         "type",

package/dist/tools/ti-development/execute-process.js

@@ -5,6 +5,7 @@ import { CONFIRM_SCHEMA, requireConfirm } from "../confirm.js";
 import { DESTRUCTIVE } from "../annotations.js";
 import { ProcessResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
+import { tailLines } from "../operations/error-log-helpers.js";
 /**
  * Client-abort recovery hint, branched by TM1 major version: v11 exposes
  * server threads (tm1_list_threads / tm1_cancel_thread), v12 exposes jobs
@@ -15,13 +16,24 @@ export function abortHint(version) {
     const cancel = version === 12 ? "tm1_cancel_job" : "tm1_cancel_thread";
     return `Request aborted by the client — the process was NOT confirmed failed and may still be executing. Use ${monitor} to check for it and ${cancel} to stop it. Do NOT blindly re-run: that risks a duplicate execution.`;
 }
+const ERROR_LOG_TAIL_LINES = 40;
+async function fetchErrorLog(tm1Client, filename) {
+    try {
+        const raw = await tm1Client.server.getErrorLogContent(filename);
+        const { body, truncated, totalLines } = tailLines(raw, ERROR_LOG_TAIL_LINES);
+        return { filename, totalLines, truncated, content: body };
+    }
+    catch (e) {
+        return { filename, fetchError: e.message };
+    }
+}
 export const registerExecuteProcess = defineTool({
     name: "tm1_execute_process",
     description: [
         "Execute a TurboIntegrator process on the TM1 server with optional parameters.",
         "Non-idempotent: each call re-runs the process — do not retry blindly on transport errors without checking server state.",
-        "Before: tm1_check_process_code (syntax) and/or tm1_compile_process (full compile). Discover required params with tm1_get_process_parameters.",
-        "On failure: use tm1_diagnose_process_error for combined log + cascade fetch.",
+        "Before: tm1_check_process_code (syntax) and/or tm1_compile_process (full compile). Discover required params with tm1_get_process.",
+        "When TM1 wrote an error log for the run (failure or minor errors), its last 40 lines come back as errorLog. For cascade siblings and older logs use tm1_diagnose_process_error.",
     ],
     annotations: DESTRUCTIVE,
     output: ProcessResultSchema,
@@ -74,9 +86,22 @@ export const registerExecuteProcess = defineTool({
             const result = await withToolHint(tm1Client.processes.execute(processName, parameters, {
                 signal: extra?.signal,
                 ...(timeoutMs ? { timeoutMs } : {}),
-            }), `Process '${processName}' failed at runtime. Inspect cascade with tm1_diagnose_process_error(processName='${processName}', includeRelated=true). Verify parameter shape via tm1_get_process_parameters; check syntax with tm1_compile_process before re-running.`);
+            }), `Process '${processName}' failed at runtime. Inspect cascade with tm1_diagnose_process_error(processName='${processName}', includeRelated=true). Verify parameter shape via tm1_get_process; check syntax with tm1_compile_process before re-running.`);
+            // TM1 names the run's own error log when it wrote one (minor errors
+            // included). Attach its tail so judging the run takes no extra call.
+            const errorLog = result.errorLogFile
+                ? await fetchErrorLog(tm1Client, result.errorLogFile)
+                : undefined;
             return {
-                content: [{ type: "text", text: JSON.stringify(result) }],
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ...result,
+                            ...(errorLog ? { errorLog } : {}),
+                        }),
+                    },
+                ],
                 // A TI process that ran but reported failure is a tool failure, not a
                 // successful call carrying success:false. Flag isError so agents that
                 // branch on the MCP error signal don't silently treat it as success;

package/dist/tools/ti-development/import-pro-file.js

@@ -79,7 +79,7 @@ export const registerImportProFile = defineTool({
             if (failure)
                 return preflightResult(failure);
         }
-        const allProcs = await tm1Client.processes.list();
+        const allProcs = await tm1Client.processes.list({ namesOnly: true });
         const exists = allProcs.some((p) => p.name === processName);
         if (mode === "create" && exists) {
             throw new TM1Error({

package/dist/tools/ti-development/preflight.d.ts

@@ -36,4 +36,28 @@ export declare function preflightResult(failure: PreflightFailure): {
     }[];
     isError: true;
 };
+export interface PreflightChecks {
+    ok: boolean;
+    syntax: {
+        ok: boolean;
+        errors: Array<{
+            procedure?: string | undefined;
+            lineNumber?: number | undefined;
+            message: string;
+        }>;
+    };
+    references: {
+        ok: boolean;
+        unresolved: number;
+        issues: RefIssue[];
+        partial: boolean;
+        unresolvableArgs: number;
+    };
+}
+/**
+ * Both checks, neither short-circuiting the other: the dryRun report the
+ * user approves from. runPreflight stops at the first failure because the
+ * install is refused either way; a pre-approval report needs every finding.
+ */
+export declare function runChecks(tm1Client: TM1Client, p: PreflightPayload): Promise<PreflightChecks>;
 //# sourceMappingURL=preflight.d.ts.map

package/dist/tools/ti-development/preflight.js

@@ -53,4 +53,36 @@ export function preflightResult(failure) {
         isError: true,
     };
 }
+/**
+ * Both checks, neither short-circuiting the other: the dryRun report the
+ * user approves from. runPreflight stops at the first failure because the
+ * install is refused either way; a pre-approval report needs every finding.
+ */
+export async function runChecks(tm1Client, p) {
+    const [check, refs] = await Promise.all([
+        tm1Client.processes.check({
+            name: p.name,
+            prolog: p.prolog,
+            metadata: p.metadata,
+            data: p.data,
+            epilog: p.epilog,
+            ...(p.parameters !== undefined ? { parameters: p.parameters } : {}),
+            ...(p.variables !== undefined ? { variables: p.variables } : {}),
+            ...(p.dataSource !== undefined ? { dataSource: p.dataSource } : {}),
+        }),
+        checkProcessRefs(tm1Client, p),
+    ]);
+    const references = {
+        ok: refs.unresolved === 0,
+        unresolved: refs.unresolved,
+        issues: refs.issues,
+        partial: refs.partial,
+        unresolvableArgs: refs.unresolvableArgs,
+    };
+    return {
+        ok: check.success && references.ok,
+        syntax: { ok: check.success, errors: check.errors },
+        references,
+    };
+}
 //# sourceMappingURL=preflight.js.map

package/dist/tools/ti-development/search-code.js

@@ -14,7 +14,7 @@ export const registerSearchCode = defineTool({
         "Regex search across all TI process code (Prolog/Metadata/Data/Epilog).",
         "Returns matches paginated (default 50/page) with process name, tab, line number, and trimmed line text.",
         "Wrapper over tm1_get_all_processes_code that avoids dumping ~MB of code through the channel.",
-        "Use tm1_get_process_code on a hit to inspect the surrounding context.",
+        "Use tm1_get_process on a hit to inspect the surrounding context.",
         "Set groupBy='process' (or 'tab') for a sorted count aggregation instead of individual match lines.",
     ],
     annotations: READ_ONLY,

package/dist/tools/ti-development/upsert-process.js

@@ -6,12 +6,14 @@ import { IDEMPOTENT_DESTRUCTIVE } from "../annotations.js";
 import { UpsertProcessResultSchema } from "../schemas/items.js";
 import { defineTool } from "../define-tool.js";
 import { OVERWRITE_CONFIRM_SCHEMA, requireOverwriteConfirm, } from "../confirm.js";
-import { preflightResult, runPreflight } from "./preflight.js";
+import { preflightResult, runChecks, runPreflight, } from "./preflight.js";
+import { diffDs, diffParams, diffVars, tabCodeDiff } from "./diff-processes.js";
+import { maskCode } from "../../lib/mask-secrets.js";
 import { backupProcess } from "./process-backup.js";
 // The same data source shape the git round-trip and check_process_code use.
 // This tool used to carry its own copy, which had drifted: it was missing
 // `query`, so an ODBC source could be created here but its SQL could not —
-// while tm1_get_process_datasource reads it back.
+// while tm1_get_process reads it back.
 // Strict, so a misspelled field is rejected instead of silently dropped.
 const dataSourceSchema = sharedDataSourceSchema.strict();
 const parameterSchema = z.object({
@@ -20,6 +22,7 @@ const parameterSchema = z.object({
     defaultValue: z.union([z.string(), z.number()]),
     prompt: z.string().optional(),
 });
+const TABS = ["prolog", "metadata", "data", "epilog"];
 const variableSchema = z.object({
     name: z.string(),
     type: z.enum(["String", "Numeric"]),
@@ -57,8 +60,13 @@ export const registerUpsertProcess = defineTool({
             .optional()
             .default(false)
             .describe("After deploy, run tm1.Compile and include the result in the response (compile: {ok, errorCount, errors}). Off by default — compile holds a brief lock on the process and serializes badly under bulk-deploy."),
+        dryRun: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Write nothing. Run the syntax AND reference check on the process as it would be after this call (both reported, neither stops the other) and diff it against the installed version (credentials masked). Needs no confirm and is not one: the real call still needs it. Replaces a separate check_process_code + validate_process_refs + diff before the risk assessment."),
     },
-    handler: async ({ processName, prolog, metadata, data, epilog, parameters, variables, dataSource, hasSecurityAccess, mode, preflight, autoCompile, confirm, }, tm1Client) => {
+    handler: async ({ processName, prolog, metadata, data, epilog, parameters, variables, dataSource, hasSecurityAccess, mode, preflight, autoCompile, dryRun, confirm, }, tm1Client) => {
         const trail = [];
         const exists = await tm1Client.processes.exists(processName);
         if (mode === "create" && exists) {
@@ -73,16 +81,13 @@ export const registerUpsertProcess = defineTool({
                 message: `Process '${processName}' does not exist; mode=update`,
             });
         }
-        // Replacing an installed process is not undoable through the API.
-        if (exists)
-            requireOverwriteConfirm(confirm, processName, "process");
-        if (preflight) {
-            // Check the process as it will stand after this call, not the fields
-            // the caller happened to send: an omitted tab keeps its installed code.
+        // The process as it will stand after this call, not the fields the
+        // caller happened to send: an omitted tab keeps its installed code.
+        const resolve = async () => {
             const current = exists
                 ? await tm1Client.processes.getCode(processName)
                 : { prolog: "", metadata: "", data: "", epilog: "" };
-            const failure = await runPreflight(tm1Client, {
+            return {
                 name: processName,
                 prolog: prolog ?? current.prolog,
                 metadata: metadata ?? current.metadata,
@@ -96,7 +101,79 @@ export const registerUpsertProcess = defineTool({
                         ? await tm1Client.processes.getVariables(processName)
                         : [],
                 ...(dataSource !== undefined ? { dataSource } : {}),
-            });
+            };
+        };
+        if (dryRun) {
+            // Deliberately before the confirm gate: a dry run writes nothing, and
+            // it is what the risk assessment is built from.
+            const payload = await resolve();
+            const [checks, installed, installedParams] = await Promise.all([
+                runChecks(tm1Client, payload),
+                exists
+                    ? tm1Client.processes.getCode(processName)
+                    : Promise.resolve({ prolog: "", metadata: "", data: "", epilog: "" }),
+                exists
+                    ? tm1Client.processes.getParameters(processName)
+                    : Promise.resolve([]),
+            ]);
+            const tabs = Object.fromEntries(TABS.map((t) => [
+                t,
+                tabCodeDiff(maskCode(installed[t] ?? ""), maskCode(payload[t]), 3),
+            ]));
+            const params = diffParams(installedParams, payload.parameters ?? []);
+            // Variables and datasource change only when the caller sends them; a
+            // datasource swap must not come back as "identical".
+            const sendsVars = variables !== undefined && variables.length > 0;
+            const [installedVars, installedDs] = await Promise.all([
+                sendsVars && exists
+                    ? tm1Client.processes.getVariableLayout(processName)
+                    : Promise.resolve({ variables: [] }),
+                dataSource !== undefined && exists
+                    ? tm1Client.processes.getDataSource(processName)
+                    : Promise.resolve({}),
+            ]);
+            const vars = sendsVars
+                ? diffVars(installedVars.variables, variables)
+                : undefined;
+            const ds = dataSource !== undefined
+                ? // updateDataSource PATCHes only the fields sent; the rest stay.
+                    diffDs(installedDs, {
+                        ...installedDs,
+                        ...dataSource,
+                    })
+                : undefined;
+            const identical = Object.values(tabs).every((t) => t.identical) &&
+                params.identical &&
+                (vars?.identical ?? true) &&
+                (ds?.identical ?? true);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            processName,
+                            dryRun: true,
+                            action: exists ? "wouldUpdate" : "wouldCreate",
+                            appliedSteps: [],
+                            overwritesExisting: exists,
+                            checks,
+                            diff: {
+                                identical,
+                                tabs,
+                                parameters: params,
+                                ...(vars ? { variables: vars } : {}),
+                                ...(ds ? { dataSource: ds } : {}),
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        // Replacing an installed process is not undoable through the API.
+        if (exists)
+            requireOverwriteConfirm(confirm, processName, "process");
+        if (preflight) {
+            const failure = await runPreflight(tm1Client, await resolve());
             if (failure)
                 return preflightResult(failure);
         }
@@ -137,6 +214,17 @@ export const registerUpsertProcess = defineTool({
         // Process body/parameters/datasource may have changed call sites — drop the
         // 60s callgraph TTL so the next analysis sees fresh references instead of stale graph.
         const { cleared: callgraphEntriesCleared } = invalidateCallgraphCache();
+        // Read the code back: TM1 stores what REST sent, so a mismatch means the
+        // write did not land as sent. Saves the caller a get_process turn.
+        const sent = { prolog, metadata, data, epilog };
+        const sentTabs = TABS.filter((t) => sent[t] !== undefined);
+        let verified;
+        if (sentTabs.length > 0) {
+            const stored = await tm1Client.processes.getCode(processName);
+            const norm = (x) => (x ?? "").replace(/\r\n/g, "\n").trimEnd();
+            const mismatchedTabs = sentTabs.filter((t) => norm(stored[t]) !== norm(sent[t]));
+            verified = { codeMatches: mismatchedTabs.length === 0, mismatchedTabs };
+        }
         let compile;
         if (autoCompile) {
             const result = await tm1Client.processes.compile(processName);
@@ -157,6 +245,7 @@ export const registerUpsertProcess = defineTool({
                         appliedSteps: trail,
                         callgraphEntriesCleared,
                         ...(backup ? { backup } : {}),
+                        ...(verified !== undefined ? { verified } : {}),
                         ...(compile !== undefined ? { compile } : {}),
                     }, null, 2),
                 },

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

@@ -1,6 +1,16 @@
 import type pino from "pino";
 import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type McpToolResult } from "./error-format.js";
 export declare function deriveTitle(toolName: string): string;
+/**
+ * Cut an oversized page down to the longest prefix of its items that fits,
+ * turning it into an ordinary shorter page: count, has_more and next_offset
+ * are rewritten so the caller walks on from exactly where it stopped. The
+ * result is still valid JSON of the declared shape — unlike a text cut — and
+ * the call is not wasted. Returns undefined when not even one item fits (or
+ * the payload is not a page), leaving the caller to report the overflow.
+ */
+export declare function trimPageToFit(result: McpToolResult, maxChars: number): McpToolResult | undefined;
 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

@@ -14,7 +14,7 @@ const TITLE_CASING = {
     v11: "v11",
 };
 // Derive a human-readable title from a snake_case tool name:
-// "tm1_get_process_code" → "Get Process Code". Single point of derivation —
+// "tm1_get_process" → "Get Process". Single point of derivation —
 // no per-tool overrides in ANNOTATION_MAP.
 export function deriveTitle(toolName) {
     return toolName
@@ -49,6 +49,55 @@ function responseChars(result) {
         return text;
     return JSON.stringify(result.structuredContent).length;
 }
+function isPagePayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (Array.isArray(v.items) &&
+        typeof v.offset === "number" &&
+        typeof v.total === "number");
+}
+/**
+ * Cut an oversized page down to the longest prefix of its items that fits,
+ * turning it into an ordinary shorter page: count, has_more and next_offset
+ * are rewritten so the caller walks on from exactly where it stopped. The
+ * result is still valid JSON of the declared shape — unlike a text cut — and
+ * the call is not wasted. Returns undefined when not even one item fits (or
+ * the payload is not a page), leaving the caller to report the overflow.
+ */
+export function trimPageToFit(result, maxChars) {
+    const page = result.structuredContent;
+    if (!isPagePayload(page))
+        return undefined;
+    const withText = (result.content ?? []).some((c) => c.type === "text");
+    const build = (n) => {
+        const trimmed = {
+            ...page,
+            count: n,
+            has_more: true, // n < items.length: at least one item was dropped
+            next_offset: page.offset + n,
+            items: page.items.slice(0, n),
+        };
+        return {
+            ...result,
+            content: withText
+                ? [{ type: "text", text: JSON.stringify(trimmed) }]
+                : [],
+            structuredContent: trimmed,
+        };
+    };
+    // Largest n in [1, items.length) whose serialization fits.
+    let lo = 0;
+    let hi = page.items.length - 1;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (responseChars(build(mid)) <= maxChars)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo > 0 ? build(lo) : undefined;
+}
 // 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) {
@@ -199,12 +248,18 @@ responseMode = "legacy", maxResponseChars = DEFAULT_MAX_RESPONSE_CHARS) {
         }
     };
     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.
+    // An oversized page is cut to the items that fit (see trimPageToFit).
+    // Anything else becomes an error that says how to narrow the call — never a
+    // truncated text: a cut JSON payload is worse than none.
     const guardSize = (toolName, result, hint) => {
         const size = responseChars(result);
         if (size <= maxResponseChars)
             return result;
+        const trimmed = trimPageToFit(result, maxResponseChars);
+        if (trimmed) {
+            logger.info({ tool: toolName, size, maxResponseChars }, "page trimmed to fit the response limit");
+            return trimmed;
+        }
         logger.warn({ tool: toolName, size, maxResponseChars }, "response too large");
         return formatTm1ErrorResult(new TM1Error({
             code: TM1ErrorCode.RESPONSE_TOO_LARGE,