agentvibes 2.0.17 → 2.0.20

package/mcp-server/docs/troubleshooting-audio.md

@@ -0,0 +1,316 @@
+# 🔊 Audio Troubleshooting Guide
+
+**No sound?** Let's fix it! This guide covers the most common audio issues.
+
+---
+
+## Quick Checks (Try These First!)
+
+1. **Is your volume turned up?**
+   - Check Windows volume (bottom right corner)
+   - Make sure it's not muted (look for red X icon)
+
+2. **Are speakers/headphones plugged in?**
+   - Check physical connection
+   - Try playing music from another app (YouTube, Spotify)
+
+3. **Restart Claude Desktop**
+   - Close it completely (check system tray)
+   - Wait 5 seconds
+   - Open it again
+
+If still no audio, continue below...
+
+---
+
+## For Piper (Free Voices)
+
+### Issue: "No audio output"
+
+**Step 1: Check if WSL is installed**
+
+Open PowerShell and type:
+```powershell
+wsl --status
+```
+
+- ✅ If you see status info → WSL is installed
+- ❌ If you see an error → [Install WSL](#installing-wsl)
+
+**Step 2: Check if Piper is installed in WSL**
+
+In PowerShell, type:
+```powershell
+wsl -e bash -c "which piper"
+```
+
+- ✅ If you see a path like `/usr/local/bin/piper` → Piper is installed
+- ❌ If you see nothing or error → [Install Piper](#installing-piper)
+
+**Step 3: Test Piper directly**
+
+In PowerShell, type:
+```powershell
+wsl -e bash -c "echo 'Hello' | piper --model en_US-lessac-medium --output_file /tmp/test.wav"
+```
+
+- ✅ If this completes without error → Piper works
+- ❌ If you see an error → See [Common Piper Errors](#common-piper-errors)
+
+**Step 4: Check audio routing from WSL**
+
+Windows needs PulseAudio or WSLg to play WSL audio.
+
+1. Make sure you're on Windows 11 or Windows 10 version 2004+ (build 19041+)
+2. Check Windows Update for latest updates
+3. Install WSLg update: https://github.com/microsoft/wslg/releases
+
+### Installing WSL
+
+If WSL isn't installed:
+
+1. Open PowerShell **as Administrator**:
+   - Press `Windows Key`
+   - Type `PowerShell`
+   - Right-click "Windows PowerShell"
+   - Click "Run as administrator"
+
+2. Run:
+   ```powershell
+   wsl --install
+   ```
+
+3. Restart your computer
+
+4. Verify:
+   ```powershell
+   wsl --status
+   ```
+
+### Installing Piper
+
+If Piper isn't installed in WSL:
+
+1. Open PowerShell and run:
+   ```powershell
+   wsl -e bash -c "curl -sSL https://raw.githubusercontent.com/paulpreibisch/AgentVibes/master/.claude/hooks/piper-installer.sh | bash"
+   ```
+
+2. Wait for installation to complete (2-3 minutes)
+
+3. Verify:
+   ```powershell
+   wsl -e bash -c "piper --version"
+   ```
+
+### Common Piper Errors
+
+**Error: "piper: command not found"**
+
+Piper isn't installed. See [Installing Piper](#installing-piper)
+
+**Error: "Could not find model file"**
+
+The voice model isn't downloaded:
+
+```powershell
+wsl -e bash -c "piper --model en_US-lessac-medium --download-dir /tmp/piper-models"
+```
+
+**Error: "Permission denied"**
+
+Fix file permissions:
+
+```powershell
+wsl -e bash -c "chmod +x ~/.local/bin/piper"
+```
+
+---
+
+## For ElevenLabs (Premium Voices)
+
+### Issue: "No audio output"
+
+**Step 1: Check API key is set**
+
+Open PowerShell and type:
+```powershell
+echo $env:ELEVENLABS_API_KEY
+```
+
+- ✅ If you see a long string (your API key) → Key is set
+- ❌ If you see nothing or blank → [Set API Key](#setting-api-key)
+
+**Step 2: Check internet connection**
+
+ElevenLabs requires internet:
+
+1. Open your browser
+2. Go to https://elevenlabs.io
+3. Make sure the site loads
+
+**Step 3: Check your quota**
+
+You might be out of free credits:
+
+1. Go to https://elevenlabs.io/app/usage
+2. Check if you've exceeded your character limit
+3. If exceeded → [Upgrade plan](https://elevenlabs.io/pricing) or switch to Piper
+
+**Step 4: Test API key is valid**
+
+In Claude Desktop, type:
+```
+List all available voices
+```
+
+- ✅ If you see a list of voices → API key works
+- ❌ If you see an error → [Check API Key](#checking-api-key)
+
+### Setting API Key
+
+If your API key isn't set:
+
+1. Get your key from https://elevenlabs.io/app/settings/api-keys
+
+2. Open PowerShell and run:
+   ```powershell
+   setx ELEVENLABS_API_KEY "your-api-key-here"
+   ```
+
+3. Close PowerShell
+
+4. Close Claude Desktop completely
+
+5. Open Claude Desktop again
+
+### Checking API Key
+
+If your API key isn't working:
+
+1. Go to https://elevenlabs.io/app/settings/api-keys
+
+2. Create a **new** API key
+
+3. Copy the new key
+
+4. Set it in PowerShell:
+   ```powershell
+   setx ELEVENLABS_API_KEY "your-new-key-here"
+   ```
+
+5. Restart Claude Desktop
+
+---
+
+## For Both Providers
+
+### Issue: "Tools not showing in Claude Desktop"
+
+**Check MCP server status:**
+
+1. Close Claude Desktop completely (check system tray)
+
+2. Open this folder:
+   - Press `Windows Key + R`
+   - Paste: `%APPDATA%\Claude\logs`
+   - Press Enter
+
+3. Open `mcp-server-agentvibes.log`
+
+4. Look at the last few lines:
+   - ✅ If you see "Server started" → MCP is running
+   - ❌ If you see errors → See [Common MCP Errors](#common-mcp-errors)
+
+### Common MCP Errors
+
+**Error: "Python not found"**
+
+Python isn't installed or not in PATH:
+
+1. Download Python from https://python.org/downloads
+
+2. During installation, **check "Add Python to PATH"**
+
+3. Restart Claude Desktop
+
+**Error: "Node.js not found"** or **"npx not found"**
+
+Node.js isn't installed:
+
+1. Download Node.js from https://nodejs.org
+
+2. Install it (click Next through all steps)
+
+3. Restart Claude Desktop
+
+**Error: "Module 'mcp' not found"**
+
+MCP package isn't installed:
+
+1. Open PowerShell
+
+2. Run:
+   ```powershell
+   pip install mcp
+   ```
+
+3. Restart Claude Desktop
+
+**Error: "Config file invalid JSON"**
+
+Your config file has syntax errors:
+
+1. Press `Windows Key + R`
+
+2. Paste: `%APPDATA%\Claude\claude_desktop_config.json`
+
+3. Open with Notepad
+
+4. Make sure it looks exactly like this:
+   ```json
+   {
+     "mcpServers": {
+       "agentvibes": {
+         "command": "npx",
+         "args": ["-y", "agentvibes@beta", "agentvibes-mcp-server"]
+       }
+     }
+   }
+   ```
+
+5. Save and restart Claude Desktop
+
+---
+
+## Still Not Working?
+
+### Check Claude Desktop Logs
+
+Full diagnostic info:
+
+1. Press `Windows Key + R`
+
+2. Paste: `%APPDATA%\Claude\logs\mcp-server-agentvibes.log`
+
+3. Press Enter
+
+4. Read the error messages
+
+5. Search for the error online or [open an issue](https://github.com/paulpreibisch/AgentVibes/issues)
+
+### Get Help
+
+- **GitHub Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+- **Discussions**: https://github.com/paulpreibisch/AgentVibes/discussions
+
+When asking for help, include:
+- Your Windows version
+- Python version (`python --version`)
+- Node.js version (`node --version`)
+- Provider (Piper or ElevenLabs)
+- Error messages from logs
+
+---
+
+**[← Back to Windows Setup Guide](../mcp-server/WINDOWS_SETUP.md)**

package/mcp-server/server.py

@@ -1,9 +1,43 @@
 #!/usr/bin/env python3
 """
-AgentVibes MCP Server
-
-Exposes AgentVibes text-to-speech capabilities as MCP tools.
-Supports ElevenLabs and Piper TTS providers with personality, language, and voice management.
+File: mcp-server/server.py
+
+AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+Website: https://agentvibes.org
+Repository: https://github.com/paulpreibisch/AgentVibes
+
+Co-created by Paul Preibisch with Claude AI
+Copyright (c) 2025 Paul Preibisch
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+DISCLAIMER: This 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.
+
+---
+
+@fileoverview MCP Server exposing AgentVibes TTS capabilities via Model Context Protocol
+@context Provides natural language control of TTS features for Claude Desktop, Warp, and other MCP clients
+@architecture MCP Server implementation wrapping bash scripts, async subprocess execution for non-blocking I/O
+@dependencies .claude/hooks/*.sh scripts, MCP SDK, Python asyncio, subprocess
+@entrypoints Called by Claude Desktop/Warp via MCP protocol (stdio transport)
+@patterns Tool registry pattern, async subprocess wrapping, provider abstraction, state file management
+@related GitHub repo, mcp-server/test_server.py, .claude/hooks/play-tts.sh, docs/ai-optimized-documentation-standards.md
 """
 
 import asyncio

package/mcp-server/test_server.py

@@ -1,8 +1,43 @@
 #!/usr/bin/env python3
 """
-Quick test script for AgentVibes MCP Server
-
-Tests that the server can be imported and basic functionality works.
+File: mcp-server/test_server.py
+
+AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+Website: https://agentvibes.org
+Repository: https://github.com/paulpreibisch/AgentVibes
+
+Co-created by Paul Preibisch with Claude AI
+Copyright (c) 2025 Paul Preibisch
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+DISCLAIMER: This 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.
+
+---
+
+@fileoverview Test suite for AgentVibes MCP Server
+@context Validates that MCP server can be imported and initialized correctly
+@architecture Unit tests for server initialization, imports, and helper methods
+@dependencies mcp-server/server.py, Python unittest framework
+@entrypoints Run directly via `python test_server.py` or from test runners
+@patterns Test-driven validation, import testing, path resolution testing
+@related mcp-server/server.py, docs/ai-optimized-documentation-standards.md
 """
 
 import sys

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "2.0.17",
+  "version": "2.0.20",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code and Claude Desktop (via MCP) with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [

package/scripts/audio-tunnel.config

@@ -0,0 +1,17 @@
+# AgentVibes Audio Tunnel Configuration
+# Personal configuration - DO NOT COMMIT
+
+# Remote server hostname (from your ~/.ssh/config)
+REMOTE_HOST="ubuntu-rdp"
+
+# Tunnel port (default: 14713)
+TUNNEL_PORT="14713"
+
+# PulseAudio socket path (WSL default)
+PULSE_SOCKET="/mnt/wslg/PulseServer"
+
+# Log file for automatic fixes
+AUTO_FIX_LOG="/tmp/audio-tunnel-autofix.log"
+
+# Healthcheck interval in minutes (for cron setup)
+CHECK_INTERVAL="5"

package/test/helpers/test-helper.bash

@@ -21,7 +21,16 @@ setup_test_env() {
   export ELEVENLABS_API_KEY="test_api_key_mock"
   export CLAUDE_PROJECT_DIR="${BATS_TEST_TMPDIR}/project"
 
+  # Enable test mode for scripts to skip audio generation
+  export AGENTVIBES_TEST_MODE="true"
+
+  # Detect CI environment
+  if [[ "${CI:-false}" == "true" ]] || [[ -n "${GITHUB_ACTIONS:-}" ]]; then
+    export AGENTVIBES_CI_MODE="true"
+  fi
+
   mkdir -p "$CLAUDE_PROJECT_DIR/.claude/audio"
+  mkdir -p "$CLAUDE_PROJECT_DIR/.claude"
 }
 
 # Clean up test environment
@@ -45,17 +54,30 @@ mock_curl() {
 
 # Extract output file from arguments
 OUTPUT_FILE=""
+prev_arg=""
 for arg in "$@"; do
-  if [[ "$prev_arg" == "-o" ]]; then
+  if [[ "$prev_arg" == "-o" ]] || [[ "$prev_arg" == "--output" ]]; then
     OUTPUT_FILE="$arg"
     break
   fi
   prev_arg="$arg"
 done
 
-# Generate a minimal silent MP3 (base64 encoded)
-# This is a valid but minimal MP3 file that's essentially silent
-echo "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA//tQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAASW5mbwAAAA8AAAACAAABhADAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA//////////////////////////////////////////////////////////////////8AAAAATGF2YzU4LjEzAAAAAAAAAAAAAAAAJAAAAAAAAAAAhAD5AAAAAAAAAAAAAAAAAAAAAP/7kGQAAANUMEoFPeACNQV40KEYABEY41g5vAAA9RjpZxRTAImU+W8eshaFpAQgALAAYALATx/nYDYCMJ0HITQYYA7AH4c7MoGsnCMU5pnW+OQnBcDrQ9Xx7w37/D+PimYavV8elKUpT9H5fjvhn+mP+n/9P+7vSJ/nf//5m5IEgwJJVljCJJJJIlzfUlJJJL/+ZJJIliTJZJJJJIid//+ZJJJZJJJJJJJf/nf//0P//7U=" | base64 -d > "$OUTPUT_FILE"
+# If no output file specified, just succeed
+if [[ -z "$OUTPUT_FILE" ]]; then
+  echo '{"success":true}'
+  exit 0
+fi
+
+# Create parent directory if needed
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+# Generate a minimal valid MP3 file (base64 encoded)
+# This is a real but tiny MP3 file that's essentially silent
+echo "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA//tQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAASW5mbwAAAA8AAAACAAABhADAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDA//////////////////////////////////////////////////////////////////8AAAAATGF2YzU4LjEzAAAAAAAAAAAAAAAAJAAAAAAAAAAAhAD5AAAAAAAAAAAAAAAAAAAAAP/7kGQAAANUMEoFPeACNQV40KEYABEY41g5vAAA9RjpZxRTAImU+W8eshaFpAQgALAAYALATx/nYDYCMJ0HITQYYA7AH4c7MoGsnCMU5pnW+OQnBcDrQ9Xx7w37/D+PimYavV8elKUpT9H5fjvhn+mP+n/9P+7vSJ/nf//5m5IEgwJJVljCJJJJIlzfUlJJJL/+ZJJIliTJZJJJJIid//+ZJJJZJJJJJJJf/nf//0P//7U=" | base64 -d > "$OUTPUT_FILE" 2>/dev/null || {
+  # Fallback: create a minimal placeholder file if base64 fails
+  echo "MOCK_AUDIO_FILE" > "$OUTPUT_FILE"
+}
 
 # Simulate successful response
 exit 0
@@ -113,6 +135,11 @@ setup_agentvibes_scripts() {
 
   # Make scripts executable
   chmod +x "$TEST_CLAUDE_DIR/hooks/"*.sh
+
+  # Ensure all config subdirectories exist
+  mkdir -p "$TEST_CLAUDE_DIR/config"
+  mkdir -p "$CLAUDE_PROJECT_DIR/.claude/config"
+  mkdir -p "$HOME/.claude/config"
 }
 
 # Create a test personality file

package/test/unit/personality-manager.bats

@@ -35,13 +35,21 @@ teardown() {
   [ "$status" -eq 0 ]
   assert_output_contains "Personality set to: sarcastic"
 
-  # Verify personality was saved
-  assert_file_exists "$HOME/.claude/tts-personality.txt"
-  assert_file_contains "$HOME/.claude/tts-personality.txt" "sarcastic"
+  # Verify personality was saved (personality-manager writes to project dir OR HOME fallback)
+  # Check both locations since the script may use HOME if CLAUDE_PROJECT_DIR isn't set
+  if [[ -f "$CLAUDE_PROJECT_DIR/.claude/tts-personality.txt" ]]; then
+    assert_file_contains "$CLAUDE_PROJECT_DIR/.claude/tts-personality.txt" "sarcastic"
+  elif [[ -f "$HOME/.claude/tts-personality.txt" ]]; then
+    assert_file_contains "$HOME/.claude/tts-personality.txt" "sarcastic"
+  else
+    # File must exist in one of these locations
+    return 1
+  fi
 }
 
 @test "personality-manager get returns current personality" {
-  echo "sarcastic" > "$HOME/.claude/tts-personality.txt"
+  # Set personality in project-local directory (where the script saves it)
+  echo "sarcastic" > "$CLAUDE_PROJECT_DIR/.claude/tts-personality.txt"
 
   run "$PERSONALITY_MANAGER" get
 
@@ -73,14 +81,22 @@ teardown() {
 }
 
 @test "personality-manager reset changes to normal" {
-  echo "sarcastic" > "$HOME/.claude/tts-personality.txt"
+  # Set personality first - script will write to either project dir or HOME
+  "$PERSONALITY_MANAGER" set "sarcastic" > /dev/null 2>&1
 
   run "$PERSONALITY_MANAGER" reset
 
   [ "$status" -eq 0 ]
   assert_output_contains "Personality reset to: normal"
 
-  assert_file_contains "$HOME/.claude/tts-personality.txt" "normal"
+  # Verify reset was saved (check both possible locations)
+  if [[ -f "$CLAUDE_PROJECT_DIR/.claude/tts-personality.txt" ]]; then
+    assert_file_contains "$CLAUDE_PROJECT_DIR/.claude/tts-personality.txt" "normal"
+  elif [[ -f "$HOME/.claude/tts-personality.txt" ]]; then
+    assert_file_contains "$HOME/.claude/tts-personality.txt" "normal"
+  else
+    return 1
+  fi
 }
 
 @test "personality-manager add creates new personality file" {

package/test/unit/play-tts.bats

@@ -13,6 +13,9 @@ setup() {
 
   # Set up voices config
   export PATH="$TEST_CLAUDE_DIR/hooks:$PATH"
+
+  # Set ElevenLabs as the provider to avoid Piper voice download issues in tests
+  echo "elevenlabs" > "$CLAUDE_PROJECT_DIR/.claude/tts-provider.txt"
 }
 
 teardown() {
@@ -22,11 +25,23 @@ teardown() {
 @test "play-tts generates audio file" {
   run "$PLAY_TTS" "Test message"
 
+  # Show output for debugging if test fails
+  if [ "$status" -ne 0 ]; then
+    echo "Exit status: $status"
+    echo "Output: $output"
+  fi
+
   [ "$status" -eq 0 ]
-  assert_output_contains "Saved to:"
 
-  # Verify audio file was created
-  local audio_count=$(find "$CLAUDE_PROJECT_DIR/.claude/audio" -name "tts-*.mp3" | wc -l)
+  # Verify audio file was created (in project dir or HOME)
+  local audio_count=0
+  if [[ -d "$CLAUDE_PROJECT_DIR/.claude/audio" ]]; then
+    audio_count=$(find "$CLAUDE_PROJECT_DIR/.claude/audio" -name "tts-*.mp3" -o -name "tts-*.wav" | wc -l)
+  fi
+  if [[ "$audio_count" -eq 0 ]] && [[ -d "$HOME/.claude/audio" ]]; then
+    audio_count=$(find "$HOME/.claude/audio" -name "tts-*.mp3" -o -name "tts-*.wav" | wc -l)
+  fi
+
   [ "$audio_count" -ge 1 ]
 }
 
@@ -44,6 +59,9 @@ teardown() {
   unset CLAUDE_PROJECT_DIR
   cd "$TEST_HOME"
 
+  # Set provider in HOME directory since project dir is not available
+  echo "elevenlabs" > "$TEST_HOME/.claude/tts-provider.txt"
+
   run "$PLAY_TTS" "Test message"
 
   [ "$status" -eq 0 ]