FunASR-Powered MCP Server (MCPServer)

FunASR を活用した MCP サーバー（MCPServer）

概要

MCPServer は、Alibaba の FunASR ライブラリを活用し、FastMCP フレームワークを通じて音声処理サービスを提供する Python ベースのサーバーです。次のツールを利用できます。

• 音声の検証： 音声ファイルが有効で読み取り可能かを確認し、そのプロパティを提示します。
• 音声の文字起こし： Paraformer などの高度な ASR モデルを使用して、音声ファイルの音声を非同期で文字起こしします。文字起こしタスクの管理や、詳細なタイムスタンプ情報を含む結果の取得にも対応しています。
• 音声区間検出（VAD）： 音声ファイル内の音声区間を特定します。

このサーバーは拡張性を考慮して設計されており、ASR モデルと VAD モデルを動的に読み込んで切り替えることができます。

機能

• 音声ファイルの検証： 音声ファイルの整合性、読み取り可能性、フォーマットを確認します。
• 非同期の音声テキスト変換： 長い音声ファイルに適した、ノンブロッキングの文字起こしを行います。
• 文字起こしタスクの管理： タスクの開始、ステータスの確認、結果の取得ができます。
• 詳細な文字起こし結果： 文字起こし全文、セグメントごとの開始・終了時刻、単語ごとのタイムスタンプ（ASR モデルが提供する場合）を取得できます。
• 音声区間検出（VAD）： 音声ファイル内の音声区間の開始・終了時刻を正確に返します。
• マルチモデル対応： ASR と VAD の両方で、FunASR の多様なモデル群を活用します。
• 動的なモデル設定：
  • 文字起こしまたは VAD のリクエストごとにモデルを指定できます。
  • サーバーインスタンスで使用するデフォルトの ASR モデルと VAD モデルを明示的に読み込んで切り替えられます。
• 設定可能なモデルパラメーター： FunASR モデルに固有の読み込み引数と生成引数を渡せます。

前提条件

• Python： 3.8+
• Pip： Python パッケージのインストールに使用します。
• MODELSCOPE_API_TOKEN（任意）：
  • FunASR は ModelScope からモデルをダウンロードします。レート制限に遭遇した場合や、非公開モデルへのアクセスが必要な場合は、MODELSCOPE_API_TOKEN 環境変数の設定が必要になることがあります。
  • ModelScope のウェブサイトからトークンを取得できます。
  • 環境に設定します：export MODELSCOPE_API_TOKEN="YOUR_TOKEN_HERE"

セットアップとインストール

1. リポジトリをクローンする（該当する場合）： このサーバーが大規模なリポジトリの一部である場合は、そのリポジトリをクローンしてください。それ以外の場合は、MCPServer ディレクトリとその内容が揃っていることを確認してください。

2. 仮想環境を作成して有効化する（推奨）：

   python -m venv .venv
   source .venv/bin/activate  # Windows の場合：.venv\Scripts\activate
   

3. 依存関係をインストールする： MCPServer ディレクトリ（この README と server.py が含まれるディレクトリ）に移動します。 必要なパッケージをインストールします：

   pip install -r requirements.txt
   

   これにより、fastmcp、funasr とその依存関係がインストールされます。FunASR の直接の依存関係で別途指定されていない場合、PyTorch はデフォルトで CPU 版がインストールされます。特定の PyTorch が必要な場合（GPU 版など）は、上記のコマンドを実行する前に、PyTorch の公式ウェブサイトの手順に従って PyTorch を手動でインストールすることをおすすめします。

サーバーの起動

1. MCPServer ディレクトリに移動します。
2. サーバーアプリケーションを実行します：

   uvicorn main:app --host 0.0.0.0 --port 9000
   

3. サーバーが起動すると、通常は http://0.0.0.0:9000 で稼働していることを示すログが表示されます。初回起動時には、FunASR がデフォルトの ASR モデルと VAD モデルをダウンロードするため、時間がかかることがあります。

利用可能な MCP ツール

MCPServer: http://0.0.0.0:9000/sse

mcp_client などの MCP クライアントや HTTP リクエストを使用して、これらのツールを利用できます。サーバーでは次のツールを提供しています。

---

1. validate_audio_file

• 説明： 音声ファイルが処理に適しているかを検証し、そのプロパティを返します。
• パラメーター：
  • file_path (str, 必須)：音声ファイルへのパス。
