# asr-mcp

基于本地 [Whisper Large V3 (MLX)](https://huggingface.co/mlx-community/whisper-large-v3-mlx) 模型的语音转文本 [MCP](https://modelcontextprotocol.io) 服务（stdio 传输）。转写全程本地运行，不联网、不上传音频。

## 功能

对外暴露两个 MCP 工具：

| 工具 | 说明 |
| --- | --- |
| `transcribe_audio` | 将音频转写为文本，支持三种输出：`text` 纯文本含标点（默认）/ `timestamps` 带时间轴 / `srt` 字幕 |
| `correct_transcription` | 调用当前会话的 LLM 对转写结果纠错，支持 `semantic`（语义/术语纠错，默认）和 `reference`（对照标准文稿纠错，适合字幕制作）两种模式 |

设计要点：

- **工具调用与重任务解耦**：转写在独立子进程（`worker.py`）中执行，server 以事件驱动方式等待并每 15 秒上报心跳进度，不轮询进程状态。
- **超时语义诚实**：默认超时 10 分钟；超时后不杀子进程，任务继续在后台跑完并自行落盘，工具如实返回「未完成」而非「出错」，并提示稍后检查输出文件。
- **中文标点修复**：该模型转写中文时默认不输出任何标点，本服务按语言注入 `initial_prompt` 引导生成规范标点。
- **Sampling 优雅回退**：纠错优先走 MCP Sampling；客户端不支持时（多数客户端的现状），工具返回一份现成的纠错提示词，由当前会话的 LLM 直接完成纠错。

## 环境要求

- macOS + Apple Silicon（MLX 仅支持 Apple 芯片）
- Python ≥ 3.12
- [uv](https://docs.astral.sh/uv/) 包管理器
- 本地模型目录（见下节）

## 安装

```bash
git clone https://github.com/fengredrum/asr-mcp.git
cd asr-mcp
uv sync
```

> 本项目默认 PyPI 索引为阿里云镜像（见 `pyproject.toml`），海外网络可在 `[tool.uv]` 中删除或替换该配置。

### 准备模型

下载模型到本地任意目录，例如：

```bash
huggingface-cli download mlx-community/whisper-large-v3-mlx --local-dir ~/models/whisper-large-v3-mlx
```

通过环境变量 `ASR_MCP_MODEL_PATH` 指定模型目录（也支持直接填 Hugging Face 仓库 ID，mlx_whisper 会自动下载）：

```bash
export ASR_MCP_MODEL_PATH=~/models/whisper-large-v3-mlx
```

## 接入 MCP 客户端

以 Claude Code 为例：

```bash
claude mcp add asr-mcp \
  --env ASR_MCP_MODEL_PATH=$HOME/models/whisper-large-v3-mlx \
  -- uv --directory /绝对路径/asr-mcp run server.py
```

或在客户端的 MCP 配置中手动添加：

```json
{
  "mcpServers": {
    "asr-mcp": {
      "command": "uv",
      "args": ["--directory", "/绝对路径/asr-mcp", "run", "server.py"],
      "env": {
        "ASR_MCP_MODEL_PATH": "/你的模型目录/whisper-large-v3-mlx"
      }
    }
  }
}
```

接入后直接让 LLM「转写这个音频文件」即可，它会调用 `transcribe_audio` 并在完成后询问是否需要纠错。

## 调试转写链路

可绕过 MCP 直接运行 worker：

```bash
.venv/bin/python worker.py <音频路径> <text|timestamps|srt> <输出文件> [语言]
```

## 输出文件命名约定

| 类型 | 文件名 |
| --- | --- |
| 纯文本 | `{音频名}.txt` |
| 时间轴 | `{音频名}_timestamps.txt` |
| 字幕 | `{音频名}.srt` |
| 纠错结果（约定） | `{音频名}_corrected.txt` |

输出默认与音频文件同目录，也可由调用方指定输出目录。

## 项目结构

```
server.py        # MCP server：工具定义、子进程调度、心跳进度、Sampling 回退
worker.py        # 一次性转写工作进程，stdout 最后一行 JSON 为状态协议
transcriber.py   # mlx_whisper.transcribe 薄封装（含中文标点 workaround）
formatter.py     # text / timestamps / srt 三种格式化输出
```

## 许可证

[MIT](LICENSE)