Audio File MCP App

Audio File MCP App

MCP ホストでローカルのオーディオファイルを再生、確認するためのMCP Appです。

会話内に、再生機能、メタデータ、ラウドネス、スペクトログラム、オプションの注釈レーンタイムラインを備えた UI を表示します。

ファイルのメタデータ、ラウドネス統計、現在の再生ヘッド位置、選択したリージョン、再生ヘッド位置で有効な注釈レーンもモデルに返されるため、後続のタスクでユーザーが実際に聞いたり見たりしている内容を参照できます。

機能

• 全体的なラウドネス指標は EBU R128 に基づいて算出されます。Integrated Loudness（LUFS）、Loudness Range（LRA）、True Peak（dBTP）、Sample Peak、RMS を表示します。
• 瞬時ラウドネス指標は、再生中またはポインターを合わせたときに表示されます。Momentary（400 ms）と Short-Term（3 s）の LUFS に加えて、カーソル位置の Sample Peak と RMS も表示します。
• スペクトル重心に基づく波形の色分けでは、低・中・高域のエネルギー比を使って、各波形スライスを音色のグラデーションで色付けします。明るい／暗い領域から、明るい／暗い音がひと目でわかります。
• 再割り当てスペクトログラムは、対数周波数ビン（下限 20 Hz）と Inferno カラースケールを使用します。時間周波数再割り当てにより、通常の STFT よりもトランジェントや音色の部分音が鮮明になります。
• **ループ再生するリージョンの選択。**タイムライン上をドラッグしてリージョンを指定します。その範囲をループ再生し、リージョンの開始／終了位置は、ファイルのラウドネスや再生ヘッドの状態とともにモデルに返されます。
• **注釈レーンタイムライン。**タイムライン注釈を渡すと、ウィジェットは波形とスペクトログラムの間に、音声自体のタイムラインに合わせた細いラベル付きレーンを積み重ねて描画します。各レーンには時間範囲、任意の色、レーン上の範囲の不透明度を変化させる任意のエンベロープを設定できます。範囲にポインターを合わせるとラベルが表示されます。また、再生ヘッド位置で有効なレーンに加え、選択したリージョン内で開始、終了、または有効になるレーンもモデルに返されます。

インストール

サーバーは stdio 経由でローカルに実行されます。以下のどの方法でインストールしても、同じコマンド npx -y @counterpoint-studio/audio-file-mcp-app が設定されます。

Claude Desktop

最も簡単な方法は、リリースページから最新の .mcpb をダウンロードして、ダブルクリックすることです。Claude Desktop には Node がバンドルされているため、追加のランタイムは必要ありません。

または、claude_desktop_config.json にサーバーを手動で追加します。

{
  "mcpServers": {
    "audio-file": {
      "command": "npx",
      "args": ["-y", "@counterpoint-studio/audio-file-mcp-app"]
    }
  }
}

Codex Desktop

1. Settings -> MCP Servers に移動します
2. Add Server を選択します
3. 名前：audiofile-mcp-app
4. 起動コマンド：npx
5. 引数 -y と @counterpoint-studio/audio-file-mcp-app を指定します

VS Code（Copilot、Agent mode）

または、.vscode/mcp.json（ワークスペース）またはユーザーの mcp.json に追加します。

{
  "servers": {
    "audio-file": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@counterpoint-studio/audio-file-mcp-app"]
    }
  }
}

Goose

このディープリンクをブラウザーに貼り付けます（Goose Desktop をインストールしておく必要があります。カスタム URI スキームは、GitHub README 内で通常のリンクとしては使用できません）。

goose://extension?id=audio-file&name=Audio%20File%20MCP%20App&cmd=npx&arg=-y&arg=%40counterpoint-studio%2Faudio-file-mcp-app

または、goose configure → Add Extension → Command-line Extension を実行し、npx -y @counterpoint-studio/audio-file-mcp-app を入力します。

MCP Inspector

npx @modelcontextprotocol/inspector npx -y @counterpoint-studio/audio-file-mcp-app

使い方

ホストに、絶対パスで指定したローカルのオーディオファイルを表示するよう依頼します。例：

