mcp-video-analyzer 0.2.3 → 0.2.5

package/README.md

@@ -1,5 +1,11 @@
 # mcp-video-analyzer
 
+<a href="https://glama.ai/mcp/servers/guimatheus92/mcp-video-analyzer">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/guimatheus92/mcp-video-analyzer/badge" alt="mcp-video-analyzer MCP server" />
+</a>
+
+Featured in [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers#-multimedia-process).
+
 MCP server for video analysis — extracts transcripts, key frames, and metadata from video URLs. Supports Loom, direct video files (.mp4, .webm), and more.
 
 No existing video MCP combines **transcripts + visual frames + metadata** in one tool. This one does.

package/dist/processors/frame-ocr.d.ts

@@ -10,4 +10,4 @@ export interface IOcrResult {
  *
  * Only includes results with meaningful text (confidence > 50%, text length > 3).
  */
-export declare function extractTextFromFrames(frames: IFrameResult[]): Promise<IOcrResult[]>;
+export declare function extractTextFromFrames(frames: IFrameResult[], language?: string, onProgress?: (completed: number, total: number) => void): Promise<IOcrResult[]>;

package/dist/processors/frame-ocr.js

@@ -4,14 +4,15 @@
  *
  * Only includes results with meaningful text (confidence > 50%, text length > 3).
  */
-export async function extractTextFromFrames(frames) {
+export async function extractTextFromFrames(frames, language = 'eng+por', onProgress) {
     const Tesseract = await loadTesseract();
     if (!Tesseract)
         return [];
-    const worker = await Tesseract.createWorker('eng');
+    const worker = await Tesseract.createWorker(language);
     try {
         const results = [];
-        for (const frame of frames) {
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i];
             try {
                 const { data: { text, confidence }, } = await worker.recognize(frame.filePath);
                 const cleaned = text.trim();
@@ -26,6 +27,7 @@ export async function extractTextFromFrames(frames) {
             catch {
                 // Skip frames that fail OCR
             }
+            onProgress?.(i + 1, frames.length);
         }
         return results;
     }

package/dist/server.js

@@ -12,7 +12,7 @@ import { registerGetTranscript } from './tools/get-transcript.js';
 export function createServer() {
     const server = new FastMCP({
         name: 'mcp-video-analyzer',
-        version: '0.2.3',
+        version: '0.2.5',
         instructions: `Video analysis MCP server. Extracts transcripts, key frames, metadata, comments, OCR text, and annotated timelines from video URLs.
 
 AUTOMATIC BEHAVIOR — Do NOT wait for the user to ask:

package/dist/tools/analyze-moment.js

@@ -6,6 +6,7 @@ import { deduplicateFrames } from '../processors/frame-dedup.js';
 import { extractFrameBurst, parseTimestamp } from '../processors/frame-extractor.js';
 import { extractTextFromFrames } from '../processors/frame-ocr.js';
 import { optimizeFrames } from '../processors/image-optimizer.js';
+import { createProgressReporter } from '../utils/progress.js';
 import { createTempDir } from '../utils/temp-files.js';
 const AnalyzeMomentSchema = z.object({
     url: z.string().url().describe('Video URL (Loom share link or direct mp4/webm URL)'),
@@ -18,6 +19,10 @@ const AnalyzeMomentSchema = z.object({
         .default(10)
         .optional()
         .describe('Number of frames to extract in the range (default: 10)'),
+    ocrLanguage: z
+        .string()
+        .optional()
+        .describe('Tesseract OCR language codes (default: "eng+por"). Use "+" to combine: "eng+spa", "eng+fra+deu".'),
 });
 export function registerAnalyzeMoment(server) {
     server.addTool({
@@ -45,8 +50,10 @@ Requires video download capability for frame extraction.`,
             openWorldHint: true,
         },
         execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url, from, to } = args;
             const count = args.count ?? 10;
+            const ocrLanguage = args.ocrLanguage ?? 'eng+por';
             // Validate timestamps
             const fromSeconds = parseTimestamp(from);
             const toSeconds = parseTimestamp(to);
@@ -64,7 +71,7 @@ Requires video download capability for frame extraction.`,
             }
             const warnings = [];
             const tempDir = await createTempDir();
-            await reportProgress({ progress: 0, total: 100 });
+            await progress(0, `Starting moment analysis (${from} → ${to})...`);
             // Fetch transcript and filter to time range
             const fullTranscript = await adapter.getTranscript(url).catch((e) => {
                 warnings.push(`Failed to fetch transcript: ${e instanceof Error ? e.message : String(e)}`);
@@ -74,7 +81,7 @@ Requires video download capability for frame extraction.`,
                 const entrySeconds = parseTimestampLoose(entry.time);
                 return entrySeconds !== null && entrySeconds >= fromSeconds && entrySeconds <= toSeconds;
             });
-            await reportProgress({ progress: 20, total: 100 });
+            await progress(15, 'Transcript filtered to time range');
             // Download video and extract burst frames
             if (!adapter.capabilities.videoDownload) {
                 throw new UserError('Moment analysis requires video download capability. Use a direct video URL (.mp4, .webm, .mov).');
@@ -83,9 +90,9 @@ Requires video download capability for frame extraction.`,
             if (!videoPath) {
                 throw new UserError('Failed to download video for moment analysis.');
             }
-            await reportProgress({ progress: 40, total: 100 });
+            await progress(35, 'Video downloaded, extracting burst frames...');
             const rawFrames = await extractFrameBurst(videoPath, tempDir, from, to, count);
-            await reportProgress({ progress: 60, total: 100 });
+            await progress(55, `Extracted ${rawFrames.length} frames, optimizing...`);
             // Optimize frames
             const optimizedPaths = await optimizeFrames(rawFrames.map((f) => f.filePath), tempDir).catch((e) => {
                 warnings.push(`Frame optimization failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -101,16 +108,20 @@ Requires video download capability for frame extraction.`,
             if (frames.length < beforeDedup) {
                 warnings.push(`Removed ${beforeDedup - frames.length} near-duplicate frames (${beforeDedup} → ${frames.length})`);
             }
-            await reportProgress({ progress: 75, total: 100 });
+            await progress(70, 'Filtering and deduplicating frames...');
             // OCR
-            const ocrResults = await extractTextFromFrames(frames).catch((e) => {
+            await progress(75, `Running OCR on ${frames.length} frames...`);
+            const ocrResults = await extractTextFromFrames(frames, ocrLanguage, (completed, total) => {
+                const pct = 75 + Math.round((completed / total) * 15);
+                progress(pct, `OCR: processing frame ${completed}/${total}...`);
+            }).catch((e) => {
                 warnings.push(`OCR failed: ${e instanceof Error ? e.message : String(e)}`);
                 return [];
             });
-            await reportProgress({ progress: 90, total: 100 });
+            await progress(92, 'Building annotated timeline...');
             // Build mini-timeline for this range
             const timeline = buildAnnotatedTimeline(transcriptSegment, frames, ocrResults);
-            await reportProgress({ progress: 100, total: 100 });
+            await progress(100, 'Moment analysis complete');
             // Build response
             const textData = {
                 range: { from, to, fromSeconds, toSeconds },

package/dist/tools/analyze-video.js

@@ -11,6 +11,7 @@ import { extractTextFromFrames } from '../processors/frame-ocr.js';
 import { optimizeFrames } from '../processors/image-optimizer.js';
 import { AnalysisCache, cacheKey } from '../utils/cache.js';
 import { filterAnalysisResult } from '../utils/field-filter.js';
+import { createProgressReporter } from '../utils/progress.js';
 import { cleanupTempDir, createTempDir } from '../utils/temp-files.js';
 const cache = new AnalysisCache();
 const ANALYSIS_FIELDS = [
@@ -62,6 +63,10 @@ const AnalyzeOptionsSchema = z
         .default(false)
         .optional()
         .describe('Bypass cache and re-analyze the video'),
+    ocrLanguage: z
+        .string()
+        .optional()
+        .describe('Tesseract OCR language codes (default: "eng+por"). Use "+" to combine: "eng+spa", "eng+fra+deu". See Tesseract docs for codes.'),
 })
     .optional();
 const AnalyzeVideoSchema = z.object({
@@ -99,11 +104,13 @@ Use options.forceRefresh to bypass the cache.`,
             openWorldHint: true,
         },
         execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url, options } = args;
             const detail = options?.detail ?? 'standard';
             const forceRefresh = options?.forceRefresh ?? false;
             const fields = options?.fields;
             const threshold = options?.threshold ?? 0.1;
+            const ocrLanguage = options?.ocrLanguage ?? 'eng+por';
             // Resolve detail config
             const config = getDetailConfig(detail);
             const maxFrames = options?.maxFrames ?? config.maxFrames;
@@ -142,7 +149,7 @@ Use options.forceRefresh to bypass the cache.`,
             const warnings = [];
             let tempDir = null;
             try {
-                await reportProgress({ progress: 0, total: 100 });
+                await progress(0, 'Starting video analysis...');
                 // Fetch metadata, transcript, comments in parallel
                 const [metadata, transcript, comments, chapters, aiSummary] = await Promise.all([
                     adapter.getMetadata(url).catch((e) => {
@@ -166,7 +173,7 @@ Use options.forceRefresh to bypass the cache.`,
                     adapter.getChapters(url).catch(() => []),
                     adapter.getAiSummary(url).catch(() => null),
                 ]);
-                await reportProgress({ progress: 40, total: 100 });
+                await progress(35, 'Metadata and transcript fetched');
                 // Apply transcript limit for brief mode
                 const limitedTranscript = config.transcriptMaxEntries !== null
                     ? transcript.slice(0, config.transcriptMaxEntries)
@@ -191,7 +198,7 @@ Use options.forceRefresh to bypass the cache.`,
                     if (adapter.capabilities.videoDownload) {
                         videoPath = await adapter.downloadVideo(url, tempDir);
                         if (videoPath) {
-                            await reportProgress({ progress: 60, total: 100 });
+                            await progress(50, 'Video downloaded, extracting frames...');
                             // Probe duration if metadata didn't provide it
                             if (metadata.duration === 0) {
                                 const duration = await probeVideoDuration(videoPath).catch(() => 0);
@@ -211,7 +218,7 @@ Use options.forceRefresh to bypass the cache.`,
                                     warnings.push(`Frame extraction failed: ${e instanceof Error ? e.message : String(e)}`);
                                     return [];
                                 });
