WebVoice

WebVoice MCP 服务

本地 Model Context Protocol 服务，向 Cursor、Claude Desktop 和其他 MCP 客户端提供 WebVoice REST API 工具。

从 PyPI 安装：

pip install webvoice-mcp

从源代码安装（开发）

pip install -r requirements-mcp.txt
# or editable install from repo root:
pip install -e .

配置 Cursor

选项 A — 通过 MCP 注册 Agent（无需浏览器）

1. 先添加 MCP，不要设置 WEBVOICE_API_KEY（或从任意客户端使用注册工具）。
2. 使用你的邮箱调用 webvoice_register_send_code。
3. 从邮件中读取 OTP，然后使用验证码调用 webvoice_register_verify。
4. 响应中包含 api_key（仅显示一次）、onboarding.credits、onboarding.can_use_api，以及可选的 onboarding.solana（钱包地址和用于 USDC/SOL 充值的 memo_code）。
5. 如果 can_use_api 为 true，即可使用欢迎额度立即调用 chat/TTS/STT。
6. 在 MCP 配置中设置 WEBVOICE_API_KEY 并重启 Cursor（之后可选用 Solana/PayPal 充值）。

REST 等效流程：POST /api/v1/auth/send-code/ → 使用 create_api_key: true 调用 POST /api/v1/auth/verify-code/。请参阅 API 文档。

选项 B — 浏览器注册（人工操作）

1. 登录 — 使用邮箱 OTP 或 Google（/accounts/login/）。新用户可获得欢迎额度和每日免费额度。
2. API 密钥 — 前往 API 控制面板 → 创建密钥 → 复制 wv_…（仅显示一次）。
3. 额度（可选） — 购买额度、订阅 Premium（PayPal），或使用 Solana（发送 USDC/SOL，并附上 webvoice_onboarding 中提供的个人 memo）。

余额为零时，MCP 调用会因额度不足而失败；你会收到一封包含充值链接的邮件。

MCP 配置

编辑 Cursor MCP 配置（~/.cursor/mcp.json 或 Settings → MCP）：

{
  "mcpServers": {
    "webvoice": {
      "command": "webvoice-mcp",
      "env": {
        "WEBVOICE_API_KEY": "wv_your_key_here"
      }
    }
  }
}

如果 PATH 中没有 webvoice-mcp，请使用 Python 模块形式：

{
  "mcpServers": {
    "webvoice": {
      "command": "python",
      "args": ["-m", "webvoice_mcp"],
      "cwd": "/path/to/webvoice",
      "env": {
        "WEBVOICE_API_KEY": "wv_your_key_here"
      }
    }
  }
}

可选：WEBVOICE_BASE_URL（默认值为 https://webvoice.easytaskflow.app/api/v1）。

工具

工具	描述
webvoice_register_send_code	开始注册 — 向邮箱发送 OTP
webvoice_register_verify	完成注册 → API 密钥和引导信息（额度、can_use_api）
webvoice_onboarding	额度、can_use_api、可选的 Solana 钱包/memo、充值 URL
webvoice_status	额度余额
webvoice_list_chat_models	可用的聊天模型
webvoice_list_voices	TTS 语音
webvoice_chat	聊天补全（默认使用 DeepSeek）
webvoice_tts	文本转语音 → MP3
webvoice_stt	转录本地音频文件
webvoice_translate	文本翻译
webvoice_image	MiniMax 图像生成

Agent 工作流示例

新 Agent（注册 → 使用 → 可选充值）：

1. 调用 webvoice_register_send_code → webvoice_register_verify → 保存 api_key。
2. 如果 onboarding.can_use_api 为 true：立即调用 webvoice_chat / webvoice_tts / …。
3. 可选：需要更多额度时，调用 webvoice_onboarding 获取 Solana memo 或 PayPal URL。

已有账户：

1. 让模型使用你的问题调用 webvoice_chat。
2. 调用 webvoice_tts 并指定 output_path，保存语音回复。
3. 调用 webvoice_stt 并提供录制文件的 audio_path，进行语音输入。

每次 API 调用的费用都会从你的 WebVoice 账户额度中扣除。