@atlassian/mcp-compressor 0.37.0 → 0.38.0

package/dist/executable_tool_bridge.d.ts

@@ -1,3 +1,4 @@
+import { type HostShrinkfitOptions } from "./host_shrinkfit.js";
 import type { ExecutableTool } from "./adapters.js";
 import type { ToolSpec } from "./rust_core.js";
 export interface ExecutableToolBridgeServer {
@@ -15,7 +16,7 @@ export interface ExecutableToolBridge extends ExecutableToolBridgeRuntime {
     token: string;
     close(): void;
 }
-export interface CreateExecutableToolBridgeOptions {
+export interface CreateExecutableToolBridgeOptions extends HostShrinkfitOptions {
     serverName: string;
 }
 export declare function createExecutableToolBridge(tools: Record<string, ExecutableTool<unknown>>, options: CreateExecutableToolBridgeOptions): Promise<ExecutableToolBridge>;

package/dist/executable_tool_bridge.js

@@ -1,6 +1,9 @@
+import { shrinkfitTools } from "./host_shrinkfit.js";
 import { startLocalToolBridge } from "./local_tool_bridge.js";
 import { executableToolsToSpecs } from "./tool_specs.js";
 export async function createExecutableToolBridge(tools, options) {
+    const shrinking = shrinkfitTools(tools, options);
+    tools = shrinking.tools;
     const bridge = await startLocalToolBridge(tools);
     const server = {
         name: options.serverName,
@@ -12,7 +15,10 @@ export async function createExecutableToolBridge(tools, options) {
         server,
         bridgeUrl: bridge.bridgeUrl,
         token: bridge.token,
-        close: bridge.close,
+        close: () => {
+            shrinking.close();
+            bridge.close();
+        },
         invokeTool: async (toolName, input = {}) => invokeBridgeTool(bridge.bridgeUrl, bridge.token, toolName, input),
     };
 }

package/dist/host_shrinkfit.d.ts

@@ -0,0 +1,10 @@
+import type { ExecutableTool } from "./adapters.js";
+export interface HostShrinkfitOptions {
+    /** Text-content character budget including recovery instructions. Structured content is never shrunk. Disabled by default. */
+    shrinkfit?: number;
+}
+/** Per-toolset recovery: no files, no backend retries, no shared cross-session cache. */
+export declare function shrinkfitTools(tools: Record<string, ExecutableTool<unknown>>, options?: HostShrinkfitOptions): {
+    tools: Record<string, ExecutableTool<unknown>>;
+    close(): void;
+};

package/dist/host_shrinkfit.js

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto";
+import { loadNativeCore } from "./native.js";
+import { normalizeHostToolResult } from "./rust_core.js";
+/** Per-toolset recovery: no files, no backend retries, no shared cross-session cache. */
+export function shrinkfitTools(tools, options = {}) {
+    const limit = options.shrinkfit;
+    if (limit === undefined)
+        return { tools, close() { } };
+    if (!Number.isInteger(limit) || limit <= 0 || limit > 0xffffffff) {
+        throw new Error("shrinkfit must be a positive integer no greater than 4294967295");
+    }
+    // Avoid collisions with genuine upstream tools, including CLI kebab aliases.
+    let recoveryName = "compressor_recover_response";
+    const normalizeName = (name) => name.replace(/[^a-z0-9]/giu, "").toLowerCase();
+    const names = new Set(Object.keys(tools).map(normalizeName));
+    let suffix = 2;
+    while (names.has(normalizeName(recoveryName)))
+        recoveryName = `compressor_recover_response_${suffix++}`;
+    const cache = new Map();
+    const maxBytes = 64 * 1024 * 1024;
+    let bytes = 0;
+    let closed = false;
+    function remove(id) {
+        const entry = cache.get(id);
+        if (entry)
+            bytes -= entry.bytes;
+        cache.delete(id);
+    }
+    function prune() {
+        for (const [id, entry] of cache)
+            if (entry.expires <= Date.now())
+                remove(id);
+    }
+    const result = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        result[name] = {
+            ...tool,
+            execute: async (input) => {
+                if (closed)
+                    throw new Error("Shrinkfit toolset is closed");
+                const value = await tool.execute(input);
+                // Error and multimodal envelopes must retain their original semantics.
+                if (preserveEnvelope(value))
+                    return value;
+                // Envelope content is presentation; structuredContent is schema-bearing.
+                // Preserve all envelope fields and shrink only text blocks, never the
+                // serialized envelope or its structured payload.
+                const envelope = contentEnvelope(value);
+                if (envelope && !Array.isArray(envelope.content))
+                    return value;
+                const blocks = envelope?.content;
+                const output = blocks
+                    ? blocks.map((block) => (typeof block.text === "string" ? block.text : "")).join("\n")
+                    : normalizeHostToolResult(value, false);
+                if (output.length <= limit || withinLimit(output, limit))
+                    return value;
+                const id = randomUUID();
+                const message = `This response was automatically shrunk to limit token consumption. Only if more detail is required, call ${recoveryName} with response_id=${id} (CLI: --response-id ${id}). Recovery returns the cached original without repeating the upstream call. Cache expires after 5 minutes and may be evicted earlier.`;
+                let preview;
+                try {
+                    if (blocks) {
+                        // Budget all text, including separators, without touching annotations.
+                        let remaining = limit - Math.max(0, blocks.length - 1);
+                        const pending = blocks.map((block, index) => ({
+                            block,
+                            index,
+                            length: Array.from(String(block.text ?? "")).length,
+                        }));
+                        const content = blocks.map((block) => ({ ...block }));
+                        // Small blocks retain their full text; divide remaining space among
+                        // larger blocks. A budget too small for notices fails explicitly.
+                        pending.sort((a, b) => a.length - b.length);
+                        for (let i = 0; i < pending.length; i++) {
+                            const { block, index, length } = pending[i];
+                            const budget = Math.floor(remaining / (pending.length - i));
+                            if (budget < 1)
+                                throw new Error("Text content budget too small");
+                            const text = String(block.text ?? "");
+                            const condensed = length <= budget ? text : ((await shrinkOutput(text, budget, message)) ?? text);
+                            content[index] = { ...block, text: condensed };
+                            remaining -= Array.from(condensed).length;
+                        }
+                        preview = replaceContentEnvelope(value, { ...envelope, content });
+                    }
+                    else {
+                        preview = await shrinkOutput(output, limit, message);
+                    }
+                }
+                catch (error) {
+                    throw new Error(`Could not shrink response after upstream execution; do not retry a write. ${error instanceof Error ? error.message : String(error)}`);
+                }
+                if (preview === null)
+                    return value;
+                if (closed)
+                    throw new Error("Shrinkfit toolset was closed during execution");
+                const original = envelope ? JSON.stringify(value) : output;
+                const size = Buffer.byteLength(original, "utf8");
+                if (size > maxBytes)
+                    throw new Error("Response exceeds shrinkfit recovery cache capacity; upstream call already executed. Do not retry a write.");
+                prune();
+                while (cache.size >= 128 || bytes + size > maxBytes)
+                    remove(cache.keys().next().value);
+                cache.set(id, { output: original, bytes: size, expires: Date.now() + 300_000 });
+                bytes += size;
+                return preview;
+            },
+        };
+    }
+    result[recoveryName] = {
+        name: recoveryName,
+        description: "Retrieve a complete cached response only when its shortened preview lacks required information. Never repeats an upstream call. IDs are scoped to this toolset; expired or evicted IDs fail safely.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                response_id: { type: "string", description: "Response ID from the truncation notice." },
+            },
+            required: ["response_id"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            prune();
+            const id = input?.response_id;
+            const entry = typeof id === "string" && !closed ? cache.get(id) : undefined;
+            if (!entry)
+                throw new Error("Recovery response unavailable (unknown, expired, evicted, or closed). The upstream tool was NOT called.");
+            return entry.output;
+        },
+    };
+    return {
+        tools: result,
+        close() {
+            closed = true;
+            cache.clear();
+            bytes = 0;
+        },
+    };
+}
+function preserveEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const object = value;
+    if (Object.keys(object).length === 1 && "result" in object)
+        return preserveEnvelope(object.result);
+    if (object.isError === true)
+        return true;
+    return (Array.isArray(object.content) &&
+        object.content.some((block) => !block || typeof block !== "object" || block.type !== "text"));
+}
+function withinLimit(output, limit) {
+    let count = 0;
+    for (const _char of output)
+        if (++count > limit)
+            return false;
+    return true;
+}
+// Bound active CPU jobs across toolsets (N-API itself executes these off-thread).
+let activeJobs = 0;
+const waiters = [];
+async function shrinkOutput(output, limit, message) {
+    if (activeJobs >= 4)
+        await new Promise((resolve) => waiters.push(resolve));
+    else
+        activeJobs++;
+    try {
+        return await loadNativeCore().shrinkHostOutput(output, limit, message);
+    }
+    finally {
+        const next = waiters.shift();
+        if (next)
+            next();
+        else
+            activeJobs--;
+    }
+}
+function contentEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const object = value;
+    if (Object.keys(object).length === 1 && "result" in object)
+        return contentEnvelope(object.result);
+    return "content" in object || "structuredContent" in object ? object : undefined;
+}
+function replaceContentEnvelope(value, envelope) {
+    const object = value;
+    return Object.keys(object).length === 1 && "result" in object
+        ? { ...object, result: replaceContentEnvelope(object.result, envelope) }
+        : envelope;
+}

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export * from "./transforms.js";
 export { interpolateString, interpolateRecord, interpolateMCPConfig, parseServerConfigJson, normalizeConfigServer, } from "./config.js";
 export type { BackendConfig, HttpBackendConfig, JsonConfigServerEntry, MCPConfigShape, SseBackendConfig, StdioBackendConfig, } from "./types.js";
 export { type GeneratedClientKind, type GeneratedCodeClient, type JustBashCommand, type JustBashProvider, type CompressorClientOptions, type NativeCompressorMode as CompressorMode, type NativeServersInput as ServersInput, CompressorClient, CompressorProxy, type NormalizedBackendConfig, type ProxyResponse, type ProxyTool, normalizeServers, } from "./native_client.js";
