@atlassian/mcp-compressor 0.0.2

package/dist/config.js

@@ -0,0 +1,102 @@
+import { InvalidConfigurationError } from "./errors.js";
+/**
+ * Interpolate environment variables in a single string using ${VAR_NAME} or $VAR_NAME syntax.
+ * If a referenced variable is not set, the placeholder is left as-is (matching Python behaviour).
+ */
+export function interpolateString(value) {
+    if (!value.includes("$")) {
+        return value;
+    }
+    return value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, braced, bare) => {
+        const varName = braced ?? bare ?? "";
+        const envValue = process.env[varName];
+        return envValue !== undefined ? envValue : match;
+    });
+}
+export function interpolateRecord(record) {
+    if (!record)
+        return record;
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        result[key] = interpolateString(value);
+    }
+    return result;
+}
+/**
+ * Interpolate environment variables in all string values of an MCP config object or JSON string.
+ *
+ * Accepts either a parsed `MCPConfigShape` object or a raw JSON string and returns an interpolated
+ * copy with `${VAR_NAME}` and `$VAR_NAME` placeholders replaced by their environment variable
+ * values. Unset variables are left as-is.
+ *
+ * @example
+ * ```ts
+ * const config = interpolateMCPConfig({
+ *   mcpServers: {
+ *     myServer: { url: "https://example.com", headers: { Authorization: "Bearer $MY_TOKEN" } },
+ *   },
+ * });
+ * ```
+ */
+export function interpolateMCPConfig(config) {
+    const parsed = typeof config === "string" ? JSON.parse(config) : config;
+    const interpolated = { mcpServers: {} };
+    for (const [name, entry] of Object.entries(parsed.mcpServers ?? {})) {
+        interpolated.mcpServers[name] = {
+            ...entry,
+            ...(entry.url !== undefined ? { url: interpolateString(String(entry.url)) } : {}),
+            ...(entry.args ? { args: entry.args.map(interpolateString) } : {}),
+            ...(entry.env ? { env: interpolateRecord(entry.env) } : {}),
+            ...(entry.headers ? { headers: interpolateRecord(entry.headers) } : {}),
+        };
+    }
+    return interpolated;
+}
+/**
+ * Parse an MCP config JSON string containing one or more servers.
+ *
+ * Returns an array of `{ backend, serverName }` entries — one per server in `mcpServers` — or
+ * `null` if the input is not a JSON object string.  Throws {@link InvalidConfigurationError} for
+ * malformed JSON or an empty `mcpServers` map.
+ */
+export function parseServerConfigJson(input) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("{")) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (error) {
+        throw new InvalidConfigurationError(`Invalid MCP config JSON: ${error.message}`);
+    }
+    const names = Object.keys(parsed.mcpServers ?? {});
+    if (names.length === 0) {
+        throw new InvalidConfigurationError("MCP config JSON must contain at least one server in mcpServers.");
+    }
+    return names.map((serverName) => ({
+        backend: normalizeConfigServer(parsed.mcpServers[serverName]),
+        serverName,
+    }));
+}
+export function normalizeConfigServer(entry) {
+    const interpolated = interpolateMCPConfig({ mcpServers: { _: entry } }).mcpServers["_"];
+    if (interpolated.command) {
+        return {
+            type: "stdio",
+            command: interpolated.command,
+            args: interpolated.args,
+            cwd: interpolated.cwd,
+            env: interpolated.env,
+        };
+    }
+    if (!interpolated.url) {
+        throw new InvalidConfigurationError("Server config must contain either command or url.");
+    }
+    return {
+        type: interpolated.transport === "sse" ? "sse" : "http",
+        url: interpolated.url.toString(),
+        headers: interpolated.headers,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class ToolNotFoundError extends Error {
+    constructor(toolName: string, availableTools: string[]);
+}
+export declare class InvalidConfigurationError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class ToolNotFoundError extends Error {
+    constructor(toolName, availableTools) {
+        super(`Tool not found: ${toolName}. Available tools: ${availableTools.sort().join(", ")}`);
+        this.name = "ToolNotFoundError";
+    }
+}
+export class InvalidConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidConfigurationError";
+    }
+}

package/dist/formatting.d.ts

@@ -0,0 +1,3 @@
+import { type ToolSpec } from "./rust_core.js";
+import type { CompressionLevel } from "./types.js";
+export declare function formatToolDescription(tool: ToolSpec, compressionLevel: CompressionLevel): string;

