Video Reader MCP

MCP视频阅读器

MCP（模型上下文协议）服务器，使AI模型能够使用 渐进式语境丰富 原则。

🚀 快速入门：VS代码扩展

使用此MCP服务器的最简单方法是通过 VS代码扩展:

1. 安装扩展:

   cd extension
   npm install
   npm run package
   code --install-extension video-reader-mcp-1.0.0.vsix

1. 重新启动VS代码 -MCP服务器自动配置GitHub Copilot聊天！

1. 开始分析视频 在Copilot聊天中：

   Analyze this video: /path/to/video.mp4

📦 扩展功能:

• ✅ 为GitHub Copilot自动配置MCP服务器
• ✅ 无需手动配置
• ✅ 命令：配置、重新启动、状态、查看文档
• ✅ 适用于macOS、Windows和Linux

______________________________________________________________________

🎯 主要特点

• 渐进式语境丰富：启动灯，按需获取详细信息
• 🆕 场景检测：自动检测场景变化以进行智能帧提取
• 🆕 块分析：将视频分成片段，以便逐步理解
• 🆕 流分析：使用状态管理逐步模拟“观看”视频
• 🆕 音频转录支持：为转录服务准备音频
• 代币高效：优化输出，最大限度地减少上下文消耗
• 上下文提示：用可操作的建议指导人工智能行为
• 通用格式支持：适用于任何视频格式（mp4、avi、mov、mkv、webm等）
• 粒度工具：小型、集中的工具，而不是单一的操作

🧠 上下文工程原理

本MCP实施了以下最佳实践：

• 人工智能代理的有效上下文工程 -人类学
• LLMs的渐进式语境丰富 -可推断

看 内容_吉林大学博士 详细文档。

渐进式方法

Traditional Approach (Bad):
└─ analyze_video_full → Returns ALL frames → 100K+ tokens consumed

Progressive Approach (Good):
├─ get_video_overview → Light metadata + frame timestamps → ~200 tokens
├─ get_frame(t=30) → Specific frame → ~10K tokens  
├─ get_frame(t=90) → Another frame → ~10K tokens
└─ extract_audio → Audio path → ~50 tokens

✨ 100%自给自足

🎉 无需安装FFmpeg！

所有二进制文件都通过npm包包含在内：

• ✅ @ffmpeg-installer/ffmpeg
• ✅ @ffprobe-installer/ffprobe

工作在 任何操作系统 （macOS、Windows、Linux）无需手动安装！

🚀 安装

# Clone the repository
git clone 
cd mcp-video-reader

# Install dependencies
npm install

# Build
npm run build

# (Optional) Verify setup
node test-setup.js

⚙️ 配置

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json :