• 戻り値の例（成功）：

  {
    "status": "valid",
    "message": "Audio file is valid.",
    "details": {
      "samplerate": 16000,
      "channels": 1,
      "duration": 10.5,
      "formatted_duration": "00:10.500",
      "format": "WAV",
      "subtype": "PCM_16"
    }
  }
  

• 戻り値の例（エラー - ファイルが見つからない）：

  {
     "status": "invalid",
     "message": "Error: File not found at 'path/to/non_existent_audio.wav'.",
     "details": null
  }
  

---

2. start_speech_transcription

• 説明： 指定された音声ファイルの音声文字起こしタスクを非同期で開始します。ASR モデルと生成パラメーターを指定できます。
• パラメーター：
  • audio_path (str, 必須)：音声ファイルへのパス。
  • model_name (str, 任意)：このタスクで使用する特定の ASR モデル（例：ModelScope ID）。サーバーの現在のデフォルト ASR モデルを上書きします。指定されたモデルが互換性のある設定ですでに読み込まれていない場合、サーバーはそのモデルのデフォルトの読み込みパラメーター、またはインスタンスの全般的なデフォルト読み込みパラメーターを使用して、モデルの読み込みを試みます。
  • model_generate_kwargs (dict, 任意)：ASR モデルの generate メソッドに渡す特定の引数（例：{"batch_size_s": 60, "hotword": "特定热词"}）。サーバーで現在の ASR モデルに設定されているデフォルトの生成引数を上書きします。
• 戻り値の例（成功）：

  {
    "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "processing_started",
    "message": "Transcription task started and is now processing."
  }
  

• 戻り値の例（エラー - 無効な音声）：

  {
     "task_id": null,
     "status": "error",
     "message": "Error: File at '/path/to/your/bad_audio.wav' is not a valid audio file or is corrupted. Details: <error from soundfile>",
     "details": null
  }
  

• 戻り値の例（エラー - タスク中のモデル読み込み失敗）：

  {
     "task_id": null,
     "status": "error",
     "message": "Failed to switch to model 'non_existent_model_id'. Error: Error loading model 'non_existent_model_id': <actual error>"
  }
  

---

3. get_transcription_task_status

• 説明： 以前に開始した音声文字起こしタスクのステータスを照会します。
• パラメーター：
  • task_id（str、必須）：文字起こしタスクの一意の ID です。
• 戻り値の例（処理中）：

  {
     "status": "processing",
     "audio_path": "/path/to/your/audio.wav",
     "model_used": "iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch",
     "submitted_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00",
     "details_from_validation": { /* ... audio details from validate_audio ... */ },
     "model_generate_kwargs": {"batch_size_s": 300, "hotword": "魔搭"},
     "processing_started_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
  }
  

- **戻り値の例（完了）：**

 ```json
 {
    "status": "completed",
    "audio_path": "/path/to/your/audio.wav",
    "model_used": "iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch",
    "submitted_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00",
    "details_from_validation": { /* ... */ },
    "model_generate_kwargs": { /* ... */ },
    "processing_started_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00",
    "result": [ /* ... actual transcription result ... */ ],
    "completed_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
 }
 ```
- **戻り値の例（エラー - タスクが見つかりません）：**
  ```json
  {
      "status": "error",
      "message": "Task ID not found."
  }
  ```

---

4. get_transcription_result

• 説明： 完了した音声文字起こしタスクの結果を取得します。
• パラメーター：
  • task_id（str、必須）：文字起こしタスクの一意の ID です。
• 戻り値の例（成功／完了）：

  {
    "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "completed",
    "result": [
      {
        "text": "这是 一段 测试 文本",
        "start": 120,
        "end": 2850,
        "timestamp": [[120, 300], [330, 500], [550, 900], [920, 1200]]
      }
    ],
    "completed_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
  }
  

• 戻り値の例（タスク処理中）：

  {
     "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
     "status": "processing",
     "message": "Transcription not yet completed or has failed."
  }
  

• 戻り値の例（タスク失敗）：

  {
     "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
     "status": "failed",
     "message": "Transcription failed.",
     "error_details": "Description of the error during transcription.",
     "failed_at": "YYYY-MM-DDTHH:MM:SS.ffffff+00:00"
  }
  

