@atlassian/mcp-compressor 0.38.2 → 0.40.0

package/README.md

@@ -391,3 +391,32 @@ import { CompressorRuntime } from "@atlassian/mcp-compressor";
 // light: ~zero runtime deps
 import { interpolateString } from "@atlassian/mcp-compressor/config";
 ```
+
+### Summary-only CLI discovery
+
+Host-owned CLI and Just Bash transforms can retain their complete command surface
+while advertising only a short toolset description to the model:
+
+```typescript
+const transformed = await transformToolsForCliMode(tools, {
+  serverName: "records",
+  helpMode: "summary",
+  helpSummary: "Search, read and manage enterprise records.",
+});
+```
+
+`helpMode` defaults to `"full"` (the existing subcommand catalog). With `"summary"`,
+the model-visible `records_help` description omits that catalog. `helpSummary` is
+optional caller-authored capability text, not an inferred or permission-checked
+capability promise. Missing/blank summaries fall back to a generic CLI description.
+Both `records --help` and calling `records_help` still return full discovery;
+`records <subcommand> --help` and all invocations are unchanged. The same options
+are available on `planToolsForJustBash` / `transformToolsForJustBash`.
+
+Hosts using `buildHostTransformPlan` directly can pass the same options. Use
+`plan.helpDescription` for the model-visible description and `plan.helpText` for
+the help tool's execution result. Do **not** use the shortened description as the
+on-demand help response. Artifacts, command registrations, auth and schemas do
+not change. Python/TypeScript code-generation transforms do not support summary
+mode. This is independent of MCP proxy `compressionLevel`; it does not add a new
+standalone CLI flag or change the high-level `CompressorClient` session modes.

package/dist/adapters.d.ts

@@ -1,5 +1,7 @@
 export interface ExecutableTool<TResult = string> {
     name: string;
+    title?: string | null;
+    annotations?: Record<string, unknown> | null;
     description?: string;
     inputSchema: Record<string, unknown>;
     execute(input?: Record<string, unknown>): Promise<TResult>;

package/dist/local_tools.d.ts

@@ -2,6 +2,8 @@ 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> {
+    title?: string | null;
+    annotations?: Record<string, unknown> | null;
     description?: string;
     inputSchema: unknown;
     execute: (input: TInput) => TResult | Promise<TResult>;

package/dist/local_tools.js

@@ -46,6 +46,8 @@ export function compressTools(tools, options = {}) {
     const compressionLevel = options.compressionLevel ?? "medium";
     const specs = Object.entries(tools).map(([name, tool]) => ({
         name,
+        title: tool.title,
+        annotations: tool.annotations,
         description: tool.description,
         inputSchema: asJsonSchema(tool.inputSchema, options.schemaAdapter),
     }));

package/dist/native.d.ts

@@ -1,5 +1,7 @@
 export interface NativeToolSpec {
     name: string;
+    title?: string | null;
+    annotations?: Record<string, unknown> | null;
     description?: string | null;
     input_schema: Record<string, unknown>;
 }

package/dist/native_client.d.ts

@@ -24,6 +24,8 @@ export interface CompressorClientOptions {
 }
 export interface ProxyTool {
     name: string;
+    title?: string | null;
+    annotations?: Record<string, unknown> | null;
     description?: string | null;
     inputSchema: Record<string, unknown>;
 }

package/dist/native_client.js

@@ -198,6 +198,8 @@ export class CompressorProxy {
     get tools() {
         return this.info().frontend_tools.map((tool) => ({
             name: tool.name,
+            title: tool.title,
+            annotations: tool.annotations,
             description: tool.description,
             inputSchema: tool.input_schema,
         }));
@@ -275,6 +277,8 @@ export class CompressorProxy {
         for (const tool of this.tools) {
             result[tool.name] = {
                 name: tool.name,
+                title: tool.title,
+                annotations: tool.annotations,
                 description: tool.description ?? undefined,
                 inputSchema: tool.inputSchema,
                 execute: async (input = {}) => (await this.invokeWrapper(tool.name, input)).text,
@@ -291,6 +295,8 @@ export class CompressorProxy {
             token: info.token,
             tools: info.backend_tools.map((tool) => ({
                 name: tool.name,
+                title: tool.title,
+                annotations: tool.annotations,
                 description: tool.description,
                 inputSchema: tool.input_schema,
             })),

package/dist/rust_core.d.ts

@@ -1,6 +1,8 @@
 import { type NativeCompressedSession } from "./native.js";
 export interface ToolSpec {
     name: string;
+    title?: string | null;
+    annotations?: Record<string, unknown> | null;
     description?: string | null;
     inputSchema: Record<string, unknown>;
 }
@@ -63,11 +65,15 @@ export interface CompressedSessionInfo {
     token: string;
     frontend_tools: Array<{
         name: string;
+        title?: string | null;
+        annotations?: Record<string, unknown> | null;
         description?: string | null;
         input_schema: Record<string, unknown>;
     }>;
     backend_tools: Array<{
         name: string;
+        title?: string | null;
+        annotations?: Record<string, unknown> | null;
         description?: string | null;
         input_schema: Record<string, unknown>;
     }>;
@@ -76,6 +82,8 @@ export interface CompressedSessionInfo {
         serverName?: string;
         tool: {
             name: string;
+            title?: string | null;
+            annotations?: Record<string, unknown> | null;
             description?: string | null;
             input_schema: Record<string, unknown>;
         };
@@ -116,6 +124,10 @@ export interface OAuthStoreEntry {
 export declare function listOAuthCredentials(): OAuthStoreEntry[];
 export declare function clearOAuthCredentials(target?: string | null): string[];
 export interface HostTransformPlanConfig {
+    /** Model-visible shell help only; commands and full help are unchanged. */
+    helpMode?: "full" | "summary";
+    /** Optional toolset capability description for summary mode. */
+    helpSummary?: string;
     kind: ClientArtifactKind | "just-bash";
     serverName: string;
     tools: ToolSpec[];
@@ -126,6 +138,8 @@ export interface HostTransformPlanConfig {
     sessionPid?: number;
 }
 export interface HostTransformPlan {
+    /** Full on-demand help, independent of the model-visible description. */
+    helpText: string;
     helpToolName: string;
     helpDescription: string;
     outputDir?: string;

package/dist/rust_core.js

@@ -2,6 +2,8 @@ import { loadNativeCore } from "./native.js";
 function toNativeTool(tool) {
     return {
         name: tool.name,
+        title: tool.title ?? null,
+        annotations: tool.annotations ?? null,
         description: tool.description ?? null,
         input_schema: tool.inputSchema,
     };
@@ -138,6 +140,8 @@ export function clearOAuthCredentials(target) {
 export function buildHostTransformPlan(config) {
     return JSON.parse(loadNativeCore().buildHostTransformPlanJson(stringify({
         kind: config.kind,
+        helpMode: config.helpMode,
+        helpSummary: config.helpSummary,
         serverName: config.serverName,
         tools: config.tools.map(toNativeTool),
         outputDir: config.outputDir,

package/dist/transforms.d.ts

@@ -4,7 +4,13 @@ import { type JustBashCommandRegistration } from "./just_bash_commands.js";
 export interface TransformToolOptions extends HostShrinkfitOptions {
     serverName?: string;
 }
-export interface PlanToolsForJustBashOptions extends TransformToolOptions {
+export interface ShellHelpOptions {
+    /** Defaults to full; summary omits the upfront subcommand catalog. */
+    helpMode?: "full" | "summary";
+    /** Toolset capability summary, used only with helpMode: "summary". */
+    helpSummary?: string;
+}
+export interface PlanToolsForJustBashOptions extends TransformToolOptions, ShellHelpOptions {
     /**
      * Convert JSON/CSV/YAML tool results to TOON before writing them to stdout.
      * Defaults to ``false`` so Just Bash output matches the generated CLI byte for
@@ -25,7 +31,7 @@ export interface TransformToolsForCodeModeOptions extends TransformToolOptions {
     language: CodeTransformLanguage;
     outputDir?: string;
 }
-export interface TransformToolsForCliModeOptions extends TransformToolOptions {
+export interface TransformToolsForCliModeOptions extends TransformToolOptions, ShellHelpOptions {
     outputDir?: string;
 }
 export interface GeneratedToolTransformResult {

package/dist/transforms.js

@@ -8,7 +8,13 @@ export function planToolsForJustBash(tools, options = {}) {
     const shrinking = shrinkfitTools(tools, options);
     tools = shrinking.tools;
     const toolSpecs = executableToolsToSpecs(tools);
-    const plan = buildHostTransformPlan({ kind: "just-bash", serverName, tools: toolSpecs });
+    const plan = buildHostTransformPlan({
+        kind: "just-bash",
+        serverName,
+        tools: toolSpecs,
+        helpMode: options.helpMode,
+        helpSummary: options.helpSummary,
+    });
     const registrations = createJustBashCommandRegistrations((plan.justBash?.commands ?? []).map((command) => justBashSource(serverName, command.commandName, command.backendToolName, tools, options.shrinkfit === undefined && (options.toonify ?? false))));
     return {
         registrations,
@@ -16,7 +22,7 @@ export function planToolsForJustBash(tools, options = {}) {
         tools: helpTools({
             name: plan.helpToolName,
             description: plan.helpDescription,
-            output: plan.helpDescription,
+            output: plan.helpText,
         }),
     };
 }
@@ -39,6 +45,8 @@ export async function transformToolsForCliMode(tools, options = {}) {
     return generatedTransform(tools, {
         shrinkfit: options.shrinkfit,
         kind: "cli",
+        helpMode: options.helpMode,
+        helpSummary: options.helpSummary,
         serverName,
         outputDir: options.outputDir,
         commandName: serverName,
@@ -64,6 +72,8 @@ async function generatedTransform(tools, options) {
     const bridge = await startLocalToolBridge(tools);
     const plan = buildHostTransformPlan({
         kind: options.kind,
+        helpMode: options.helpMode,
+        helpSummary: options.helpSummary,
         serverName: options.serverName,
         tools: executableToolsToSpecs(tools),
         outputDir: options.outputDir,
@@ -80,7 +90,7 @@ async function generatedTransform(tools, options) {
         tools: helpTools({
             name: plan.helpToolName,
             description: plan.helpDescription,
-            output: plan.helpDescription,
+            output: plan.helpText,
         }),
         close: () => {
             shrinking.close();

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: 34550480 bytes
-sha256: d08919951b7c469b4e53e8ce38f01c60b6a5c1aba03ae95acf5d1d614d45e92e
+size: 34662656 bytes
+sha256: 2d5f74b045200e5ec57ab6285b75b5403a7a251008e2bb3be5d1f039d24460fb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlassian/mcp-compressor",
-  "version": "0.38.2",
+  "version": "0.40.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",