Metadata-Version: 2.5
Name: workbuddy-mcp-asr
Version: 1.0.1
Summary: WorkBuddy Connector MCP server for self-hosted ASR transcription (stdio, auth_mode: token)
Author: dangsys
License: MIT
Keywords: asr,mcp,model-context-protocol,transcription,whisper,workbuddy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Description-Content-Type: text/markdown

# 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 服务的两个端点：

| 端点 | 方法 | 说明 |
|---|---|---|
| `/` | POST (multipart, 字段 `file`) | 上传音频，触发转写，结果落盘到服务端监听目录 |
| `/api/jobs` | GET | JSON 列表，每项含 `name` / `status` / `text` |

## 提供的 MCP 工具

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

## 凭证（token-schema.json）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ASR_URL | text | ✅ | 服务基础地址，默认 `http://127.0.0.1:8899`（参考实现的默认端口） |
| ASR_USER | text | ✅ | Basic Auth 用户名 |
| ASR_PASS | password | ✅ | Basic Auth 密码 |

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

## 本地测试步骤

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

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

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

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

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

   ```bash
   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 本地服务）：

   ```bash
   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 交互测试**：

   ```bash
   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:8899`ngsys.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`
