# WebVoice MCP Server

<!-- mcp-name: io.github.supermarco74/webvoice-mcp -->

Local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes WebVoice REST API tools to **Cursor**, Claude Desktop, and other MCP clients.

**Install from PyPI:**

```bash
pip install webvoice-mcp
```

### From source (development)

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

## Configure Cursor

### Option A — Agent registration via MCP (no browser)

1. Add MCP **without** `WEBVOICE_API_KEY` first (or use the register tools from any client).
2. Call **`webvoice_register_send_code`** with your email.
3. Read the OTP from email, then **`webvoice_register_verify`** with the code.
4. Response includes **`api_key`** (once), **`onboarding.credits`**, **`onboarding.can_use_api`**, and optional **`onboarding.solana`** (wallet + `memo_code` for USDC/SOL top-up).
5. If `can_use_api` is true, use chat/TTS/STT immediately with welcome credits.
6. Set `WEBVOICE_API_KEY` in MCP config and restart Cursor (optional Solana/PayPal top-up later).

REST equivalent: `POST /api/v1/auth/send-code/` → `POST /api/v1/auth/verify-code/` with `create_api_key: true`. See [API docs](https://webvoice.easytaskflow.app/api/documentation/#agent-registration).

### Option B — Browser signup (human)

1. **Login** — email OTP or Google (`/accounts/login/`). New users get welcome + daily free credits.
2. **API key** — [API dashboard](https://webvoice.easytaskflow.app/api/) → Create key → copy `wv_…` (shown once).
3. **Credits (optional)** — [Buy credits](https://webvoice.easytaskflow.app/billing/purchase/), [Premium](https://webvoice.easytaskflow.app/billing/subscriptions/) (PayPal), or **Solana** (send USDC/SOL with your personal memo from `webvoice_onboarding`).

When balance is zero, MCP calls fail with insufficient credits; you receive an email with a recharge link.

### MCP config

Edit Cursor MCP config (`~/.cursor/mcp.json` or **Settings → MCP**):

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

If `webvoice-mcp` is not on PATH, use Python module form:

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

Optional: `WEBVOICE_BASE_URL` (default `https://webvoice.easytaskflow.app/api/v1`).

## Tools

| Tool | Description |
|------|-------------|
| `webvoice_register_send_code` | Start registration — OTP to email |
| `webvoice_register_verify` | Complete registration → API key + onboarding (credits, can_use_api) |
| `webvoice_onboarding` | Credits, can_use_api, optional Solana wallet/memo, recharge URLs |
| `webvoice_status` | Credits balance |
| `webvoice_list_chat_models` | Available chat models |
| `webvoice_list_voices` | TTS voices |
| `webvoice_chat` | Chat completions (DeepSeek default) |
| `webvoice_tts` | Text-to-speech → MP3 |
| `webvoice_stt` | Transcribe local audio file |
| `webvoice_translate` | Text translation |
| `webvoice_image` | MiniMax image generation |

## Example agent flow

**New agent (register → use → optional top-up):**

1. `webvoice_register_send_code` → `webvoice_register_verify` → save `api_key`.
2. If `onboarding.can_use_api`: call `webvoice_chat` / `webvoice_tts` / … immediately.
3. Optional: `webvoice_onboarding` → Solana memo or PayPal URLs when you need more credits.

**Existing account:**

1. Ask the model to call `webvoice_chat` with your question.
2. Call `webvoice_tts` with `output_path` to save spoken reply.
3. Call `webvoice_stt` with a recorded `audio_path` for voice input.

Credits are billed on your WebVoice account per API call.