@sylphx/video-reader-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SylphxAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# Video Reader MCP
+
+> Evidence-first video reading for AI agents — ffprobe, subtitles, scenes, transcripts, and timelines without frame-by-frame LLM vision.
+
+**Status:** v0.1.0 shipped — `read_video` MCP tool available.
+
+Orchestrated by [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp) — portfolio ADR lives there, not in pdf-reader-mcp.
+
+| Repository | Role |
+| --- | --- |
+| [pdf-reader-mcp](https://github.com/SylphxAI/pdf-reader-mcp) | PDF (production) |
+| [image-reader-mcp](https://github.com/SylphxAI/image-reader-mcp) | Image |
+| **video-reader-mcp** (this repo) | Video |
+| [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp) | Unified read + delegate |
+
+## Read vs interpret
+
+**Read** (this repo): extract facts, metadata, transcripts, regions, and timelines with provenance — **no generative LLM required**.
+
+**Interpret** (out of scope): summarize, classify, or answer open questions — belongs in the agent or an optional remote provider adapter.
+
+## MCP surface
+
+Primary tool: `read_video`
+
+Returns a **timeline document** per source:
+
+- ffprobe format + stream metadata
+- chapter markers
+- embedded subtitle cues (`time_ms`, text, provenance)
+- optional scene boundaries (ffmpeg `scene` filter)
+- warnings (missing ffmpeg/ffprobe, VFR, missing audio, skipped ASR)
+- optional local ASR hook (skipped in v0.1 unless adapter is wired)
+
+No per-frame vision LLM calls. No cloud APIs by default.
+
+## Prerequisites
+
+- Node.js ≥ 22.13
+- **ffprobe** (required) and **ffmpeg** (recommended for subtitles + scenes) on `PATH`
+
+## Quick start
+
+```bash
+npx @sylphx/video-reader-mcp
+```
+
+From source:
+
+```bash
+bun install
+bun run build
+bun run start
+```
+
+### Example `read_video` input
+
+```json
+{
+  "sources": [{ "path": "./sample.mp4" }],
+  "include_subtitles": true,
+  "include_scenes": true,
+  "scene_threshold": 0.4
+}
+```
+
+### HTTP transport (optional)
+
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=8080 node dist/index.js
+```
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```
+
+Unit tests mock parsers and do not require ffmpeg in CI. Integration with real media is optional locally.
+
+## License
+
+MIT © [SylphxAI](https://github.com/SylphxAI)

package/dist/handlers/readVideo.js

@@ -0,0 +1,24 @@
+import { text, tool, toolError } from '../mcp.js';
+import { readVideoArgsSchema } from '../schemas/readVideo.js';
+import { processVideoSource } from '../video/readCoordinator.js';
+const MAX_CONCURRENT_SOURCES = 2;
+export const createReadVideoHandler = (version) => tool()
+    .description('Primary video reader. Returns a timeline document with ffprobe metadata, embedded subtitles, optional scene boundaries, and warnings — no per-frame vision LLM.')
+    .input(readVideoArgsSchema)
+    .handler(async ({ input }) => {
+    const results = [];
+    for (let i = 0; i < input.sources.length; i += MAX_CONCURRENT_SOURCES) {
+        const batch = input.sources.slice(i, i + MAX_CONCURRENT_SOURCES);
+        const batchResults = await Promise.all(batch.map((source) => processVideoSource(source.path, input, version)));
+        results.push(...batchResults);
+    }
+    const allFailed = results.every((result) => !result.success);
+    if (allFailed) {
+        const errorMessages = results.map((result) => result.error).join('; ');
+        return toolError(`All video sources failed to process: ${errorMessages}`);
+    }
+    return text(JSON.stringify({
+        results,
+    }, null, 2));
+});
+export const readVideo = createReadVideoHandler('0.1.0');

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { createReadVideoHandler } from './handlers/readVideo.js';
+import { createServer, http, stdio } from './mcp.js';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+const transportType = process.env['MCP_TRANSPORT'] ?? 'stdio';
+const httpPort = Number.parseInt(process.env['MCP_HTTP_PORT'] ?? '8080', 10);
+const httpHost = process.env['MCP_HTTP_HOST'] ?? '127.0.0.1';
+const apiKey = process.env['MCP_API_KEY'];
+const corsOrigin = process.env['MCP_CORS_ORIGIN'];
+const isLoopbackHost = (host) => host === 'localhost' || host === '::1' || host === '127.0.0.1' || host.startsWith('127.');
+function createTransport() {
+    if (transportType === 'http') {
+        return http({
+            port: httpPort,
+            hostname: httpHost,
+            ...(corsOrigin ? { cors: corsOrigin } : {}),
+            ...(apiKey ? { apiKey } : {}),
+        });
+    }
+    return stdio();
+}
+const server = createServer({
+    name: 'video-reader-mcp',
+    version: packageJson.version,
+    instructions: 'Evidence-first video reader. Use read_video to extract ffprobe metadata, embedded subtitles, scene boundaries, and timeline warnings without frame-by-frame vision LLM calls.',
+    tools: {
+        read_video: createReadVideoHandler(packageJson.version),
+    },
+    transport: createTransport(),
+});
+async function main() {
+    await server.start();
+    if (transportType === 'http') {
+        console.log(`[Video Reader MCP] Server running on http://${httpHost}:${httpPort}/mcp`);
+        console.log(`[Video Reader MCP] Health check: http://${httpHost}:${httpPort}/mcp/health`);
+        if (apiKey) {
+            console.log('[Video Reader MCP] API key authentication enabled (X-API-Key header)');
+        }
+        else if (!isLoopbackHost(httpHost)) {
+            console.warn(`[Video Reader MCP] WARNING: bound to non-loopback host ${httpHost} with no API key. ` +
+                'Any client that can reach this port can read every video this process can access. ' +
+                'Set MCP_API_KEY to require an X-API-Key header, or bind MCP_HTTP_HOST=127.0.0.1.');
+        }
+        if (corsOrigin) {
+            console.log(`[Video Reader MCP] CORS allowed origin: ${corsOrigin}`);
+        }
+        console.log('[Video Reader MCP] Project root:', process.cwd());
+    }
+    else if (process.env['DEBUG_MCP']) {
+        console.error('[Video Reader MCP] Server running on stdio');
+        console.error('[Video Reader MCP] Project root:', process.cwd());
+    }
+}
+main().catch((error) => {
+    console.error('[Video Reader MCP] Server error:', error);
+    process.exit(1);
+});

package/dist/mcp.js

@@ -0,0 +1,181 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer as createHttpServer } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+export const text = (value) => ({ type: 'text', text: value });
+export const image = (data, mimeType) => ({
+    type: 'image',
+    data,
+    mimeType,
+});
+export const toolError = (message) => ({
+    content: [text(message)],
+    isError: true,
+});
+class ToolBuilder {
+    #description;
+    #inputSchema;
+    constructor(descriptionValue, inputSchema) {
+        this.#description = descriptionValue;
+        this.#inputSchema = inputSchema;
+    }
+    description(value) {
+        return new ToolBuilder(value, this.#inputSchema);
+    }
+    input(schema) {
+        return new ToolBuilder(this.#description, schema);
+    }
+    handler(handler) {
+        return {
+            description: this.#description ?? '',
+            inputSchema: this.#inputSchema ?? z.object({}),
+            handler,
+        };
+    }
+}
+export const tool = () => new ToolBuilder();
+export const stdio = () => ({ kind: 'stdio' });
+export const http = (config) => ({ kind: 'http', ...config });
+const isCallToolResult = (result) => typeof result === 'object' && result !== null && 'content' in result;
+const isContentArray = (result) => Array.isArray(result);
+const normalizeToolResult = (result) => {
+    if (isContentArray(result))
+        return { content: [...result] };
+    if (isCallToolResult(result))
+        return result;
+    return { content: [result] };
+};
+const withCors = (res, origin) => {
+    if (!origin)
+        return;
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, MCP-Protocol-Version, Mcp-Session-Id, X-API-Key');
+};
+const isApiKeyValid = (configuredKey, presented) => {
+    const provided = Array.isArray(presented) ? presented[0] : presented;
+    if (typeof provided !== 'string' || provided.length === 0)
+        return false;
+    const expected = createHash('sha256').update(configuredKey).digest();
+    const actual = createHash('sha256').update(provided).digest();
+    return timingSafeEqual(expected, actual);
+};
+const unauthorized = (res) => {
+    res.writeHead(401, { 'Content-Type': 'application/json', 'WWW-Authenticate': 'X-API-Key' });
+    res.end(JSON.stringify({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32001, message: 'Unauthorized: missing or invalid X-API-Key header' },
+    }));
+};
+const ensureStreamableAcceptHeader = (req) => {
+    const accept = req.headers.accept;
+    const acceptValues = Array.isArray(accept) ? accept.join(', ') : (accept ?? '');
+    if (acceptValues.includes('application/json') && acceptValues.includes('text/event-stream')) {
+        return;
+    }
+    req.headers.accept = 'application/json, text/event-stream';
+    const rawAcceptIndex = req.rawHeaders.findIndex((value, index) => index % 2 === 0 && value.toLowerCase() === 'accept');
+    if (rawAcceptIndex >= 0) {
+        req.rawHeaders[rawAcceptIndex + 1] = 'application/json, text/event-stream';
+        return;
+    }
+    req.rawHeaders.push('Accept', 'application/json, text/event-stream');
+};
+const handleNonMcpRoute = (req, res, pathname, transportConfig) => {
+    if (pathname === '/mcp/health' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok' }));
+        return true;
+    }
+    if (pathname !== '/mcp') {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+        return true;
+    }
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return true;
+    }
+    if (transportConfig.apiKey !== undefined &&
+        !isApiKeyValid(transportConfig.apiKey, req.headers['x-api-key'])) {
+        unauthorized(res);
+        return true;
+    }
+    return false;
+};
+const handleHttpRequest = async (req, res, mcpServer, transportConfig) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? transportConfig.hostname}`);
+    withCors(res, transportConfig.cors);
+    if (handleNonMcpRoute(req, res, url.pathname, transportConfig))
+        return;
+    ensureStreamableAcceptHeader(req);
+    const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
+    try {
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res);
+    }
+    finally {
+        await mcpServer.close();
+    }
+};
+const startHttpServer = async (serverInfo, transportConfig) => {
+    const mcpServer = buildMcpServer(serverInfo);
+    const httpServer = createHttpServer((req, res) => {
+        void handleHttpRequest(req, res, mcpServer, transportConfig);
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(transportConfig.port, transportConfig.hostname, () => {
+            httpServer.off('error', reject);
+            resolve();
+        });
+    });
+    return { mcpServer, httpServer };
+};
+const buildMcpServer = ({ name, version, instructions, tools, }) => {
+    const mcpServer = new McpServer({ name, version }, {
+        ...(instructions ? { instructions } : {}),
+    });
+    for (const [toolName, definition] of Object.entries(tools)) {
+        mcpServer.registerTool(toolName, {
+            description: definition.description,
+            inputSchema: definition.inputSchema,
+        }, async (input, ctx) => normalizeToolResult(await definition.handler({ input, ctx })));
+    }
+    return mcpServer;
+};
+export const createServer = (options) => {
+    let mcpServer;
+    let httpServer;
+    return {
+        async start() {
+            if (options.transport.kind === 'stdio') {
+                mcpServer = buildMcpServer(options);
+                await mcpServer.connect(new StdioServerTransport());
+                return;
+            }
+            const started = await startHttpServer(options, options.transport);
+            mcpServer = started.mcpServer;
+            httpServer = started.httpServer;
+        },
+        async close() {
+            await mcpServer?.close();
+            const serverToClose = httpServer;
+            if (!serverToClose)
+                return;
+            await new Promise((resolve, reject) => {
+                serverToClose.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        },
+    };
+};

package/dist/schemas/readVideo.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export const videoSourceSchema = z.object({
+    path: z.string().min(1).describe('Path to the local video file (absolute or relative to cwd).'),
+});
+export const readVideoArgsSchema = z.object({
+    sources: z.array(videoSourceSchema).min(1).describe('One or more local video sources to read.'),
+    include_streams: z
+        .boolean()
+        .optional()
+        .describe('Include stream metadata from ffprobe. Defaults to true.'),
+    include_chapters: z
+        .boolean()
+        .optional()
+        .describe('Include chapter markers when present. Defaults to true.'),
+    include_subtitles: z
+        .boolean()
+        .optional()
+        .describe('Extract embedded subtitles when available. Defaults to true.'),
+    include_scenes: z
+        .boolean()
+        .optional()
+        .describe('Detect scene boundaries with ffmpeg scene filter. Defaults to true.'),
+    scene_threshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Scene detection sensitivity for ffmpeg gt(scene,threshold). Defaults to 0.4.'),
+    include_transcript: z
+        .boolean()
+        .optional()
+        .describe('Attempt optional local ASR transcript when an adapter is installed. Defaults to false.'),
+});

package/dist/types/timeline.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/asr.js

@@ -0,0 +1,26 @@
+import { isBinaryAvailable } from './exec.js';
+const ASR_CANDIDATES = ['whisper', 'whisper-cpp', 'vosk-transcriber'];
+export const detectAsrAdapter = async () => {
+    for (const candidate of ASR_CANDIDATES) {
+        if (await isBinaryAvailable(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+};
+export const tryAsrTranscript = async (_videoPath, enabled) => {
+    if (!enabled) {
+        return { transcript: [] };
+    }
+    const adapter = await detectAsrAdapter();
+    if (!adapter) {
+        return {
+            transcript: [],
+            warning: 'ASR requested but no local adapter found (checked whisper, whisper-cpp, vosk-transcriber); transcript skipped.',
+        };
+    }
+    return {
+        transcript: [],
+        warning: `ASR adapter "${adapter}" detected but transcription is not wired in v0.1.0; transcript skipped.`,
+    };
+};

package/dist/utils/errors.js

@@ -0,0 +1,14 @@
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode[ErrorCode["InvalidParams"] = -32602] = "InvalidParams";
+    ErrorCode[ErrorCode["InvalidRequest"] = -32600] = "InvalidRequest";
+    ErrorCode[ErrorCode["MethodNotFound"] = -32601] = "MethodNotFound";
+})(ErrorCode || (ErrorCode = {}));
+export class VideoError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.code = code;
+        this.name = 'VideoError';
+    }
+}

package/dist/utils/exec.js

@@ -0,0 +1,56 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+export const execBinary = async (binary, args, options = {}) => {
+    const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBuffer = options.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    try {
+        const { stdout, stderr } = await execFileAsync(binary, [...args], {
+            timeout,
+            maxBuffer,
+            encoding: 'utf8',
+        });
+        return {
+            stdout: typeof stdout === 'string' ? stdout : String(stdout),
+            stderr: typeof stderr === 'string' ? stderr : String(stderr),
+        };
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'killed' in error &&
+            error.killed === true &&
+            'signal' in error &&
+            error.signal === 'SIGTERM') {
+            throw new Error(`${binary} timed out after ${timeout}ms`);
+        }
+        throw error;
+    }
+};
+const binaryCache = new Map();
+export const isBinaryAvailable = async (binary) => {
+    const cached = binaryCache.get(binary);
+    if (cached !== undefined)
+        return cached;
+    try {
+        await execFileAsync(binary, ['-version'], { timeout: 5_000, encoding: 'utf8' });
+        binaryCache.set(binary, true);
+        return true;
+    }
+    catch {
+        try {
+            await execFileAsync(binary, ['--version'], { timeout: 5_000, encoding: 'utf8' });
+            binaryCache.set(binary, true);
+            return true;
+        }
+        catch {
+            binaryCache.set(binary, false);
+            return false;
+        }
+    }
+};
+export const clearBinaryCache = () => {
+    binaryCache.clear();
+};

package/dist/utils/ffmpeg.js

@@ -0,0 +1,66 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execBinary, isBinaryAvailable } from './exec.js';
+import { parseSubtitleContent } from './subtitles.js';
+const subtitleFormatForStream = (stream) => {
+    const codec = stream.codec_name?.toLowerCase() ?? '';
+    if (codec.includes('webvtt') || codec === 'vtt')
+        return 'vtt';
+    return 'srt';
+};
+export const extractSubtitles = async (videoPath, subtitleStreams) => {
+    const warnings = [];
+    const subtitles = [];
+    if (subtitleStreams.length === 0) {
+        return { subtitles, warnings: ['No embedded subtitle streams found.'] };
+    }
+    const available = await isBinaryAvailable('ffmpeg');
+    if (!available) {
+        return {
+            subtitles,
+            warnings: ['ffmpeg is not installed; subtitle extraction skipped.'],
+        };
+    }
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), 'video-reader-mcp-'));
+    try {
+        for (const stream of subtitleStreams) {
+            const format = subtitleFormatForStream(stream);
+            const extension = format === 'srt' ? 'srt' : 'vtt';
+            const outputPath = path.join(tempDir, `sub-${stream.index}.${extension}`);
+            try {
+                await execBinary('ffmpeg', [
+                    '-hide_banner',
+                    '-y',
+                    '-i',
+                    videoPath,
+                    '-map',
+                    `0:${stream.index}`,
+                    '-c:s',
+                    format === 'srt' ? 'srt' : 'webvtt',
+                    outputPath,
+                ], { timeoutMs: 120_000 });
+                const content = await readFile(outputPath, 'utf8');
+                const cues = parseSubtitleContent(content, format).map((cue) => ({
+                    ...cue,
+                    index: subtitles.length + cue.index,
+                    stream_index: stream.index,
+                    ...(stream.tags?.language ? { language: stream.tags.language } : {}),
+                    provenance: {
+                        method: 'ffmpeg_extract',
+                        format,
+                    },
+                }));
+                subtitles.push(...cues);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                warnings.push(`Subtitle stream ${stream.index} extraction failed: ${message}`);
+            }
+        }
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+    return { subtitles, warnings };
+};

package/dist/utils/ffprobe.js

@@ -0,0 +1,79 @@
+import { execBinary, isBinaryAvailable } from './exec.js';
+export const parseFfprobeJson = (raw) => {
+    const parsed = JSON.parse(raw);
+    return {
+        streams: Array.isArray(parsed.streams) ? parsed.streams : [],
+        format: parsed.format ?? {},
+        chapters: Array.isArray(parsed.chapters) ? parsed.chapters : [],
+    };
+};
+export const secondsToMs = (value) => {
+    if (value === undefined)
+        return 0;
+    const seconds = typeof value === 'number' ? value : Number.parseFloat(value);
+    if (!Number.isFinite(seconds))
+        return 0;
+    return Math.round(seconds * 1000);
+};
+export const mapStreams = (streams) => streams.map((stream) => ({
+    index: stream.index,
+    codec_type: stream.codec_type,
+    ...(stream.codec_name ? { codec_name: stream.codec_name } : {}),
+    ...(stream.tags?.language ? { language: stream.tags.language } : {}),
+    ...(stream.channels !== undefined ? { channels: stream.channels } : {}),
+    ...(stream.sample_rate ? { sample_rate: Number.parseInt(stream.sample_rate, 10) } : {}),
+    ...(stream.width !== undefined ? { width: stream.width } : {}),
+    ...(stream.height !== undefined ? { height: stream.height } : {}),
+    ...(stream.avg_frame_rate ? { avg_frame_rate: stream.avg_frame_rate } : {}),
+    ...(stream.r_frame_rate ? { r_frame_rate: stream.r_frame_rate } : {}),
+    ...(stream.bit_rate ? { bit_rate: Number.parseInt(stream.bit_rate, 10) } : {}),
+    ...(stream.disposition ? { disposition: stream.disposition } : {}),
+    ...(stream.tags ? { tags: stream.tags } : {}),
+}));
+export const mapChapters = (chapters) => (chapters ?? []).map((chapter) => ({
+    id: chapter.id,
+    start_ms: secondsToMs(chapter.start),
+    end_ms: secondsToMs(chapter.end),
+    ...(chapter.tags?.title ? { title: chapter.tags.title } : {}),
+}));
+export const collectProbeWarnings = (probe, includeStreams) => {
+    const warnings = [];
+    const videoStreams = probe.streams.filter((s) => s.codec_type === 'video');
+    const audioStreams = probe.streams.filter((s) => s.codec_type === 'audio');
+    if (includeStreams && videoStreams.length === 0) {
+        warnings.push('No video stream detected.');
+    }
+    if (includeStreams && audioStreams.length === 0) {
+        warnings.push('No audio stream detected.');
+    }
+    for (const stream of videoStreams) {
+        if (stream.avg_frame_rate &&
+            stream.r_frame_rate &&
+            stream.avg_frame_rate !== stream.r_frame_rate) {
+            warnings.push(`Stream ${stream.index}: variable frame rate suspected (avg_frame_rate=${stream.avg_frame_rate}, r_frame_rate=${stream.r_frame_rate}).`);
+        }
+    }
+    const duration = probe.format.duration;
+    if (!duration || Number.parseFloat(duration) <= 0) {
+        warnings.push('Duration unavailable or zero; timeline bounds may be incomplete.');
+    }
+    return warnings;
+};
+export const runFfprobe = async (videoPath) => {
+    const available = await isBinaryAvailable('ffprobe');
+    if (!available) {
+        throw new Error('ffprobe is not installed or not on PATH');
+    }
+    const { stdout } = await execBinary('ffprobe', [
+        '-v',
+        'quiet',
+        '-print_format',
+        'json',
+        '-show_format',
+        '-show_streams',
+        '-show_chapters',
+        videoPath,
+    ], { timeoutMs: 60_000 });
+    return parseFfprobeJson(stdout);
+};
+export const findSubtitleStreams = (streams) => streams.filter((stream) => stream.codec_type === 'subtitle');

package/dist/utils/pathUtils.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ErrorCode, VideoError } from './errors.js';
+export const PROJECT_ROOT = process.cwd();
+const canonicalize = (p) => {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch (err) {
+        if (typeof err === 'object' &&
+            err !== null &&
+            'code' in err &&
+            (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+            const parent = path.dirname(p);
+            if (parent === p)
+                return p;
+            return path.join(canonicalize(parent), path.basename(p));
+        }
+        throw err;
+    }
+};
+export const resolvePath = (userPath) => {
+    if (typeof userPath !== 'string') {
+        throw new VideoError(ErrorCode.InvalidParams, 'Path must be a string.');
+    }
+    const normalizedUserPath = path.normalize(userPath);
+    const resolved = path.isAbsolute(normalizedUserPath)
+        ? normalizedUserPath
+        : path.resolve(PROJECT_ROOT, normalizedUserPath);
+    return canonicalize(resolved);
+};

package/dist/utils/scenes.js

@@ -0,0 +1,49 @@
+import { execBinary, isBinaryAvailable } from './exec.js';
+const SCENE_PTS_TIME_RE = /pts_time:([0-9.]+)/g;
+export const parseSceneFilterOutput = (stderr, threshold) => {
+    const scenes = [];
+    let match;
+    while ((match = SCENE_PTS_TIME_RE.exec(stderr)) !== null) {
+        const seconds = Number.parseFloat(match[1]);
+        if (!Number.isFinite(seconds))
+            continue;
+        scenes.push({
+            index: scenes.length,
+            time_ms: Math.round(seconds * 1000),
+            provenance: {
+                method: 'ffmpeg_scene_filter',
+                threshold,
+            },
+        });
+    }
+    return scenes;
+};
+export const detectScenes = async (videoPath, threshold) => {
+    const available = await isBinaryAvailable('ffmpeg');
+    if (!available) {
+        return {
+            scenes: [],
+            warning: 'ffmpeg is not installed; scene detection skipped.',
+        };
+    }
+    try {
+        const { stderr } = await execBinary('ffmpeg', [
+            '-hide_banner',
+            '-i',
+            videoPath,
+            '-vf',
+            `select='gt(scene,${threshold})',showinfo`,
+            '-f',
+            'null',
+            '-',
+        ], { timeoutMs: 300_000 });
+        return { scenes: parseSceneFilterOutput(stderr, threshold) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            scenes: [],
+            warning: `Scene detection failed: ${message}`,
+        };
+    }
+};

package/dist/utils/subtitles.js

@@ -0,0 +1,85 @@
+const parseTimestampToMs = (timestamp) => {
+    const normalized = timestamp.trim().replace(',', '.');
+    const parts = normalized.split(':');
+    if (parts.length !== 3)
+        return 0;
+    const [hours, minutes, secondsPart] = parts;
+    const [seconds, millis = '0'] = secondsPart.split('.');
+    const h = Number.parseInt(hours, 10);
+    const m = Number.parseInt(minutes, 10);
+    const s = Number.parseInt(seconds, 10);
+    const ms = Number.parseInt(millis.padEnd(3, '0').slice(0, 3), 10);
+    return ((h * 60 + m) * 60 + s) * 1000 + ms;
+};
+const stripTags = (text) => text
+    .replace(/<[^>]+>/g, '')
+    .replace(/\{[^}]+\}/g, '')
+    .trim();
+export const parseSrt = (content) => {
+    const blocks = content
+        .replace(/\r\n/g, '\n')
+        .split(/\n{2,}/)
+        .map((block) => block.trim())
+        .filter(Boolean);
+    const cues = [];
+    for (const block of blocks) {
+        const lines = block.split('\n');
+        if (lines.length < 2)
+            continue;
+        const timingLine = lines.find((line) => line.includes('-->'));
+        if (!timingLine)
+            continue;
+        const [startRaw, endRaw] = timingLine.split('-->').map((part) => part.trim());
+        const textLines = lines.filter((line) => line !== lines[0] && !line.includes('-->'));
+        const text = stripTags(textLines.join('\n'));
+        if (!text)
+            continue;
+        cues.push({
+            index: cues.length,
+            start_ms: parseTimestampToMs(startRaw),
+            end_ms: parseTimestampToMs(endRaw),
+            text,
+            provenance: {
+                method: 'embedded_parse',
+                format: 'srt',
+            },
+        });
+    }
+    return cues;
+};
+export const parseVtt = (content) => {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const blocks = normalized
+        .split(/\n{2,}/)
+        .map((block) => block.trim())
+        .filter((block) => block && !block.startsWith('WEBVTT') && !block.startsWith('NOTE'));
+    const cues = [];
+    for (const block of blocks) {
+        const lines = block.split('\n');
+        const timingLine = lines.find((line) => line.includes('-->'));
+        if (!timingLine)
+            continue;
+        const timing = timingLine.split('-->')[0]?.trim() ?? '';
+        const endTiming = timingLine.split('-->')[1]?.trim().split(' ')[0] ?? '';
+        const textLines = lines.filter((line) => !line.includes('-->') && !/^\d+$/.test(line));
+        const text = stripTags(textLines.join('\n'));
+        if (!text)
+            continue;
+        cues.push({
+            index: cues.length,
+            start_ms: parseTimestampToMs(timing),
+            end_ms: parseTimestampToMs(endTiming),
+            text,
+            provenance: {
+                method: 'embedded_parse',
+                format: 'vtt',
+            },
+        });
+    }
+    return cues;
+};
+export const parseSubtitleContent = (content, format) => {
+    if (format === 'srt')
+        return parseSrt(content);
+    return parseVtt(content);
+};

package/dist/video/readCoordinator.js

@@ -0,0 +1,81 @@
+import { access } from 'node:fs/promises';
+import { tryAsrTranscript } from '../utils/asr.js';
+import { extractSubtitles } from '../utils/ffmpeg.js';
+import { collectProbeWarnings, findSubtitleStreams, mapChapters, mapStreams, runFfprobe, secondsToMs, } from '../utils/ffprobe.js';
+import { resolvePath } from '../utils/pathUtils.js';
+import { detectScenes } from '../utils/scenes.js';
+const DEFAULT_SCENE_THRESHOLD = 0.4;
+export const buildTimelineDocument = async (sourcePath, args, version) => {
+    const includeStreams = args.include_streams ?? true;
+    const includeChapters = args.include_chapters ?? true;
+    const includeSubtitles = args.include_subtitles ?? true;
+    const includeScenes = args.include_scenes ?? true;
+    const includeTranscript = args.include_transcript ?? false;
+    const sceneThreshold = args.scene_threshold ?? DEFAULT_SCENE_THRESHOLD;
+    const warnings = [];
+    const probe = await runFfprobe(sourcePath);
+    warnings.push(...collectProbeWarnings(probe, includeStreams));
+    const format = {
+        ...(probe.format.format_name ? { format_name: probe.format.format_name } : {}),
+        duration_ms: secondsToMs(probe.format.duration),
+        ...(probe.format.bit_rate ? { bit_rate: Number.parseInt(probe.format.bit_rate, 10) } : {}),
+        ...(probe.format.size ? { size_bytes: Number.parseInt(probe.format.size, 10) } : {}),
+        ...(probe.format.tags ? { tags: probe.format.tags } : {}),
+    };
+    let subtitles = [];
+    if (includeSubtitles) {
+        const subtitleStreams = findSubtitleStreams(probe.streams);
+        const extracted = await extractSubtitles(sourcePath, subtitleStreams);
+        subtitles = extracted.subtitles;
+        warnings.push(...extracted.warnings);
+    }
+    let scenes = [];
+    if (includeScenes) {
+        const detected = await detectScenes(sourcePath, sceneThreshold);
+        scenes = detected.scenes;
+        if (detected.warning)
+            warnings.push(detected.warning);
+    }
+    let transcript = [];
+    if (includeTranscript) {
+        const asr = await tryAsrTranscript(sourcePath, true);
+        transcript = asr.transcript;
+        if (asr.warning)
+            warnings.push(asr.warning);
+    }
+    return {
+        provenance: {
+            source: sourcePath,
+            tool: 'read_video',
+            version,
+            extracted_at: new Date().toISOString(),
+        },
+        format,
+        streams: includeStreams ? mapStreams(probe.streams) : [],
+        chapters: includeChapters ? mapChapters(probe.chapters) : [],
+        scenes,
+        subtitles,
+        transcript,
+        warnings,
+    };
+};
+export const processVideoSource = async (userPath, args, version) => {
+    try {
+        const sourcePath = resolvePath(userPath);
+        await access(sourcePath);
+        const data = await buildTimelineDocument(sourcePath, args, version);
+        return {
+            source: userPath,
+            success: true,
+            data,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            source: userPath,
+            success: false,
+            error: message,
+        };
+    }
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@sylphx/video-reader-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.SylphxAI/video-reader-mcp",
+  "description": "Evidence-first video reading for AI agents — ffprobe, subtitles, scenes, transcripts, and timelines without frame-by-frame LLM vision.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "bin": {
+    "video-reader-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SylphxAI/video-reader-mcp.git"
+  },
+  "homepage": "https://github.com/SylphxAI/video-reader-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "video",
+    "reader",
+    "evidence",
+    "ffprobe",
+    "ffmpeg",
+    "subtitles",
+    "sylphx"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "test": "bun test",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "sync:server-json": "bun scripts/sync-server-json.ts",
+    "version-packages": "changeset version && bun run sync:server-json",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist coverage",
+    "prepublishOnly": "bun run clean && bun run build",
+    "release": "bun run typecheck && bun run check && bun run build && bun test && changeset publish"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.2.19",
+    "@types/node": "^25.9.1",
+    "typescript": "^7.0.2"
+  },
+  "packageManager": "bun@1.3.12"
+}