@ebowwa/large-output 1.1.0 → 1.3.0

package/README.md

@@ -1,100 +1,97 @@
-# @ebowwa/large-output
+# large-output
 
-Shared utility for handling large MCP outputs with automatic file fallback and **actionable LLM prompts**.
+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 MCP tools return large outputs, they typically hit Claude's ~20,000 character tool output limit. Common solutions like pagination fragment the context and require multiple round-trips.
+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** (NEW in v1.1.0)
+- **Returning actionable text that prompts the LLM to read the file**
 
-## What's New in v1.1.0
+---
 
-**Actionable Response Format (Default):**
+## Rust (Primary)
 
-Instead of returning JSON that LLMs often ignore:
-```json
-{"type": "file", "path": "...", "size": 126507}
-```
+### Installation
 
-Now returns actionable text:
+```bash
+cargo add large-output
 ```
-⚠️ 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 content...]
---- END PREVIEW ---
+Or add to `Cargo.toml`:
 
-✅ File contains the complete data. Read it to proceed.
+```toml
+[dependencies]
+large-output = "1.3"
 ```
 
-This format is designed to **prompt the LLM to take action** and read the file.
+### Quick Start
 
-## Installation
+```rust
+use large_output::{handle_output, handle_mcp_output, OutputResponse};
 
-```bash
-# From npm
-bun add @ebowwa/large-output
+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);
+    }
+}
 
-# Or from within the monorepo
-bun add ../../packages/src/large-output
+// MCP convenience function
+let mcp_text = handle_mcp_output(&content, None);
+println!("{}", mcp_text);
 ```
 
-## Quick Start
+### API
 
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
+| 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` |
 
-// In your MCP tool handler:
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { query } = request.params.arguments as { query: string };
+### Options
 
-  // Fetch your data
-  const results = await fetchData(query);
-  const content = JSON.stringify(results, null, 2);
+```rust
+use large_output::{OptionsBuilder, ResponseFormat};
 
-  // Return with automatic file fallback (actionable format by default)
-  return {
-    content: [{ type: "text", text: handleMCPOutput(content) }],
-  };
-});
+let options = OptionsBuilder::new()
+    .threshold(20000)
+    .preview_length(1000)
+    .filename_prefix("github_search")
+    .response_format(ResponseFormat::Json)
+    .build();
 ```
 
-## API
+### Feature Flags
 
-### `handleMCPOutput(content, options?)`
+- `default` - Synchronous file operations
+- `async` - Async file operations with tokio
 
-Convenience function that handles output and returns MCP-formatted string.
+---
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `threshold` | number | `15000` | Character threshold for file fallback |
-| `previewLength` | number | `500` | Preview chars when written to file |
-| `tempDir` | string | `os.tmpdir()` | Custom temp directory |
-| `filenamePrefix` | string | `"mcp_output"` | Filename prefix |
-| `includeSize` | boolean | `true` | Include size in file response |
-| `includePreview` | boolean | `true` | Include preview in file response |
-| `responseFormat` | `"actionable"` \| `"json"` | `"actionable"` | Response format for file outputs |
+## Response Formats
 
-### Response Formats
+### Inline (under threshold)
 
-**Inline (under threshold):**
-```
-<raw content returned directly>
-```
+Content returned directly.
+
+### File - Actionable format (default)
 
-**File - Actionable format (default):**
 ```
-⚠️ Large output (126.5 KB) saved to file.
+Large output (126.5 KB) saved to file.
 
-📖 **ACTION REQUIRED**: Use the Read tool to read this file:
+ACTION REQUIRED: Use the Read tool to read this file:
 
    /tmp/mcp_output_2025-02-19T12-38-00_abc123.txt
 
@@ -102,10 +99,11 @@ Convenience function that handles output and returns MCP-formatted string.
 {...preview...}
 --- END PREVIEW ---
 
-✅ File contains the complete data. Read it to proceed.
+File contains the complete data. Read it to proceed.
 ```
 
