Audio File MCP App

音频文件 MCP 应用

一个用于在 MCP 宿主中播放和检查本地音频文件的 MCP 应用。

在对话中呈现一个 UI，包含播放、元数据、响度、频谱图，以及可选的标注轨道时间线。

文件元数据、响度统计、当前播放头位置、任何选定区域，以及播放头处处于活动状态的标注轨道，也会反馈给模型，因此后续任务可以参考用户实际听到和看到的内容。

功能

• 全局响度指标，依据 EBU R128 计算：集成响度（LUFS）、响度范围（LRA）、真峰值（dBTP）、采样峰值和 RMS。
• 瞬时响度指标，播放或悬停时显示：瞬时（400 ms）和短时（3 s）LUFS，以及光标位置处的采样峰值和 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. 添加服务
3. 名称：audiofile-mcp-app
4. 启动命令：npx
5. 参数 -y 和 @counterpoint-studio/audio-file-mcp-app

VS Code（Copilot、Agent 模式）

或者添加到 .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 对象，用于描述要在时间线上绘制的轨道（也可以通过 annotationsPath 指定一个 JSON 文件，其中包含相同的 { "lanes": [...] } 结构，适合较大的数据）：

{
  "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 状态长达一小时，然后才会显示。注册表会检查 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Ü