@ebowwa/large-output 1.0.3 → 1.2.0

package/README.md

@@ -0,0 +1,167 @@
+# @ebowwa/large-output
+
+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.
+
+**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**
+
+---
+
+## TypeScript
+
+### Installation
+
+```bash
+bun add @ebowwa/large-output
+```
+
+### Quick Start
+
+```typescript
+import { handleMCPOutput } from "@ebowwa/large-output";
+
+// In your MCP tool handler:
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const results = await fetchData();
+  const content = JSON.stringify(results, null, 2);
+
+  // Return with automatic file fallback (actionable format by default)
+  return {
+    content: [{ type: "text", text: handleMCPOutput(content) }],
+  };
+});
+```
+
+### API
+
+| 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 |
+
+### 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 |
+
+---
+
+## Rust
+
+Located in `./rust/` directory.
+
+### Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+large-output = "1.2.0"
+```
+
+### Quick Start
+
+```rust
+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
+
+```rust
+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
+
+```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

@@ -40,6 +40,13 @@ export interface LargeOutputOptions {
      * @default true
      */
     includePreview?: boolean;
+    /**
+     * Response format for file outputs
+     * - "actionable" (default): Returns actionable text prompting LLM to read the file
+     * - "json": Returns structured JSON object
+     * @default "actionable"
+     */
+    responseFormat?: "actionable" | "json";
 }
 /**
  * Response when output is returned inline (under threshold)
@@ -85,31 +92,35 @@ 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()
- * @returns JSON string suitable for MCP tool return value
+ * @param format - Response format: "actionable" (default) or "json"
+ * @returns Text or JSON string suitable for MCP tool return value
  *
  * @example
  * ```ts
  * const response = handleOutput(largeContent);
- * return JSON.stringify(toMCPResponse(response));
+ * return toMCPResponse(response);
  * ```
  */
-export declare function toMCPResponse(response: OutputResponse): string;
+export declare function toMCPResponse(response: OutputResponse, format?: "actionable" | "json"): string;
 /**
  * Convenience function: handle output and return MCP-formatted string
  *
  * @param content - The content to return
- * @param options - Configuration options
- * @returns JSON string or content directly
+ * @param options - Configuration options (including responseFormat)
+ * @returns Text string with actionable instructions (default) or JSON
  *
  * @example
  * ```ts
  * import { handleMCPOutput } from "@ebowwa/large-output";
  *
- * // In your MCP tool handler:
+ * // In your MCP tool handler (default: actionable format):
  * return handleMCPOutput(JSON.stringify(results));
+ *
+ * // For JSON format:
+ * return handleMCPOutput(JSON.stringify(results), { responseFormat: "json" });
  * ```
  */
 export declare function handleMCPOutput(content: string, options?: LargeOutputOptions): string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,kBAAkB,CAAC;AAuCvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAwChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAwB9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,GAAE,kBAAuB,GAC/B,cAAc,EAAE,CAElB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,kBAAkB,CAAC;AAwCvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAwChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,MAAM,GAAE,YAAY,GAAG,MAAqB,GAC3C,MAAM,CAgDR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,GAAE,kBAAuB,GAC/B,cAAc,EAAE,CAElB"}

package/dist/index.js

@@ -17,6 +17,7 @@ const DEFAULT_OPTIONS = {
     previewLength: 500,
     includeSize: true,
     includePreview: true,
+    responseFormat: "actionable",
 };
 /**
  * Format bytes to human-readable string
@@ -99,55 +100,79 @@ 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()
- * @returns JSON string suitable for MCP tool return value
+ * @param format - Response format: "actionable" (default) or "json"
+ * @returns Text or JSON string suitable for MCP tool return value
  *
  * @example
  * ```ts
  * const response = handleOutput(largeContent);
- * return JSON.stringify(toMCPResponse(response));
+ * return toMCPResponse(response);
  * ```
  */
-export function toMCPResponse(response) {
+export function toMCPResponse(response, format = "actionable") {
     if (response.type === "inline") {
         return response.content;
     }
-    // For file type, return structured JSON
-    const result = {
-        type: "file",
-        path: response.path,
-    };
-    if (response.size !== undefined) {
-        result.size = response.size;
-    }
-    if (response.sizeFormatted !== undefined) {
-        result.sizeFormatted = response.sizeFormatted;
+    // JSON format for programmatic consumers
+    if (format === "json") {
+        const result = {
+            type: "file",
+            path: response.path,
+        };
+        if (response.size !== undefined) {
+            result.size = response.size;
+        }
+        if (response.sizeFormatted !== undefined) {
+            result.sizeFormatted = response.sizeFormatted;
+        }
+        if (response.preview !== undefined) {
+            result.preview = response.preview;
+        }
+        return JSON.stringify(result, null, 2);
     }
+    // Actionable format - prompts LLM to read the file (DEFAULT)
+    // This is critical - JSON alone gets ignored by LLMs
+    const lines = [
+        `⚠️ Large output (${response.sizeFormatted || response.size} characters) saved to file.`,
+        ``,
+        `📖 **ACTION REQUIRED**: Use the Read tool to read this file:`,
+        ``,
+        `   ${response.path}`,
+        ``,
+    ];
     if (response.preview !== undefined) {
-        result.preview = response.preview;
+        lines.push(`--- PREVIEW (first 500 chars) ---`);
+        lines.push(response.preview);
+        lines.push(`--- END PREVIEW ---`);
+        lines.push(``);
     }
-    return JSON.stringify(result, null, 2);
+    lines.push(`✅ File contains the complete data. Read it to proceed.`);
+    return lines.join("\n");
 }
 /**
  * Convenience function: handle output and return MCP-formatted string
  *
  * @param content - The content to return
- * @param options - Configuration options
- * @returns JSON string or content directly
+ * @param options - Configuration options (including responseFormat)
+ * @returns Text string with actionable instructions (default) or JSON
  *
  * @example
  * ```ts
  * import { handleMCPOutput } from "@ebowwa/large-output";
  *
- * // In your MCP tool handler:
+ * // In your MCP tool handler (default: actionable format):
  * return handleMCPOutput(JSON.stringify(results));
+ *
+ * // For JSON format:
+ * return handleMCPOutput(JSON.stringify(results), { responseFormat: "json" });
  * ```
  */
 export function handleMCPOutput(content, options = {}) {
     const response = handleOutput(content, options);
-    return toMCPResponse(response);
+    return toMCPResponse(response, options.responseFormat);
 }
 /**
  * Batch handler for multiple outputs

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ebowwa/large-output",
-  "version": "1.0.3",
-  "description": "Shared utility for handling large MCP outputs with automatic file fallback",
+  "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,22 +12,40 @@
     }
   },
   "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": [
     "mcp",
     "output",
     "pagination",
-    "file-fallback"
+    "file-fallback",
+    "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"
+    ]
   }
 }