内容
# 语音通知 MCP
一款具有神经语音、桌面和终端通道的本地 MCP 通知服务器。
它公开了 `voice_notify`，具有三个独立的通知通道：
- 通过 `notify-send` 的桌面通知（默认启用）
- 终端铃声
- 通过 Kokoro 的本地神经语音，紧急情况下使用 `spd-say` 作为备用
Kokoro 在第一个语音通知时惰性加载，并保持常驻。默认语音为 `bf_emma`。音频作为内存中的 24 kHz PCM 通过 `pw-play` 发送到 PipeWire；通知文本从未通过 shell 或发送到远程 API。
## 需求
- 具有 glibc 2.38 或更新版本和 PipeWire 的 `pw-play` 的 Linux
- 用于桌面通知的 `notify-send`
- 用于语音备用的 `spd-say`
- 从源代码构建时，需要 Rust 1.88 或更新版本和本地构建工具链
- 大约 314 MB 用于 Kokoro 模型和捆绑的语音选择
当前 ONNX Runtime 二进制文件需要 glibc 2.38 符号。Ubuntu 24.04 和 Debian 13 已测试；Debian 12 和 Ubuntu 22.04 目前不受默认构建的支持。发布二进制文件和软件包在 Ubuntu 24.04 上构建，需要 glibc 2.39 或更新版本。在 Debian 和 Ubuntu 上，运行时命令由 `pipewire-bin`、`libnotify-bin` 和 `speech-dispatcher` 提供。在 Fedora 上，它们由 `pipewire-utils`、`libnotify` 和 `speech-dispatcher` 提供。
许可的集成使用 [`kokoro-en` 0.1.4](https://crates.io/crates/kokoro-en)，许可 Apache-2.0。Kokoro 模型权重也是 Apache-2.0。
## 安装
### Debian 或 Ubuntu 软件包
下载发布的 `.deb` 和 `SHA256SUMS` 文件，验证软件包并安装：
```bash
sha256sum --check --ignore-missing SHA256SUMS
sudo apt install ./voice-notifier-mcp_*_amd64.deb
voice-notifier-install-assets
```
### Fedora 或 RPM 软件包
下载发布的 `.rpm` 和 `SHA256SUMS` 文件，验证软件包并安装：
```bash
sha256sum --check --ignore-missing SHA256SUMS
sudo dnf install ./voice-notifier-mcp-*.x86_64.rpm
voice-notifier-install-assets
```
分发软件包在 `/usr/bin` 下安装 `voice-notifier-mcp` 和 `voice-notifier-install-assets`。运行时依赖项通过软件包管理器安装。建议使用 `speech-dispatcher` 而不是必需，因为它只是紧急备用。
### 便携式存档
发布还提供了一个包含服务器、资产安装程序、文档和许可证的 `linux-x86_64.tar.gz` 存档。解压它并将两个可执行文件复制到 `PATH` 上的目录，然后运行 `voice-notifier-install-assets`。
### 从源代码构建
```bash
git clone https://github.com/ominiverdi/voice-notifier-mcp.git
cd voice-notifier-mcp
./scripts/install-kokoro-assets.sh
cargo install --locked --path .
```
资产安装程序下载官方模型和六种语音，验证它们的 SHA-256 哈希值，并将它们放在 `${XDG_DATA_HOME:-$HOME/.local/share}/voice-notifier-mcp` 下。现有的已验证资产不会再次下载。安装后，合成完全本地。
安装资产的预期 SHA-256 值：
```text
8fbea51ea711f2af382e88c833d9e288c6dc82ce5e98421ea61c058ce21a34cb model.onnx
f69d836209b78eb8c66e75e3cda491e26ea838a3674257e9d4e5703cbaf55c8b af_bella.bin
d583ccff3cdca2f7fae535cb998ac07e9fcb90f09737b9a41fa2734ec44a8f0b af_heart.bin
cd2191ab31b914ed7b318416b0e4440fdf392ddad9106a060819aa600a64f59a af_nicole.bin
4409fbc125afabacc615d94db5398d847006a737b0247d6892b7a9a0007a2f0a af_sarah.bin
1d1f21dd8da39c30705cd4c75d039d265e9bc4a2a93ed09bc9e1b1225eb95ba1 am_michael.bin
669fe0647f9dd04fcab92f1439a40eeb4c8b4ab1f82e4996fe3d918ce4a63b73 bf_emma.bin
```
### 添加额外语音
安装程序故意提供了一个小的验证选择。要添加另一个兼容的 Kokoro 语音，请从受信任的来源获取其原始小端 float32 `.bin` 嵌入，并将其复制到资产目录：
```bash
asset_dir="${XDG_DATA_HOME:-$HOME/.local/share}/voice-notifier-mcp"
install -d -m 0755 "$asset_dir"
install -m 0644 /path/to/custom_voice.bin "$asset_dir/custom_voice.bin"
```
文件名干成为 `voice_name` 值，并且必须仅包含 ASCII 字母、数字、`_` 或 `-`。PyTorch `.pt` 语音文件不支持直接使用；请获取或转换相应的原始 `.bin` 嵌入，而不是简单地重命名文件。在安装前，请验证源、许可证和校验和。在添加、替换或删除语音后，请重启每个 MCP 客户端，以便它重新加载工具模式和语音数据。
使用 `VOICE_NOTIFIER_MODEL_PATH`、`VOICE_NOTIFIER_VOICE_PATH` 和 `VOICE_NOTIFIER_VOICE` 覆盖默认值。`VOICE_NOTIFIER_VOICE_PATH` 可以命名一个 `.bin` 文件或一个包含语音文件的目录。服务器在 `voice_name` 模式中动态列出安全的 `.bin` 文件干；兼容的自定义嵌入不需要更新目录。
## 构建和测试
```bash
cargo fmt --all -- --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release
./scripts/package-release.sh
```
`package-release.sh` 在 `dist/` 下创建一个便携式存档、Debian 软件包、RPM 软件包和 SHA-256 清单。它除了 Rust 构建工具外，还需要 `dpkg-deb` 和 `cargo-generate-rpm` 0.21.0。
## 工具输入
```json
{
"title": "Ferrum 完成",
"message": "Lorenzo，代码库审查已完成。报告已准备好。",
"desktop": true,
"bell": true,
"voice": true,
"voice_name": "af_heart",
"speech_speed": 1.0
}
```
仅 `message` 是必需的。`voice_name` 选择任何已安装的兼容 `.bin` 语音，由工具模式公开，默认情况下如果可用则为 `bf_emma`。`speech_speed` 接受 0.5 到 2.0，并默认为 1.0。口语消息限制为 500 个 Unicode 字符。进程参数直接传递，不使用 shell。
服务器协商 MCP 协议版本 `2024-11-05`、`2025-06-18` 和 `2025-11-25`。已与 Ferrum、Pi 0.80.3（通过其 MCP 桥接扩展）和官方 MCP Inspector 0.22.0 验证互操作性。该工具被注释为非破坏性、非幂等且仅限本地使用。
## Ferrum 配置
```toml
[[mcp.servers]]
name = "voice-notifier"
command = "/home/your-user/.cargo/bin/voice-notifier-mcp"
enabled = true
```
使用 `command -v voice-notifier-mcp` 返回的绝对二进制路径；MCP 客户端不一定会扩展命令路径中的 `~` 或环境变量。在安装新二进制文件或更改配置后，请重启 Ferrum。
## 文档
- [第三方组件和许可证](THIRD_PARTY.md)
- [项目概述和架构](docs/PROJECT.md)
- [本地 TTS 研究和基准测试](docs/TTS_RESEARCH.md)