「/Users/me/Music/track.wav を表示して」

ホストは display_audio_file ツールを呼び出し、波形、スペクトログラム、ラウドネス指標、再生コントロールを備えたアプリ内 UI を表示します。

注釈レーン

display_audio_file は、タイムラインに描画するレーンを記述する省略可能な annotations オブジェクトを受け取ります（または、同じ { "lanes": [...] } 形式の JSON ファイルを指定する annotationsPath も利用できます。大きなペイロードに便利です）。

{
  "annotations": {
    "lanes": [
      {
        "label": "Delay tails",
        "color": "#e6007e",
        "spans": [{ "start": 8, "end": 24 }],
        "envelope": [
          { "time": 8, "value": 0 },
          { "time": 24, "value": 1 }
        ]
      }
    ]
  }
}

時刻は、音声自体のタイムライン上の秒数です。label、color、envelope は省略可能です。エンベロープを持つレーンでは、エンベロープ曲線に沿って範囲の不透明度が変化し、色が指定されていないレーンには淡いアクセントカラーの塗りつぶしが適用されます。レーン内で範囲が重なっている場合、次の範囲の開始位置で切り詰められるため、行が重なることはありません。モデルは、セクションを示したり、イベントに印を付けたり、実行した分析を可視化したりするために、注釈を作成できます。

セキュリティモデル

• サーバーは、ユーザーアカウントの権限で stdio 経由でローカルに実行されます。
• display_audio_file は、設計上、指定された任意のファイルパスを開きますが、音声として認識されるファイルのみを受け付けます。
• プレーヤーは、バイト範囲リソース（audiofile-range://…）を通じてファイルをストリーミングします。音声として認識されるファイルのバイトのみを返し、それ以外の場合は、存在しないパスも含め、同じ「認識可能な音声ファイルではありません」というエラーを返します。
• annotationsPath は指定された JSON ファイルを読み取り、注釈形式に一致する場合にのみ使用します。
• ツールのエラーは、何が問題だったのかを確認できるよう、意図的に具体的にしています。指定されたパスが存在するか、通常のファイルか、または（annotationsPath の場合）注釈形式の有効な JSON かどうかが明らかになることがあります。ファイルの内容がエラーに含まれることはありません。
• 残るリスクは、ツールを呼び出せるモデルが、マシン上の任意の音声ファイルを開けることです。ツール呼び出しの前に承認を求めるホストが、その対策となります。

脆弱性を報告するには、SECURITY.md をご覧ください。

クライアントの互換性

以下でテスト済みで、動作が確認されています。

• Claude Desktop — Chat、Cowork、Code
• Codex Desktop
• Visual Studio Code
• Goose
• MCP Inspector

開発

pnpm install
pnpm run build:dsp   # emsdk required; see WASM-BUILD.md
pnpm run serve       # runs the server with tsx, no compile step
pnpm test

pnpm run build:dist は、公開可能なレイアウトを dist/ 以下に生成します（dist/mcp-app.html + dist/server/）。

リリース

pnpm version <bump>          # bumps every version string (package.json, server.json,
                             # mcpb/manifest.json, src/server/app.ts) + commits + tags
git push && git push --tags
source /path/to/emsdk_env.sh # prepublishOnly rebuilds the DSP code with Emscripten
pnpm publish --access public # publishes to npm
gh workflow run publish-registry.yml -f tag=v<version> # MCP Registry, once npm shows the version
pnpm run build:mcpb          # produces dist/audio-file-mcp-app-<version>.mcpb
gh release create v<version> dist/*.mcpb # attaches the bundle to a GitHub release

npm では、新しいバージョンが表示されるまで、validating 状態が最大 1 時間続くことがあります。レジストリは npm パッケージをチェックするため、npm view @counterpoint-studio/audio-file-mcp-app version で新しいバージョンが表示されてから、レジストリのワークフローを実行してください。

MCP Registry は GitHub Actions（.github/workflows/publish-registry.yml）から公開されます。インタラクティブな mcp-publisher login github で付与されるのは個人の名前空間のみであり、io.github.counterpoint-studio/* ではないためです。

ライセンス

ISC © Counterpoint Studio OÜ