agentvibes 2.0.17 → 2.0.20

package/mcp-server/WINDOWS_SETUP.md

@@ -1,277 +1,260 @@
-# AgentVibes MCP Server - Windows Setup Guide
+# 🪟 Windows Setup Guide for Claude Desktop
 
-Complete guide for setting up AgentVibes MCP server on Windows with Claude Desktop.
+**Complete beginner's guide** - Start from scratch and get AgentVibes working in 20 minutes!
 
-## Quick Start (Automatic)
+---
 
-```powershell
-cd C:\Users\Paul\AgentVibes
-npm install
-```
+## What You'll Need
 
-That's it! The `npm install` command will automatically:
-- Install Node.js dependencies
-- Install Python `mcp` package
-- Verify Python is available
+This guide assumes you're starting with **just Windows** installed. We'll install everything else together, step by step.
 
-## Voice Options for Windows
+---
 
-AgentVibes supports two TTS providers on Windows:
+## Step 1: Install Python
 
-### 1. ElevenLabs (Recommended for Windows) ⭐
+Python is needed to run AgentVibes.
 
-**Pros:**
-- ✅ Works perfectly on Windows
-- ✅ 30+ premium, natural-sounding voices
-- ✅ Multi-language support (25+ languages)
-- ✅ Easy setup - no additional software needed
+1. **Download Python**:
+   - Go to https://python.org/downloads
+   - Click the big yellow "Download Python" button
 
-**Cons:**
-- ❌ Requires API key (paid service, but has free tier)
-- ❌ Requires internet connection
+2. **Install Python**:
+   - Run the downloaded installer
+   - ⚠️ **CRITICAL**: Check the box "Add Python to PATH" at the bottom
+   - Click "Install Now"
+   - Wait for installation to complete
+   - Click "Close"
 
-**Setup:**
+3. **Verify it worked**:
+   - Press `Windows Key + R`
+   - Type `cmd` and press Enter
+   - In the black window, type: `python --version`
+   - You should see something like `Python 3.12.0`
 
-1. Get API key from https://elevenlabs.io
-2. Add to Claude Desktop config:
+---
 
-```json
-{
-  "mcpServers": {
-    "agentvibes": {
-      "command": "python",
-      "args": ["C:\\\\Users\\\\Paul\\\\AgentVibes\\\\mcp-server\\\\server.py"],
-      "env": {
-        "ELEVENLABS_API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
-```
+## Step 2: Install Node.js
 
-3. Configure in AgentVibes (from WSL):
-```bash
-cd /mnt/c/Users/Paul/AgentVibes
-.claude/hooks/provider-manager.sh switch elevenlabs
-```
+Node.js is needed to download and run AgentVibes.
 
-### 2. Piper TTS (Free, Offline)
+1. **Download Node.js**:
+   - Go to https://nodejs.org
+   - Click the big green "LTS" button (recommended for most users)
 
-**Pros:**
-- ✅ Completely free
-- ✅ Works offline
-- ✅ No API key needed
-- ✅ Privacy-focused (all local)
+2. **Install Node.js**:
+   - Run the downloaded installer
+   - Click "Next" through all the steps (defaults are fine)
+   - Click "Install"
+   - Click "Finish"
 
-**Cons:**
-- ❌ More complex Windows setup
-- ❌ Fewer voice options
-- ❌ Audio quality not as good as ElevenLabs
+3. **Verify it worked**:
+   - Press `Windows Key + R`
+   - Type `cmd` and press Enter
+   - Type: `node --version`
+   - You should see something like `v20.11.0`
 
-**Setup:**
+---
 
-Piper works on Windows but requires WSL or Windows builds:
+## Step 3: Install WSL (Windows Subsystem for Linux)
 
-**Option A: Use WSL (Easier)**
+WSL is needed for the free Piper voice system.
 
-1. Install WSL if not already:
-   ```powershell
-   wsl --install
-   ```
+1. **Open PowerShell as Administrator**:
+   - Press `Windows Key`
+   - Type `PowerShell`
+   - Right-click "Windows PowerShell"
+   - Click "Run as administrator"
+   - Click "Yes" when asked
 
