Metadata-Version: 2.4
Name: mcp-asr
Version: 0.1.3
Summary: A secure stdio MCP server for OpenAI-compatible ASR endpoints
License-Expression: MIT
Keywords: mcp,asr,speech-to-text,openai-compatible,qwen3-asr
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.0.0
Requires-Dist: aiohttp<4,>=3.11
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == "publish"
Requires-Dist: twine>=6; extra == "publish"
Dynamic: license-file

# mcp-asr

`mcp-asr` 是一个 stdio MCP 语音转写服务，用于调用可配置的
OpenAI-compatible transcription 接口：

```text
Claude / Codex / Agent → stdio MCP → OpenAI-compatible transcription URL
```

可以通过 PyPI 安装 Python MCP Server，也可以通过 npx 自动准备并启动固定
版本的 PyPI 包。

## 公共配置

| 配置 | 必填 | 说明 |
|---|---:|---|
| `--url` / `MCP_ASR_URL` | 是 | OpenAI-compatible transcription 完整 URL |
| `--model` / `MCP_ASR_MODEL` | 是 | 转写模型名称 |
| `MCP_ASR_TOKEN` | 是 | 上游接口 Token，只从环境变量读取 |

URL 和模型的优先级为：**启动参数 > 环境变量**。

文件是否可访问由宿主沙箱、操作系统权限和
MCP 客户端的用户授权决定；`mcp-asr` 本身不额外弹出文件授权确认。

## 通过 PyPI 使用

### 安装

```bash
python3 -m venv .venv
.venv/bin/pip install mcp-asr
```

安装后可以使用：

```bash
.venv/bin/mcp-asr
.venv/bin/python3 -m mcp_asr
```

### 手工运行

```bash
MCP_ASR_TOKEN='your-token' \
.venv/bin/mcp-asr \
  --url https://api.openai.com/v1/audio/transcriptions \
  --model qwen3-asr
```

### Claude Code

```json
{
  "mcpServers": {
    "speech-to-text": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/mcp-asr",
      "args": [
        "--url",
        "https://api.openai.com/v1/audio/transcriptions",
        "--model",
        "qwen3-asr"
      ],
      "env": {
        "MCP_ASR_TOKEN": "your-token"
      },
      "timeout": 240000
    }
  }
}
```

### Codex

```toml
[mcp_servers.speech-to-text]
command = "/absolute/path/to/.venv/bin/mcp-asr"
args = [
  "--url", "https://api.openai.com/v1/audio/transcriptions",
  "--model", "qwen3-asr",
]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 240

[mcp_servers.speech-to-text.env]
MCP_ASR_TOKEN = "your-token"
```

## 通过 npx 使用

npm 包是 PyPI `mcp-asr==0.1.3` 的薄启动器。首次运行会在用户缓存目录创建
Python 虚拟环境并安装固定版本的 PyPI 包。

### 前置条件

- Node.js 18 或更高版本；
- Python 3.10 或更高版本；
- 首次准备时可以访问 PyPI。

### 首次预热

建议在注册 MCP 前完成环境准备，避免首次启动超过 MCP startup timeout：

```bash
npx -y mcp-asr@0.1.3 --prepare
```

如需指定 Python：

```bash
MCP_ASR_PYTHON=/path/to/python3 \
npx -y mcp-asr@0.1.3 --prepare
```

### 手工运行

```bash
MCP_ASR_TOKEN='your-token' \
npx -y mcp-asr@0.1.3 \
  --url https://api.openai.com/v1/audio/transcriptions \
  --model qwen3-asr
```

也可以通过环境变量提供 URL 和模型：

```bash
MCP_ASR_TOKEN='your-token' \
MCP_ASR_URL='https://api.openai.com/v1/audio/transcriptions' \
MCP_ASR_MODEL='qwen3-asr' \
npx -y mcp-asr@0.1.3
```

### Claude Code

```json
{
  "mcpServers": {
    "speech-to-text": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-asr@0.1.3",
        "--url",
        "https://api.openai.com/v1/audio/transcriptions",
        "--model",
        "qwen3-asr"
      ],
      "env": {
        "MCP_ASR_TOKEN": "your-token"
      },
      "timeout": 240000
    }
  }
}
```

### Codex

```toml
[mcp_servers.speech-to-text]
command = "npx"
args = [
  "-y",
  "mcp-asr@0.1.3",
  "--url", "https://api.openai.com/v1/audio/transcriptions",
  "--model", "qwen3-asr",
]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 240

[mcp_servers.speech-to-text.env]
MCP_ASR_TOKEN = "your-token"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "speech-to-text-local": {
      "type": "local",
      "command": ["npx",
        "-y",
        "mcp-asr@0.1.3",
        "--url",
        "https://api.openai.com/v1/audio/transcriptions",
        "--model",
        "qwen3-asr"
        ],
      "enabled": true,
      "timeout": 120000,
      "environment": {
        "MCP_ASR_TOKEN": "your-token"
        }
    }
  }
}
```

### npx 可选环境变量

| 环境变量 | 说明 |
|---|---|
| `MCP_ASR_PYTHON` | 指定用于创建虚拟环境的 Python |
| `MCP_ASR_NPX_CACHE_DIR` | 覆盖 npx 持久化缓存目录 |

默认缓存目录：

- macOS：`~/Library/Caches/mcp-asr-npx/`
- Linux：`${XDG_CACHE_HOME:-~/.cache}/mcp-asr-npx/`

标准 pip 环境变量，例如 `PIP_INDEX_URL`、`PIP_EXTRA_INDEX_URL`、代理和证书
变量，也会传递给安装进程。

## transcribe_audio

| 参数 | 说明 |
|---|---|
| `file_path` | 本地音频路径，与 `audio_base64` 二选一 |
| `audio_base64` | Base64 音频数据，与 `file_path` 二选一 |
| `format` | Base64 音频格式；使用 `audio_base64` 时必填 |
| `language` | 可选；省略、空字符串或 `auto` 表示自动检测 |
| `prompt` | 可选上下文提示 |
| `hotwords` | 可选热词列表，会合并进 prompt |
| `include_timestamps` | 尽力从后端响应中提取 `segments` |
| `include_raw` | 返回经过敏感字段过滤的原始 JSON |

使用限制：

- `file_path` 可以指向 MCP Server 进程有权限访问的任意本地音频；
- 选择并授权文件由用户和 MCP 客户端负责；
- 最大音频大小为 25 MB；
- 支持 `flac`、`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`ogg`、`opus`、
  `aac`、`wav`、`webm`；
- MCP 工具调用不能覆盖启动时配置的 URL 和模型。
