ocular-audio-mcp

OcularAudio MCP

面向 AI Agent 的通用本地优先媒体智能工具。

OcularAudio 让兼容 MCP 的 AI 系统能够观看、聆听、搜索、检查、比较和分析媒体。它将 URL、流媒体和本地媒体转化为可重复使用的带时间戳证据：元数据、转录文本、帧、OCR 结果、检索结果、多模态片段和跨视频智能分析结果。

v1.3.0 · MIT

产品

功能

• **通用媒体接入：**网页 URL、直接媒体、本地文件、直播／流媒体来源，以及广泛的社交、视频、音频和归档平台。
• **语音理解：**提供带时间戳的字幕；字幕不可用时，可回退到本地 Whisper。
• **视觉理解：**智能截图、精确帧、连续帧、裁剪、视觉索引和感知相似度分析。
• **屏幕文字：**可选的 Tesseract OCR 会生成可搜索的视觉文本证据。
• **证据搜索：**基于稳定且保留溯源信息的规范证据记录，执行感知时间戳的词法、语义和混合检索。
• **多模态分析：**对齐同一片段周围的转录文本、视觉和 OCR 证据。
• **批量智能分析：**处理多个来源、跨来源搜索，并在故障隔离的情况下生成跨视频比较结果。
• **Agent 式执行：**将分析请求转化为有界计划，并提供重试、超时、审计记录和健康状态报告。
• **能力模式：**Lite、Intelligence、Deep 和 Auto 模式可控制处理深度和响应丰富度。
• **本地缓存：**重复使用已处理的证据，并通过 CLI 或 MCP 管理缓存状态。
• **运行状态感知：**能力、健康状态、就绪状态、安全状态、指标和完整协议契约均可由机器读取。
• **MCP 互操作性：**通过 stdio 或 Streamable HTTP 提供工具、资源和提示词。
• **生产部署：**支持 Bearer Token 保护、主机／来源控制、Docker 部署、持久化缓存和就绪检查。

最适用场景

研究和讲座分析 · 产品演示 · 竞品分析 · 访谈 · 技术演讲 · UI 演示 · 多视频比较 · 基于证据的 AI 调查。

能力矩阵

能力	用户收益
通用来源	通过一个界面分析 URL、文件和流媒体
转录证据	精确查找某段内容的出现时间
视觉证据	检查指定时间戳显示的内容
OCR	搜索视频帧中可见的文字
混合检索	结合语音和视觉证据
多模态片段	同时理解语音和视觉内容
批量分析	调查一组视频
跨视频比较	比较不同来源中的证据
Agent 工作流	执行有界的证据调查
能力模式	自动选择或强制采用 Lite、Intelligence 和 Deep 执行预算
缓存	加快重复分析
MCP 提示词	启动常见调查工作流
MCP 资源	为宿主提供运行环境信息
HTTP 部署	作为受保护的网络服务运行

规范证据架构

所有来源素材都会统一规范化，并写入每个来源对应的本地清单。证据记录包含基于内容生成的稳定 ID、模态标签、时间戳范围、内容哈希、溯源指针和元数据。转录搜索、时间线、片段检查和混合检索共用相同的规范 ID；OCR 和视觉帧记录也会与转录证据一同编入索引。清单以原子方式写入，读取时进行验证，按 ID 去重，并从现有转录和视觉缓存中刷新，无需迁移或数据库。清除某个来源时，会同时移除其转录文本、规范清单、视觉索引和帧素材。清单元数据有意仅存储有限摘要，不包含来源 URL 或凭据。

四级智能引擎

每个请求都通过一个确定性策略引擎进行处理。Auto 会根据查询意图、请求的功能、来源数量、媒体时长以及可选的时间预算，解析为 Lite、Intelligence 或 Deep。决策会以机器可读元数据的形式返回，其中包含明确的限制、已禁用的功能、能力缺口和调整项。