package/dist/formatting.js

@@ -0,0 +1,4 @@
+import { compressToolListing } from "./rust_core.js";
+export function formatToolDescription(tool, compressionLevel) {
+    return compressToolListing(compressionLevel, [tool]);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { VERSION } from "./version.js";
+export * from "./errors.js";
+export * from "./rust_core.js";
+export * from "./just_bash_host.js";
+export * from "./adapters.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";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { VERSION } from "./version.js";
+export * from "./errors.js";
+export * from "./rust_core.js";
+export * from "./just_bash_host.js";
+export * from "./adapters.js";
+export { interpolateString, interpolateRecord, interpolateMCPConfig, parseServerConfigJson, normalizeConfigServer, } from "./config.js";
+export { CompressorClient, CompressorProxy, normalizeServers, } from "./native_client.js";

package/dist/just_bash_host.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "just-bash";
+import type { CompressorProxy } from "./native_client.js";
+export interface JustBashCommandRegistration {
+    providerName: string;
+    commandName: string;
+    backendToolName: string;
+    helpToolName: string;
+    command: Command;
+}
+export declare function installJustBashCommands(bash: unknown, proxy: CompressorProxy): JustBashCommandRegistration[];
+export declare function createJustBashCommands(proxy: CompressorProxy): JustBashCommandRegistration[];

package/dist/just_bash_host.js

@@ -0,0 +1,63 @@
+import { defineCommand } from "just-bash";
+import { parseToolArgv } from "./rust_core.js";
+function commandToToolSpec(command) {
+    return {
+        name: command.backendToolName,
+        description: command.description,
+        inputSchema: command.inputSchema,
+    };
+}
+function output(text) {
+    return { stdout: text, stderr: "", exitCode: 0 };
+}
+function failure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { stdout: "", stderr: `${message}\n`, exitCode: 1 };
+}
+export function installJustBashCommands(bash, proxy) {
+    const registrations = createJustBashCommands(proxy);
+    const host = bash;
+    if (typeof host.registerCommand === "function") {
+        for (const registration of registrations) {
+            host.registerCommand(registration.command);
+        }
+    }
+    else {
+        host.customCommands = [
+            ...(host.customCommands ?? []),
+            ...registrations.map((item) => item.command),
+        ];
+    }
+    return registrations;
+}
+export function createJustBashCommands(proxy) {
+    const rawNames = proxy.justBashProviders.flatMap((provider) => provider.tools.map((tool) => tool.commandName));
+    const duplicateNames = new Set(rawNames.filter((name, index) => rawNames.indexOf(name) !== index));
+    const registrations = [];
+    for (const provider of proxy.justBashProviders) {
+        for (const tool of provider.tools) {
+            const spec = commandToToolSpec(tool);
+            const registeredCommandName = duplicateNames.has(tool.commandName)
+                ? `${provider.providerName}_${tool.commandName}`
+                : tool.commandName;
+            registrations.push({
+                providerName: provider.providerName,
+                commandName: registeredCommandName,
+                backendToolName: tool.backendToolName,
+                helpToolName: provider.helpToolName,
+                command: defineCommand(registeredCommandName, async (args) => {
+                    try {
+                        const toolInput = parseToolArgv(spec, args);
+                        return output(await proxy.invoke(tool.backendToolName, toolInput, {
+                            server: provider.providerName,
+                        }));
+                    }
+                    catch (error) {
+                        return failure(error);
+                    }
+                }),
+            });
+        }
+    }
+    return registrations;
+}

package/dist/just_bash_transform.d.ts

