asr-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目简介

ASR MCP 服务（asr-mcp）：基于本地 Whisper Large V3 MLX 模型的语音转文本 MCP server（stdio 传输），对外暴露两个工具：transcribe_audio（转写）与 correct_transcription（LLM 纠错）。

常用命令

包管理使用 uv（默认索引为阿里云镜像，见 pyproject.toml），虚拟环境 .venv（Python 3.12）。

• 安装依赖：uv sync
• 运行 MCP server：uv run server.py
• 直接运行转写 worker（绕过 MCP 调试转写链路）：.venv/bin/python worker.py <音频路径> <text|timestamps|srt> <输出文件> [语言]
• 无自动化测试框架：用 test_samples/ 做端到端验证——Docker_Sandboxes_Claude_Code.m4a 是测试音频，同名 .md 是参考文稿（可用于 reference 模式纠错的对照文本）。

架构

四个文件构成一条流水线，核心设计是把「MCP 工具调用」与「重转写任务」解耦到不同进程：

• server.py：MCP server 本体。transcribe_audio 用 asyncio.create_subprocess_exec 把转写交给 worker.py 子进程，再以 asyncio.wait_for(proc.wait(), HEARTBEAT_SECONDS) 做事件驱动等待（不轮询进程状态），期间经 ctx.report_progress 心跳上报进度。默认超时 600 秒；超时后不杀子进程——worker 继续在后台跑完并自行落盘，工具如实返回「未完成」而非「出错」，提示调用方稍后检查输出文件。
• worker.py：一次性工作进程。转写、写文件完成后，向 stdout 打印一行 JSON 作为状态协议：成功 {"status": "ok", "output", "chars", "preview"}；失败 {"status": "error", "error"} 且退出码 1。server.py 只解析 stdout 的最后一行——改动此协议时两端必须同步。
• transcriber.py：mlx_whisper.transcribe 的薄封装。模型路径取环境变量 ASR_MCP_MODEL_PATH，未设置时回退到 DEFAULT_MODEL_PATH（作者本地路径，仅为兼容旧用法）。关键 workaround：该模型转写中文时默认不输出任何标点，必须按语言注入 initial_prompt 引导加标点（zh / other 各一条，见 _INITIAL_PROMPTS）。
• formatter.py：三种输出格式（text / timestamps / srt）。_normalize_punct 只在标点紧邻 CJK 字符时把半角转全角，避免影响纯英文内容——修改标点逻辑时保留这个约束。

输出文件命名约定：{音频名}.txt、{音频名}_timestamps.txt、{音频名}.srt；纠错结果约定保存为 {音频名}_corrected.txt。

correct_transcription 的 Sampling 回退

纠错优先走 MCP Sampling——仅当客户端 capabilities 声明了 sampling 时才调用 ctx.session.create_message；多数客户端不支持，此时工具返回一份现成的纠错提示词（semantic / reference 两种模式各一套），由当前会话的 LLM 自己按提示词完成纠错。修改该工具时两条路径都要兼顾。

开发要求（来自 开发需求.md）

• 转写必须后台运行、完成后自动上报，不得轮询进度；默认超时 10 分钟，超时后需区分「未完成」与「转写出错」两种结论。
• 所有 Python 包用 uv 管理、在 .venv 中运行、走阿里云镜像源。