@ebowwa/large-output 1.1.0 → 1.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 Shared utility for handling large MCP outputs with automatic file fallback and **actionable LLM prompts**.
 
+**Available in TypeScript and Rust with full API parity.**
+
 ## 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.
@@ -9,55 +11,26 @@ When MCP tools return large outputs, they typically hit Claude's ~20,000 charact
 **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)
-
-## What's New in v1.1.0
-
-**Actionable Response Format (Default):**
-
-Instead of returning JSON that LLMs often ignore:
-```json
-{"type": "file", "path": "...", "size": 126507}
-```
-
-Now returns actionable text:
-```
-⚠️ Large output (126.5 KB) saved to file.
-
-📖 **ACTION REQUIRED**: Use the Read tool to read this file:
+- **Returning actionable text that prompts the LLM to read the file**
 
-   /tmp/mcp_output_2025-02-19T12-38-00_abc123.txt
+---
 
---- PREVIEW (first 500 chars) ---
-[preview content...]
---- END PREVIEW ---
-
-✅ File contains the complete data. Read it to proceed.
-```
+## TypeScript
 
-This format is designed to **prompt the LLM to take action** and read the file.
-
-## Installation
+### Installation
 
 ```bash
-# From npm
 bun add @ebowwa/large-output
-
-# Or from within the monorepo
-bun add ../../packages/src/large-output
 ```
 
-## Quick Start
+### Quick Start
 
 ```typescript
 import { handleMCPOutput } from "@ebowwa/large-output";
 
 // In your MCP tool handler:
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { query } = request.params.arguments as { query: string };
-
-  // Fetch your data
-  const results = await fetchData(query);
+  const results = await fetchData();
   const content = JSON.stringify(results, null, 2);
 
   // Return with automatic file fallback (actionable format by default)
@@ -67,147 +40,128 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 ```
 
-## API
+### API
 
-### `handleMCPOutput(content, options?)`
+| Function | Description |
+|----------|-------------|
+| `handleOutput(content, options?)` | Handle output, returns `OutputResponse` |
+| `handleMCPOutput(content, options?)` | Convenience: handle + return MCP string |
+| `toMCPResponse(response, format)` | Convert `OutputResponse` to string |
+| `handleBatch(contents, options?)` | Batch handler for multiple outputs |
 
-Convenience function that handles output and returns MCP-formatted string.
+### Options
 
 | 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
+| `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 |
 
-**Inline (under threshold):**
-```
-<raw content returned directly>
-```
+---
 
-**File - Actionable format (default):**
-```
-⚠️ Large output (126.5 KB) saved to file.
+## Rust
 
-📖 **ACTION REQUIRED**: Use the Read tool to read this file:
+Located in `./rust/` directory.
 
-   /tmp/mcp_output_2025-02-19T12-38-00_abc123.txt
+### Installation
 
---- PREVIEW (first 500 chars) ---
-{...preview...}
---- END PREVIEW ---
-
-✅ File contains the complete data. Read it to proceed.
-```
+Add to your `Cargo.toml`:
 
-**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": "..."
-}
+```toml
+[dependencies]
+large-output = "1.2.0"
 ```
 
-## Advanced Usage
+### Quick Start
 
-### Using JSON format
+```rust
+use large_output::{handle_output, handle_mcp_output, OutputResponse};
 
-If you need JSON for programmatic consumers:
+let content = "very large content...".repeat(1000);
+let response = handle_output(&content, None);
 
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
+match response {
+    OutputResponse::Inline { content, .. } => println!("{}", content),
+    OutputResponse::File { path, size, .. } => {
+        println!("Written {} bytes to {:?}", size, path);
+    }
+}
 
-return handleMCPOutput(JSON.stringify(results), {
-  responseFormat: "json",
-});
+// MCP convenience function
+let mcp_text = handle_mcp_output(&content, None);
+println!("{}", mcp_text);
 ```
 
-### Direct response handling
+### API
 
-```typescript
-import { handleOutput, toMCPResponse } 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` |
 
-const response = handleOutput(largeContent, {
-  threshold: 20000,
-  filenamePrefix: "github_search",
-});
+### Options
 
-if (response.type === "file") {
-  console.log(`Written ${response.sizeFormatted} to ${response.path}`);
-}
-
-// Convert to MCP return format (actionable by default)
-return toMCPResponse(response);
+```rust
+use large_output::{OptionsBuilder, ResponseFormat};
 