@@ -0,0 +1,75 @@
+/**
+ * AST-level pipe/redirection detection for just-bash custom commands.
+ *
+ * Registers a ``TransformPlugin`` that walks the parsed AST and injects
+ * ``MCP_TOONIFY=true|false`` env-var prefixes onto each invocation of one
+ * of our wrapper commands, based on whether its stdout is piped
+ * (``cmd | jq``) or redirected (``cmd > out.json``).  The wrapper command
+ * in ``bash_commands.ts`` reads ``ctx.env.MCP_TOONIFY`` to choose between
+ * TOON and raw JSON output.  User-supplied ``MCP_TOONIFY=...`` prefixes
+ * are preserved.
+ */
+import type { Bash } from "just-bash";
+/** Env var injected into wrapper invocations: "true" -> TOON, "false" -> JSON. */
+export declare const MCP_TOONIFY_ENV_VAR = "MCP_TOONIFY";
+interface WordPart {
+    type: string;
+    value?: string;
+}
+interface WordNode {
+    type: "Word";
+    parts: WordPart[];
+}
+interface AssignmentNode {
+    type: "Assignment";
+    name: string;
+    value: WordNode | null;
+    append: boolean;
+    array: WordNode[] | null;
+}
+interface RedirectionNode {
+    type: "Redirection";
+    fd: number | null;
+    fdVariable?: string;
+    operator: string;
+    target: unknown;
+}
+interface SimpleCommandNode {
+    type: "SimpleCommand";
+    assignments: AssignmentNode[];
+    name: WordNode | null;
+    args: WordNode[];
+    redirections: RedirectionNode[];
+    line?: number;
+}
+interface PipelineNode {
+    type: "Pipeline";
+    commands: AnyCommandNode[];
+}
+interface StatementNode {
+    type: "Statement";
+    pipelines: PipelineNode[];
+}
+interface ScriptNode {
+    type: "Script";
+    statements: StatementNode[];
+}
+type AnyCommandNode = SimpleCommandNode | Record<string, unknown>;
+interface TransformInput {
+    ast: ScriptNode;
+    metadata: Record<string, unknown>;
+}
+interface TransformOutput {
+    ast: ScriptNode;
+    metadata?: Record<string, unknown>;
+}
+interface TransformPlugin {
+    transform(input: TransformInput): TransformOutput;
+}
+/** Build a ``TransformPlugin`` that injects ``MCP_TOONIFY`` prefixes (in-place AST mutation). */
+export declare function createPipingHintPlugin(customCommandNames: readonly string[]): TransformPlugin;
+/** Read ``MCP_TOONIFY`` from *env*, returning *defaultValue* if absent/invalid. */
+export declare function resolveToonifyFromEnv(env: Map<string, string> | Record<string, string> | undefined, defaultValue: boolean): boolean;
+/** Register :func:`createPipingHintPlugin` on *bash*. */
+export declare function installPipingHintPlugin(bash: Bash, customCommandNames: readonly string[]): void;
+export {};

package/dist/just_bash_transform.js

