lazy-media-mcp 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# lazy-media-mcp
+
+Local MCP server that **compresses images/videos** and **prepares media for AI vision agents**.
+
+Designed for coding agents (Claude / Codex / Grok): returns **file paths only** (no inline base64).
+
+## Why this exists
+
+Large screenshots and long demos burn context and often fail tool limits. This server:
+
+1. Shrinks images to a sensible size/quality
+2. Turns videos into **frame packs** agents can actually open
+3. Uses **JPEG by default** for widest agent compatibility
+
+### WebP / WebM — do they help AI “read better”?
+
+| Format | Role | Default here? |
+|--------|------|----------------|
+| **JPEG** | Best universal image input for local agents | **Yes** |
+| **PNG** | Sharper for OCR / UI text / alpha | `ocr_text` profile |
+| **WebP** | Smaller files when the host supports it | **Opt-in only** |
+| **MP4** | Storage/sharing re-encode | Video compress default |
+| **WebM** | Optional container | Opt-in via `video_compress` |
+
+**Format does not improve model understanding by itself.** Resolution, blur, and compression artifacts matter more. Over-aggressive WebP/JPEG hurts OCR.
+
+Local agents usually **do not natively watch WebM/MP4**. Prefer `prepare_for_ai` / `video_extract_frames` → JPEG paths.
+
+## Requirements
+
+- Node.js ≥ 20
+- [ffmpeg](https://ffmpeg.org/) + ffprobe on `PATH` (video tools)
+
+```bash
+# macOS
+brew install ffmpeg
+```
+
+## Install / run
+
+```bash
+cd lazy-media-mcp
+npm install
+npm run build
+npm test
+node dist/cli.js   # stdio MCP
+```
+
+### MCP client config (example)
+
+```json
+{
+  "mcpServers": {
+    "lazy-media": {
+      "command": "node",
+      "args": ["/absolute/path/to/lazy-media-mcp/dist/cli.js"],
+      "env": {
+        "MEDIA_ALLOWED_ROOTS": "/Users/you,/Users/you/WorkSpace",
+        "MEDIA_WORKDIR": "/Users/you/.cache/lazy-media-mcp/jobs"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `media_inspect` | Metadata only |
+| `image_compress` | Resize/compress image → workdir path |
+| `video_compress` | Re-encode video (default MP4) |
+| `video_extract_frames` | Extract frames for vision |
+| `prepare_for_ai` | One-shot profile pipeline (**recommended**) |
+| `media_cleanup` | Delete a job directory by `job_id` |
+
+### `prepare_for_ai` profiles
+
+| Profile | Behavior |
+|---------|----------|
+| `ai_vision` (default) | Image → JPEG ≤1536 edge; video → up to 10 JPEG frames |
+| `ocr_text` | Prefer PNG / higher quality |
+| `inline_small` | Smaller edges, fewer frames |
+| `archive` | Higher quality + optional compressed MP4 |
+
+## Environment
+
+| Variable | Default |
+|----------|---------|
+| `MEDIA_ALLOWED_ROOTS` | `$HOME`, cwd, workdir |
+| `MEDIA_WORKDIR` | `~/.cache/lazy-media-mcp/jobs` |
+| `MEDIA_MAX_INPUT_BYTES` | 500MB |
+| `MEDIA_MAX_OUTPUT_BYTES` | 200MB |
+| `MEDIA_MAX_FRAMES` | 24 |
+| `MEDIA_PROCESS_TIMEOUT_MS` | 120000 |
+| `FFMPEG_BIN` / `FFPROBE_BIN` | `ffmpeg` / `ffprobe` |
+| `LOG_LEVEL` | `info` |
+
+## Security
+
+- Path allowlist (realpath checks)
+- Input/output size caps
+- Process timeout
+- ffmpeg/ffprobe invoked with argv arrays only (no shell interpolation)
+- Outputs go to workdir; originals are not overwritten
+- Cleanup only deletes direct children of workdir by `job_id`
+
+## Typical agent flow
+
+```text
+1. prepare_for_ai({ path: "/path/to/demo.mp4", profile: "ai_vision" })
+2. Read returned outputs[].path frame files in the next vision step
+3. media_cleanup({ job_id }) when done (optional)
+```
+
+## License
+
+MIT

package/bin/lazy-media-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.js

@@ -0,0 +1,41 @@
+import { startServer } from "./index.js";
+function usage() {
+    return [
+        "Usage:",
+        "  lazy-media-mcp              Start MCP server over stdio",
+        "  lazy-media-mcp --help       Show this help",
+        "",
+        "Environment:",
+        "  MEDIA_ALLOWED_ROOTS         Comma-separated allowed path roots (default: $HOME,cwd,workdir)",
+        "  MEDIA_WORKDIR               Job output directory (default: ~/.cache/lazy-media-mcp/jobs)",
+        "  MEDIA_MAX_INPUT_BYTES       Max input file size (default: 500MB)",
+        "  MEDIA_MAX_OUTPUT_BYTES      Max single output file size (default: 200MB)",
+        "  MEDIA_MAX_FRAMES            Max frames per extract (default: 24)",
+        "  MEDIA_PROCESS_TIMEOUT_MS    ffmpeg/ffprobe timeout (default: 120000)",
+        "  FFMPEG_BIN / FFPROBE_BIN    Binary paths (default: ffmpeg / ffprobe)",
+        "  LOG_LEVEL                   debug|info|warn|error"
+    ].join("\n");
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0] ?? "";
+    if (command === "--help" || command === "-h") {
+        process.stdout.write(`${usage()}\n`);
+        return;
+    }
+    if (command !== "" && command !== undefined) {
+        process.stderr.write(`Unknown command: ${command}\n`);
+        process.stderr.write("Run 'lazy-media-mcp --help' for usage.\n");
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await startServer();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${JSON.stringify({ level: "error", event: "fatal", error: message })}\n`);
+        process.exit(1);
+    }
+}
+void main();

