内容
# STT-MCP
让您的 AI 代理理解音频和视频。使用 FFMPEG 标准化音频 -> 翻译 -> 自动清理。
选择的后端实现取决于您的硬件，您的代理将帮助您选择：Parakeet 或 Granite。
该选择将为 CLI 和 MCP 服务器保存。
## 后端
| 后端 | 最适合 | 运行时 |
| -------- | ---------------------------------------------------- | ----------------------------------------------------------- |
| Parakeet | 仅限 CPU 的 Windows/Linux、Intel Mac 和 Apple Silicon | 固定的 `parakeet.cpp` v0.4.0 加上本地多语言 GGUF |
| Granite | 最高质量的 CUDA 路径验证 | 固定 IBM Granite Speech 模型，限 NVIDIA GPU |
Windows x86-64 已验证 Parakeet CPU 和 Granite CUDA SDPA。Linux、WSL2、Intel macOS 和
Apple Silicon 路径已实现，但仍未在运行时验证。不支持容器。
## 快速开始
推荐的安装路径是指向权威运行手册的编码代理。
复制并粘贴此指令到您的代理：
> 从上到下阅读 [`docs/SETUP.md`](docs/SETUP.md)。检查我的硬件，向我展示
> 推荐的后端及原因，要求我确认或选择支持的替代方案，然后按照
> 运行手册安装、配置和验证 STT-MCP。不要静默选择后端或跳过
> 真实的语音验收测试。
代理必须在安装后端特定资产之前暂停以确认后端。如果
您更喜欢手动安装，请直接按照相同的操作手册进行。在继续之前，请安装：
- [uv](https://docs.astral.sh/uv/)，使用托管的 CPython 3.13；
- `ffmpeg` 和 `ffprobe` 在 `PATH` 上；
- 足够的存储空间用于选定的运行时和模型。
依赖和模型安装还需要网络访问。准备项目并检查机器：
```console
uv --version
uv python install 3.13
ffmpeg -version
ffprobe -version
uv sync --python 3.13 --locked
uv run stt-mcp setup inspect
```
查看 JSON 推荐结果，然后在安装或配置之前确认后端。
`setup inspect` 永远不会更改配置。
### Granite
Granite 需要支持的 NVIDIA/CUDA 环境和可选依赖组：
```console
uv sync --python 3.13 --locked --extra granite
uv run stt-mcp setup configure --backend granite
```
### Parakeet
下载并验证确切的可执行文件和模型，详见
[Parakeet 设置说明](docs/SETUP.md#4-install-parakeet)，然后保存其本地路径：
```console
uv run stt-mcp setup configure --backend parakeet \
--parakeet-executable "/path/to/parakeet-cli" \
--parakeet-model "/path/to/tdt-0.6b-v3-q4_k.gguf" \
--parakeet-device cpu
```
Parakeet 二进制文件和模型仅在显式设置期间下载，运行时从不下载。
## 从 CLI 转录
发布 TXT、Markdown、JSON、SRT 和 WebVTT 到源文件旁边：
```console
uv run stt-mcp transcribe "/path/to/media.mp4"
```
选择格式和输出目录：
```console
uv run stt-mcp transcribe "/path/to/media.mp4" --output "/path/to/transcripts" --format json --format srt
```
JSON 输出包括有效的 `backend`。字幕时间是粗略的 30 秒源窗口
时间，以确保在两个后端之间行为一致。
## 作为 MCP 服务器使用
注册支持的客户端，然后重启它：
```console
uv run stt-mcp register opencode
uv run stt-mcp register claude-desktop
```
其他 stdio 客户端可以使用以下命令启动已安装的 Python 环境：
```text
-m stt_mcp.server
```
服务器公开：
```text
transcribe(
source_path: string,
output_directory?: string,
formats?: ("txt" | "md" | "json" | "srt" | "vtt")[]
)
```
省略 `output_directory` 会在源文件旁边写入。省略 `formats` 会发布所有格式。
## 操作行为
- 为 MCP 进程选择并锁定一个后端。
- 每次只有一个转录运行；并发请求立即失败，因为忙碌。
- 显式 Granite 在其 CUDA/NVML 安全策略下保持故障关闭。
- 取消关闭活动 Parakeet 进程或使 Granite 工作线程失效。
- 工件原子发布，因此失败的请求不会留下部分输出。
- 运行时代码从不下载 Parakeet 资产。
- Granite 仅在选择时加载；仅 Parakeet 的导入不会加载 Torch、Transformers 或 NVML。
## 贡献者和后端验证
权威验证和真实验收顺序在
[`docs/SETUP.md`](docs/SETUP.md#6-run-static-and-default-test-gates)。默认项目门控是：
```console
uv sync --python 3.13 --locked --extra granite
uv run ruff check .
uv run basedpyright
uv run ty check src tests
uv run mypy
uv run pytest
uv build
```
使用配置的后端运行真实验收：
```powershell
$env:STT_MCP_TEST_MEDIA = (Resolve-Path "D:\path\to\speech.wav").Path
uv run pytest tests/test_mcp_acceptance.py -q -s
Remove-Item Env:STT_MCP_TEST_MEDIA
```
## 卸载
```console
uv run stt-mcp unregister opencode
uv run stt-mcp unregister claude-desktop
```
存储库工作流程通过 `uv sync` 将 STT-MCP 安装到 `.venv` 中；它不会创建 uv
工具安装。仅当您还想删除该项目环境时，请删除 `.venv`。
转录、配置、模型缓存和下载的 Parakeet 资产在您明确删除它们之前将保留。
MCP 市场