@@ -0,0 +1,167 @@
+/**
+ * AST-level pipe/redirection detection for just-bash custom commands.
+ *
+ * Registers a ``TransformPlugin`` that walks the parsed AST and injects
+ * ``MCP_TOONIFY=true|false`` env-var prefixes onto each invocation of one
+ * of our wrapper commands, based on whether its stdout is piped
+ * (``cmd | jq``) or redirected (``cmd > out.json``).  The wrapper command
+ * in ``bash_commands.ts`` reads ``ctx.env.MCP_TOONIFY`` to choose between
+ * TOON and raw JSON output.  User-supplied ``MCP_TOONIFY=...`` prefixes
+ * are preserved.
+ */
+/** Env var injected into wrapper invocations: "true" -> TOON, "false" -> JSON. */
+export const MCP_TOONIFY_ENV_VAR = "MCP_TOONIFY";
+/** Redirection operators that move stdout off the caller's pipe. */
+const OUTPUT_REDIR_OPERATORS = new Set([">", ">>", ">|", "&>", "&>>", "<>"]);
+// --- helpers ----------------------------------------------------------------
+function isLiteralPart(part) {
+    return part.type === "Literal" && typeof part.value === "string";
+}
+/** Return *cmd*'s literal name, or ``null`` for dynamic invocations. */
+function simpleCommandName(cmd) {
+    if (cmd.name === null) {
+        return null;
+    }
+    const pieces = [];
+    for (const part of cmd.name.parts) {
+        if (!isLiteralPart(part)) {
+            return null;
+        }
+        pieces.push(part.value);
+    }
+    const joined = pieces.join("");
+    return joined.length > 0 ? joined : null;
+}
+/** Return ``true`` if *cmd* redirects fd 1 (stdout) somewhere else. */
+function hasStdoutRedirection(cmd) {
+    for (const redir of cmd.redirections ?? []) {
+        if (!OUTPUT_REDIR_OPERATORS.has(redir.operator)) {
+            continue;
+        }
+        // fd defaults to 1 for >/>>/>|; &>/&>> always cover stdout.
+        if (redir.fd === null ||
+            redir.fd === 1 ||
+            redir.operator === "&>" ||
+            redir.operator === "&>>") {
+            return true;
+        }
+    }
+    return false;
+}
+function makeAssignment(name, value) {
+    return {
+        type: "Assignment",
+        name,
+        value: { type: "Word", parts: [{ type: "Literal", value }] },
+        append: false,
+        array: null,
+    };
+}
+function isSimpleCommand(node) {
+    return (typeof node === "object" &&
+        node !== null &&
+        node.type === "SimpleCommand");
+}
+function injectToonify(cmd, toonify) {
+    // Preserve user-set MCP_TOONIFY assignments.
+    for (const assignment of cmd.assignments ?? []) {
+        if (assignment.name === MCP_TOONIFY_ENV_VAR) {
+            return;
+        }
+    }
+    cmd.assignments = [
+        makeAssignment(MCP_TOONIFY_ENV_VAR, toonify ? "true" : "false"),
+        ...(cmd.assignments ?? []),
+    ];
+}
+function transformPipeline(pipeline, names) {
+    const n = pipeline.commands.length;
+    pipeline.commands.forEach((cmd, index) => {
+        if (isSimpleCommand(cmd)) {
+            const name = simpleCommandName(cmd);
+            if (name !== null && names.has(name)) {
+                const isLast = index === n - 1;
+                const isPiped = !isLast || hasStdoutRedirection(cmd);
+                injectToonify(cmd, !isPiped);
+            }
+        }
+        else {
+            transformCompound(cmd, names);
+        }
+    });
+}
+function transformStatements(statements, names) {
+    for (const stmt of statements) {
+        for (const pipeline of stmt.pipelines) {
+            transformPipeline(pipeline, names);
+        }
+    }
+}
+/** Recurse into compound nodes (``if``/``for``/``while``/subshell/etc.) by shape. */
+function transformCompound(node, names) {
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item && typeof item === "object") {
+                    const t = item.type;
+                    if (t === "Statement") {
+                        transformStatements(value, names);
+                        break;
+                    }
+                    if ("body" in item ||
+                        "condition" in item ||
+                        "patterns" in item ||
+                        "clauses" in item ||
+                        "elseBody" in item) {
+                        transformCompound(item, names);
+                    }
+                }
+            }
+        }
+        else if (value && typeof value === "object") {
+            transformCompound(value, names);
+        }
+    }
+}
+// --- public plugin factory --------------------------------------------------
+/** Build a ``TransformPlugin`` that injects ``MCP_TOONIFY`` prefixes (in-place AST mutation). */
+export function createPipingHintPlugin(customCommandNames) {
+    const names = new Set(customCommandNames);
+    return {
+        transform({ ast, metadata }) {
+            if (names.size === 0) {
+                return { ast, metadata };
+            }
+            transformStatements(ast.statements, names);
+            return { ast, metadata };
+        },
+    };
+}
+/** Read ``MCP_TOONIFY`` from *env*, returning *defaultValue* if absent/invalid. */
+export function resolveToonifyFromEnv(env, defaultValue) {
+    if (!env) {
+        return defaultValue;
+    }
+    let raw;
+    if (env instanceof Map) {
+        raw = env.get(MCP_TOONIFY_ENV_VAR);
+    }
+    else {
+        raw = env[MCP_TOONIFY_ENV_VAR];
+    }
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "true") {
+        return true;
+    }
+    if (normalized === "false") {
+        return false;
+    }
+    return defaultValue;
+}
+/** Register :func:`createPipingHintPlugin` on *bash*. */
+export function installPipingHintPlugin(bash, customCommandNames) {
+    bash.registerTransformPlugin(createPipingHintPlugin(customCommandNames));
+}

package/dist/native.d.ts

@@ -0,0 +1,25 @@
+export interface NativeToolSpec {
+    name: string;
+    description?: string | null;
+    input_schema: Record<string, unknown>;
+}
+export interface NativeCore {
+    compressToolListingJson(level: string, toolsJson: string): string;
+    formatToolSchemaResponseJson(toolJson: string): string;
+    parseToolArgvJson(toolJson: string, argvJson: string): string;
+    generateClientArtifactsJson(kind: string, configJson: string): string;
+    normalizeServersJson(serversJson: string): string;
+    parseMcpConfigJson(configJson: string): string;
+    rememberOauthBackendJson(backendUri: string, backendName: string, storeDir: string): void;
+    listOauthCredentialsJson(): string;
+    clearOauthCredentialsJson(target?: string | null): string;
+    startCompressedSessionJson(configJson: string, backendsJson: string): Promise<NativeCompressedSession>;
+    startCompressedSessionWithProviderBackendsJson(configJson: string, backendsJson: string, providersJson: string): Promise<NativeCompressedSession>;
+    startCompressedSessionFromMcpConfigJson(configJson: string, mcpConfigJson: string): Promise<NativeCompressedSession>;
+}
+export interface NativeCompressedSession {
+    infoJson(): string;
+    close(): void;
+    updateAuthProviderHeadersJson(providerIndex: number, headersJson: string): void;
+}
+export declare function loadNativeCore(): NativeCore;