模式	证据	视觉帧	默认采样间隔	运行时限	来源	行为
Lite	8	8	30 s	45 s	1	优先使用转录文本和元数据；禁用 OCR、多模态分析和批量处理
Intelligence	24	24	10 s	180 s	10	均衡地进行检索、视觉/OCR 和多模态分析
Deep	64	64	3 s	600 s	32	扩展证据并进行多步调查
Auto	由策略选择	由策略选择	由策略选择	由策略选择	由策略选择	解析为三种执行模式之一

各模式都会强制执行证据上限、帧数限制、来源数量限制、重试次数、并发数、采样间隔和运行时限。缺少 OpenCV、FFmpeg 或 Tesseract 时会报告能力缺口；无法使用的可选功能会被禁用，而不会被表示为已成功启用。超出明确来源数量限制时会返回清晰的错误，而不会悄悄丢弃来源。所有模式共用来源覆盖范围。

现有的 CLI --mode 标志现在会传递到 Python 运行时。使用 --budget-seconds 设置调用方指定的运行时限（0.001-900 秒）。MCP 规划、Agent 式执行、混合搜索、视觉索引、多模态分析和批量分析均采用相同的决策约定。使用 --mode deep 获取全面证据，或使用 --mode lite 快速了解概况。

快速入门

NPM / MCP

**发布状态：**此仓库包含源代码版本 1.3.0，但该版本尚未发布到 npm。最新的已发布软件包为 1.2.1，因此在另行批准并发布 1.3.0 之前，以下 npx 示例会安装 1.2.1。若要测试当前检出版本，请克隆仓库，从 requirements.txt 安装 Python 依赖项，然后在检出目录中运行 node bin/cli.js。

npx -y ocular-audio-mcp

本地 MCP 主机也可以启动同一命令。示例：

{
  "mcpServers": {
    "ocular-audio": {
      "command": "npx",
      "args": ["-y", "ocular-audio-mcp"]
    }
  }
}

Claude Code：

claude mcp add ocular-audio -- npx -y ocular-audio-mcp

Codex CLI：

codex mcp add ocular-audio -- npx -y ocular-audio-mcp

直接使用 CLI

npx ocular-audio "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
npx ocular-audio --check
npx ocular-audio --json "URL"
npx ocular-audio --visual-index --ocr "URL"
npx ocular-audio --multimodal-search "pricing" "URL"
npx ocular-audio --plan "Find the pricing discussion and inspect its visual evidence"
npx ocular-audio --agentic "Find every pricing discussion and inspect the relevant slides"

技术概览

MCP 主机 / Agent
        |
MCP 工具 + 提示词 + 资源
        |
通用来源解析器
        |
证据：元数据 + 转录文本 + 时间戳 + 章节
      /   |   \
视觉  OCR  检索
      \   |   /
   多模态时刻
         |
   批量智能分析
         |
   Agent 式执行
         |
   运维 / 审计 / 就绪状态

核心模块

• media_resolver.py + universal_sources.py：来源分类、平台系列、流、本地媒体和分析策略。
• evidence_index.py：带时间戳的证据分段、章节关联和确定性检索。
• evidence_store.py：规范化的转录文本／章节／元数据／视觉／OCR 记录、稳定的证据 ID、来源信息、完整性校验清单、原子持久化和生命周期清理。
• visual_index.py：帧采样、连拍、裁剪、感知哈希、描述符和 OCR 证据。
• semantic_index.py：本地 TF-IDF／词法／语义检索和混合检索。
• multimodal_index.py：转录文本／视觉／OCR 时间戳对齐与排序。
• batch_index.py：有界多来源执行、持久化、搜索和比较。
• agentic_index.py：确定性规划、重试、超时、审计记录和执行健康状态。
• capability_modes.py：Lite、Intelligence、Deep 和 Auto 策略解析。
• protocol_contract.py：机器可读的 MCP 互操作契约。
• deployment_security.py：受控 HTTP 身份验证和传输安全。
• runtime_ops.py：有界指标、延迟观测、就绪状态和审计保留。

MCP 接口

33 个工具

