内容
<p align="center">
<img src="https://raw.githubusercontent.com/vishalguptax/media-context-mcp/main/assets/banner.svg" alt="media-context-mcp — 本地媒体分析工具" width="100%">
</p>
<p align="center">
<a href="https://www.npmjs.com/package/media-context-mcp"><img src="https://img.shields.io/npm/v/media-context-mcp.svg?color=2ea043&label=npm" alt="npm 版本"></a>
<a href="https://www.npmjs.com/package/media-context-mcp"><img src="https://img.shields.io/npm/dm/media-context-mcp.svg?color=2ea043&label=downloads" alt="npm 下载量"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="许可证"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/media-context-mcp.svg?color=blue" alt="Node.js 版本"></a>
</p>
<p align="center">
<b>给你的 AI 助手眼睛和耳朵。</b><br>
分析任意视频、音频或图像 — 在本地，在编辑器中。
</p>
<p align="center">
<a href="#-install"><b>安装</b></a> ·
<a href="#-capabilities">功能</a> ·
<a href="#-modes">模式</a> ·
<a href="#-examples">示例</a> ·
<a href="#-tools">工具</a> ·
<a href="#-options">选项</a> ·
<a href="./docs/usage.md">文档</a>
</p>
<br>
大型语言模型可以读取文本并浏览单个图像，但它们无法观看视频或聆听音频。**media-context-mcp** 弥补了这一空白。它可以处理文件或链接，并在本地返回干净的、模型可读的上下文 — 关键帧、转录或屏幕文本。无需上传任何内容。
<p align="center">
<img src="https://raw.githubusercontent.com/vishalguptax/media-context-mcp/main/assets/example.webp" alt="10 秒视频转换为一页关键帧" width="88%">
</p>
<p align="center"><sub>10 秒视频转换为一页关键帧，模型可按顺序读取。</sub></p>
<br>
## 🚀 安装
两步完成 — 添加服务器，然后安装它使用的本地助手。
### 1 · 将服务器添加到客户端
```bash
# Claude Code
claude mcp add media-context -- npx -y media-context-mcp
```
启动命令始终为 `npx -y media-context-mcp`。请选择您的客户端：
<details>
<summary><b>Claude Desktop</b></summary>
设置 → 开发者 → 编辑配置 (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（按项目）：
```json
{
"mcpServers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>VS Code</b>（GitHub Copilot，代理模式）</summary>
`.vscode/mcp.json` — VS Code 使用 `servers` 键：
```json
{
"servers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
`~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>Cline / Roo Code</b></summary>
`cline_mcp_settings.json`（扩展的 MCP 设置）：
```json
{
"mcpServers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>Kiro</b></summary>
`.kiro/settings/mcp.json`（项目）或 `~/.kiro/settings/mcp.json`（用户）：
```json
{
"mcpServers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>Gemini CLI</b></summary>
`~/.gemini/settings.json`:
```json
{
"mcpServers": {
"media-context": { "command": "npx", "args": ["-y", "media-context-mcp"] }
}
}
```
</details>
<details>
<summary><b>Zed</b></summary>
`settings.json` — Zed 使用 `context_servers`:
```json
{
"context_servers": {
"media-context": { "command": { "path": "npx", "args": ["-y", "media-context-mcp"] } }
}
}
```
</details>
<details>
<summary><b>Codex CLI</b></summary>
`~/.codex/config.toml`:
```toml
[mcp_servers.media-context]
command = "npx"
args = ["-y", "media-context-mcp"]
```
</details>
<details>
<summary><b>JetBrains AI Assistant</b></summary>
设置 → 工具 → AI Assistant → 模型上下文协议 → 添加，然后使用命令 `npx` 和参数 `-y media-context-mcp`。
</details>
> **提示：** 在 Claude Code 中，您可以将其安装为插件 — 运行 `/plugin marketplace add vishalguptax/media-context-mcp`，然后 `/plugin install media-context`。要与团队共享，请按项目安装：`--scope project`（写入 `.mcp.json`）或在仓库中提交 `.cursor/mcp.json`。
### 2 · 安装本地助手
一条命令通过您的操作系统包管理器设置服务器使用的一切：
```bash
npx media-context-mcp setup # 核心：关键帧、链接、屏幕文本
npx media-context-mcp setup --audio # 还启用转录
```
服务器随后会自动找到助手 — 无需额外配置。运行 `check_media_deps` 查看已准备就绪的内容，并运行 `setup --uninstall` 删除它们。（[手动安装 →](./docs/installation.md#local-helpers)）
### 3 · 提问
> *“总结 `demo.mp4`。”*
## ✨ 功能
| | |
|--|--|
| **视频** | 关键帧概览、完整尺寸静帧、场景检测或密集的帧条带，可捕捉亚秒级故障 |
| **音频** | 语音转换为文本 — 剪辑、语音笔记、会议、播客 |
| **图像** | 图片，以及屏幕上显示的确切文本 |
| **任何地方** | 本地文件或链接 — YouTube、Vimeo 和 1000+ 个网站 |
| **私有** | 在您的机器上运行。无需 API 密钥，无需上传 |
| **高效** | 长视频转换为几张图片，而不是数百张 |
## 🎞️ 模式
`analyze_media` 自动检测音频和图像。对于视频，请选择如何采样帧：
| 模式 | 最适合 |
|------|----------|
| `sheet` *(默认)* | 廉价概览 — 帧拼贴成一或两张联系表 |
| `frames` | 特定时刻的详细信息 — 单个完整尺寸静帧 |
| `scenes` | 幻灯片和静态屏幕录制 — 仅场景变化帧 |
| `filmstrip` | 捕捉亚秒级 UI 故障 — 密集的、接近原生速率的条带 |
## 💬 示例
只需用自然语言提问 — 助手会选择合适的选项。
| 您提问 | 您得到的结果 |
|---------|--------------|
| *“总结 `demo.mp4`。”* | 关键帧的快速概览 |
| *“`bug.mp4` 显示什么错误？”* | 屏幕上的确切文本，读回 |
| *“遍历 `onboarding.mov` 中的 UI 流程。”* | 场景变化帧的逐步指南 |
| *“转录 `standup.m4a` 并列出行动项。”* | 本地转录 |
| *“总结 `https://youtu.be/…` 并附上转录。”* | 获取并转录 |
| *“读取此截图 `crash.png` 中的错误。”* | 图片及其确切文本 |
| *“在 `ui.mp4` 中找到滑块在 ~0:06 处闪烁的位置。”* | 亚秒级故障的确切帧 |
## 🧰 工具
| 工具 | 它做什么 |
|------|--------------|
| **`analyze_media`** | 将视频、音频或图像（文件或 URL）转换为模型可读的上下文。自动检测类型并支持裁剪、时间窗口、语言和采样率。 |
| **`check_media_deps`** | 报告此机器上已准备就绪的功能。 |
每次调用都在本地运行并自行清理。
## ⚙️ 选项
您的助手为您填写这些内容，但您可以指导它（“使用 filmstrip 模式”，“裁剪到工具栏”）。
<details>
<summary><b>完整的 <code>analyze_media</code> 参数</b></summary>
| 参数 | 默认值 | 描述 |
|-------|---------|-------------|
| `source` | — | 本地文件路径（视频/音频/图像）或 http(s) URL |
| `context` | — | 分析的框架；显示在摘要顶部 |
| `detail` | — | `high` = 屏幕录制的可读静帧；`low` = 廉价概览 |
| `mode` | `sheet` | `sheet` · `frames` · `scenes` · `filmstrip` |
| `format` | `webp` | `webp`（最小）· `jpeg` · `png`（清晰文本） |
| `maxFrames` | `30` | 采样帧数的上限 |
| `grid` | `5` | 联系表模式的每行/列的图块数 |
| `scale` | `320` | 每帧的像素宽度 — 越低 = 越少标记 |
| `sceneThreshold` | `0.4` | 场景变化敏感度（`scenes` 模式） |
| `fps` | 自动 | 显式采样率；与 `filmstrip` 配对使用高值 |
| `crop` | — | `{x,y,width,height}`（像素或 `0–1` 分数）缩放区域 |
| `stripRows` | `18` | `filmstrip` 模式下的每张图像的行数 |
| `startSec` / `endSec` | — | 限制在时间窗口内 |
| `transcript` | `false` | 还生成转录（视频） |
| `whisperModel` | `small` | `tiny` · `base` · `small` · `medium` · `large` |
| `ocr` | `false` | 提取屏幕文本 |
| `ocrLang` | `eng` | 语言代码（例如 `eng+deu`） |
| `ocrPsm` | `3` | 页面分割：`3` 自动 · `6` 块 · `11` 稀疏 |
| `detectJumps` | `false` | 跟踪屏幕上的数字并报告带有时间戳的跳回故障 |
| `maxDurationSec` | `3600` | 拒绝超过此长度的 URL 下载 |
| `maxFileSizeMb` | `500` | 终止超过此大小的 URL 下载 |
每个的已编译配方都在 **[使用指南](./docs/usage.md)** 中。
</details>
## ❓ 常见问题
**LLM 可以观看视频吗？** 不直接 — 模型接受图像和文本，不接受视频。此服务器将视频转换为帧和转录，模型可以阅读。
**是否上传任何内容？** 不。所有操作都在您的机器上运行；无需密钥，无需云服务。
**哪些客户端有效？** 任意 MCP 客户端 — Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Cline、Kiro、Gemini CLI、JetBrains、Zed、Codex。
**它是否处理 YouTube 和其他链接？** 是的。
**费用是多少？** 它是免费且开源的。
## 📋 要求
Node.js 18+，在 Windows、macOS 或 Linux 上。一次性 `npx media-context-mcp setup` 安装其他所有内容。
## 🛠️ 开发
```bash
npm install
npm run build
npm test
```
欢迎提出问题和拉取请求 — 请参阅 **[使用指南](./docs/usage.md)** 以了解架构。
## 📄 许可证
[Apache-2.0](./LICENSE) © Vishal Gupta
