large-output

Utility for handling large outputs with automatic file fallback and actionable LLM prompts.

Primary distribution: Rust crate (TypeScript source preserved in typescript/ for reference).

Problem Solved

When tools return large outputs, they typically hit context limits. Common solutions like pagination fragment the context and require multiple round-trips.

This library solves it by:

• Returning content inline if under the threshold
• Automatically writing to a temp file if over the threshold
• Returning actionable text that prompts the LLM to read the file

Rust (Primary)

Installation

cargo add large-output

Or add to Cargo.toml:

[dependencies]
large-output = "1.3"

Quick Start

use large_output::{handle_output, handle_mcp_output, OutputResponse};

let content = "very large content...".repeat(1000);
let response = handle_output(&content, None);

match response {
    OutputResponse::Inline { content, .. } => println!("{}", content),
    OutputResponse::File { path, size, .. } => {
        println!("Written {} bytes to {:?}", size, path);
    }
}

// MCP convenience function
let mcp_text = handle_mcp_output(&content, None);
println!("{}", mcp_text);

API

| Function | Description | |----------|-------------| | handle_output(content, options) | Handle output, returns OutputResponse | | handle_mcp_output(content, options) | Convenience: handle + return MCP string | | to_mcp_response(response, format) | Convert OutputResponse to string | | handle_batch(contents, options) | Batch handler for multiple outputs | | OptionsBuilder::new()...build() | Builder for LargeOutputOptions |

Options

use large_output::{OptionsBuilder, ResponseFormat};

let options = OptionsBuilder::new()
    .threshold(20000)
    .preview_length(1000)
    .filename_prefix("github_search")
    .response_format(ResponseFormat::Json)
    .build();

Feature Flags

• default - Synchronous file operations
• async - Async file operations with tokio

Response Formats

Inline (under threshold)

Content returned directly.

File - Actionable format (default)

Large output (126.5 KB) saved to file.

ACTION REQUIRED: Use the Read tool to read this file:

   /tmp/mcp_output_2025-02-19T12-38-00_abc123.txt

--- PREVIEW (first 500 chars) ---
{...preview...}
--- END PREVIEW ---

File contains the complete data. Read it to proceed.

File - JSON format

{
  "type": "file",
  "path": "/tmp/mcp_output_2025-02-19T12-38-00_abc123.txt",
  "size": 126507,
  "sizeFormatted": "126.5 KB",
  "preview": "..."
}

TypeScript (Legacy/Reference)

TypeScript implementation preserved in typescript/ directory for reference. Not distributed via npm.

If you need TypeScript support, consider:

1. Using the Rust crate via FFI (like napi-rs)
2. Copying the TypeScript source from typescript/ into your project

License

MIT