内容
# mcp-server-pronunciation
[](https://glama.ai/mcp/servers/JuhongPark/mcp-server-pronunciation)
<!-- mcp-name: io.github.JuhongPark/pronunciation -->
> **准确性和安全性声明**
>
> 本项目是一个本地语言学习实践工具。它可能包含错误、运行时错误、不准确的转录、不准确的发音反馈或特定于平台的录音问题。发音反馈是一种指导信号，而不是标准化测试、临床、就业或高风险评估。请仔细检查输出结果，然后再依赖它们。参见 [DISCLAIMER.md](DISCLAIMER.md)。
MCP（模型上下文协议）服务器，允许您**通过语音与 MCP 助手交谈，同时获得英语发音、语法和流利度反馈**。在同一回合中使用它进行随意的语音聊天和轻松指导，或在您想要练习特定句子时切换到练习模式。
为 Codex CLI、Claude Desktop、Claude Code、Cursor、VS Code 和其他 MCP 客户端构建。所有操作都在本地运行 — 音频通过麦克风捕获，在设备上使用 [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) 转录，并且永远不会离开您的机器。
`mcp-name: io.github.JuhongPark/pronunciation`
## 为什么
当今的语音 MCP 服务器将语音视为打字的替代品。英语辅导 MCP 服务器仅限于文本。本服务器结合了两者：您可以自由发言，助手回复，并及时提供您刚刚所说内容的反馈（发音、语法、流利度），以便助手可以将这些反馈融入自然的回复中 — 或者在您只是聊天时不干预。
## 功能
- **语音对话** 与您的 MCP 助手。说话，自动在沉默时停止，然后让助手读取您的转录并回应。
- **基于音素的练习反馈** （当给定参考句子时）：Needleman-Wunsch 单词对齐、逐字预期与实际 IPA、学习者配置文件提示、最小对练习和韵律检查（单词重音、最终升调、子句内暂停）。
- **可扩展的学习者配置文件支持**：当前的规则包包括韩语-L1 发音模式提示和韩语提示。欢迎为其他 L1 配置文件做出贡献。
- **减轻 Whisper 偏差** 通过可选的 `[phoneme]` 额外功能：wav2vec2 CTC 强制对齐验证用户是否实际发出了每个参考单词，因此 Whisper 重写为更常见的替代词的罕见专有名词和特定领域术语不再表现为发音错误。
- **对话中的内联英语反馈**：发音、语法（常见不规则动词错误）和流利度（速度 + 长暂停）。
- **练习模式**（`practice`、`quick_practice`、`retry`）用于专注的句子练习。
- **仅本地**：Whisper 模型在您的机器上运行，音频从未离开。
- **跨平台**：macOS、Linux、Windows 和 WSL2（录音自动路由到 Windows）。
- **快速启动**：延迟导入 + 后台模型预加载，使 MCP 握手在 1 秒内完成。
## 要求
- Python 3.11+
- 可用的麦克风
- 约 150 MB 磁盘空间用于默认的 Whisper 模型 (`base.en`)
- 如果您安装可选的 `[phoneme]` 额外功能，则需要额外的约 360 MB（用于强制对齐的 wav2vec2 权重）
- MCP 规范：目标 `2025-06-18`，通过官方 Python SDK (`mcp>=1.2`)
## 安装
### 稳定版本
安装最新的稳定版本：
```bash
uvx mcp-server-pronunciation
```
对于 pip 用户：
```bash
pip install mcp-server-pronunciation
```
要显式锁定此版本：
```bash
uvx mcp-server-pronunciation@0.3.0
```
在实时会话中依赖服务器之前，请运行 `doctor`：
```bash
mcp-server-pronunciation doctor
```
### 通用安装命令
```bash
# 推荐：uvx（无全局安装，在运行之间缓存）
uvx mcp-server-pronunciation
# 或作为 uv 工具安装
uv tool install mcp-server-pronunciation
# 或 pip
pip install mcp-server-pronunciation
# 可选：强制对齐升级以减轻 Whisper 偏差 + 更严格的音素级反馈。添加约 200 MB 的 torch CPU 轮。
pip install 'mcp-server-pronunciation[phoneme]'
```
### Linux：先安装 PortAudio
`sounddevice` 在 macOS 和 Windows 上将 PortAudio 捆绑在轮中，但在 Linux 上，您需要系统库：
```bash
# Debian / Ubuntu
sudo apt-get install libportaudio2
# Fedora / RHEL
sudo dnf install portaudio
# Arch
sudo pacman -S portaudio
# 仅限 PipeWire 系统可能还需要
sudo apt-get install pipewire-alsa
```
### 首次检查
在将服务器连接到 MCP 客户端之前，请运行预检：
```bash
uvx mcp-server-pronunciation doctor
```
可选 — 预下载 Whisper 模型（~150 MB），以便首次调用立即生效：
```bash
uvx mcp-server-pronunciation pull-model base.en
```
## 添加到您的 MCP 客户端
### Codex CLI
```bash
codex mcp add pronunciation -- uvx mcp-server-pronunciation
```
### Claude Code
```bash
claude mcp add pronunciation -- uvx mcp-server-pronunciation
```
### Claude Desktop
编辑 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"pronunciation": {
"command": "uvx",
"args": ["mcp-server-pronunciation"]
}
}
}
```
在 macOS 上，如果 Claude Desktop 找不到 `uvx`（`spawn uvx ENOENT`），请使用绝对路径。在终端中使用 `which uvx` 查找。
### Cursor
添加到 `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"pronunciation": {
"command": "uvx",
"args": ["mcp-server-pronunciation"]
}
}
}
```
### VS Code（支持 MCP）
添加到 `.vscode/mcp.json` 或您的用户设置：
```json
{
"servers": {
"pronunciation": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-pronunciation"]
}
}
}
```
## 用例
### 1. 语音聊天并带有反馈
> **您**：“让我们进行语音聊天。我会问你关于周末的事情。使用对话工具。”
>
> **助手**（调用 `converse`）：*记录您的语音，转录它，注意到您说的是“buyed”而不是“bought”*
>
> **助手**：“哦，很酷 — 你买了什么苹果？顺便说一下，'buy' 的过去时态是 'bought' — 小事一桩，但我注意到了。”
### 2. 练习特定句子
> **您**：“给我一个带有 'th' 音的句子练习。”
>
> **助手**（调用 `suggest_sentence`，焦点为 `th`）： “试试这个： *The three brothers thought thoroughly about their future.* ”
>
> **您**：“记录我朗读它。”
>
> **助手**（调用 `practice`，带有该参考）：*返回一个对齐表（匹配/子/插入/删除），带有每个单词的声学置信度，当安装 `[phoneme]` 额外功能时，带有音素级问题和预期与实际 IPA 的比较，当适用时带有学习者配置文件提示，带有最小对练习和韵律笔记（单词重音，最终升调，子句内暂停）。*
### 3. 在反馈后重试
> **您**：“让我再试一次。”
>
> **助手**（调用 `retry`）：*重新记录相同的目标句子，并比较新尝试与之前的尝试。*
## 工具
| 工具 | 目的 |
|---|---|
| **`converse`** | **主要**。记录 + 转录 + 快速反馈 + 助手指导，用于自然的语音聊天和指导。 |
| `practice` | 练习模式：记录用户朗读特定参考句子，返回详细评估。 |
| `quick_practice` | 选择一个随机句子（按音素焦点 + 难度），并进行练习。 |
| `retry` | 重新记录上一个句子，并将新尝试与之前的尝试进行比较。 |
| `open_voice_panel` | 当客户端支持嵌入式 UI 时，打开 MCP 应用的语音面板。 |
| `analyze_uploaded_audio` | 分析语音面板上传的 WAV 音频，并将其存储为最新的语音捕获。 |
| `start_voice_capture` | 在后台开始录音，并立即返回会话 ID。 |
| `voice_capture_status` | 检查后台捕获是否正在录音、分析、完成、取消或失败。 |
| `wait_for_voice_capture` | 等待后台捕获完成，并返回转录 + 反馈。 |
| `latest_voice_capture` | 返回最近的后台语音捕获结果。 |
| `cancel_voice_capture` | 在分析开始前将后台捕获标记为取消。 |
| `suggest_sentence` | 在不录音的情况下返回练习句子。 |
| `record` | 记录音频并保存 WAV 文件（原始，无分析）。 |
| `assess` | 评估上一次录音（或指定的 WAV），无需重新录音。当给定参考时，运行完整的练习管道（对齐，音素差异，学习者配置文件提示，韵律）。 |
| `check_mic` | 列出可用的音频输入设备。 |
评估语音的工具还会返回具有 `transcript`、`clarity_pct`、`speaking_rate_wpm`、`top_issue`、`next_action`、`retry_comparison`、`assessment` 和渲染的 `report_markdown` 的结构化 MCP 输出。MCP 客户端可以使用结构化结果提供重试、显示顶部问题或在不解析 Markdown 的情况下构建更丰富的练习 UI。
### 可见的语音捕获工作流程
对于没有嵌入式语音 UI 的 MCP 客户端，请使用后台捕获工具让用户了解情况：
```text
start_voice_capture(duration=8, mode="conversation")
voice_capture_status(session_id)
wait_for_voice_capture(session_id, timeout=30)
latest_voice_capture()
```
状态响应包括 `recording`、`analyzing`、`done`、`error` 或 `cancelled`，以及已用时间、转录、清晰度、说话速度、反馈降噪和可用时的完整结构化评估。在 WSL2 上，请保持 `duration` 短暂，因为 PowerShell 录音可能会等待整个请求持续时间，然后再开始分析。
### MCP 应用语音面板
支持 MCP 应用的客户端可以调用 `open_voice_panel` 来渲染 `ui://pronunciation/voice-panel` 资源。该面板请求浏览器麦克风访问，在浏览器中本地记录，上传 WAV 剪辑到 `analyze_uploaded_audio`，并显示返回的转录和反馈。
上传的剪辑存储在与 MCP 独家录音相同的语音会话注册表中，因此助手可以在面板完成后调用 `latest_voice_capture` 并响应开发笔记和发音反馈。没有支持 MCP 应用的客户端应该使用上面的可见语音捕获工作流程。
## 提示快捷方式
MCP 客户端可以公开服务器提示，直接启动常见工作流程：
| 提示 | 目的 |
|---|---|
| `start_voice_chat` | 启动带有轻度反馈的本地语音对话。 |
| `daily_practice` | 运行一个短暂的建议句子练习循环。 |
| `practice_focus` | 启动针对所选焦点和难度的练习。 |
| `troubleshoot_mic` | 检查麦克风设备和录音设置。 |
## 配置
### Whisper 模型
设置 `MCP_PRONUNCIATION_MODEL` 以选择不同大小的模型：
```bash
# 默认 — 快速，仅限英语（~150 MB）
export MCP_PRONUNCIATION_MODEL=base.en
# 更小/更快（~75 MB）
export MCP_PRONUNCIATION_MODEL=tiny.en
# 更准确（~470 MB）
export MCP_PRONUNCIATION_MODEL=small.en
# 多语言选项（更大）
export MCP_PRONUNCIATION_MODEL=small
export MCP_PRONUNCIATION_MODEL=medium
```
可用：`tiny`、`tiny.en`、`base`、`base.en`、`small`、`small.en`、`medium`、`medium.en`、`large-v3`、`large-v3-turbo`。对于仅限英语使用，`.en` 变体在给定大小下更快、更准确。
当可用时，GPU（CUDA 12 + cuDNN 9）会自动检测；否则在 CPU 上以 int8 量化运行。
### 缓存位置
默认情况下，Whisper 权重缓存在 `~/.cache/huggingface/hub/` 中。使用 `HF_HUB_CACHE` 覆盖：
```bash
export HF_HUB_CACHE=/path/to/cache
```
### 启动预加载
默认情况下，服务器在 MCP 握手开始后在后台预加载 Whisper 模型。设置 `MCP_PRONUNCIATION_PRELOAD=0` 以进行注册检查、Docker 烟雾测试或其他只需要工具发现且应避免模型下载的环境：
```bash
export MCP_PRONUNCIATION_PRELOAD=0
```
### 临时录音
录音被写入临时 WAV 文件，以便 `assess` 可以检查上一次录音。默认情况下，它们在服务器进程退出时被删除：
```bash
export MCP_PRONUNCIATION_AUDIO_RETENTION=session
```
设置 `MCP_PRONUNCIATION_AUDIO_RETENTION=keep` 以使临时录音保留在磁盘上以便手动检查。
### 麦克风和自动停止控制
默认情况下，服务器使用系统的默认麦克风。本地 `sounddevice` 录音在检测到 1.5 秒的沉默后停止。WSL2 通过 Windows PowerShell 记录，并可能等待整个请求持续时间，因此对于快速语音检查，请使用短暂的 `duration` 值。您可以覆盖本地录音行为：
```bash
# 使用 `check_mic` 工具的特定输入设备索引或名称
export MCP_PRONUNCIATION_INPUT_DEVICE=1
# 选项：low、normal、high
# high 有助于软语者；low 在嘈杂的房间中更好
export MCP_PRONUNCIATION_VAD_SENSITIVITY=high
# 静音前秒数，限制在 0.3-5.0 之间
export MCP_PRONUNCIATION_SILENCE_DURATION=2.0
```
运行 `check_mic` 以查看默认输入设备、可用设备索引和活动 VAD 设置。
### MCP 客户端中的模型覆盖
```bash
# Codex CLI
codex mcp add --env MCP_PRONUNCIATION_MODEL=small.en pronunciation -- uvx mcp-server-pronunciation
# Claude Code
claude mcp add pronunciation -e MCP_PRONUNCIATION_MODEL=small.en -- uvx mcp-server-pronunciation
```
### 音素分析额外功能
安装 `mcp-server-pronunciation[phoneme]` 启用基于 wav2vec2 的 CTC 强制对齐。它验证用户实际发音的单词，而不是 Whisper 的语言模型加权解码器重写的单词 — 因此，Whisper 重写为更常见的替代词的罕见专有名词和领域术语不再表现为错误发音。首次运行时，额外功能会下载约 360 MB 的权重到 `~/.cache/torch/hub/`（通过 `TORCH_HOME` 覆盖）。推理默认仅限 CPU，并量化为 int8（~95 MB RAM）。
如果没有额外功能，`assess` / `practice` 仍会运行完整的流水线，除了强制对齐步骤：您将获得 Needleman-Wunsch 单词对齐、CMUdict 音素序列差异、学习者配置文件提示和韵律。
## 平台支持
| 平台 | 录音方法 | 状态 |
|----------|------------------|--------|
| macOS | sounddevice（捆绑 PortAudio） | 支持 |
| Linux | sounddevice（需要 `libportaudio2`） | 支持 |
| Windows | sounddevice（捆绑 PortAudio） | 支持 |
| WSL2 | PowerShell MCI（winmm.dll） | 支持 |
**WSL2 注意**：WSLg 的 PulseAudio 不会将 Windows 主机的麦克风音频转发到 WSL2。此服务器会自动检测 WSL2，并改为通过 Windows 侧的 PowerShell 记录。WSL2 记录可能会等待整个请求持续时间，而不是在静音时自动停止。
## 故障排除
### `uvx mcp-server-pronunciation doctor` 是您的第一站
它报告 PortAudio、输入设备、Whisper 模型缓存、发音资源、强制对齐依赖项、可用磁盘空间和 Python 版本。运行它时，任何问题都可能出现。
### Linux 上的 `sounddevice` 导入失败
您缺少 `libportaudio2`。参见上面的安装部分。安装后：
```bash
uvx mcp-server-pronunciation doctor
```
### 未捕获音频 / 空录音
- **macOS**：系统设置 → 隐私和安全 → 麦克风。授予对已启动 MCP 客户端的应用程序（如 Codex CLI、Claude Desktop 或 Claude Code）的访问权限。
- **Linux**：检查 `pavucontrol`（PulseAudio）或 `pw-cli list-objects`（PipeWire）的输入级别。在 PipeWire 仅限系统上，安装 `pipewire-alsa`。
- **WSL2**：在 Windows 设置 → 声音 → 输入中测试麦克风。服务器通过 Windows 记录，而不是通过 WSLg。
### 首次运行缓慢
Whisper 模型在首次使用时下载（~150 MB）。预下载它：
```bash
uvx mcp-server-pronunciation pull-model base.en
```
后续运行会重用缓存的权重。如果启动仍然缓慢，请尝试 `MCP_PRONUNCIATION_MODEL=tiny.en`。
### macOS 上的 Claude Desktop：`spawn uvx ENOENT`
Claude Desktop 从没有 `~/.local/bin` 的 GUI 环境启动 MCP 服务器。在配置中使用 `uvx` 的绝对路径（`/Users/YOU/.local/bin/uvx` 或 `which uvx` 报告的位置）。
## 已知限制
- 此版本稳定，但发音和韵律反馈仍然是实验性的指导信号。仍然可能出现错误、运行时错误、不准确的反馈和特定于平台的录音问题。
- 发音分数是辅导信号，而不是标准化测试、临床或母语者等效性判断。
- Whisper 仍然可能听错罕见的名称、领域术语、短片段、安静的音频或口音很重的语音。 可选的 `[phoneme]` 额外功能减少了一些参考句子误报，但并未消除它们。
- 韵律反馈是启发式的。音高跟踪在嘈杂的音频、非常短的语句、声带嘎吱声、重叠的语音或剪辑录音中可能不可靠。
- 学习者配置文件提示是故意基于规则的。当前的包包括韩语-L1 提示，但它们可能会错过错误，在 ASR 错误时过度触发，并应视为有针对性的练习辅助工具。欢迎为其他 L1 配置文件做出贡献。
- 首次设置可能会下载模型或发音资源。在实时会话中依赖服务器之前，请运行 `doctor` 和 `pull-model`。
- 临时 WAV 录音在系统临时目录下写入，以便可以评估最后一次录音。默认情况下，它们在服务器退出时被删除。如果您想检查它们，请设置 `MCP_PRONUNCIATION_AUDIO_RETENTION=keep`。
## 基准测试状态
该项目正在朝着基于基准测试的评分方向发展。计划中的公共基准测试工作在 [ROADMAP.md](ROADMAP.md) 中跟踪，测试方法在 [docs/TESTING.md](docs/TESTING.md) 中描述，当前的基准测试助手文档在 [docs/BENCHMARKS.md](docs/BENCHMARKS.md) 中。主要的候选者是 Speechocean762，因为它具有允许的 CC BY 4.0 许可证和多级别的专家发音评分。L2-ARCTIC 对于电话错误和学习者配置文件研究检查很有用，包括韩语-L1 子集审查，但其非商业许可证意味着它应该保持可选和与默认发布声明分开。
## 发布状态
源代码仓库是公开的。PyPI、GitHub Release 和 MCP Registry 发布步骤在 [docs/PUBLICATION.md](docs/PUBLICATION.md) 中跟踪。
## 隐私
- 所有音频处理都在您的本地机器上进行。
- 录音是临时 `.wav` 文件，位于您的系统临时目录（`$TMPDIR`）下，在服务器退出时会被删除，除非设置了 `MCP_PRONUNCIATION_AUDIO_RETENTION=keep`。
- Whisper 模型在本地运行 - 不会将任何音频数据发送到外部服务。
- 当安装可选的 `[phoneme]` 额外功能时，wav2vec2 强制对齐器也在本地运行。权重从 PyTorch Hub 下载一次。
- 没有遥测。没有分析。除了一次性的模型权重下载（Whisper 从 Hugging Face，wav2vec2 从 PyTorch Hub）之外，没有网络调用。
## 开发
```bash
git clone https://github.com/JuhongPark/mcp-server-pronunciation.git
cd mcp-server-pronunciation
uv sync --extra dev
uv run pytest -v
uv run ruff check .
uv run ruff format --check .
```
要开发可选的 wav2vec2 强制对齐路径，还需要安装 phoneme 额外功能：
```bash
uv sync --extra dev --extra phoneme
```
## 支持
问题：https://github.com/JuhongPark/mcp-server-pronunciation/issues
## 许可证
MIT。参见 [LICENSE](LICENSE)。
第三方组件（均为 MIT / 允许协议）：
- [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) — MIT
- [OpenAI Whisper 模型](https://github.com/openai/whisper) — MIT
- [CTranslate2](https://github.com/OpenNMT/CTranslate2) — MIT
- [`sounddevice`](https://python-sounddevice.readthedocs.io/) — MIT
- [PortAudio](http://www.portaudio.com/) — MIT
- [`cmudict`](https://pypi.org/project/cmudict/) — BSD
- [`g2p-en`](https://github.com/Kyubyong/g2p) — Apache 2.0
- [`librosa`](https://librosa.org/) — ISC
- 可选（`[phoneme]` 额外功能）：[PyTorch](https://pytorch.org/) — BSD，[torchaudio](https://pytorch.org/audio/) — BSD，[wav2vec2 权重](https://github.com/facebookresearch/fairseq) — MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器