vidlens-mcp

Instructions

Implementation Reference

• src/server/mcp-server.ts:1138-1164 (handler)

  The handler implementation for the `downloadAsset` tool within `src/server/mcp-server.ts`. It utilizes `MediaDownloader` to perform the actual download.

  case "downloadAsset": {
    const mediaStore = getMediaStore();
    const mediaDownloader = getMediaDownloader();
    const videoIdOrUrl = readString(args, "videoIdOrUrl");
    const format = readString(args, "format") as "best_video" | "best_audio" | "thumbnail" | "worst_video";
    const maxSizeMb = optionalNumber(args, "maxSizeMb");
    const result = await mediaDownloader.download({ videoIdOrUrl, format, maxSizeMb });
    const provenance = { sourceTier: "yt_dlp" as const, fetchedAt: new Date().toISOString(), fallbackDepth: 0 as const, partial: false };
    return {
      asset: {
        assetId: result.asset.assetId,
        videoId: result.asset.videoId,
        kind: result.asset.kind,
        filePath: result.asset.filePath,
        fileName: result.asset.fileName,
        fileSizeBytes: result.asset.fileSizeBytes,
        mimeType: result.asset.mimeType,
        durationSec: result.asset.durationSec,
        width: result.asset.width,
        height: result.asset.height,
      },
      downloadedBytes: result.downloadedBytes,
      durationMs: result.durationMs,
      cached: result.downloadedBytes === 0,
      provenance,
    };
  }

• src/server/mcp-server.ts:445-462 (registration)

  The registration of the `downloadAsset` tool, including its name, description, and input schema.

  {
    name: "downloadAsset",
    description: "Download a YouTube video, audio track, or thumbnail to local storage. Returns asset manifest entry with file path. Does NOT perform visual indexing — this is honest file storage.",
    inputSchema: {
      type: "object",
      properties: {
        videoIdOrUrl: { type: "string", description: "YouTube video ID or URL" },
        format: {
          type: "string",
          enum: ["best_video", "best_audio", "thumbnail", "worst_video"],
          description: "What to download. best_video = highest quality video+audio, best_audio = audio only, thumbnail = YouTube thumbnail image, worst_video = smallest video for previews",
        },
        maxSizeMb: { type: "number", minimum: 1, maximum: 5000, description: "Max download size in MB (default 500)" },
      },
      required: ["videoIdOrUrl", "format"],
      additionalProperties: false,
    },
  },