@ebowwa/large-output 1.0.0

package/README.md

@@ -0,0 +1,168 @@
+# @mcp/large-output
+
+Shared utility for handling large MCP outputs with automatic file fallback.
+
+## 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 a structured response with file path, size, and preview
+
+## Installation
+
+```bash
+# From within an MCP package
+bun add ../../large-output
+
+# Or as a local dependency
+# In package.json:
+# "dependencies": {
+#   "@mcp/large-output": "file:../large-output"
+# }
+```
+
+## Quick Start
+
+```typescript
+import { handleMCPOutput } from "@mcp/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
+  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 |
+
+### Response Formats
+
+**Inline (under threshold):**
+```
+<raw content returned directly>
+```
+
+**File (over threshold):**
+```json
+{
+  "type": "file",
+  "path": "/tmp/mcp_output_2025-02-04T12-38-00_abc123.txt",
+  "size": 45000,
+  "sizeFormatted": "45.0 KB",
+  "preview": "..."
+}
+```
+
+## Advanced Usage
+
+### Direct response handling
+
+```typescript
+import { handleOutput, toMCPResponse } from "@mcp/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
+return toMCPResponse(response);
+```
+
+### Batch handling
+
+```typescript
+import { handleBatch } from "@mcp/large-output";
+
+const outputs = handleBatch([data1, data2, data3]);
+// Each output handled independently
+```
+
+## Examples by MCP Server
+
+### github-search
+```typescript
+import { handleMCPOutput } from "@mcp/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 "@mcp/large-output";
+
+const conversations = await getConversations({ limit: 1000 });
+return handleMCPOutput(JSON.stringify(conversations, null, 2));
+```
+
+### git
+```typescript
+import { handleMCPOutput } from "@mcp/large-output";
+
+const commits = await gitLog({ maxCount: 500 });
+return handleMCPOutput(JSON.stringify(commits, null, 2));
+```
+
+### npm-publish
+```typescript
+import { handleMCPOutput } from "@mcp/large-output";
+
+const packages = await searchPackages({ limit: 500 });
+return handleMCPOutput(JSON.stringify(packages, null, 2));
+```
+
+## Integration Steps
+
+For each paginating MCP server:
+
+1. **Add dependency:**
+   ```bash
+   bun add ../../large-output
+   ```
+
+2. **Remove pagination params from tools:**
+   - Remove `limit`, `page`, `offset` parameters
+   - Or make them internal defaults, not user-facing
+
+3. **Fetch all data:**
+   - Remove pagination loops
+   - Fetch maximum amount in single call
+
+4. **Use `handleMCPOutput`:**
+   ```typescript
+   return handleMCPOutput(JSON.stringify(results));
+   ```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,262 @@
+/**
+ * @ebowwa/large-output
+ *
+ * Shared utility for handling large MCP outputs with automatic file fallback.
+ *
+ * When output size exceeds the threshold, automatically writes to a temp file
+ * and returns a structured response with file path and preview.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+/**
+ * Configuration options for the output handler
+ */
+export interface LargeOutputOptions {
+  /**
+   * Character threshold for file fallback
+   * @default 15000 (safety margin under Claude's ~20K limit)
+   */
+  threshold?: number;
+
+  /**
+   * Number of characters to include in preview when writing to file
+   * @default 500
+   */
+  previewLength?: number;
+
+  /**
+   * Custom temp directory for output files
+   * @default OS temp directory
+   */
+  tempDir?: string;
+
+  /**
+   * Custom filename prefix
+   * @default "mcp_output"
+   */
+  filenamePrefix?: string;
+
+  /**
+   * Whether to include a size indicator in the response
+   * @default true
+   */
+  includeSize?: boolean;
+
+  /**
+   * Whether to include a preview in the file response
+   * @default true
+   */
+  includePreview?: boolean;
+}
+
+/**
+ * Response when output is returned inline (under threshold)
+ */
+export interface InlineOutputResponse {
+  type: "inline";
+  content: string;
+}
+
+/**
+ * Response when output is written to file (over threshold)
+ */
+export interface FileOutputResponse {
+  type: "file";
+  path: string;
+  size: number;
+  preview?: string;
+  sizeFormatted?: string;
+}
+
+/**
+ * Union type for all possible responses
+ */
+export type OutputResponse = InlineOutputResponse | FileOutputResponse;
+
+/**
+ * Default options
+ */
+const DEFAULT_OPTIONS: Required<Omit<LargeOutputOptions, "tempDir" | "filenamePrefix">> = {
+  threshold: 15000,
+  previewLength: 500,
+  includeSize: true,
+  includePreview: true,
+};
+
+/**
+ * Format bytes to human-readable string
+ */
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Generate a unique filename with timestamp
+ */
+function generateFilename(prefix: string): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, -5);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `${prefix}_${timestamp}_${random}.txt`;
+}
+
+/**
+ * Ensure directory exists, create if not
+ */
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Handle output with automatic file fallback
+ *
+ * @param content - The content to return
+ * @param options - Configuration options
+ * @returns Structured response with inline content or file reference
+ *
+ * @example
+ * ```ts
+ * import { handleOutput } from "@mcp/large-output";
+ *
+ * const results = await fetchLargeData();
+ * const response = handleOutput(JSON.stringify(results));
+ *
+ * if (response.type === "file") {
+ *   console.log(`Written to: ${response.path}`);
+ * } else {
+ *   console.log(response.content);
+ * }
+ * ```
+ */
+export function handleOutput(
+  content: string,
+  options: LargeOutputOptions = {}
+): OutputResponse {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const contentLength = content.length;
+
+  // Return inline if under threshold
+  if (contentLength <= opts.threshold) {
+    return {
+      type: "inline",
+      content,
+    };
+  }
+
+  // Write to file if over threshold
+  const tempDir = options.tempDir || os.tmpdir();
+  const filenamePrefix = options.filenamePrefix || "mcp_output";
+  ensureDir(tempDir);
+
+  const filename = generateFilename(filenamePrefix);
+  const filepath = path.join(tempDir, filename);
+
+  fs.writeFileSync(filepath, content, "utf-8");
+
+  const response: FileOutputResponse = {
+    type: "file",
+    path: filepath,
+    size: contentLength,
+  };
+
+  if (opts.includeSize) {
+    response.sizeFormatted = formatSize(contentLength);
+  }
+
+  if (opts.includePreview) {
+    response.preview = content.slice(0, opts.previewLength);
+    if (contentLength > opts.previewLength) {
+      response.preview += "...";
+    }
+  }
+
+  return response;
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * const response = handleOutput(largeContent);
+ * return JSON.stringify(toMCPResponse(response));
+ * ```
+ */
+export function toMCPResponse(response: OutputResponse): string {
+  if (response.type === "inline") {
+    return response.content;
+  }
+
+  // For file type, return structured JSON
+  const result: Record<string, unknown> = {
+    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);
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { handleMCPOutput } from "@mcp/large-output";
+ *
+ * // In your MCP tool handler:
+ * return handleMCPOutput(JSON.stringify(results));
+ * ```
+ */
+export function handleMCPOutput(
+  content: string,
+  options: LargeOutputOptions = {}
+): string {
+  const response = handleOutput(content, options);
+  return toMCPResponse(response);
+}
+
+/**
+ * Batch handler for multiple outputs
+ *
+ * @param contents - Array of content strings
+ * @param options - Configuration options (applied to all)
+ * @returns Array of OutputResponse
+ *
+ * @example
+ * ```ts
+ * const outputs = handleBatch([data1, data2, data3]);
+ * // Each output handled independently
+ * ```
+ */
+export function handleBatch(
+  contents: string[],
+  options: LargeOutputOptions = {}
+): OutputResponse[] {
+  return contents.map((content) => handleOutput(content, options));
+}
+

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ebowwa/large-output",
+  "version": "1.0.0",
+  "description": "Shared utility for handling large MCP outputs with automatic file fallback",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts"
+    }
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "large-output",
+    "file-fallback"
+  ],
+  "author": "Ebowwa Labs <labs@ebowwa.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ebowwa/codespaces/tree/main/packages/src/large-output#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ebowwa/codespaces.git",
+    "directory": "packages/src/large-output"
+  },
+  "bugs": {
+    "url": "https://github.com/ebowwa/codespaces/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}