媒体／证据：get_ocular_audio_transcript、get_ocular_audio_video_context、search_ocular_audio_video、get_ocular_audio_video_timeline、inspect_ocular_audio_moment、query_ocular_audio_evidence、get_ocular_audio_metadata、get_ocular_audio_chapters、inspect_ocular_audio_source、get_ocular_audio_capabilities。

视觉／OCR：get_ocular_audio_video_screenshots、index_ocular_audio_video_visuals、search_ocular_audio_visuals、get_ocular_audio_video_frame、get_ocular_audio_video_frame_burst、crop_ocular_audio_video_frame。

检索／多模态：search_ocular_audio_hybrid、analyze_ocular_audio_multimodal、inspect_ocular_audio_multimodal_moment、search_ocular_audio_cache。

批处理：analyze_ocular_audio_batch、search_ocular_audio_videos、compare_ocular_audio_videos、get_ocular_audio_batch、list_ocular_audio_batches。

Agent／运维：plan_ocular_audio_analysis、run_ocular_audio_analysis、get_ocular_audio_health、get_ocular_audio_audit、get_ocular_audio_contract、get_ocular_audio_identity。

缓存：list_ocular_audio_cache、clear_ocular_audio_cache。

7 个资源

• ocularaudio://capabilities
• ocularaudio://modes
• ocularaudio://health
• ocularaudio://contract
• ocularaudio://security
• ocularaudio://readiness
• ocularaudio://metrics

4 个提示词

• inspect_video
• search_video_evidence
• review_visual_evidence
• compare_videos

部署

本地 stdio

stdio 是默认的本地 MCP 传输方式，无需 HTTP 身份验证。

Streamable HTTP

npx ocular-audio --transport streamable-http --host 127.0.0.1 --port 8000

MCP 端点为 /mcp。如需向网络开放，请配置身份验证、真实的颁发者／资源 URL、允许的主机和允许的源。请勿将未经过身份验证的实例暴露给不受信任的网络。

Docker

cp .env.example .env
docker compose -f docker/docker-compose.yml up --build -d

所提供的部署使用 Python 3.11、FFmpeg、持久化缓存卷、只读容器文件系统、已移除的能力、no-new-privileges、重启策略和健康检查。

面向互联网的部署应使用 TLS 和组织身份提供商。内置的静态 Bearer 验证器适用于受控部署，也可以替换为 JWT 验证或 RFC 7662 内省。

运行时要求

• 发布环境建议使用 Python 3.11+。
• NPM CLI 需要 Node.js 18+。
• 媒体处理需要 FFmpeg。
• 视觉处理需要 OpenCV。
• 本地转录回退需要 faster-whisper。
• Tesseract 可选，用于 OCR。
• 远程来源需要网络访问。

NPM 包不会隐藏原生 Python／系统前置条件；OcularAudio 是本地媒体处理服务，而非托管 API。

Cookie 和受限媒体

对于需要经过身份验证的浏览器会话的来源，可以使用运维人员提供的 cookies.txt。切勿提交 Cookie、访问令牌或凭据。

发布 v1.3.0

npm install
npm run check
npm pack

这会创建 ocular-audio-mcp-1.3.0.tgz。发布前请检查：

npm publish ocular-audio-mcp-1.3.0.tgz --access public

请参阅 RELEASE_v1.3.0.md。也可以通过手动触发 GitHub Actions 工作流来构建并上传确切的 tarball 作为构建产物。

验证

python -m unittest discover -s tests -v
node --check bin/cli.js
npm run check

CI 还会验证 MCP SDK 接口、工具／资源／提示词注册、Streamable HTTP 授权行为、编译、CLI 语法和包元数据。

设计原则

• 本地优先： 不强制使用云端推理 API。
• 证据优先： 保留时间戳和来源证据。
• 可组合： 每个分析层都基于前一层的证据构建。
• 有界： 明确限制步骤数、重试次数、并发数、指标基数和审计保留时长。
• 原生支持 MCP： 工具、资源和提示词都是协议原语。
• 基础设施具有确定性： OcularAudio 提供执行／证据原语，同时由宿主负责模型层推理。

许可证

MIT。请参阅 LICENSE。