---

5. load_asr_model

• 説明： 特定の ASR モデルを読み込むか再読み込みし、上書きされない限り以降のタスクでデフォルトとして使用します。操作のステータスを返します。
• パラメーター：
  • model_name（str、必須）：読み込む FunASR モデル識別子（例：ModelScope ID）です。
  • device（str、任意）：モデルを読み込むデバイス（例："cpu"、"cuda:0"）です。None の場合はインスタンスのデフォルトを使用します。
  • model_load_kwargs（dict、任意）：ASR モデルの読み込みに使用する引数（例：{"ncpu": 2, "vad_model": "other-vad-id", "punc_model": "other-punc-id"}）です。これらは funasr.AutoModel に渡されます。
• 戻り値の例（成功）：

  {
    "status": "success",
    "message": "Model 'iic/speech_paraformer-large-en-16k-common-vocab10020' loaded successfully on cpu with load_kwargs: {'ncpu': 2, 'vad_model': 'fsmn-vad'}."
  }
  

• 戻り値の例（エラー）：

  {
     "status": "error",
     "message": "Error loading model 'invalid-model-id': <FunASR or ModelScope error details>"
  }
  

---

6. get_voice_activity_segments

• 説明： Voice Activity Detection（VAD）モデルを使用して、音声ファイル内の発話セグメントを検出します。
• パラメーター：
  • audio_path（str、必須）：音声ファイルへのパス。
  • vad_model_name（str、任意）：使用する特定のVADモデル。サーバーの現在のデフォルトVADモデルを上書きします。
  • model_load_kwargs（dict、任意）：vad_model_nameが指定され、現在読み込まれているモデルと異なる場合に、VADモデルの読み込みに使用する特定の引数。
  • model_generate_kwargs（dict、任意）：VADモデルのgenerateメソッドに渡す特定の引数。
• 戻り値の例（成功時）：

  {
    "status": "success",
    "segments": [ [100, 2500], [3000, 5500] ],
    "audio_path": "path/to/your/audio.wav",
    "vad_model_used": "damo/speech_fsmn_vad_zh-cn-16k-common-pytorch",
    "generate_kwargs_used": {},
    "audio_details": { /* ... audio properties ... */ }
  }
  

- **戻り値の例（エラー ― VAD処理の失敗）：**

 ```json
 {
    "status": "error",
    "message": "VAD processing failed for 'path/to/audio.wav': <FunASR error details>",
    "audio_path": "path/to/audio.wav",
    "vad_model_used": "damo/speech_fsmn_vad_zh-cn-16k-common-pytorch"
 }
 ```

---

7. load_vad_model

• 説明： 特定のVADモデルを読み込むか再読み込みし、上書きされない限り、以降のVADタスクでデフォルトとして使用します。操作のステータスを返します。
• パラメーター：
  • model_name（str、必須）：読み込むFunASR VADモデルの識別子。
  • device（str、任意）：モデルの読み込み先デバイス。Noneの場合はインスタンスのデフォルトを使用します。
  • ncpu（int、任意）：デバイスがCPUの場合のCPUスレッド数。Noneの場合はインスタンスのデフォルトを使用します。
  • model_load_kwargs（dict、任意）：VADモデルの読み込みに使用する特定の引数。
• 戻り値の例（成功時）：

  {
    "status": "success",
    "message": "VAD Model 'damo/speech_fsmn_vad_zh-cn-16k-common-pytorch' loaded successfully on cpu with load_kwargs: {'ncpu': 2}."
  }
  

---

curlを使った使用例

curlを使用してstart_speech_transcriptionツールを呼び出す方法は次のとおりです。

# Ensure the audio_path is accessible by the server.
# For paths with spaces or special characters, ensure proper JSON escaping if needed.
curl -X POST http://localhost:8000/mcp/start_speech_transcription \
     -H "Content-Type: application/json" \
     -d '{"params": {"audio_path": "/path/to/your/audio_sample.wav"}}'

レスポンス：

{
  "jsonrpc": "2.0",
  "id": "some_client_generated_id",
  "result": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "processing_started",
    "message": "Transcription task started and is now processing."
  }
}

後で結果を取得するには、レスポンスに含まれるtask_idを使用します。

