内容
# TypeWhisper MCP
`@typewhisper/mcp` 将本地的 TypeWhisper API 作为模型上下文协议（MCP）服务器暴露给编码代理和其他 MCP 客户端。
它连接到本地或远程主机上运行的 TypeWhisper 应用程序，并允许代理转录文件、检查模型状态、搜索转录历史、管理词典术语和更正。
## 要求
- 运行此 MCP 服务器的机器上安装 Node.js 20 或更高版本
- 在可访问的 macOS 或 Windows 主机上安装 TypeWhisper
- 在 **设置 > 高级** 下启用 TypeWhisper 本地 API 服务器
## 安装
```bash
npm install -g @typewhisper/mcp
```
从此存储库进行本地开发：
```bash
npm install
npm run build
node dist/bin.js --help
```
## MCP 配置
大多数 MCP 客户端可以通过 stdio 运行服务器：
```json
{
"mcpServers": {
"typewhisper": {
"command": "npx",
"args": ["-y", "@typewhisper/mcp"]
}
}
}
```
对于本地检查：
```json
{
"mcpServers": {
"typewhisper": {
"command": "node",
"args": ["/Users/marco/Projects/typewhisper-mcp/dist/bin.js"]
}
}
}
```
## 发现
默认情况下，服务器镜像 TypeWhisper CLI 发现行为：
1. `TYPEWHISPER_API_BASE_URL`、`TYPEWHISPER_API_PORT` 和 `TYPEWHISPER_API_TOKEN`
2. TypeWhisper 发现文件：
- macOS: `~/Library/Application Support/TypeWhisper/api-discovery.json`
- Windows: `%LOCALAPPDATA%\\TypeWhisper-UserData\\api-discovery.json`
- Windows 旧版备用： `%LOCALAPPDATA%\\TypeWhisper\\api-discovery.json`
3. 匹配的旧版 `api-port` 文件
4. `http://127.0.0.1:8978`
使用 `--dev` 或 `TYPEWHISPER_DEV=1` 读取开发发现文件（macOS 上的 `TypeWhisper-Dev` 和 Windows 上的 `TypeWhisper-DevUserData`，并带有 `TypeWhisper-Dev` 备用）。
```bash
typewhisper-mcp --dev
typewhisper-mcp --base-url http://127.0.0.1:8978 --api-token "$TYPEWHISPER_API_TOKEN"
```
## 远程 TypeWhisper 主机
MCP 服务器本身可以在任何 Node.js 平台上运行。目前，TypeWhisper 将其 API 绑定到主机的环回接口，因此通过私有隧道连接远程客户端，而不是公开暴露 API。
例如，从代理机器转发本地端口到 TypeWhisper 主机：
```bash
ssh -N -L 18978:127.0.0.1:8978 user@typewhisper-host
```
然后使用转发 URL 和来自 TypeWhisper 主机的 `api-discovery.json` 的 bearer token 启动 MCP 服务器：
```bash
TYPEWHISPER_API_BASE_URL=http://127.0.0.1:18978 \
TYPEWHISPER_API_TOKEN="your-token" \
typewhisper-mcp
```
对于 `typewhisper_transcribe_file`，绝对路径由 TypeWhisper 主机解析。因此，远程客户端必须提供存在于该主机上的路径，例如通过共享或同步目录。
## 工具
- `typewhisper_status`
- `typewhisper_list_models`
- `typewhisper_transcribe_file`
- `typewhisper_search_history`
- `typewhisper_list_dictionary_terms`
- `typewhisper_upsert_dictionary_terms`
- `typewhisper_delete_dictionary_term`
- `typewhisper_list_dictionary_corrections`
- `typewhisper_upsert_dictionary_correction`
- `typewhisper_delete_dictionary_correction`
`typewhisper_transcribe_file` 需要 TypeWhisper 主机上的绝对路径，因为 TypeWhisper 作为单独的应用程序进程运行。
录音和实时听写控件在第一个版本中故意不包含。
## 开发
```bash
npm run typecheck
npm test
npm run build
npm pack --dry-run
```
## 许可证
GPL-3.0-only
