mirror of
https://github.com/waeckerlinfederowicz66-sketch/mcp-flowspeech-server.git
synced 2026-11-16 20:50:49 +00:00
80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# FlowSpeech MCP Server
|
|
|
|
Use [FlowSpeech](https://flowspeech.io) speech generation from an MCP client. Version 0.2.0 uses the public API v1: create a job, wait for completion, download the WAV, and save it locally.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 20.3 or newer.
|
|
- A FlowSpeech developer API key from [API settings](https://flowspeech.io/settings/apikeys).
|
|
- Active paid Basic, Pro or Scale API access for generation. Trials do not include API access; generated speech consumes account credits.
|
|
|
|
Keep keys in your MCP client's local environment or secret manager, not in prompts or public configuration files.
|
|
|
|
## Configuration
|
|
|
|
Set `FLOWSPEECH_API_KEY` in the environment used to launch your MCP client. A stdio configuration is:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"flowspeech": {
|
|
"command": "npx",
|
|
"args": ["-y", "mcp-flowspeech-server@0.2.0"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The MCP client must pass the key to its child process. Clients which do not inherit environment variables need a private `env` entry or their own secret configuration.
|
|
|
|
| Variable | Meaning | Default |
|
|
| --- | --- | --- |
|
|
| `FLOWSPEECH_API_KEY` | Required developer key | None |
|
|
| `FLOWSPEECH_OUTPUT_DIR` | Local output directory; `~/` is expanded | `~/.flowspeech-mcp/audio` |
|
|
| `FLOWSPEECH_TIMEOUT_MS` | Total operation deadline, at most 7200000 ms | `120000` |
|
|
| `FLOWSPEECH_BASE_URL` | Trusted API origin; never use an untrusted key recipient | `https://flowspeech.io` |
|
|
|
|
HTTP is allowed only for loopback test servers. Audio downloads never include the API key. Redirects are rejected, and audio downloads are limited to 100 MiB.
|
|
|
|
## Tools
|
|
|
|
| Tool | Arguments | Result |
|
|
| --- | --- | --- |
|
|
| `flowspeech_tts` | Required `text`; optional `voice` (Kore), `output_path`, `request_id` | Local WAV path, job ID, request ID and usage |
|
|
| `flowspeech_tts_multi` | Required labelled `text`; optional `voice_a` (Charon), `voice_b` (Kore), `output_path`, `request_id` | Local WAV path and recovery IDs |
|
|
| `flowspeech_list_voices` | Optional `gender`: male, female or all | Current authenticated voice catalog |
|
|
| `flowspeech_quota` | None | Available, remaining and reserved credits |
|
|
| `flowspeech_get_job` | Required UUID `job_id` | Current job status and result |
|
|
|
|
Two-speaker input uses one label per turn. Continuation lines belong to the preceding speaker:
|
|
|
|
```text
|
|
Speaker1: Welcome.[pause:2s]Let's begin.
|
|
Speaker2: Thanks for inviting me.
|
|
Speaker1: What should we cover first?
|
|
```
|
|
|
|
Output is 24 kHz, mono, 16-bit WAV. Existing output files are never overwritten. Anyone holding a result URL can download it, so keep job results and recordings private when appropriate.
|
|
|
|
## Recovery and migration
|
|
|
|
Version 0.1.0 called the retired synchronous endpoint. Upgrade the npm package and restart your MCP client. All tools now require a developer key, including voice listing. The three original tool names remain available, and two read-only tools have been added.
|
|
|
|
The server submits `{ "input": ... }` with a UUID idempotency key, polls no faster than five seconds, honors a longer `Retry-After`, and downloads `result.url`. It does not expect an API Base64 response. Transient API retries preserve the exact request ID and body, with at most five attempts per API request.
|
|
|
|
For deliberate recovery, supply a UUID `request_id` and reuse it with unchanged text and voices. Errors include available recovery IDs. A timeout or client cancellation stops local waiting; it does not cancel a server-side job. Use `flowspeech_get_job` to inspect it. A failed download or local save should be retried from the existing result rather than starting another recording. A terminal failed/cancelled job requires a new UUID only when intentionally requesting a new attempt.
|
|
|
|
## Development and tests
|
|
|
|
```sh
|
|
npm ci --ignore-scripts
|
|
npm test
|
|
npm pack --dry-run
|
|
```
|
|
|
|
Tests cover mocked v1 contracts and a loopback HTTP server exercised through the built MCP stdio process. They do not call paid production generation. See [CHANGELOG.md](CHANGELOG.md) and the [public API documentation](https://flowspeech.io/docs/public-api).
|
|
|
|
## License
|
|
|
|
MIT
|