commit 448aae72dc3fe29d1da5d120a127abb6b4614bec Author: waeckerlinfederowicz66-sketch Date: Mon May 18 15:52:41 2026 +0800 Initial release: FlowSpeech MCP server v0.1.0 MCP server that wraps FlowSpeech TTS API with three tools: - flowspeech_tts: single-voice text-to-speech - flowspeech_tts_multi: two-speaker dialogue synthesis - flowspeech_list_voices: list 30+ available voices diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e871be6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +dist/ +*.js.map +.env +.env.local diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..43130e9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 FlowSpeech + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..30d0dd5 --- /dev/null +++ b/README.md @@ -0,0 +1,141 @@ +# FlowSpeech MCP Server + +An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that brings [FlowSpeech](https://flowspeech.io) text-to-speech capabilities directly into your LLM workflows. + +## What is FlowSpeech? + +[FlowSpeech](https://flowspeech.io) is a context-aware text-to-speech tool that converts text into human-like audio with: + +- 🎭 **Emotion control** β€” stage directions like `***(say cheerfully: Hello!)***` +- ⏸️ **Pause control** β€” natural pacing and rhythm +- πŸŽ™οΈ **30+ voices** β€” male and female voices across moods and styles +- 🌊 **Human-like output** β€” natural-sounding synthesis for creators, educators, and developers + +## Installation + +Run the MCP server directly with npx (no install needed): + +```bash +npx mcp-flowspeech-server +``` + +Or install globally: + +```bash +npm install -g mcp-flowspeech-server +``` + +## Configuration + +Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`): + +```json +{ + "mcpServers": { + "flowspeech": { + "command": "npx", + "args": ["-y", "mcp-flowspeech-server"], + "env": { + "FLOWSPEECH_OUTPUT_DIR": "~/flowspeech-audio" + } + } + } +} +``` + +### Environment Variables + +| Variable | Description | Default | +|---|---|---| +| `FLOWSPEECH_OUTPUT_DIR` | Directory to save generated audio files | `~/.flowspeech-mcp/audio` | + +## Tools + +### `flowspeech_tts` + +Convert text to speech with a single voice. + +**Parameters:** + +| Name | Type | Required | Description | +|---|---|---|---| +| `text` | string | βœ… | Text to synthesize. Supports emotion stage directions. | +| `voice` | string | | Voice name (default: `Kore`) | +| `output_path` | string | | Custom file path for the output audio | + +**Example:** + +``` +Convert this to audio with a cheerful tone using the Puck voice: +"***(say cheerfully: Good morning, everyone!)*** Today we're going to explore something amazing." +``` + +### `flowspeech_tts_multi` + +Convert a two-speaker dialogue to speech. + +**Parameters:** + +| Name | Type | Required | Description | +|---|---|---|---| +| `text` | string | βœ… | Dialogue with `Speaker1:` and `Speaker2:` prefixes | +| `voice_a` | string | | Voice for Speaker1 (default: `Charon`) | +| `voice_b` | string | | Voice for Speaker2 (default: `Kore`) | +| `output_path` | string | | Custom file path for the output audio | + +**Example:** + +``` +Speaker1: Welcome to the show! I'm your host. +Speaker2: And I'm your co-host. Great to be here! +Speaker1: Today we're talking about AI voices. +``` + +### `flowspeech_list_voices` + +List all available voices. + +**Parameters:** + +| Name | Type | Description | +|---|---|---| +| `gender` | `male` \| `female` \| `all` | Filter by gender (default: `all`) | + +## Available Voices + +| Voice | Gender | Style | +|---|---|---| +| Puck | Male | Upbeat and playful | +| Fenrir | Male | Excitable and energetic | +| Zephyr | Female | Bright and cheerful | +| Autonoe | Female | Bright and welcoming | +| Charon | Male | Informative and narrative | +| Kore | Female | Firm and focused | +| Orus | Male | Firm and decisive | +| Iapetus | Male | Clear and professional | +| Umbriel | Male | Easy-going and relaxed | +| Callirrhoe | Female | Easy-going and soothing | +| Sulafat | Female | Warm and inviting | +| Achernar | Female | Soft and tender | +| Gacrux | Female | Mature and experienced | +| … | … | 30+ total β€” use `flowspeech_list_voices` to see all | + +## Emotion Stage Directions + +FlowSpeech supports inline emotion control using the format `***(say