ocular-audio-mcp

OcularAudio MCP

AI エージェント向けの、あらゆるメディアに対応したローカルファーストのインテリジェンスです。

OcularAudio を使うと、MCP 対応の AI システムでメディアの視聴、検索、確認、比較、推論ができます。URL、ストリーム、ローカルメディアを、メタデータ、トランスクリプト、フレーム、OCR、検索結果、マルチモーダルな場面、動画横断型のインテリジェンスなど、再利用可能なタイムスタンプ付きのエビデンスに変換します。

v1.3.0 · MIT

製品

できること

• あらゆるメディアの取り込み： Web URL、直接アクセス可能なメディア、ローカルファイル、ライブ／ストリームソース、幅広いソーシャル、動画、音声、アーカイブプラットフォームに対応します。
• 音声の理解： タイムスタンプ付きの字幕を取得し、字幕が利用できない場合はローカルの Whisper にフォールバックします。
• 視覚的な理解： インテリジェントなスクリーンショット、正確なフレーム、連続フレーム、切り抜き、視覚インデックス、知覚的類似性に対応します。
• 画面上のテキスト： オプションの Tesseract OCR により、検索可能な視覚テキストのエビデンスを生成します。
• エビデンス検索： 安定性と来歴の保持を備えた正規化エビデンスレコードを対象に、タイムスタンプを考慮した字句検索、セマンティック検索、ハイブリッド検索を行います。
• マルチモーダル分析： 同じ場面の周辺で、トランスクリプト、視覚、OCR のエビデンスを関連付けます。
• バッチ処理のインテリジェンス： 複数のソースを処理し、横断検索を行い、失敗を個別に分離しながら動画横断比較を生成します。
• エージェント型実行： 分析リクエストを、リトライ、タイムアウト、監査記録、ヘルスレポートを備えた制限付きプランに変換します。
• 機能モード： Lite、Intelligence、Deep、Auto により、処理の深さと応答の詳細度を制御します。
• ローカルキャッシュ： 処理済みのエビデンスを再利用し、CLI または MCP からキャッシュの状態を管理できます。
• 運用状況の把握： 機能、ヘルス、準備状況、セキュリティ状態、メトリクス、プロトコル仕様全体を機械可読形式で提供します。
• MCP 相互運用性： stdio または Streamable HTTP を介して、ツール、リソース、プロンプトを提供します。
• 本番環境へのデプロイ： ベアラートークン保護、ホスト／オリジン制御、Docker デプロイ、永続キャッシュ、準備状況チェックに対応します。

主な用途

研究と講義の分析 · 製品デモ · 競合分析 · インタビュー · 技術講演 · UI の操作説明 · 複数動画の比較 · エビデンスに基づく AI 調査

機能マトリクス

機能	ユーザーが得られること
あらゆるソースに対応	1 つのインターフェースから URL、ファイル、ストリームを分析できます
トランスクリプトのエビデンス	発言された正確な時刻を見つけられます
視覚的なエビデンス	タイムスタンプ時点で何が表示されていたかを確認できます
OCR	動画フレーム内に表示されたテキストを検索できます
ハイブリッド検索	音声と視覚のエビデンスを組み合わせられます
マルチモーダルな場面	音声と映像を合わせて理解できます
バッチ分析	動画のコレクションを調査できます
動画横断比較	複数のソースにわたってエビデンスを比較できます
エージェント型ワークフロー	制限付きのエビデンス調査を実行できます
機能モード	Lite、Intelligence、Deep の実行予算を自動選択、または適用できます
キャッシュ	繰り返し行う分析を高速化できます
MCP プロンプト	よく使う調査ワークフローを開始できます
MCP リソース	ホストに運用コンテキストを提供できます
HTTP デプロイ	保護されたネットワークサービスとして実行できます

正規化エビデンスのアーキテクチャ

すべてのソースアーティファクトは、ソースごとに 1 つのローカルマニフェストへ正規化されます。エビデンスレコードには、コンテンツから導出された安定した ID、モダリティラベル、タイムスタンプの範囲、コンテンツハッシュ、来歴を示すポインター、メタデータが含まれます。トランスクリプト検索、タイムライン、場面の確認、ハイブリッド検索では同じ正規 ID を共有し、OCR と視覚フレームのレコードもトランスクリプトのエビデンスと並べてインデックス化されます。マニフェストはアトミックに書き込まれ、読み込み時に検証され、ID に基づいて重複が排除されます。また、移行やデータベースを必要とせず、既存のトランスクリプトキャッシュと視覚キャッシュから更新されます。ソースを消去すると、そのトランスクリプト、正規マニフェスト、視覚インデックス、フレームアーティファクトがまとめて削除されます。マニフェストのメタデータには、ソース URL や認証情報を含めず、意図的に上限を設けた要約のみを保存します。

4段階のインテリジェンスエンジン

すべてのリクエストは、単一の決定論的ポリシーエンジンによって処理されます。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	ポリシーにより選択	ポリシーにより選択	ポリシーにより選択	ポリシーにより選択	ポリシーにより選択	3つの実行モードのいずれかに解決されます

各モードでは、エビデンス数の上限、フレーム数の上限、ソース数の上限、再試行回数、同時実行数、サンプリング間隔、実行時間の上限が適用されます。OpenCV、FFmpeg、または Tesseract が見つからない場合は、機能の不足として報告されます。利用できないオプション機能は、成功したかのように扱わず無効化されます。明示されたソース数の上限に違反した場合、ソースを黙って削除するのではなく、明確なエラーで失敗します。ソースのカバレッジは、すべてのモードで共通です。

CLI の既存の --mode フラグが Python ランタイムに渡されるようになりました。呼び出し元が指定する実行時間の上限を設定するには、--budget-seconds を使用します（0.001-900 seconds）。MCP のプランニング、エージェント型実行、ハイブリッド検索、ビジュアルインデックス作成、マルチモーダル分析、バッチ分析では、同じ判断結果の仕様が公開されます。包括的なエビデンスを得るには --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 ホスト／エージェント
        |
MCP ツール + プロンプト + リソース
        |
ユニバーサルソースリゾルバー
        |
エビデンス：メタデータ + 文字起こし + タイムスタンプ + チャプター
      /   |   \
ビジュアル  OCR  検索
      \   |   /
   マルチモーダルな場面
         |
   バッチインテリジェンス
         |
   エージェント型実行
         |
   運用／監査／準備状況

コアモジュール

• 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。

エージェント型／運用：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です。ネットワークに公開する場合は、認証、実際のissuer／resource URL、許可するホスト、許可するオリジンを設定してください。信頼できないネットワークに、認証なしのインスタンスを公開しないでください。

Docker

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

付属のデプロイ設定では、Python 3.11、FFmpeg、永続キャッシュボリューム、読み取り専用のコンテナファイルシステム、権限の削除、no-new-privileges、再起動ポリシー、ヘルスチェックを使用します。

インターネットに公開するデプロイでは、TLSと組織のアイデンティティプロバイダーを使用してください。組み込みの静的ベアラートークン検証機能は、制御されたデプロイ向けです。JWT検証またはRFC 7662イントロスペクションに置き換えることもできます。

ランタイム要件

• リリース環境ではPython 3.11以降を推奨します。
• NPM CLIにはNode.js 18以降が必要です。
• メディア処理にはFFmpegが必要です。
• 映像処理にはOpenCVが必要です。
• ローカルの文字起こしフォールバックにはfaster-whisperが必要です。
• OCR用のTesseractは任意です。
• リモートソースにはネットワークアクセスが必要です。

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 を参照してください。