-**File - JSON format (for programmatic consumers):**
+### File - JSON format
+
 ```json
 {
   "type": "file",
@@ -116,97 +114,17 @@ Convenience function that handles output and returns MCP-formatted string.
 }
 ```
 
-## Advanced Usage
-
-### Using JSON format
-
-If you need JSON for programmatic consumers:
-
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
-
-return handleMCPOutput(JSON.stringify(results), {
-  responseFormat: "json",
-});
-```
-
-### Direct response handling
-
-```typescript
-import { handleOutput, toMCPResponse } from "@ebowwa/large-output";
+---
 
-const response = handleOutput(largeContent, {
-  threshold: 20000,
-  filenamePrefix: "github_search",
-});
+## TypeScript (Legacy/Reference)
 
-if (response.type === "file") {
-  console.log(`Written ${response.sizeFormatted} to ${response.path}`);
-}
+TypeScript implementation preserved in `typescript/` directory for reference. Not distributed via npm.
 
-// Convert to MCP return format (actionable by default)
-return toMCPResponse(response);
+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
 
-// Or explicitly use JSON format
-return toMCPResponse(response, "json");
-```
-
-### Batch handling
-
-```typescript
-import { handleBatch } from "@ebowwa/large-output";
-
-const outputs = handleBatch([data1, data2, data3]);
-// Each output handled independently
-```
-
-## Examples by MCP Server
-
-### github-search
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
-
-const results = await githubApi.search(query, { per_page: 100 });
-// Fetch all pages, accumulate results
-return handleMCPOutput(JSON.stringify(results, null, 2));
-```
-
-### claude-code-history
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
-
-const conversations = await getConversations({ limit: 1000 });
-return handleMCPOutput(JSON.stringify(conversations, null, 2));
-```
-
-### git
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
-
-const commits = await gitLog({ maxCount: 500 });
-return handleMCPOutput(JSON.stringify(commits, null, 2));
-```
-
-### npm-publish
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
-
-const packages = await searchPackages({ limit: 500 });
-return handleMCPOutput(JSON.stringify(packages, null, 2));
-```
-
-## Migration from v1.0.x
-
-No code changes needed! The default behavior now uses actionable format.
-
-If you relied on JSON format:
-```typescript
-// Old (v1.0.x) - JSON was default
-handleMCPOutput(content);
-
-// New (v1.1.0) - Explicitly request JSON
-handleMCPOutput(content, { responseFormat: "json" });
-```
+---
 
 ## License
 

package/package.json

@@ -1,34 +1,45 @@
 {
   "name": "@ebowwa/large-output",
-  "version": "1.1.0",
-  "description": "Shared utility for handling large MCP outputs with automatic file fallback and actionable LLM prompts",
+  "version": "1.3.0",
+  "description": "Utility for handling large outputs with automatic file fallback and actionable LLM prompts. Rust implementation (crate: large-output). TypeScript source preserved in typescript/ for reference.",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
+  "main": "./rust/src/lib.rs",
   "files": [
-    "dist"
+    "rust/src",
+    "rust/Cargo.toml",
+    "rust/README.md"
   ],
   "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "bun run build"
+    "build": "cd rust && cargo build --release",
+    "test": "cd rust && cargo test",
+    "publish:crate": "cd rust && cargo publish",
+    "build:ts": "cd typescript && tsc",
+    "test:ts": "cd typescript && tsc --noEmit"
   },
   "keywords": [
     "mcp",
     "output",
     "pagination",
     "file-fallback",
-    "llm-actionable"
+    "llm-actionable",
+    "rust"
   ],
   "author": "ebowwa",
   "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^22.10.2",
-    "typescript": "^5.7.2"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ebowwa/codespaces",
+    "directory": "packages/src/ai/large-output"
+  },
+  "ownership": {
+    "domain": "tooling",
+    "responsibilities": [
+      "output-handling",
+      "large-response-management"
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   }
 }

package/rust/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "large-output"
+version = "1.3.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