Audio Transcriber

CLI または API | MCP | エージェント

バージョン: 2.1.0

ドキュメント — CLI、Python API、MCP サーバー、および A2A エージェントにわたるインストール、デプロイ、使用方法は、公式ドキュメント に記載されています。

Related MCP server: audio-transcription-mcp

概要

Audio Transcriber は、「.wav .mp4 .mp3 .flac ファイルをテキストに文字起こしするか、自分のオーディオを録音しましょう！」と直接連携するように設計された、本番環境対応のエージェント兼 Model Context Protocol (MCP) サーバーです。

主な機能

• 統合されたアクションルーティング型 MCP ツール: メソッドを最適化された切り替え可能なツールモジュールにグループ化することで、LLM コンテキストにおけるトークンオーバーヘッドを最小限に抑え、ツールの肥大化を排除します。

• エンタープライズグレードのセキュリティ: Eunomia ポリシー、OIDC トークン委任、詳細な実行コンテキスト追跡を包括的にサポートします。

• 統合グラフエージェント: Agent Control Protocol (ACP) と標準の Web インターフェース (AG-UI) をサポートする組み込みの Pydantic AI エージェント。

• ネイティブのテレメトリーとトレーシング: そのまま使用できる OpenTelemetry エクスポートと、ネイティブの Langfuse トレーシング。

CLI または API

このエージェントは、「.wav .mp4 .mp3 .flac ファイルをテキストに文字起こしするか、自分のオーディオを録音しましょう！」API をラップしています。プログラムから、または統合された実行エントリポイントを介して操作できます。

基盤となる API ラッパー、拡張スキーマバインディング、開発者向け SDK リファレンスの使用方法に関する詳細な手順は、docs/index.md に記載されています。

MCP

このサーバーは、動的なアクションルーティング型ツールを利用して、トークンオーバーヘッドを最適化し、IDE との互換性を最大化します。

利用可能な MCP ツール

以下の表は、稼働中のサーバーから自動生成されています。手動で編集しないでください。

凝縮版アクションルーティング型ツール (MCP_TOOL_MODE=condensed)

詳細版 1:1 API マッピング型ツール (MCP_TOOL_MODE=verbose または both)

アクションルーティング型ツール 4 個 · 詳細版 1:1 ツール 7 個。各ツールは、対応する <DOMAIN>TOOL トグルが false に設定されていない限り有効です。MCP_TOOL_MODE はサーフェスを選択します（**intent がデフォルト* — 6 つの動詞ツール、オンデマンドで読み込まれる細粒度セット · condensed アクションルーティング型 · verbose 1:1 · both）。自動生成 — 手動で編集しないでください。*

詳細なツールスキーマ、パラメータ形状、検証制約は、docs/usage.md に記載されています。

動的なツール選択と可視性

この MCP サーバーは、実行時の動的なツールセット選択と可視性フィルタリングをサポートしています。これにより、LLM のコンテキストウィンドウが肥大化するのを防ぐために、公開するツールのセットを制限できます。

ツールのフィルタリングは、複数の入力チャネルを介して構成できます。

• CLI 引数: 起動時に --tools または --toolsets（または、無効化に対応する --disabled-tools と --disabled-toolsets）を渡します。

• 環境変数: 標準の環境変数を定義します。

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP SSE リクエストヘッダー: トランスポート初期化時にカスタムヘッダーを渡します。

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• HTTP SSE リクエストクエリパラメータ: トランスポート接続 URL にクエリパラメータを直接追加します。

  • ?tools=tool1,tool2

  • ?tags=tag1

クエリ文字列またはパラメータが指定されると、LLM を使用しないナレッジグラフ解決レイヤー（DynamicToolOrchestrator を使用）が、クエリの意図を既知のツールタグ、名前、または説明と照合し、安全なフォールバックと 24 時間ごとの自動バックグラウンドキャッシュ更新を提供します。

MCP 設定例

コネクタ中心の [mcp] エクストラをインストールしてください。 例では、audio-transcriber[mcp] を使用して、agent-utilities[mcp] 経由で FastMCP / FastAPI を追加しています。必要な Agent Utilities コアには引き続き epistemic-graph[full] が含まれます。[agent-runtime] エクストラは、さらにモデルオーケストレーションを有効にします。

stdio トランスポート（ローカル IDE — Cursor、Claude Desktop、VS Code）

