ASR Transcribe Connector（asr-transcribe）

WorkBuddy 连接器：把本机音频文件上传到用户自托管的 ASR 转写服务，返回转写文字。

按 06 Connector 开发规范（MCP 方案）+ 06D 附录C（MCP 用户自填 Token 模式）实现：

• MCP Server：Python + FastMCP（stdio 本地子进程），依赖 mcp[cli] + httpx
• 鉴权：auth_mode: "token"，凭证通过 token-schema 表单由用户填写，仅存储在本机， 连接时以 ${VAR} 占位符注入 stdio 子进程的 env

文件结构

asr-transcribe/
├── connector-meta.json   # 元信息（source: asr-transcribe, type: mcp, auth_mode: token）
├── mcp.json              # MCP 连接配置（stdio + env 注入 ASR_URL / ASR_USER / ASR_PASS）
├── token-schema.json     # 用户自填凭证表单定义
├── skills/
│   └── SKILL.md          # 教 AI 何时/如何调用转写工具
├── server/
│   └── asr_mcp_server.py # MCP Server 本体
├── icon.svg              # 图标（麦克风）
└── README.md

对接的后端 API

MCP Server 只对接自托管 ASR 服务的两个端点：

提供的 MCP 工具

• transcribe_audio(file_path) — 上传音频并轮询 /api/jobs（间隔 3s、最多 60 次），返回转写文本
• list_recent_jobs(limit=20) — 返回最近的转写记录列表

凭证（token-schema.json）

三项凭证仅存储在本机（~/.workbuddy/connectors/asr-transcribe/ 下），由服务提供方发放账号。

本地测试步骤

1. 裸测后端 API（本机真服务在 127.0.0.1:8899，无 basic auth，可直接验证对接逻辑）：

   curl -s http://127.0.0.1:8899/api/jobs | python3 -m json.tool
   

2. 准备 venv（已就绪可跳过）：

   python3 -m venv .venv
   .venv/bin/pip install "mcp[cli]" httpx
   

3. 无令牌/缺凭证时的友好错误：

   env -i PATH="$PATH" .venv/bin/python -c "
   import asyncio, server.asr_mcp_server as s
   print(asyncio.run(s.list_recent_jobs.fn(limit=5)) if hasattr(s.list_recent_jobs,'fn') else 'see test')"
   

   （详见 server/test_smoke.py，缺 env 应返回「缺少连接配置：ASR_URL、ASR_USER、ASR_PASS…」）

4. 带凭证实测转写（用 8899 本地服务）：

   ASR_URL=http://127.0.0.1:8899 ASR_USER=dummy ASR_PASS=dummy \
     .venv/bin/python server/test_smoke.py /path/to/audio.m4a
   

5. MCP Inspector 交互测试：

   ASR_URL=http://127.0.0.1:8899 ASR_USER=dummy ASR_PASS=dummy \
     .venv/bin/mcp dev server/asr_mcp_server.py
   

6. WorkBuddy 内测试：在连接器设置表单填入真实凭证（自托管服务地址，如 http://127.0.0.1:8899ngsys.top/` + 真实账号密码），连接后说「帮我把这段录音转成文字」。

正式提交 TODO

• mcp.json 中 command 目前指向本机 venv 绝对路径；正式提交前需按 06 规范改为通用分发形式 （如打包 PyPI 包后用 uvx asr-transcribe-mcp，并声明 runtime / 私有源）

• docUrl 目前留空；如有对外文档页需补上

• 按 06 规范 2.2.5 完成压测并附压测报告（自托管个人服务场景可与 WorkBuddy 团队确认豁免口径）

• 按 06E 完成图标多尺寸/技能打包与提交审核

• 确认 8899 本地服务未鉴权的裸测端口不对公网暴露（外网如需暴露务必加鉴权，见部署方文档sys.top/` + basic auth）

• 按灵感模块 08 规范：提交 Skill 时必须同步提交 3~5 个灵感案例（case.json + output 单文件 + cover.png 720×400）。参考 <项目目录>/playbooks/asr-feishu-pipeline/ 的 case 结构

uvx 分发状态（2026-09-09 已切换）

• mcp.json 已是正式提交形式：{"command": "uvx", "args": ["workbuddy-mcp-asr"]}
• 本地联调用：uvx --from <本目录> workbuddy-mcp-asr（uv 用 hatchling 现场构建隔离环境，已实测 MCP stdio 全通）
• 分发状态（2026-09-09）：1.0.0 已构建（dist/）+ 安全审计通过 + 从 wheel 冒烟通过；只差 uv publish dist/*，流程见 <项目目录>/PUBLISH.md