{
  "mcpServers": {
    "video-reader": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-video-reader/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

注： 这 OPENAI_API_KEY 是可选的，但却是必需的 transcribe_audio 功能。

🛠️ 工具参考

第1层：发现工具（先使用）

get_video_overview

\[推荐的第一步\] 无需提取帧数据即可获得轻量级概述。

// Returns: metadata summary, frame timestamps (no images), context hints
get_video_overview({
  videoPath: "/path/to/video.mp4",
  frameCount: 10  // Number of reference timestamps
})

get_video_metadata

仅提供快速技术规格。

// Returns: duration, resolution, fps, codec, format, has audio
get_video_metadata({ videoPath: "/path/to/video.mp4" })

estimate_analysis_cost

执行前计划-估算代币成本。

// Returns: token estimates, warnings if too large
estimate_analysis_cost({
  videoPath: "/path/to/video.mp4",
  frameCount: 10
})

第二层：渐进式提取工具

get_frame

\[主要工具\] 在特定时间戳提取单个帧。

// Returns: single frame image + metadata
get_frame({
  videoPath: "/path/to/video.mp4",
  timestamp: 30,        // seconds
  maxWidth: 1920,       // optional
  format: "jpeg",       // jpeg (smaller) or png
  quality: 80           // JPEG quality 1-100
})

get_frames_batch

提取多个特定帧（建议最多5个）。

// Returns: multiple frame images
get_frames_batch({
  videoPath: "/path/to/video.mp4",
  timestamps: [30, 90, 150],  // Array of timestamps
  maxWidth: 1920,
  format: "jpeg"
})

extract_audio

使用分段支持提取音轨。

// Returns: path to extracted audio file
extract_audio({
  videoPath: "/path/to/video.mp4",
  format: "mp3",        // mp3 or wav
  bitrate: "128k",      // 64k, 128k, 192k, 256k
  startTime: 0,         // optional segment start
  endTime: 60           // optional segment end
})

第3级：综合工具（谨慎使用）

analyze_video_full

⚠️ 高语境成本 -多帧全分析。

// Returns: metadata + all frames + audio path
// WARNING: Can produce 50K-150K+ tokens
analyze_video_full({
  videoPath: "/path/to/video.mp4",
  maxFrames: 8,         // Keep low!
  extractAudio: true,
  frameInterval: 10     // seconds between frames
})

🆕 第2.5层：智能分析工具

detect_scenes

在不提取帧的情况下检测场景变化。返回发生视觉变化的时间戳。

// Returns: scene list with timestamps and suggested keyframes
detect_scenes({
  videoPath: "/path/to/video.mp4",
  threshold: 0.3,       // 0.0-1.0 (lower = more scenes)
  maxScenes: 20,
  minSceneDuration: 1   // Minimum scene duration in seconds
})

get_scene_frames

在检测到的场景变化时提取帧-比均匀间隔的帧更智能。

// Returns: frames at scene change points
get_scene_frames({
  videoPath: "/path/to/video.mp4",
  threshold: 0.3,
  maxScenes: 10,
  maxWidth: 1920
})

get_video_chunks

将视频分成块进行渐进分析。

// Returns: chunk metadata without extracting content
get_video_chunks({
  videoPath: "/path/to/video.mp4",
  chunkDuration: 30     // seconds per chunk
})

analyze_chunk

使用关键帧+可选音频分析特定块。

// Returns: frame + audio path for specific segment
analyze_chunk({
  videoPath: "/path/to/video.mp4",
  chunkIndex: 0,        // 0-based index
  chunkDuration: 30,
  includeAudio: true
})

🆕 第2.6层：流分析（渐进式观察）

stream_start

开始流媒体分析-逐步模拟观看视频。

// Returns: first segment + state initialization
stream_start({
  videoPath: "/path/to/video.mp4",
  stepDuration: 30,     // seconds per step
  includeAudio: false,
  useSceneDetection: true,
  startPosition: 0
})

stream_next

继续播放-前进到下一个片段。

// Returns: next frame + position + accumulated context
stream_next({
  videoPath: "/path/to/video.mp4",
  stepDuration: 30,
  includeAudio: false
})

stream_status

在不前进的情况下检查流媒体进度。

// Returns: current state, observations, key events
stream_status({ videoPath: "/path/to/video.mp4" })

🆕 第2.7层：音频转录

transcribe_audio

使用带有定时片段的OpenAI Whisper API转录音频。

⚠️ 要求： OPENAI_API_KEY 环境变量

// Returns: full transcript + timed segments + subtitles
transcribe_audio({
  videoPath: "/path/to/video.mp4",
  subtitleFormat: "vtt",  // vtt, srt, or none
  startTime: 0,           // optional segment
  endTime: 60,
  language: "en"          // improves accuracy
})

⚙️ 配置

环境变量

例子：

export OPENAI_API_KEY="sk-..."

💡 使用示例

推荐：渐进分析

User: "Analyze this tutorial video: /path/video.mp4"

AI uses tools progressively:
1. get_video_overview → See it's 10 minutes, has audio, 10 frame timestamps
2. get_frame(0) → Check intro
3. get_frame(180) → Check middle section  
4. get_frame(540) → Check end
5. extract_audio → Get audio for transcription

Result: Comprehensive analysis with ~30K tokens instead of 150K+

🆕 智能场景检测

User: "What are the main scenes in this video?"

AI uses scene detection:
1. detect_scenes → Find 8 scene changes with timestamps
2. get_scene_frames → Extract frames at scene boundaries

Result: Captures actual content changes, not arbitrary intervals

🆕 流媒体分析（长视频）

User: "Watch through this 1-hour presentation"

AI uses streaming:
1. stream_start → Initialize and see first 30 seconds
2. stream_next → Advance to 0:30-1:00
3. stream_next → Continue to 1:00-1:30
... continues until video ends

Result: Progressive understanding with maintained context state

🆕 基于块的分析

User: "Analyze this video section by section"

AI uses chunks:
1. get_video_chunks → See video has 10 chunks of 30s each
2. analyze_chunk(0) → Analyze first chunk with audio
3. analyze_chunk(1) → Continue with second chunk
...

Result: Systematic coverage with audio support

快速元数据检查

User: "How long is this video?"

AI: get_video_metadata → Returns duration, resolution, etc. (~100 tokens)

规划大型分析

AI: estimate_analysis_cost(frameCount=20)
← "Estimated 120K tokens. Consider progressive fetching."

AI: get_video_overview → Reviews timestamps
AI: get_frames_batch([key_timestamps]) → Only important moments

📊 代币成本参考

🏗️ 建筑

mcp-video-reader/
├── src/
│   ├── index.ts              # MCP server with tiered tools
│   ├── video-processor.ts    # Processing with progressive support
│   └── types.ts              # Context-aware types
├── CONTEXT_ENGINEERING.md    # Principles documentation
├── build/                    # Compiled code
├── package.json
└── tsconfig.json

🔧 发展

# Build in watch mode
npm run watch

# Test locally
npm run build && node build/index.js

📝 支持格式

所有支持FFmpeg的格式，包括：

• 视频：mp4、avi、mov、mkv、webm、flv、wmv、m4v、mpg、3gp
• 容器：ts、mts、m2ts、vob、ogv

⚠️ 重要说明

1. 默认情况下，帧为JPEG -小于PNG，适合大多数分析
2. 最大1920px宽度 -较大的图像会自动调整大小
3. 临时文件 -音频/帧存储在 /tmp/mcp-video-reader/
4. 批量限制 - get_frames_batch 上下文管理限制为5帧

📄 许可证

麻省理工学院

📚 延伸阅读

• 内容_吉林大学博士 -详细原则
• 人类学：有效的情境工程
• 可推断：渐进式语境丰富