{
  "mcpServers": {
    "audio-transcriber-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "audio-transcriber[mcp]",
        "audio-transcriber-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "AUDIO_PROCESSINGTOOL": "True",
        "MEDIA_SIDECARTOOL": "True",
        "MISCTOOL": "True",
        "TRANSCRIBE_DIRECTORY": "/path/to/transcribe_directory",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

ランタイム参照には、GraphOS などのエイリアス対応ランチャーが必要です。その他のランチャーは、これらのエントリを省略し、解決された値を独自のランタイムシークレット境界を通じて注入する必要があります。

Streamable-HTTP トランスポート（ネットワーク / 本番環境）

{
  "mcpServers": {
    "audio-transcriber-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "audio-transcriber[mcp]",
        "audio-transcriber-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "AUDIO_PROCESSINGTOOL": "True",
        "MEDIA_SIDECARTOOL": "True",
        "MISCTOOL": "True",
        "TRANSCRIBE_DIRECTORY": "/path/to/transcribe_directory",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

あるいは、事前にデプロイされた Streamable-HTTP インスタンスに url で接続します。

{
  "mcpServers": {
    "audio-transcriber-mcp": {
      "url": "http://localhost:8000/audio-transcriber-mcp/mcp"
    }
  }
}

レビュー済みのコンテナイメージを、最小特権の stdio 子プロセスとして実行します（リスナーや公開ポートなし）。

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e AUDIO_PROCESSINGTOOL=True \
  -e MEDIA_SIDECARTOOL=True \
  -e MISCTOOL=True \
  -e TRANSCRIBE_DIRECTORY=/path/to/transcribe_directory \
  -e WHISPER_MODEL=base \
  registry.example.invalid/audio-transcriber@sha256:<digest> audio-transcriber-mcp

コンテナ化されたネットワーク HTTP の場合は、運用者所有のデプロイプロファイルを通じて、認証付き TLS イングレス（またはサーバー直接の TLS）、正確な MCP_ALLOWED_HOSTS、正確な信頼済みプロキシ CIDR ポリシーを指定します。ジェネレータは、認証なしの非ループバックリスナーを生成しません。

コード読み取りの環境サーフェス（MCP_TOOL_MODE + パッケージ変数）から自動生成 — 手動で編集しないでください。

追加のデプロイオプション

audio-transcriber は、ローカルの stdio プロセスまたはコンテナとして、あるいはリモートネットワーク境界の背後で実行できます。デプロイガイド に、詳細なトランスポート契約が記載されています。

• ローカルコンテナ — レビュー済みのイミュータブルイメージを、リスナーや公開ポートのない最小特権の stdio 子プロセスとして起動します。

• リモート URL — 運用者が提供する認証付き HTTPS イングレスを介して接続します。その URL、送信 ID 参照、信頼プロファイル、正確な MCP_ALLOWED_HOSTS を AgentConfig に保持します。

エージェント

このリポジトリには、完全に統合された Pydantic AI Graph Agent が搭載されています。これは、Agent Control Protocol (ACP) を介して通信し、Agent Web UI (AG-UI) およびターミナルインターフェースとシームレスに連携します。

エージェント CLI の実行

対話型コマンドラインエージェントを起動するには：

# Configure transcription (optional)
export WHISPER_MODEL="base"
export TRANSCRIBE_DIRECTORY="/path/to/transcribe_directory"

# Run the agent server
audio-transcriber-agent --provider openai --model-id gpt-4o

Docker Compose オーケストレーション

以下の docker/agent.compose.yml は、エージェント、Web UI、ターミナルインターフェースをまとめて構成します。

version: '3.8'

services:
  audio-transcriber-mcp:
    image: example/audio-transcriber:mcp
    container_name: audio-transcriber-mcp
    hostname: audio-transcriber-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  audio-transcriber-agent:
    image: example/audio-transcriber@sha256:<digest>
    container_name: audio-transcriber-agent
    hostname: audio-transcriber-agent
    restart: always
    depends_on:
      - audio-transcriber-mcp
    env_file:
      - ../.env
    command: [ "audio-transcriber-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9014
      - MCP_URL=http://audio-transcriber-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9014:9014"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9014/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

グラフノードアーキテクチャの詳細な説明、カスタムスキル構成、エージェントトレースガイドは、docs/deployment.md で確認できます。

セキュリティとガバナンス

エンタープライズ対応の agent-utilities コア上に直接構築されており、標準のセキュリティパラメータを完全にサポートしています。

アクセス制御とポリシー適用

• Eunomia ポリシー: きめ細かいポリシー駆動型のツール認可。none、ローカルの embedded（mcp_policies.json）、または集中管理型の remote モードをサポートします。

• OIDC トークン委任: Web UI / ACP → エージェント → MCP の順に認証ユーザー資格情報を流すための RFC 8693 トークン交換に準拠しています。

• スコープ付き資格情報: 実行コンテキストは、特定の呼び出し元 ID に制限されます。

ランタイムセキュリティグリッド

環境変数

パッケージ環境変数

継承された agent-utilities 変数（すべてのコネクタに適用）

16個のパッケージ変数 + 16個の継承変数。.env.example と共有 agent-utilities セットから自動生成 — 編集しないでください。

サーバーが読み取るすべての変数を目的別にグループ化したものです。

文字起こし

MCPサーバー / トランスポート

ツールのトグル

各アクションルーティングツールは、対応するトグル環境変数（false に設定）で個別に無効化できます。 正式な名称については、上記の利用可能なMCPツールテーブルを参照してください。

テレメトリーとガバナンス

エージェントCLI（フル [agent] ランタイムのみ）

コピー＆ペーストで使える出発点として .env.example を参照してください。

インストール

実行したい内容に合ったエクストラを選択してください:

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "audio-transcriber[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "audio-transcriber[agent]"

# Everything (development)
uv pip install "audio-transcriber[all]"      # or: python -m pip install "audio-transcriber[all]"

コンテナイメージ（:mcp と :agent）

1つのマルチステージ docker/Dockerfile が、--target で選択される2つの適切なサイズのイメージをビルドします:

docker build --target mcp   -t example/audio-transcriber:mcp    docker/   # connector-focused MCP server
docker build --target agent -t example/audio-transcriber:agent-local docker/   # agent runtime

docker/mcp.compose.yml はコネクタ特化型の :mcp サーバーを実行し、docker/agent.compose.yml は同一配置の :mcp サイドカーを伴うエージェント（immutable agent digest）を実行します。

ナレッジグラフデータベース（epistemic-graph）

[mcp] と [agent] はどちらも、必須の Agent Utilities コア依存関係（epistemic-graph[full]）を通じて epistemic-graph エンジンを保持します。[mcp] エクストラはサーバーをコネクタ特化型に保ち、[agent] は追加でモデルオーケストレーションを有効にします。ローカルデプロイではバンドルされたエンジンを使用できます。本番環境または共有状態の場合は、epistemic-graph を専用のデータベースサービスとして実行し、ランタイムがそれを使用するように設定してください。デプロイレシピ（単一ノード + Raft HA）、接続設定、アーキテクチャ図は、epistemic-graph デプロイガイド に記載されています。

リポジトリオーナー

ドキュメント

完全なドキュメントは公式ドキュメントサイトとして公開されており、インストール、デプロイ、日常運用の推奨リファレンスです。

コントリビュート

コントリビューションを歓迎します！プルリクエストを送信する前に、ローカルチェックを実行してコード品質を確保してください：

• ruff format . を使用してコードをフォーマットする

• ruff check . を使用してコードをリントする

• mypy . を使用して型安全性を検証する

• pytest を使用してテストスイートを実行する

agent-utilities-deployment でデプロイ

このパッケージは、統合された agent-utilities-deployment ワークフローでプロビジョニングします。このワークフローは、インストール済みパッケージ、編集可能ソース、イミュータブルコンテナのいずれかのパスを選択し、AgentConfig にはランタイムのシークレットと TLS プロファイルの参照のみを記録し、doctor、登録、ポリシー、可観測性、ロールバックの各ゲートを実行します。エージェントに 「agent-utilities-deployment で audio-transcriber をデプロイ」 と依頼してください。

リポジトリには、デプロイプロファイル、認証情報の値、証明書パス、環境固有のエンドポイントは埋め込まれていません。これらは実行時に AgentConfig と設定済みのシークレットプロバイダーを通じて提供してください。

ガバナンス対象の機能契約

このパッケージは、専門的な手順を参照ワークフローとして保持した、コンパクトな標準スキルサーフェスを提供します。現在の MCP ツール、スキルメタデータ、connector_manifest.yml、オントロジー、マッピング、シェイプ、フィクスチャ、マイグレーション、ツールスキーマフィンガープリント、認定メタデータは、単一のバージョン管理された機能契約を構成します。これらはまとめて検証してください。古いツール名や過去のタスク別スキルラッパーに依存しないでください。

ランタイムエンドポイント、認証情報、証明書トラスト、テナント ID、保持ポリシー、可観測性ポリシーはデプロイ時の入力であり、パッケージ化された値ではありません。ネットワークトランスポート、コネクタ取り込み、GraphOS 委任、トレースエクスポートを有効にする前に、設定、信頼、プライバシー を参照してください。