curl -X POST http://localhost:8000/mcp/get_transcription_result \
     -H "Content-Type: application/json" \
     -d '{"params": {"task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}}'

モデルの設定

• デフォルトモデル： サーバーは MCPServer/server.py で指定されたデフォルトの ASR モデルと VAD モデルで初期化されます。
  • デフォルトの ASR：iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch（VAD damo/speech_fsmn_vad_zh-cn-16k-common-pytorch および句読点モデル damo/punc_ct-transformer_zh-cn-common-vocab272727-pytorch が事前設定されています）。
  • デフォルトの VAD：damo/speech_fsmn_vad_zh-cn-16k-common-pytorch。
• リクエストごとのモデル指定：
  • start_speech_transcription では、model_name パラメーターを使用して、そのタスクに別の ASR モデルを指定します。
  • get_voice_activity_segments では、vad_model_name パラメーターを使用して、そのタスクに別の VAD モデルを指定します。
  • リクエストごとに指定されたモデルが現在読み込まれているモデルと異なる場合、サーバーはそのモデルの読み込みを試みます。この新しいモデルの読み込みに成功すると、以降のリクエストでモデルが指定されていない場合、そのプロセッサーの種類（ASR または VAD）の現在のデフォルトモデルになります。
• グローバルなモデル読み込み：
  • load_asr_model ツールを使用すると、SpeechTranscriber インスタンスのデフォルト ASR モデルを変更できます。
  • load_vad_model ツールを使用すると、VADProcessor インスタンスのデフォルト VAD モデルを変更できます。
  • これらのツールでは、モデルの読み込みを細かく制御するために、device、ncpu（VAD 用）、および model_load_kwargs も指定できます（たとえば、ASR の場合、model_load_kwargs に VAD モデル ID と句読点モデル ID を含められます）。
• モデルの引数：
  • model_load_kwargs は、モデルの読み込み方法を制御するために load_asr_model と load_vad_model に渡せます（たとえば、ASR パイプラインの VAD や句読点モデルなどのサブモデルの指定や、VAD モデルが読み込み時にサポートしている場合の max_single_segment_time など、モデル固有の読み込みパラメーターの指定に使用できます）。
  • model_generate_kwargs は、モデルの推論／生成ステップの動作を制御するために start_speech_transcription と get_voice_activity_segments に渡せます（ASR の batch_size_s や hotword などが該当します。VAD モデルでは通常、生成時のパラメーターはより少なくなります）。

トラブルシューティング

• モデルのダウンロードに関する問題：
  • ModelScope（hub.modelscope.cn）からモデルをダウンロードできるよう、サーバーがインターネットに接続できることを確認してください。
  • ダウンロードエラーや認証エラー（HTTP 401/403 など）が繰り返し発生する場合は、MODELSCOPE_API_TOKEN 環境変数を設定してください。
  • ModelScope のキャッシュディレクトリ（通常は ~/.cache/modelscope/hub/）の空き容量を確認してください。
• 依存関係の競合：
  • システム全体のパッケージや他のプロジェクトとの競合を避けるため、Python 仮想環境の使用を強く推奨します。
• PyTorch のバージョン：
  • FunASR には特定の範囲の PyTorch バージョンが必要です。requirements.txt で互換性のあるバージョンを取得できない場合、または既存の PyTorch のインストールと競合する場合は、互換性のあるバージョンを手動でインストールする必要があります。互換性のある PyTorch バージョンについては、FunASR のドキュメントを参照してください。
• リソースの制限：
  • ASR モデル、特に Paraformer などの大規模モデルは、メモリと CPU を多く使用する場合があります。サーバーに十分なリソースがあることを確認してください。CPU 推論のパフォーマンスは、ncpu（CPU スレッド数。SpeechTranscriber と VADProcessor で設定可能）および CPU の性能に大きく左右されます。
• ファイルパス：
  • ツールに指定する audio_path は絶対パス、または server.py スクリプトの実行場所からの相対パスであること、またサーバープロセスからアクセスできることを確認してください。
• CUDA／GPU に関する問題（GPU を使用する場合）：
  • GPU（device="cuda:X"）を使用する場合は、NVIDIA ドライバー、CUDA Toolkit、および GPU 対応版の PyTorch が正しくインストールされ、互換性があることを確認してください。診断には nvidia-smi や torch.cuda.is_available() などのツールを使用してください。