-                            await reportProgress({ progress: 80, total: 100 });
+                            await progress(70, `Extracted ${rawFrames.length} frames, optimizing...`);
                             if (rawFrames.length > 0) {
                                 const optimizedPaths = await optimizeFrames(rawFrames.map((f) => f.filePath), tempDir).catch((e) => {
                                     warnings.push(`Frame optimization failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -227,7 +234,7 @@ Use options.forceRefresh to bypass the cache.`,
                     }
                     // Strategy 2: Browser-based extraction (fallback)
                     if (!framesExtracted && metadata.duration > 0) {
-                        await reportProgress({ progress: 60, total: 100 });
+                        await progress(50, 'Extracting frames via browser fallback...');
                         const timestamps = generateTimestamps(metadata.duration, maxFrames);
                         const browserFrames = await extractBrowserFrames(url, tempDir, {
                             timestamps,
@@ -235,7 +242,7 @@ Use options.forceRefresh to bypass the cache.`,
                             warnings.push(`Browser frame extraction failed: ${e instanceof Error ? e.message : String(e)}`);
                             return [];
                         });
-                        await reportProgress({ progress: 80, total: 100 });
+                        await progress(70, `Browser extracted ${browserFrames.length} frames`);
                         if (browserFrames.length > 0) {
                             result.frames = browserFrames;
                             framesExtracted = true;
@@ -264,18 +271,23 @@ Use options.forceRefresh to bypass the cache.`,
                         if (result.frames.length < beforeDedup) {
                             warnings.push(`Removed ${beforeDedup - result.frames.length} near-duplicate frames (${beforeDedup} → ${result.frames.length})`);
                         }
-                        await reportProgress({ progress: 85, total: 100 });
+                        await progress(80, 'Filtering and deduplicating frames...');
                         // OCR: extract text visible on screen
                         if (config.includeOcr) {
-                            result.ocrResults = await extractTextFromFrames(result.frames).catch((e) => {
+                            await progress(85, `Running OCR on ${result.frames.length} frames...`);
+                            result.ocrResults = await extractTextFromFrames(result.frames, ocrLanguage, (completed, total) => {
+                                const pct = 85 + Math.round((completed / total) * 8);
+                                progress(pct, `OCR: processing frame ${completed}/${total}...`);
+                            }).catch((e) => {
                                 warnings.push(`OCR failed: ${e instanceof Error ? e.message : String(e)}`);
                                 return [];
                             });
                         }
-                        await reportProgress({ progress: 95, total: 100 });
+                        await progress(93, 'OCR complete');
                     }
                     // Build annotated timeline
                     if (config.includeTimeline) {
+                        await progress(95, 'Building annotated timeline...');
                         result.timeline = buildAnnotatedTimeline(result.transcript, result.frames, result.ocrResults);
                     }
                 }
@@ -300,7 +312,7 @@ Use options.forceRefresh to bypass the cache.`,
                         // Audio extraction or transcription failed — not critical
                     }
                 }
-                await reportProgress({ progress: 100, total: 100 });
+                await progress(100, 'Analysis complete');
                 // Cache the full result
                 cache.set(key, result);
                 // Apply field filter

package/dist/tools/get-frame-at.js

@@ -4,8 +4,8 @@ import { getAdapter } from '../adapters/adapter.interface.js';
 import { extractBrowserFrames } from '../processors/browser-frame-extractor.js';
 import { extractFrameAt, parseTimestamp } from '../processors/frame-extractor.js';
 import { optimizeFrame } from '../processors/image-optimizer.js';
-import { createTempDir } from '../utils/temp-files.js';
-import { getTempFilePath } from '../utils/temp-files.js';
+import { createProgressReporter } from '../utils/progress.js';
+import { createTempDir, getTempFilePath } from '../utils/temp-files.js';
 const GetFrameAtSchema = z.object({
     url: z.string().url().describe('Video URL (Loom share link or direct mp4/webm URL)'),
     timestamp: z
@@ -42,19 +42,20 @@ Returns: A single image of the video frame at the specified timestamp.`,
             openWorldHint: true,
         },
         execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url, timestamp } = args;
             const adapter = getAdapter(url);
-            await reportProgress({ progress: 0, total: 100 });
+            await progress(0, 'Starting frame extraction...');
             const tempDir = await createTempDir();
             // Strategy 1: Download video + ffmpeg extraction
             if (adapter.capabilities.videoDownload) {
                 const videoPath = await adapter.downloadVideo(url, tempDir);
                 if (videoPath) {
-                    await reportProgress({ progress: 50, total: 100 });
+                    await progress(50, `Extracting frame at ${timestamp}...`);
                     const frame = await extractFrameAt(videoPath, tempDir, timestamp);
                     const optimizedPath = getTempFilePath(tempDir, `opt_frame_at.jpg`);
                     await optimizeFrame(frame.filePath, optimizedPath);
-                    await reportProgress({ progress: 100, total: 100 });
+                    await progress(100, 'Frame extracted');
                     return {
                         content: [
                             { type: 'text', text: `Frame extracted at ${timestamp}` },
@@ -64,13 +65,13 @@ Returns: A single image of the video frame at the specified timestamp.`,
                 }
             }
             // Strategy 2: Browser-based extraction (fallback)
-            await reportProgress({ progress: 30, total: 100 });
+            await progress(30, 'Extracting frame via browser fallback...');
             const seconds = parseTimestamp(timestamp);
             const browserFrames = await extractBrowserFrames(url, tempDir, {
                 timestamps: [seconds],
             });
             if (browserFrames.length > 0) {
-                await reportProgress({ progress: 100, total: 100 });
+                await progress(100, 'Frame extracted');
                 return {
                     content: [
                         {

package/dist/tools/get-frame-burst.js

@@ -4,6 +4,7 @@ import { getAdapter } from '../adapters/adapter.interface.js';
 import { extractBrowserFrames } from '../processors/browser-frame-extractor.js';
 import { extractFrameBurst, parseTimestamp } from '../processors/frame-extractor.js';
 import { optimizeFrames } from '../processors/image-optimizer.js';
+import { createProgressReporter } from '../utils/progress.js';
 import { createTempDir } from '../utils/temp-files.js';
 const GetFrameBurstSchema = z.object({
     url: z.string().url().describe('Video URL (Loom share link or direct mp4/webm URL)'),
@@ -53,20 +54,21 @@ Returns: N images evenly distributed between the from and to timestamps.`,
             openWorldHint: true,
         },
         execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url, from, to, count } = args;
             const frameCount = count ?? 5;
             const adapter = getAdapter(url);
-            await reportProgress({ progress: 0, total: 100 });
+            await progress(0, `Starting burst extraction (${from} → ${to})...`);
             const tempDir = await createTempDir();
             // Strategy 1: Download video + ffmpeg burst extraction
             if (adapter.capabilities.videoDownload) {
                 const videoPath = await adapter.downloadVideo(url, tempDir);
                 if (videoPath) {
-                    await reportProgress({ progress: 40, total: 100 });
+                    await progress(40, 'Video downloaded, extracting burst frames...');
                     const frames = await extractFrameBurst(videoPath, tempDir, from, to, frameCount);
-                    await reportProgress({ progress: 70, total: 100 });
+                    await progress(70, `Extracted ${frames.length} frames, optimizing...`);
                     const optimizedPaths = await optimizeFrames(frames.map((f) => f.filePath), tempDir);
-                    await reportProgress({ progress: 100, total: 100 });
+                    await progress(100, 'Burst extraction complete');
                     const content = [
                         {
                             type: 'text',
@@ -80,14 +82,14 @@ Returns: N images evenly distributed between the from and to timestamps.`,
                 }
             }
             // Strategy 2: Browser-based extraction (fallback)
-            await reportProgress({ progress: 30, total: 100 });
+            await progress(30, 'Extracting frames via browser fallback...');
             const fromSeconds = parseTimestamp(from);
             const toSeconds = parseTimestamp(to);
             const interval = (toSeconds - fromSeconds) / Math.max(frameCount - 1, 1);
             const timestamps = Array.from({ length: frameCount }, (_, i) => Math.round(fromSeconds + i * interval));
             const browserFrames = await extractBrowserFrames(url, tempDir, { timestamps });
             if (browserFrames.length > 0) {
-                await reportProgress({ progress: 100, total: 100 });
+                await progress(100, 'Burst extraction complete');
                 const content = [
                     {
                         type: 'text',

package/dist/tools/get-frames.js

@@ -5,6 +5,7 @@ import { extractBrowserFrames, generateTimestamps } from '../processors/browser-
 import { deduplicateFrames, filterBlackFrames } from '../processors/frame-dedup.js';
 import { extractDenseFrames, extractSceneFrames, formatTimestamp, probeVideoDuration, } from '../processors/frame-extractor.js';
 import { optimizeFrames } from '../processors/image-optimizer.js';
+import { createProgressReporter } from '../utils/progress.js';
 import { createTempDir } from '../utils/temp-files.js';
 const GetFramesSchema = z.object({
     url: z.string().url().describe('Video URL (Loom share link or direct mp4/webm URL)'),
@@ -53,6 +54,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             openWorldHint: true,
         },
         execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url, options } = args;
             const maxFrames = options?.maxFrames ?? 20;
             const threshold = options?.threshold ?? 0.1;
@@ -68,7 +70,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             }
             const warnings = [];
             const tempDir = await createTempDir();
-            await reportProgress({ progress: 0, total: 100 });
+            await progress(0, 'Starting frame extraction...');
             // Get metadata for duration (needed for browser fallback)
             const metadata = await adapter.getMetadata(url).catch(() => ({
                 platform: adapter.name,
@@ -82,7 +84,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             if (adapter.capabilities.videoDownload) {
                 const videoPath = await adapter.downloadVideo(url, tempDir);
                 if (videoPath) {
-                    await reportProgress({ progress: 50, total: 100 });
+                    await progress(40, 'Video downloaded, extracting frames...');
                     if (metadata.duration === 0) {
                         const duration = await probeVideoDuration(videoPath).catch(() => 0);
                         metadata.duration = duration;
@@ -108,7 +110,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             }
             // Strategy 2: Browser fallback
             if (frames.length === 0 && metadata.duration > 0) {
-                await reportProgress({ progress: 50, total: 100 });
+                await progress(40, 'Extracting frames via browser fallback...');
                 const timestamps = generateTimestamps(metadata.duration, maxFrames);
                 frames = await extractBrowserFrames(url, tempDir, { timestamps }).catch((e) => {
                     warnings.push(`Browser extraction failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -116,6 +118,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
                 });
             }
             // Filter black/blank frames
+            await progress(80, 'Filtering and deduplicating frames...');
             if (frames.length > 0) {
                 const blackResult = await filterBlackFrames(frames).catch(() => ({
                     frames,
@@ -134,7 +137,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
                     warnings.push(`Removed ${before - frames.length} duplicate frames`);
                 }
             }
-            await reportProgress({ progress: 100, total: 100 });
+            await progress(100, 'Frames extracted');
             if (frames.length === 0) {
                 throw new UserError('Could not extract any frames. Install yt-dlp or Chrome/Chromium for frame extraction.');
             }

package/dist/tools/get-metadata.js

@@ -1,6 +1,7 @@
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getAdapter } from '../adapters/adapter.interface.js';
+import { createProgressReporter } from '../utils/progress.js';
 const GetMetadataSchema = z.object({
     url: z.string().url().describe('Video URL (Loom share link or direct mp4/webm URL)'),
 });
@@ -21,7 +22,8 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             idempotentHint: true,
             openWorldHint: true,
         },
-        execute: async (args) => {
+        execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url } = args;
             let adapter;
             try {
@@ -33,6 +35,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
                 throw new UserError(`Failed to detect video platform for URL: ${url}`);
             }
             const warnings = [];
+            await progress(0, 'Fetching video metadata...');
             const [metadata, comments, chapters, aiSummary] = await Promise.all([
                 adapter.getMetadata(url).catch((e) => {
                     warnings.push(`Failed to fetch metadata: ${e instanceof Error ? e.message : String(e)}`);
@@ -51,6 +54,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
                 adapter.getChapters(url).catch(() => []),
                 adapter.getAiSummary(url).catch(() => null),
             ]);
+            await progress(100, 'Metadata fetched');
             return {
                 content: [
                     {

package/dist/tools/get-transcript.js

@@ -2,6 +2,7 @@ import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getAdapter } from '../adapters/adapter.interface.js';
 import { extractAudioTrack, transcribeAudio } from '../processors/audio-transcriber.js';
+import { createProgressReporter } from '../utils/progress.js';
 import { cleanupTempDir, createTempDir } from '../utils/temp-files.js';
 const GetTranscriptSchema = z.object({
     url: z.string().url().describe('Video URL (Loom share link or direct mp4/webm URL)'),
@@ -26,7 +27,8 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             idempotentHint: true,
             openWorldHint: true,
         },
-        execute: async (args) => {
+        execute: async (args, { reportProgress }) => {
+            const progress = createProgressReporter(reportProgress);
             const { url } = args;
             let adapter;
             try {
@@ -38,18 +40,22 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
                 throw new UserError(`Failed to detect video platform for URL: ${url}`);
             }
             const warnings = [];
+            await progress(0, 'Fetching transcript...');
             // Try native transcript first
             let transcript = await adapter.getTranscript(url).catch((e) => {
                 warnings.push(`Failed to fetch native transcript: ${e instanceof Error ? e.message : String(e)}`);
                 return [];
             });
+            await progress(40, 'Native transcript fetched');
             // Whisper fallback if no native transcript
             if (transcript.length === 0 && adapter.capabilities.videoDownload) {
                 let tempDir = null;
                 try {
+                    await progress(45, 'No native transcript, downloading video for Whisper...');
                     tempDir = await createTempDir();
                     const videoPath = await adapter.downloadVideo(url, tempDir);
                     if (videoPath) {
+                        await progress(65, 'Transcribing audio with Whisper...');
                         const audioPath = await extractAudioTrack(videoPath, tempDir);
                         transcript = await transcribeAudio(audioPath);
                         if (transcript.length > 0) {
@@ -68,6 +74,7 @@ Supports: Loom (loom.com/share/...) and direct video URLs (.mp4, .webm, .mov).`,
             if (transcript.length === 0) {
                 warnings.push('No transcript available for this video.');
             }
+            await progress(100, 'Transcript complete');
             return {
                 content: [
                     {

package/dist/utils/progress.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Progress reporting utility with descriptive messages.
+ *
+ * The MCP spec supports an optional `message` field in progress notifications.
+ * FastMCP's TypeScript type omits it, but the runtime passes it through via spread.
+ */
+type ReportProgressFn = (progress: {
+    progress: number;
+    total?: number;
+}) => Promise<void>;
+export declare function createProgressReporter(reportProgress: ReportProgressFn, total?: number): (progress: number, message?: string) => Promise<void>;
+export {};

package/dist/utils/progress.js

@@ -0,0 +1,15 @@
+/**
+ * Progress reporting utility with descriptive messages.
+ *
+ * The MCP spec supports an optional `message` field in progress notifications.
+ * FastMCP's TypeScript type omits it, but the runtime passes it through via spread.
+ */
+export function createProgressReporter(reportProgress, total = 100) {
+    return async (progress, message) => {
+        const payload = { progress, total };
+        if (message) {
+            payload.message = message;
+        }
+        await reportProgress(payload);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-video-analyzer",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "MCP server for video analysis — extracts transcripts, key frames, OCR text, and metadata from video URLs. Supports Loom and direct video files.",
   "author": "guimatheus92",
   "license": "MIT",