-2. In WSL Ubuntu:
-   ```bash
-   pipx install piper-tts
-   ```
+2. **Install WSL**:
+   - Type this command and press Enter:
+     ```powershell
+     wsl --install
+     ```
+   - Wait for it to download and install (5-10 minutes)
 
-3. Configure audio to work from WSL → Windows:
-   - See: `setup-ubuntu-rdp-audio.sh` in the repo
+3. **Restart your computer**:
+   - After installation completes, restart Windows
+   - WSL will finish setup after restart
 
-**Option B: Windows Native (Advanced)**
+4. **Verify it worked**:
+   - Open PowerShell again (doesn't need to be as administrator this time)
+   - Type: `wsl --status`
+   - You should see status information (not an error)
 
-1. Download Piper Windows release:
-   - https://github.com/rhasspy/piper/releases
-   - Extract to `C:\Program Files\Piper\`
+---
 
-2. Add to PATH in PowerShell:
-   ```powershell
-   $env:PATH += ";C:\Program Files\Piper"
-   ```
+## Step 4: Install Claude Desktop
 
-3. Configure in AgentVibes
+Claude Desktop is the app where you'll talk to Claude with voice.
 
-**Recommendation:** For Windows, use **ElevenLabs**. It's much easier to set up and provides better voice quality.
+1. **Download Claude Desktop**:
+   - Go to https://claude.ai/download
+   - Click "Download for Windows"
 
-## Complete Installation Steps
+2. **Install Claude Desktop**:
+   - Run the downloaded installer
+   - Follow the installation steps
+   - Sign in with your Anthropic account (or create one)
 
-### 1. Prerequisites
+3. **Close Claude Desktop for now** (we'll configure it in the next step)
 
-- **Python 3.10+** installed from https://python.org
-  - During installation, check "Add Python to PATH"
-- **Node.js 16+** installed from https://nodejs.org
-- **Git** (optional, for cloning)
+---
 
-### 2. Install AgentVibes
+## Step 5: Configure AgentVibes in Claude Desktop
+
+Now we'll tell Claude Desktop to use AgentVibes.
+
+1. **Open the config file**:
+   - Press `Windows Key + R`
+   - Copy and paste this path:
+     ```
+     %APPDATA%\Claude\claude_desktop_config.json
+     ```
+   - Press Enter
+   - If asked "How do you want to open this file?", choose "Notepad"
+
+2. **Add AgentVibes configuration**:
+   - If the file is empty or just has `{}`, replace everything with this:
+     ```json
+     {
+       "mcpServers": {
+         "agentvibes": {
+           "command": "npx",
+           "args": ["-y", "agentvibes@beta", "agentvibes-mcp-server"]
+         }
+       }
+     }
+     ```
+   - If the file already has content, carefully add the `"agentvibes"` section inside `"mcpServers"`
+
+3. **Save the file**:
+   - Click "File" → "Save"
+   - Close Notepad
 
-Clone or download the repository:
+---
 
-```powershell
-cd C:\Users\Paul
-git clone https://github.com/paulpreibisch/AgentVibes.git
-cd AgentVibes
-```
+## Step 6: Install Piper Voice System
 
-### 3. Run NPM Install
+Piper needs to be installed inside WSL for the free voices to work.
 
-```powershell
-npm install
-```
+1. **Open PowerShell**
 
-This automatically installs:
-- Node.js dependencies
-- Python `mcp` package
+2. **Run the automated installer**:
+   - Copy and paste this single command and press Enter:
+     ```powershell
+     wsl -e bash -c "curl -sSL https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/.claude/hooks/piper-installer.sh | bash"
+     ```
+   - The installer will:
+     - Install pipx (if needed)
+     - Install Piper TTS
+     - Download a default voice (en_US-lessac-medium)
+   - Wait for installation (2-3 minutes)
 
-### 4. Configure Claude Desktop
+3. **When prompted** "Would you like to download voice models now?":
+   - Type `y` and press Enter
+   - This downloads the free voice model
 
-Edit: `C:\Users\Paul\AppData\Roaming\Claude\claude_desktop_config.json`
+4. **Installation complete!**
+   - You should see "🎉 Piper TTS Setup Complete!"
 
-**For ElevenLabs:**
+---
 
-```json
-{
-  "mcpServers": {
-    "agentvibes": {
-      "command": "python",
-      "args": ["C:\\\\Users\\\\Paul\\\\AgentVibes\\\\mcp-server\\\\server.py"],
-      "env": {
-        "ELEVENLABS_API_KEY": "sk-your-key-here"
-      }
-    }
-  }
-}
-```
+## Step 7: Start Using AgentVibes!
 
-**For Piper (if you set it up):**
+1. **Open Claude Desktop**
 
-```json
-{
-  "mcpServers": {
-    "agentvibes": {
-      "command": "python",
-      "args": ["C:\\\\Users\\\\Paul\\\\AgentVibes\\\\mcp-server\\\\server.py"],
-      "env": {}
-    }
-  }
-}
-```
+2. **Wait for setup** (first time only):
+   - The first time, AgentVibes MCP server needs to start (10-20 seconds)
+   - You'll see a small notification when it's ready
 
-### 5. Restart Claude Desktop
+3. **Test it**:
+   - Type: `What AgentVibes tools do you have?`
+   - Claude should list tools like `text_to_speech`, `list_voices`, etc.
 
-Close Claude Desktop completely and reopen it.
+4. **Hear your first voice**:
+   - Type: `Use text to speech to say "Hello, I'm using AgentVibes!"`
+   - You should hear audio! 🎉
 
-### 6. Test It!
+---
 
-In Claude Desktop:
+## Common Tasks
 
-```
-"What AgentVibes tools do you have?"
-```
+### Change Voice
 
-Should show: `text_to_speech`, `list_voices`, `set_voice`, etc.
+Type: `List all available voices`
 
-```
-"Use text to speech to say hello"
-```
+Then: `Switch to [voice name]`
 
-You should hear audio!
+Example: `Switch to Northern Terry voice`
 
-## Troubleshooting
+### Add Personality
+
+Type: `Set personality to pirate`
+
+Now Claude will talk like a pirate! Try: `Use text to speech to say "Hello there!"`
+
+Other personalities: `sarcastic`, `flirty`, `robot`, `zen`, `millennial`
 
-### "No module named 'mcp'"
+### Speak Different Language
 
-Run manually:
-```powershell
-pip install mcp
-# or
-python -m pip install mcp
-```
+Type: `Speak in Spanish`
 
-Verify:
-```powershell
-python -c "import mcp; print('Success!')"
-```
+Now TTS will speak in Spanish! Try: `Use text to speech to say "Hello"`
 
-### Python Not Found
+### Check Your Settings
 
-1. Install Python from https://python.org
-2. During installation, check "Add Python to PATH"
-3. Restart PowerShell
-4. Verify: `python --version`
+Type: `What's my current AgentVibes configuration?`
 
-### Audio Not Playing (ElevenLabs)
+Shows your current voice, personality, language, and provider.
 
-1. Check API key is correct
-2. Check internet connection
-3. View logs: `C:\Users\Paul\AppData\Roaming\Claude\logs\mcp-server-agentvibes.log`
+---
 
-### Audio Not Playing (Piper)
+## Troubleshooting
 
-Piper on Windows requires:
-- PulseAudio or WSL audio setup
-- See `setup-ubuntu-rdp-audio.sh` for WSL configuration
-- Or use ElevenLabs instead (much easier)
+### "I don't hear any audio"
 
-## Voice Configuration
+1. Check your Windows volume (unmuted?)
+2. Make sure speakers/headphones are plugged in
+3. Restart Claude Desktop
+4. See [Audio Troubleshooting Guide](docs/troubleshooting-audio.md)
 
-List available voices:
-```
-"List all AgentVibes voices"
-```
+### "AgentVibes tools not showing"
 
-Switch voice:
-```
-"Switch to Northern Terry voice"
-```
+1. Close Claude Desktop completely (check system tray)
+2. Reopen Claude Desktop
+3. Wait 30 seconds for MCP server to start
+4. Try again
 
-Set personality:
-```
-"Set personality to pirate"
-```
+### "Python not found" error
 
-## Advanced: Custom Instructions
+You forgot to check "Add Python to PATH" during installation!
 
-Add to Claude Desktop custom instructions for automatic TTS:
+Fix:
+1. Uninstall Python (Windows Settings → Apps)
+2. Reinstall Python
+3. **CHECK THE BOX** "Add Python to PATH"
 
-```markdown
-When I give you a task:
-1. Use text_to_speech to acknowledge before starting
-2. Perform the task
-3. Use text_to_speech to confirm completion
+---
 
-Keep messages brief (under 150 characters).
-```
+## Want Better Voice Quality?
 
-See `mcp-server/examples/custom_instructions.md` for full examples.
+The free Piper voices are good, but if you want **premium AI voices**, see:
 
-## Performance Notes
+📖 **[ElevenLabs Setup Guide](docs/elevenlabs-setup.md)** - Premium voices (paid)
 
-- **ElevenLabs**: ~1-2 second latency (API call over internet)
-- **Piper**: Near instant (runs locally)
-- **Windows Python**: Slightly slower startup than WSL Python
+---
 
-## Recommended Setup for Windows Users
+## Next Steps
 
-1. Use **ElevenLabs** for best voice quality
-2. Get a free API key (500 characters/month free tier)
-3. Upgrade to paid plan if you use it heavily
-4. Keep Piper as backup for offline use
+✅ You're all set with AgentVibes!
 
-## Support
+Want to learn more?
 
-- **Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-- **Docs**: See main README.md
-- **Logs**: `%APPDATA%\Claude\logs\mcp-server-agentvibes.log`
+- 🎭 **[Personality Guide](docs/personalities.md)** - All available personalities
+- 🎤 **[Voice Library](docs/voice-library.md)** - Browse all voices
+- 🌍 **[Language Learning Mode](docs/language-learning-mode.md)** - Learn languages while coding
 
 ---
 
-🎤 **Enjoy your talking Claude Desktop on Windows!**
+**[← Back to Main README](../README.md)**

package/mcp-server/docs/elevenlabs-setup.md

@@ -0,0 +1,213 @@
+# 🎤 ElevenLabs Premium Voice Setup
+
+**Want the best voice quality?** ElevenLabs offers premium AI voices that sound incredibly natural.
+
+⚠️ **Note**: ElevenLabs is a paid service after the free trial.
+
+---
+
+## What You Get
+
+✅ **Premium Voice Quality** - The most natural-sounding AI voices available
+
+✅ **30+ Voices** - Wide variety of accents, ages, and styles
+
+✅ **Multi-Language** - 25+ languages supported
+
+✅ **No WSL Required** - Works on Windows without Linux subsystem
+
+❌ **Costs Money** - Free trial (10,000 characters), then requires paid subscription
+
+---
+
+## Step 1: Get Your ElevenLabs API Key
+
+1. **Sign up for ElevenLabs**:
+   - Go to https://elevenlabs.io
+   - Click "Sign Up" (or "Log In" if you have an account)
+   - Complete registration
+
+2. **Get your API key**:
+   - Go to https://elevenlabs.io/app/settings/api-keys
+   - Click "Create API Key" (or copy existing key)
+   - **Save this key** - you'll need it in the next step
+
+3. **Check your free trial**:
+   - Free trial includes 10,000 characters
+   - After trial, you'll need a paid subscription
+   - See pricing: https://elevenlabs.io/pricing
+
+---
+
+## Step 2: Set Your API Key in Windows
+
+1. **Open PowerShell**:
+   - Press `Windows Key`
+   - Type `PowerShell`
+   - Click "Windows PowerShell"
+
+2. **Set the API key**:
+   - Type this command (replace `your-api-key-here` with your actual key):
+     ```powershell
+     setx ELEVENLABS_API_KEY "your-api-key-here"
+     ```
+   - Press Enter
+   - You should see: "SUCCESS: Specified value was saved."
+
+3. **Restart everything**:
+   - Close PowerShell
+   - Close Claude Desktop completely (check system tray)
+   - Wait 5 seconds
+   - Open Claude Desktop again
+
+---
+
+## Step 3: Switch to ElevenLabs Provider
+
+In Claude Desktop, type:
+
+```
+Switch to ElevenLabs provider
+```
+
+Claude will confirm the switch and you'll start using premium voices!
+
+---
+
+## Testing ElevenLabs Voices
+
+### Test Your Setup
+
+Type:
+```
+Use text to speech to say "Hello from ElevenLabs!"
+```
+
+You should hear premium quality audio!
+
+### Browse Available Voices
+
+Type:
+```
+List all available voices
+```
+
+You'll see voices like:
+- **Aria** (default, warm female)
+- **Northern Terry** (friendly male)
+- **Cowboy Bob** (western male)
+- **Jessica Anne Bogart** (professional female)
+- **Ms. Walker** (mature female)
+- And many more!
+
+### Change Voice
+
+Type:
+```
+Switch to Northern Terry voice
+```
+
+---
+
+## Managing Your Usage
+
+### Check Your Quota
+
+1. Go to https://elevenlabs.io/app/usage
+2. See how many characters you've used
+3. Monitor your free trial or subscription limit
+
+### Tips to Save Characters
+
+- Keep TTS messages short and concise
+- Use TTS for important notifications only
+- Switch to Piper (free) for less critical audio
+
+---
+
+## Switching Back to Piper (Free)
+
+Want to go back to the free voices?
+
+Type in Claude Desktop:
+```
+Switch to Piper provider
+```
+
+You can switch between providers anytime!
+
+---
+
+## Troubleshooting
+
+### "No audio output"
+
+1. **Check your API key**:
+   - Open PowerShell
+   - Type: `echo $env:ELEVENLABS_API_KEY`
+   - You should see your API key (not blank)
+
+2. **Verify internet connection**:
+   - ElevenLabs requires internet
+   - Try opening https://elevenlabs.io in your browser
+
+3. **Check quota**:
+   - Go to https://elevenlabs.io/app/usage
+   - Make sure you haven't exceeded your character limit
+
+4. **Check logs**:
+   - Press `Windows Key + R`
+   - Paste: `%APPDATA%\Claude\logs\mcp-server-agentvibes.log`
+   - Look for error messages related to ElevenLabs
+
+### "Invalid API key" error
+
+Your API key is wrong or expired:
+
+1. Go to https://elevenlabs.io/app/settings/api-keys
+2. Create a new API key
+3. Set it again in PowerShell:
+   ```powershell
+   setx ELEVENLABS_API_KEY "your-new-key-here"
+   ```
+4. Restart Claude Desktop
+
+### "Quota exceeded" error
+
+You've used all your free credits:
+
+1. Go to https://elevenlabs.io/pricing
+2. Choose a paid plan
+3. Or switch back to Piper (free):
+   ```
+   Switch to Piper provider
+   ```
+
+---
+
+## Pricing Information
+
+As of 2024:
+
+- **Free Trial**: 10,000 characters
+- **Starter Plan**: ~$5/month for 30,000 characters
+- **Creator Plan**: ~$22/month for 100,000 characters
+- **Pro Plan**: ~$99/month for 500,000 characters
+
+**Note**: Prices subject to change. Check https://elevenlabs.io/pricing for current rates.
+
+---
+
+## Next Steps
+
+✅ **You're using premium voices!**
+
+Explore more:
+
+- 🎭 **[Personality Guide](personalities.md)** - Add personality styles
+- 🌍 **[Language Learning Mode](language-learning-mode.md)** - Learn languages
+- 🎤 **[Voice Library](voice-library.md)** - Browse all ElevenLabs voices
+
+---
+
+**[← Back to Windows Setup Guide](../mcp-server/WINDOWS_SETUP.md)**