package/dist/config.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function parseCsv(input) {
+    if (!input) {
+        return [];
+    }
+    return input
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}
+function parsePositiveInt(input, fallback) {
+    if (!input) {
+        return fallback;
+    }
+    const value = Number.parseInt(input, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Invalid positive integer: ${input}`);
+    }
+    return value;
+}
+export function loadConfig(env = process.env) {
+    const home = os.homedir();
+    const workdir = env.MEDIA_WORKDIR ?? path.join(home, ".cache", "lazy-media-mcp", "jobs");
+    const configuredRoots = parseCsv(env.MEDIA_ALLOWED_ROOTS).map((root) => path.resolve(root));
+    const defaultRoots = [home, process.cwd(), workdir].map((root) => path.resolve(root));
+    const allowedRoots = configuredRoots.length > 0 ? configuredRoots : defaultRoots;
+    const logLevel = env.LOG_LEVEL ?? "info";
+    if (!["debug", "info", "warn", "error"].includes(logLevel)) {
+        throw new Error(`Invalid LOG_LEVEL: ${logLevel}`);
+    }
+    return {
+        allowedRoots: dedupePaths([...allowedRoots, path.resolve(workdir)]),
+        workdir: path.resolve(workdir),
+        logLevel,
+        ffmpegBin: env.FFMPEG_BIN ?? "ffmpeg",
+        ffprobeBin: env.FFPROBE_BIN ?? "ffprobe",
+        maxInputBytes: parsePositiveInt(env.MEDIA_MAX_INPUT_BYTES, 500 * 1024 * 1024),
+        maxOutputBytes: parsePositiveInt(env.MEDIA_MAX_OUTPUT_BYTES, 200 * 1024 * 1024),
+        maxFrames: parsePositiveInt(env.MEDIA_MAX_FRAMES, 24),
+        processTimeoutMs: parsePositiveInt(env.MEDIA_PROCESS_TIMEOUT_MS, 120_000)
+    };
+}
+function dedupePaths(paths) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of paths) {
+        const absolute = path.resolve(entry);
+        let normalized = absolute;
+        try {
+            if (fs.existsSync(absolute)) {
+                normalized = fs.realpathSync(absolute);
+            }
+        }
+        catch {
+            normalized = absolute;
+        }
+        if (seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}

package/dist/engines/ffmpegVideo.js

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../errors.js";
+import { extensionForImageFormat, extensionForVideoContainer } from "../formats/profiles.js";
+import { runCommand } from "./process.js";
+export async function probeMedia(filePath, options) {
+    const result = await runCommand(options.ffprobeBin, [
+        "-v",
+        "quiet",
+        "-print_format",
+        "json",
+        "-show_format",
+        "-show_streams",
+        filePath
+    ], {
+        timeoutMs: options.timeoutMs,
+        traceId: options.traceId,
+        label: "ffprobe"
+    });
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new AppError({
+            message: "ffprobe returned invalid JSON",
+            code: "ERR_FFPROBE_PARSE",
+            category: "dependency",
+            traceId: options.traceId,
+            cause: error
+        });
+    }
+}
+export function toVideoMeta(filePath, probe) {
+    const streams = probe.streams ?? [];
+    const video = streams.find((s) => s.codec_type === "video");
+    const audio = streams.find((s) => s.codec_type === "audio");
+    const durationRaw = probe.format?.duration ?? video?.duration;
+    const sizeRaw = probe.format?.size;
+    return {
+        path: filePath,
+        bytes: sizeRaw ? Number.parseInt(sizeRaw, 10) : fs.statSync(filePath).size,
+        duration_sec: durationRaw ? Number.parseFloat(durationRaw) : null,
+        width: video?.width ?? null,
+        height: video?.height ?? null,
+        video_codec: video?.codec_name ?? null,
+        audio_codec: audio?.codec_name ?? null,
+        format_name: probe.format?.format_name ?? null,
+        has_audio: Boolean(audio),
+        has_video: Boolean(video)
+    };
+}
+export async function compressVideo(input) {
+    // spawn without shell: no backslash escaping needed for commas
+    const scaleFilter = `scale=-2:min(ih\\,${input.maxHeight})`;
+    const args = [
+        "-y",
+        "-i",
+        input.inputPath,
+        "-map_metadata",
+        "-1",
+        "-vf",
+        scaleFilter,
+        "-c:v",
+        input.container === "webm" ? "libvpx-vp9" : "libx264",
+        "-crf",
+        String(input.crf),
+        "-pix_fmt",
+        "yuv420p"
+    ];
+    if (input.container === "mp4") {
+        args.push("-preset", "medium", "-movflags", "+faststart");
+    }
+    else {
+        args.push("-b:v", "0");
+    }
+    args.push("-c:a", input.container === "webm" ? "libopus" : "aac", "-b:a", `${input.audioBitrateK}k`);
+    args.push(input.outputPath);
+    await fs.promises.mkdir(path.dirname(input.outputPath), { recursive: true });
+    await runCommand(input.ffmpegBin, args, {
+        timeoutMs: input.timeoutMs,
+        traceId: input.traceId,
+        label: "ffmpeg-compress"
+    });
+    const stat = await fs.promises.stat(input.outputPath);
+    return { path: input.outputPath, bytes: stat.size };
+}
+export async function extractFrames(input) {
+    await fs.promises.mkdir(input.outputDir, { recursive: true });
+    const ext = extensionForImageFormat(input.format);
+    const pattern = path.join(input.outputDir, `frame_%04d.${ext}`);
+    const fpsExpr = buildFpsExpression(input);
+    const vfParts = [`fps=${fpsExpr}`, `scale=min(${input.maxEdge}\\,iw):-2`];
+    const args = ["-y", "-i", input.inputPath, "-vf", vfParts.join(","), "-frames:v", String(input.maxFrames)];
+    if (input.format === "jpeg") {
+        args.push("-q:v", jpegQualityToFfmpeg(input.quality));
+    }
+    else if (input.format === "webp") {
+        args.push("-quality", String(input.quality));
+    }
+    args.push(pattern);
+    await runCommand(input.ffmpegBin, args, {
+        timeoutMs: input.timeoutMs,
+        traceId: input.traceId,
+        label: "ffmpeg-frames"
+    });
+    const files = (await fs.promises.readdir(input.outputDir))
+        .filter((name) => name.startsWith("frame_") && name.endsWith(`.${ext}`))
+        .sort()
+        .map((name) => path.join(input.outputDir, name));
+    if (files.length === 0) {
+        throw new AppError({
+            message: "No frames were extracted from the video",
+            code: "ERR_NO_FRAMES",
+            category: "business",
+            traceId: input.traceId
+        });
+    }
+    return files.slice(0, input.maxFrames);
+}
+function buildFpsExpression(input) {
+    if (input.mode === "interval") {
+        const interval = Math.max(0.2, input.intervalSec);
+        return `1/${interval}`;
+    }
+    const duration = input.durationSec && input.durationSec > 0 ? input.durationSec : null;
+    if (!duration) {
+        // Fallback: ~1 fps capped by maxFrames via -frames:v
+        return "1";
+    }
+    // Spread maxFrames across duration (avoid div by zero)
+    const fps = Math.max(input.maxFrames / duration, 0.05);
+    return String(fps);
+}
+/** Map 1-100 quality to ffmpeg mjpeg qscale (2 best .. 31 worst). */
+function jpegQualityToFfmpeg(quality) {
+    const q = Math.min(100, Math.max(1, quality));
+    const scale = Math.round(2 + ((100 - q) / 100) * 29);
+    return String(scale);
+}
+export function defaultVideoOutputName(baseName, container) {
+    const stem = path.parse(baseName).name || "video";
+    return `${stem}.${extensionForVideoContainer(container)}`;
+}
+export function isLikelyVideoPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return [".mp4", ".mov", ".mkv", ".webm", ".avi", ".m4v", ".mpeg", ".mpg", ".wmv", ".flv", ".3gp"].includes(ext);
+}

package/dist/engines/process.js

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process";
+import { AppError } from "../errors.js";
+export async function runCommand(bin, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            child.kill("SIGKILL");
+            reject(new AppError({
+                message: `${options.label} timed out after ${options.timeoutMs}ms`,
+                code: "ERR_PROCESS_TIMEOUT",
+                category: "dependency",
+                traceId: options.traceId
+            }));
+        }, options.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            const notFound = "code" in error && error.code === "ENOENT";
+            reject(new AppError({
+                message: notFound
+                    ? `${options.label} binary not found: ${bin}. Install ffmpeg (brew install ffmpeg) or set FFMPEG_BIN/FFPROBE_BIN.`
+                    : `${options.label} failed to start: ${error.message}`,
+                code: notFound ? "ERR_BINARY_NOT_FOUND" : "ERR_PROCESS_SPAWN",
+                category: "dependency",
+                traceId: options.traceId,
+                cause: error
+            }));
+        });
+        child.on("close", (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            const exitCode = code ?? 1;
+            if (exitCode !== 0) {
+                reject(new AppError({
+                    message: `${options.label} exited with code ${exitCode}: ${stderr.trim() || stdout.trim() || "no output"}`,
+                    code: "ERR_PROCESS_FAILED",
+                    category: "dependency",
+                    traceId: options.traceId
+                }));
+                return;
+            }
+            resolve({ stdout, stderr, code: exitCode });
+        });
+    });
+}

package/dist/engines/sharpImage.js

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import sharp from "sharp";
+import { AppError } from "../errors.js";
+import { clampQuality, extensionForImageFormat, resolveImageFormat } from "../formats/profiles.js";
+export async function inspectImage(filePath, traceId) {
+    try {
+        const stat = fs.statSync(filePath);
+        const meta = await sharp(filePath).metadata();
+        return {
+            path: filePath,
+            bytes: stat.size,
+            width: meta.width ?? null,
+            height: meta.height ?? null,
+            format: meta.format ?? null,
+            hasAlpha: Boolean(meta.hasAlpha),
+            space: meta.space ?? null
+        };
+    }
+    catch (error) {
+        throw new AppError({
+            message: `Failed to inspect image: ${filePath}`,
+            code: "ERR_IMAGE_INSPECT",
+            category: "dependency",
+            traceId,
+            cause: error
+        });
+    }
+}
+export async function compressImage(input) {
+    const source = await inspectImage(input.inputPath, input.traceId);
+    const format = resolveImageFormat(input.format, {
+        hasAlpha: source.hasAlpha,
+        preferLossless: input.preferLossless
+    });
+    const quality = clampQuality(input.quality, input.qualityFloor);
+    try {
+        let pipeline = sharp(input.inputPath, { failOn: "none" }).rotate();
+        if (source.width && source.height) {
+            const longest = Math.max(source.width, source.height);
+            if (longest > input.maxEdge) {
+                pipeline = pipeline.resize({
+                    width: source.width >= source.height ? input.maxEdge : undefined,
+                    height: source.height > source.width ? input.maxEdge : undefined,
+                    fit: "inside",
+                    withoutEnlargement: true
+                });
+            }
+        }
+        // sharp strips most metadata by default; only re-attach when strip is false
+        if (!input.stripMetadata) {
+            pipeline = pipeline.withMetadata();
+        }
+        switch (format) {
+            case "jpeg":
+                pipeline = pipeline.jpeg({ quality, mozjpeg: true });
+                break;
+            case "png":
+                pipeline = pipeline.png({ compressionLevel: 9 });
+                break;
+            case "webp":
+                pipeline = pipeline.webp({ quality });
+                break;
+        }
+        await fs.promises.mkdir(path.dirname(input.outputPath), { recursive: true });
+        const info = await pipeline.toFile(input.outputPath);
+        return {
+            path: input.outputPath,
+            bytes: info.size,
+            width: info.width,
+            height: info.height,
+            format,
+            input_bytes: source.bytes,
+            input_width: source.width,
+            input_height: source.height
+        };
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            throw error;
+        }
+        throw new AppError({
+            message: `Image compression failed: ${error instanceof Error ? error.message : "unknown"}`,
+            code: "ERR_IMAGE_COMPRESS",
+            category: "dependency",
+            traceId: input.traceId,
+            cause: error
+        });
+    }
+}
+export function defaultImageOutputName(baseName, format) {
+    const stem = path.parse(baseName).name || "image";
+    return `${stem}.${extensionForImageFormat(format)}`;
+}
+export function isLikelyImagePath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return [".jpg", ".jpeg", ".png", ".webp", ".gif", ".tif", ".tiff", ".heic", ".heif", ".avif", ".bmp"].includes(ext);
+}

package/dist/errors.js

@@ -0,0 +1,57 @@
+import { ZodError } from "zod";
+export class AppError extends Error {
+    code;
+    category;
+    traceId;
+    constructor(options) {
+        super(options.message, { cause: options.cause });
+        this.name = "AppError";
+        this.code = options.code;
+        this.category = options.category;
+        this.traceId = options.traceId;
+    }
+}
+export function toErrorResponse(error) {
+    return {
+        error: error.message,
+        code: error.code,
+        trace_id: error.traceId
+    };
+}
+export function normalizeError(error, traceId) {
+    if (error instanceof AppError) {
+        return error;
+    }
+    if (error instanceof ZodError) {
+        return new AppError({
+            message: summarizeZodError(error),
+            code: "ERR_VALIDATION",
+            category: "validation",
+            traceId,
+            cause: error
+        });
+    }
+    if (error instanceof Error) {
+        return new AppError({
+            message: error.message,
+            code: "ERR_INTERNAL",
+            category: "system",
+            traceId,
+            cause: error
+        });
+    }
+    return new AppError({
+        message: "Unknown server error",
+        code: "ERR_INTERNAL",
+        category: "system",
+        traceId
+    });
+}
+function summarizeZodError(error) {
+    const issue = error.issues[0];
+    if (!issue) {
+        return "Invalid tool arguments";
+    }
+    const path = issue.path.length > 0 ? issue.path.join(".") : "arguments";
+    return `Invalid tool arguments: ${path} ${issue.message}`;
+}