@ebowwa/large-output 1.0.3 → 1.2.0

package/rust/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "large-output"
+version = "1.2.0"
+edition = "2021"
+authors = ["ebowwa"]
+description = "Utility for handling large outputs with automatic file fallback and actionable LLM prompts"
+license = "MIT"
+keywords = ["mcp", "output", "pagination", "file-fallback", "llm"]
+categories = ["filesystem", "text-processing"]
+repository = "https://github.com/ebowwa/codespaces"
+readme = "README.md"
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+chrono = "0.4"
+uuid = { version = "1.0", features = ["v4"] }
+
+[dev-dependencies]
+tempfile = "3.10"
+
+[features]
+default = []
+async = ["tokio", "tokio/fs"]
+
+[dependencies.tokio]
+version = "1.0"
+features = ["fs", "io-util"]
+optional = true

package/rust/README.md

@@ -0,0 +1,185 @@
+# large-output (Rust)
+
+Shared utility for handling large outputs with automatic file fallback and **actionable LLM prompts**.
+
+Rust port of [`@ebowwa/large-output`](../large-output/).
+
+## Problem Solved
+
+When tools return large outputs, they typically hit character 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**
+
+## Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+large-output = "1.1.0"
+```
+
+Or use cargo:
+
+```bash
+cargo add large-output
+```
+
+## Quick Start
+
+```rust
+use large_output::{handle_output, handle_mcp_output, OutputResponse};
+
+// Basic usage
+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 (returns actionable text by default)
+let mcp_text = handle_mcp_output(&content, None);
+println!("{}", mcp_text);
+```
+
+## API
+
+### `handle_output(content, options) -> OutputResponse`
+
+Handle output with automatic file fallback.
+
+```rust
+use large_output::{handle_output, OutputResponse, OptionsBuilder};
+
+let options = OptionsBuilder::new()
+    .threshold(20000)
+    .preview_length(1000)
+    .filename_prefix("my_tool")
+    .build();
+
+let response = handle_output("content", Some(options));
+```
+
+### `handle_mcp_output(content, options) -> String`
+
+Convenience function that handles output and returns MCP-formatted string.
+
+```rust
+use large_output::handle_mcp_output;
+
+// Default: actionable format
+let text = handle_mcp_output(&large_content, None);
+
+// JSON format for programmatic consumers
+use large_output::{OptionsBuilder, ResponseFormat};
+let options = OptionsBuilder::new()
+    .response_format(ResponseFormat::Json)
+    .build();
+let json = handle_mcp_output(&large_content, Some(options));
+```
+
+### `to_mcp_response(response, format) -> String`
+
+Convert an OutputResponse to a string for MCP tool return.
+
+```rust
+use large_output::{handle_output, to_mcp_response, ResponseFormat};
+
+let response = handle_output(&content, None);
+let text = to_mcp_response(&response, ResponseFormat::Actionable);
+```
+
+### `handle_batch(contents, options) -> Vec<OutputResponse>`
+
+Batch handler for multiple outputs.
+
+```rust
+use large_output::handle_batch;
+
+let contents = vec!["data1", "data2", "data3"];
+let outputs = handle_batch(&contents.iter().map(|s| *s).collect::<Vec<_>>(), None);
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `threshold` | `usize` | `15000` | Character threshold for file fallback |
+| `preview_length` | `usize` | `500` | Preview chars when written to file |
+| `temp_dir` | `Option<PathBuf>` | `None` (OS temp) | Custom temp directory |
+| `filename_prefix` | `String` | `"mcp_output"` | Filename prefix |
+| `include_size` | `bool` | `true` | Include size in file response |
+| `include_preview` | `bool` | `true` | Include preview in file response |
+| `response_format` | `ResponseFormat` | `Actionable` | Response format for file outputs |
+
+### Using OptionsBuilder
+
+```rust
+use large_output::{OptionsBuilder, ResponseFormat};
+
+let options = OptionsBuilder::new()
+    .threshold(20000)
+    .preview_length(1000)
+    .filename_prefix("github_search")
+    .response_format(ResponseFormat::Json)
+    .build();
+```
+
+## 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 (for programmatic consumers)
+
+```json
+{
+  "type": "file",
+  "path": "/tmp/mcp_output_2025-02-19T12-38-00_abc123.txt",
+  "size": 126507,
+  "sizeFormatted": "126.5 KB",
+  "preview": "..."
+}
+```
+
+## Feature Flags
+
+- `default` - Synchronous file operations
+- `async` - Async file operations with tokio (requires `tokio` feature)
+
+### Async Usage
+
+Enable the `async` feature:
+
+```toml
+[dependencies]
+large-output = { version = "1.1.0", features = ["async"] }
+```
+
+## License
+
+MIT