@ebowwa/large-output 1.0.3 → 1.1.0

package/README.md

@@ -0,0 +1,213 @@
+# @ebowwa/large-output
+
+Shared utility for handling large MCP outputs with automatic file fallback and **actionable LLM prompts**.
+
+## 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** (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:
+
+   /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.
+```
+
+This format is designed to **prompt the LLM to take action** and read the file.
+
+## Installation
+
+```bash
+# From npm
+bun add @ebowwa/large-output
+
+# Or from within the monorepo
+bun add ../../packages/src/large-output
+```
+
+## 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 content = JSON.stringify(results, null, 2);
+
+  // Return with automatic file fallback (actionable format by default)
+  return {
+    content: [{ type: "text", text: handleMCPOutput(content) }],
+  };
+});
+```
+
+## API
+
+### `handleMCPOutput(content, options?)`
+
+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
+
+**Inline (under threshold):**
+```
+<raw 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": "..."
+}
+```
+
+## 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",
+});
+
+if (response.type === "file") {
+  console.log(`Written ${response.sizeFormatted} to ${response.path}`);
+}
+
+// Convert to MCP return format (actionable by default)
+return toMCPResponse(response);
+
+// 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
+
+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)
@@ -88,7 +95,8 @@ export declare function handleOutput(content: string, options?: LargeOutputOptio
  * Convert an OutputResponse to a JSON 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
@@ -96,20 +104,23 @@ export declare function handleOutput(content: string, options?: LargeOutputOptio
  * return JSON.stringify(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
@@ -102,7 +103,8 @@ export function handleOutput(content, options = {}) {
  * Convert an OutputResponse to a JSON 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
@@ -110,44 +112,67 @@ export function handleOutput(content, options = {}) {
  * return JSON.stringify(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.1.0",
+  "description": "Shared utility for handling large MCP outputs with automatic file fallback and actionable LLM prompts",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,7 +22,8 @@
     "mcp",
     "output",
     "pagination",
-    "file-fallback"
+    "file-fallback",
+    "llm-actionable"
   ],
   "author": "ebowwa",
   "license": "MIT",