@rv404/mcp-launchpad 1.0.0

package/lib/mcp-file-output/src/index.ts

@@ -0,0 +1,309 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+// Default data root - can be overridden via environment variable or init()
+// Uses environment variable, or falls back to a folder in user's home directory
+const getDefaultDataRoot = (): string => {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '.';
+  return path.join(homeDir, '.router-mcp', 'data');
+};
+let DATA_ROOT = process.env.MCP_FILE_OUTPUT_DIR || process.env.ROUTER_MCP_DATA_DIR || getDefaultDataRoot();
+const TOKEN_THRESHOLD = 20000; // Auto-save responses exceeding this estimated token count
+const CHARS_PER_TOKEN = 4; // Rough estimate for token calculation
+
+/**
+ * Initialize the file output utility with a custom data root
+ */
+export function init(dataRoot: string): void {
+  DATA_ROOT = dataRoot;
+}
+
+/**
+ * Get the current data root directory
+ */
+export function getDataRoot(): string {
+  return DATA_ROOT;
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface FileOutputConfig {
+  service: string;
+  action: string;
+  outputType?: 'temp' | 'outputs' | 'cache';
+  filename?: string;
+  subdir?: string;
+}
+
+export interface FileOutputResult {
+  saved: boolean;
+  path?: string;
+  dir?: string;
+  files?: string[];
+  manifest?: string;
+  bytesSaved?: number;
+  reason?: string;
+}
+
+export interface ManifestEntry {
+  filename: string;
+  url?: string;
+  title?: string;
+  timestamp: string;
+  bytes: number;
+}
+
+export interface OutputManifest {
+  service: string;
+  action: string;
+  created: string;
+  totalFiles: number;
+  totalBytes: number;
+  files: ManifestEntry[];
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function estimateTokens(data: unknown): number {
+  const str = typeof data === 'string' ? data : JSON.stringify(data);
+  return Math.ceil(str.length / CHARS_PER_TOKEN);
+}
+
+function sanitizeFilename(name: string): string {
+  return name
+    .replace(/[<>:"/\\|?*]/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 100);
+}
+
+function generateTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
+}
+
+async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Determines if a response should be saved to disk based on size
+ */
+export function shouldSaveToDisk(data: unknown, forceFile?: boolean): boolean {
+  if (forceFile) return true;
+  return estimateTokens(data) > TOKEN_THRESHOLD;
+}
+
+/**
+ * Gets the output directory path for a given configuration
+ */
+export function getOutputDir(config: FileOutputConfig): string {
+  const { service, outputType = 'outputs', subdir } = config;
+  const parts = [DATA_ROOT, outputType, service];
+  if (subdir) parts.push(subdir);
+  return path.join(...parts);
+}
+
+/**
+ * Saves a single file and returns the result
+ */
+export async function saveFile(
+  data: string | Buffer,
+  config: FileOutputConfig
+): Promise<FileOutputResult> {
+  const dir = getOutputDir(config);
+  await ensureDir(dir);
+
+  const filename = config.filename || `${config.action}-${generateTimestamp()}`;
+  const ext = typeof data === 'string' ? '.json' : '';
+  const fullFilename = filename.includes('.') ? filename : `${filename}${ext}`;
+  const filePath = path.join(dir, fullFilename);
+
+  const content = typeof data === 'string' ? data : data;
+  await fs.writeFile(filePath, content, typeof data === 'string' ? 'utf-8' : undefined);
+
+  const stats = await fs.stat(filePath);
+
+  return {
+    saved: true,
+    path: filePath,
+    bytesSaved: stats.size,
+  };
+}
+
+/**
+ * Saves multiple files with a manifest - ideal for crawl results
+ */
+export async function saveMultipleFiles(
+  files: Array<{ filename: string; content: string; url?: string; title?: string }>,
+  config: FileOutputConfig,
+  metadata?: Record<string, unknown>
+): Promise<FileOutputResult> {
+  const timestamp = generateTimestamp();
+  const subdir = config.subdir || timestamp;
+  const dir = getOutputDir({ ...config, subdir });
+  await ensureDir(dir);
+
+  const manifestEntries: ManifestEntry[] = [];
+  let totalBytes = 0;
+
+  // Save each file
+  for (const file of files) {
+    const safeName = sanitizeFilename(file.filename);
+    const filePath = path.join(dir, safeName);
+    await fs.writeFile(filePath, file.content, 'utf-8');
+
+    const stats = await fs.stat(filePath);
+    totalBytes += stats.size;
+
+    manifestEntries.push({
+      filename: safeName,
+      url: file.url,
+      title: file.title,
+      timestamp: new Date().toISOString(),
+      bytes: stats.size,
+    });
+  }
+
+  // Create manifest
+  const manifest: OutputManifest = {
+    service: config.service,
+    action: config.action,
+    created: new Date().toISOString(),
+    totalFiles: files.length,
+    totalBytes,
+    files: manifestEntries,
+    metadata,
+  };
+
+  const manifestPath = path.join(dir, 'manifest.json');
+  await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+
+  return {
+    saved: true,
+    dir,
+    files: manifestEntries.map(e => e.filename),
+    manifest: manifestPath,
+    bytesSaved: totalBytes,
+  };
+}
+
+/**
+ * Saves large response data automatically if it exceeds threshold
+ * Returns either the original data (if small) or a reference to saved file(s)
+ */
+export async function handleLargeResponse<T>(
+  data: T,
+  config: FileOutputConfig,
+  options?: {
+    forceFile?: boolean;
+    returnData?: boolean;
+  }
+): Promise<{ data: T; fileOutput?: FileOutputResult } | { data: { savedToFile: true; location: string; summary: string }; fileOutput: FileOutputResult }> {
+  const shouldSave = shouldSaveToDisk(data, options?.forceFile);
+
+  if (!shouldSave) {
+    return { data };
+  }
+
+  const result = await saveFile(
+    JSON.stringify(data, null, 2),
+    config
+  );
+
+  const summary = generateSummary(data);
+
+  return {
+    data: {
+      savedToFile: true,
+      location: result.path!,
+      summary,
+    } as unknown as T,
+    fileOutput: result,
+  };
+}
+
+/**
+ * Generates a brief summary of saved data for the response
+ */
+function generateSummary(data: unknown): string {
+  if (Array.isArray(data)) {
+    return `Array with ${data.length} items`;
+  }
+  if (typeof data === 'object' && data !== null) {
+    const keys = Object.keys(data);
+    return `Object with keys: ${keys.slice(0, 5).join(', ')}${keys.length > 5 ? '...' : ''}`;
+  }
+  return `${typeof data} data`;
+}
+
+/**
+ * Cleans up old temp files (utility for manual cleanup)
+ */
+export async function cleanupTempFiles(olderThanDays?: number): Promise<{ deleted: number; freedBytes: number }> {
+  const tempDir = path.join(DATA_ROOT, 'temp');
+  let deleted = 0;
+  let freedBytes = 0;
+
+  try {
+    const services = await fs.readdir(tempDir);
+
+    for (const service of services) {
+      const serviceDir = path.join(tempDir, service);
+      const stats = await fs.stat(serviceDir);
+
+      if (stats.isDirectory()) {
+        const files = await fs.readdir(serviceDir);
+
+        for (const file of files) {
+          const filePath = path.join(serviceDir, file);
+          const fileStats = await fs.stat(filePath);
+
+          if (olderThanDays) {
+            const ageInDays = (Date.now() - fileStats.mtime.getTime()) / (1000 * 60 * 60 * 24);
+            if (ageInDays < olderThanDays) continue;
+          }
+
+          freedBytes += fileStats.size;
+          await fs.rm(filePath, { recursive: true });
+          deleted++;
+        }
+      }
+    }
+  } catch {
+    // Temp dir might not exist yet
+  }
+
+  return { deleted, freedBytes };
+}
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+export const fileOutput = {
+  init,
+  getDataRoot,
+  shouldSaveToDisk,
+  getOutputDir,
+  saveFile,
+  saveMultipleFiles,
+  handleLargeResponse,
+  cleanupTempFiles,
+  TOKEN_THRESHOLD,
+};
+
+export default fileOutput;

package/lib/mcp-file-output/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@rv404/mcp-launchpad",
+  "version": "1.0.0",
+  "description": "Unified MCP router for Claude Code - ClickUp, Notion, GitHub, Slack, n8n, Gemini, QuickBooks, Firecrawl, YouTube, Kie.ai",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-launchpad": "./dist/index.js"
+  },
+  "scripts": {
+    "build:lib": "cd lib/mcp-file-output && npx tsc",
+    "build": "npm run build:lib && tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "router",
+    "notion",
+    "slack",
+    "github",
+    "n8n",
+    "gemini",
+    "quickbooks"
+  ],
+  "author": "404-rv",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/404-rv/mcp-launchpad.git"
+  },
+  "bugs": {
+    "url": "https://github.com/404-rv/mcp-launchpad/issues"
+  },
+  "homepage": "https://github.com/404-rv/mcp-launchpad#readme",
+  "files": [
+    "dist",
+    "lib",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@mendable/firecrawl-js": "^4.9.1",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@octokit/rest": "^21.0.0",
+    "axios": "^1.7.9",
+    "dotenv": "^16.4.7",
+    "form-data": "^4.0.5",
+    "google-auth-library": "^9.14.0",
+    "googleapis": "^144.0.0",
+    "mcp-file-output": "file:./lib/mcp-file-output",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}