-// Or explicitly use JSON format
-return toMCPResponse(response, "json");
+let options = OptionsBuilder::new()
+    .threshold(20000)
+    .preview_length(1000)
+    .filename_prefix("github_search")
+    .response_format(ResponseFormat::Json)
+    .build();
 ```
 
-### Batch handling
+### Feature Flags
 
-```typescript
-import { handleBatch } from "@ebowwa/large-output";
+- `default` - Synchronous file operations
+- `async` - Async file operations with tokio
 
-const outputs = handleBatch([data1, data2, data3]);
-// Each output handled independently
-```
+---
 
-## Examples by MCP Server
+## Response Formats
 
-### github-search
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
+### Inline (under threshold)
 
-const results = await githubApi.search(query, { per_page: 100 });
-// Fetch all pages, accumulate results
-return handleMCPOutput(JSON.stringify(results, null, 2));
-```
+Content returned directly.
 
-### claude-code-history
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
+### File - Actionable format (default)
 
-const conversations = await getConversations({ limit: 1000 });
-return handleMCPOutput(JSON.stringify(conversations, null, 2));
 ```
+Large output (126.5 KB) saved to file.
 
-### git
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
+ACTION REQUIRED: Use the Read tool to read this file:
 
-const commits = await gitLog({ maxCount: 500 });
-return handleMCPOutput(JSON.stringify(commits, null, 2));
-```
+   /tmp/mcp_output_2025-02-19T12-38-00_abc123.txt
 
-### npm-publish
-```typescript
-import { handleMCPOutput } from "@ebowwa/large-output";
+--- PREVIEW (first 500 chars) ---
+{...preview...}
+--- END PREVIEW ---
 
-const packages = await searchPackages({ limit: 500 });
-return handleMCPOutput(JSON.stringify(packages, null, 2));
+File contains the complete data. Read it to proceed.
 ```
 
-## Migration from v1.0.x
+### File - JSON format
 
-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" });
+```json
+{
+  "type": "file",
+  "path": "/tmp/mcp_output_2025-02-19T12-38-00_abc123.txt",
+  "size": 126507,
+  "sizeFormatted": "126.5 KB",
+  "preview": "..."
+}
 ```
 
+---
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -92,7 +92,7 @@ export type OutputResponse = InlineOutputResponse | FileOutputResponse;
  */
 export declare function handleOutput(content: string, options?: LargeOutputOptions): OutputResponse;
 /**
- * Convert an OutputResponse to a JSON string for MCP tool return
+ * Convert an OutputResponse to a string for MCP tool return
  *
  * @param response - The response from handleOutput()
  * @param format - Response format: "actionable" (default) or "json"
@@ -101,7 +101,7 @@ export declare function handleOutput(content: string, options?: LargeOutputOptio
  * @example
  * ```ts
  * const response = handleOutput(largeContent);
- * return JSON.stringify(toMCPResponse(response));
+ * return toMCPResponse(response);
  * ```
  */
 export declare function toMCPResponse(response: OutputResponse, format?: "actionable" | "json"): string;

package/dist/index.js

@@ -100,7 +100,7 @@ export function handleOutput(content, options = {}) {
     return response;
 }
 /**
- * Convert an OutputResponse to a JSON string for MCP tool return
+ * Convert an OutputResponse to a string for MCP tool return
  *
  * @param response - The response from handleOutput()
  * @param format - Response format: "actionable" (default) or "json"
@@ -109,7 +109,7 @@ export function handleOutput(content, options = {}) {
  * @example
  * ```ts
  * const response = handleOutput(largeContent);
- * return JSON.stringify(toMCPResponse(response));
+ * return toMCPResponse(response);
  * ```
  */
 export function toMCPResponse(response, format = "actionable") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.2.0",
+  "description": "Shared utility for handling large MCP outputs with automatic file fallback and actionable LLM prompts. Includes TypeScript and Rust implementations.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,10 +12,13 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "rust"
   ],
   "scripts": {
     "build": "tsc",
+    "build:rust": "cd rust && cargo build --release",
+    "test": "tsc --noEmit && cd rust && cargo test",
     "prepublishOnly": "bun run build"
   },
   "keywords": [
@@ -23,12 +26,26 @@
     "output",
     "pagination",
     "file-fallback",
-    "llm-actionable"
+    "llm-actionable",
+    "rust",
+    "typescript"
   ],
   "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"
+    ]
   }
 }