+export * from "./host_shrinkfit.js";

package/dist/index.js

@@ -12,3 +12,4 @@ export * from "./tool_specs.js";
 export * from "./transforms.js";
 export { interpolateString, interpolateRecord, interpolateMCPConfig, parseServerConfigJson, normalizeConfigServer, } from "./config.js";
 export { CompressorClient, CompressorProxy, normalizeServers, } from "./native_client.js";
+export * from "./host_shrinkfit.js";

package/dist/local_tools.d.ts

@@ -1,3 +1,4 @@
+import { type HostShrinkfitOptions } from "./host_shrinkfit.js";
 import type { CompressionLevel } from "./types.js";
 import type { ExecutableTool } from "./adapters.js";
 export interface LocalTool<TInput = Record<string, unknown>, TResult = unknown> {
@@ -5,7 +6,7 @@ export interface LocalTool<TInput = Record<string, unknown>, TResult = unknown>
     inputSchema: unknown;
     execute: (input: TInput) => TResult | Promise<TResult>;
 }
-export interface CompressToolsOptions {
+export interface CompressToolsOptions extends HostShrinkfitOptions {
     compressionLevel?: CompressionLevel;
     namePrefix?: string;
     toonify?: boolean;

package/dist/local_tools.js

@@ -1,3 +1,4 @@
+import { shrinkfitTools } from "./host_shrinkfit.js";
 import { compressToolListing, formatToolSchemaResponse, normalizeHostToolResult, } from "./rust_core.js";
 import { stringifyToolResult } from "./tool_specs.js";
 function wrapperName(prefix, name) {
@@ -48,6 +49,24 @@ export function compressTools(tools, options = {}) {
         description: tool.description,
         inputSchema: asJsonSchema(tool.inputSchema, options.schemaAdapter),
     }));
+    if (options.shrinkfit !== undefined) {
+        const executable = Object.fromEntries(specs.map((spec) => [
+            spec.name,
+            {
+                ...tools[spec.name],
+                name: spec.name,
+                execute: async (input) => tools[spec.name].execute(input),
+                inputSchema: spec.inputSchema,
+            },
+        ]));
+        const shrunk = shrinkfitTools(executable, options);
+        return compressTools(shrunk.tools, {
+            ...options,
+            shrinkfit: undefined,
+            toonify: false,
+            schemaAdapter: undefined,
+        });
+    }
     const specByName = new Map(specs.map((spec) => [spec.name, spec]));
     const toolByName = new Map(Object.entries(tools));
     const listing = compressToolListing(compressionLevel, specs);

package/dist/native.d.ts

@@ -4,6 +4,7 @@ export interface NativeToolSpec {
     input_schema: Record<string, unknown>;
 }
 export interface NativeCore {
+    shrinkHostOutput(output: string, maxChars: number, recoveryMessage: string): Promise<string | null>;
     compressToolListingJson(level: string, toolsJson: string): string;
     formatToolSchemaResponseJson(toolJson: string): string;
     maybeToonifyOutputJson(output: string): string;

package/dist/transforms.d.ts

@@ -1,6 +1,7 @@
+import { type HostShrinkfitOptions } from "./host_shrinkfit.js";
 import type { ExecutableTool } from "./adapters.js";
 import { type JustBashCommandRegistration } from "./just_bash_commands.js";
-export interface TransformToolOptions {
+export interface TransformToolOptions extends HostShrinkfitOptions {
     serverName?: string;
 }
 export interface PlanToolsForJustBashOptions extends TransformToolOptions {
@@ -15,6 +16,7 @@ export interface TransformToolsForJustBashOptions extends PlanToolsForJustBashOp
     bash: unknown;
 }
 export interface JustBashTransformResult {
+    close(): void;
     tools: Record<string, ExecutableTool>;
     registrations: JustBashCommandRegistration[];
 }

package/dist/transforms.js

@@ -1,14 +1,18 @@
+import { shrinkfitTools } from "./host_shrinkfit.js";
 import { createJustBashCommandRegistrations, installJustBashRegistrations, } from "./just_bash_commands.js";
 import { startLocalToolBridge } from "./local_tool_bridge.js";
 import { buildHostTransformPlan, normalizeHostToolResult, } from "./rust_core.js";
 import { executableToolToSpec, executableToolsToSpecs, normalizeServerName } from "./tool_specs.js";
 export function planToolsForJustBash(tools, options = {}) {
     const serverName = normalizeServerName(options.serverName);
+    const shrinking = shrinkfitTools(tools, options);
+    tools = shrinking.tools;
     const toolSpecs = executableToolsToSpecs(tools);
     const plan = buildHostTransformPlan({ kind: "just-bash", serverName, tools: toolSpecs });
-    const registrations = createJustBashCommandRegistrations((plan.justBash?.commands ?? []).map((command) => justBashSource(serverName, command.commandName, command.backendToolName, tools, options.toonify ?? false)));
+    const registrations = createJustBashCommandRegistrations((plan.justBash?.commands ?? []).map((command) => justBashSource(serverName, command.commandName, command.backendToolName, tools, options.shrinkfit === undefined && (options.toonify ?? false))));
     return {
         registrations,
+        close: () => shrinking.close(),
         tools: helpTools({
             name: plan.helpToolName,
             description: plan.helpDescription,
@@ -24,6 +28,7 @@ export function transformToolsForJustBash(tools, options) {
 export async function transformToolsForCodeMode(tools, options) {
     const serverName = normalizeServerName(options.serverName);
     return generatedTransform(tools, {
+        shrinkfit: options.shrinkfit,
         kind: options.language,
         serverName,
         outputDir: options.outputDir ?? "./dist",
@@ -32,6 +37,7 @@ export async function transformToolsForCodeMode(tools, options) {
 export async function transformToolsForCliMode(tools, options = {}) {
     const serverName = normalizeServerName(options.serverName);
     return generatedTransform(tools, {
+        shrinkfit: options.shrinkfit,
         kind: "cli",
         serverName,
         outputDir: options.outputDir,
@@ -53,6 +59,8 @@ function justBashSource(serverName, commandName, backendToolName, tools, toonify
     };
 }
 async function generatedTransform(tools, options) {
+    const shrinking = shrinkfitTools(tools, options);
+    tools = shrinking.tools;
     const bridge = await startLocalToolBridge(tools);
     const plan = buildHostTransformPlan({
         kind: options.kind,
@@ -74,7 +82,10 @@ async function generatedTransform(tools, options) {
             description: plan.helpDescription,
             output: plan.helpDescription,
         }),
-        close: () => bridge.close(),
+        close: () => {
+            shrinking.close();
+            bridge.close();
+        },
     };
 }
 function helpTools(options) {

package/native/index.d.ts

@@ -44,6 +44,8 @@ export declare function renderCliTopLevelHelpJson(command: string, cliName: stri
  */
 export declare function runCliJson(argvJson: string, version?: string | undefined | null): number
 
+export declare function shrinkHostOutput(output: string, maxChars: number, recoveryMessage: string): Promise<unknown>
+
 export declare function startCompressedSessionFromMcpConfigJson(configJson: string, mcpConfigJson: string): Promise<NativeCompressedSession>
 
 export declare function startCompressedSessionJson(configJson: string, backendsJson: string): Promise<NativeCompressedSession>

package/native/index.js

@@ -593,6 +593,7 @@ module.exports.rememberOauthBackendJson = nativeBinding.rememberOauthBackendJson
 module.exports.renderCliSubcommandHelpJson = nativeBinding.renderCliSubcommandHelpJson
 module.exports.renderCliTopLevelHelpJson = nativeBinding.renderCliTopLevelHelpJson
 module.exports.runCliJson = nativeBinding.runCliJson
+module.exports.shrinkHostOutput = nativeBinding.shrinkHostOutput
 module.exports.startCompressedSessionFromMcpConfigJson = nativeBinding.startCompressedSessionFromMcpConfigJson
 module.exports.startCompressedSessionJson = nativeBinding.startCompressedSessionJson
 module.exports.startCompressedSessionWithProviderBackendsJson = nativeBinding.startCompressedSessionWithProviderBackendsJson

package/native/index.linux-x64-gnu.node

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/native/index.linux-x64-gnu.node
-size: 34486552 bytes
-sha256: fb95dc982dbf4787bf810b312d1c0a8b70e996260fc10cae09a06cbe6f5aad1a
+size: 34581720 bytes
+sha256: 8ea4450d7e1728dcf06a408aad5cb4af1c6edba709ea6bbd8cdf2420fc4a14d6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlassian/mcp-compressor",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "TypeScript MCP server wrapper for reducing tokens consumed by MCP tools.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/atlassian-labs/mcp-compressor",