package/dist/native.js

@@ -0,0 +1,11 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export function loadNativeCore() {
+    try {
+        return require("../native/index.js");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Rust native addon is not available. Run \`bun run build:native\` before using Rust-backed helpers. Cause: ${message}`);
+    }
+}

package/dist/native_client.d.ts

@@ -0,0 +1,96 @@
+import type { ExecutableTool } from "./adapters.js";
+import type { BackendConfig as LegacyBackendConfig, JsonConfigServerEntry } from "./types.js";
+import type { CompressedSession, CompressedSessionInfo } from "./rust_core.js";
+export type NativeCompressorMode = "compressed" | "cli" | "bash" | "python" | "typescript";
+export type AuthProvider = () => Record<string, string> | Promise<Record<string, string>>;
+export type NativeServerObjectConfig = (LegacyBackendConfig | JsonConfigServerEntry) & {
+    authProvider?: AuthProvider;
+    auth_provider?: AuthProvider;
+    oauthAppName?: string;
+    oauth_app_name?: string;
+};
+export type NativeServerConfig = NativeServerObjectConfig | string;
+export type NativeServersInput = Record<string, NativeServerConfig> | LegacyBackendConfig | string;
+export interface CompressorClientOptions {
+    servers: NativeServersInput;
+    mode?: NativeCompressorMode;
+    compressionLevel?: string;
+    serverName?: string | null;
+    includeTools?: string[];
+    excludeTools?: string[];
+    toonify?: boolean;
+}
+export interface ProxyTool {
+    name: string;
+    description?: string | null;
+    inputSchema: Record<string, unknown>;
+}
+export interface ProxyResponse {
+    text: string;
+}
+export interface JustBashCommand {
+    commandName: string;
+    backendToolName: string;
+    description?: string | null;
+    inputSchema: Record<string, unknown>;
+    invokeToolName: string;
+}
+export interface JustBashProvider {
+    providerName: string;
+    helpToolName: string;
+    tools: JustBashCommand[];
+}
+export type GeneratedClientKind = "cli" | "python" | "typescript";
+export interface NormalizedBackendConfig {
+    name: string;
+    commandOrUrl: string;
+    args?: string[];
+    oauth_app_name?: string;
+}
+export interface GeneratedCodeClient {
+    language: "python" | "typescript";
+    outputDir: string;
+    files: string[];
+    environment: Record<string, string>;
+}
+export declare function normalizeServers(servers: NativeServersInput): Promise<NormalizedBackendConfig[] | string>;
+export declare class CompressorProxy {
+    private readonly session;
+    private readonly defaultServer;
+    private readonly authProviders;
+    private closed;
+    constructor(session: CompressedSession, defaultServer: string | null, authProviders?: AuthProvider[]);
+    private refreshAuthProviders;
+    info(): CompressedSessionInfo;
+    get bridgeUrl(): string;
+    get token(): string;
+    get tools(): ProxyTool[];
+    get justBashProviders(): JustBashProvider[];
+    invokeWrapper(wrapperTool: string, toolInput: Record<string, unknown>): Promise<ProxyResponse>;
+    schema(tool: string, options?: {
+        server?: string;
+    }): Record<string, unknown>;
+    invoke(tool: string, toolInput?: Record<string, unknown>, options?: {
+        server?: string;
+    }): Promise<string>;
+    close(): void;
+    toExecutableTools(): Record<string, ExecutableTool>;
+    writeClient(kind: GeneratedClientKind, outputDir: string, options?: {
+        name?: string;
+    }): string[];
+    writeCodeClient(options: {
+        language: "python" | "typescript";
+        outputDir: string;
+        name?: string;
+    }): GeneratedCodeClient;
+}
+export declare class CompressorClient {
+    private readonly options;
+    private session;
+    private readonly mode;
+    private authProviders;
+    constructor(options: CompressorClientOptions);
+    connect(): Promise<CompressorProxy>;
+    close(): Promise<void>;
+    private defaultServer;
+}