voice-mcp-server 0.1.20 → 0.1.22

package/README.md

@@ -65,8 +65,8 @@ The system is built on a highly modular adapter pattern configured via `hydra` Y
 | | `kokoro_speaker` | High-quality, emotive local ML Text-to-Speech. |
 | | `elevenlabs_speaker` | Premium cloud-based ultra-realistic voices. |
 | **🎙️ Microphones** | `live_mic` | Direct hardware integration via PyAudio. |
-| **🤫 VAD (Activity)** | `silero_vad` | Conversational mode powered by Silero, heavily optimized for 1-second barge-ins. **(Default)** |
-| | `ptt_vad` | Manual Push-to-Talk mode. *(Note: Requires macOS Input Monitoring permissions for your terminal).* |
+| **🤫 VAD (Activity)** | `silero_vad` | Conversational mode powered by Silero, heavily optimized for 1-second barge-ins. *(Note: **Headphones are strictly required** for this mode to prevent the AI from hearing its own audio output and endlessly interrupting itself).* |
+| | `ptt_vad` | Manual Push-to-Talk / Walkie-Talkie mode. **(Default: Hold 'Shift' to talk)** |
 | **📝 STT (Transcription)**| `mlx_whisper_large_v3`| Blazing fast local transcription leveraging Apple's MLX framework. |
 
 -----
@@ -80,7 +80,7 @@ Once connected, the server equips your AI agent with two powerful MCP tools:
 The core communication loop. The AI calls this tool and passes a string of text it wants to say.
 
 1.  The server renders and plays the TTS.
-2.  The server instantly activates the microphone and listens for the user's reply via VAD. *(Note: By default, the server is configured to use Conversational Mode via Silero VAD).*
+2.  The server instantly activates the microphone and listens for the user's reply via VAD. *(Note: By default, the server is configured to use Push-To-Talk. You must press and hold the **Shift** key on your keyboard to speak or interrupt. You can ask the AI to change this!)*
 3.  The server transcribes the audio and returns the text to the AI.
 
 **Interrupt Handling (Barge-in):** If the user interrupts the AI mid-sentence, playback instantly stops. The server captures the interruption, transcribes it, and returns the response alongside a `was_interrupted: true` flag. This allows the AI to organically realize it was cut off and address the interruption naturally.
@@ -100,6 +100,10 @@ The easiest way to get started is to install the server globally via NPM. This w
 - **Node.js** (v18+)
 - **Python** (3.10, 3.11, or 3.12) *(Note: Python 3.13 is not yet supported by the Kokoro TTS library. The bridge will automatically search your system for a compatible version if your default is 3.13.)*
 
+> [!IMPORTANT]  
+> **Input Monitoring Permission:** By default, the server uses **Push-to-Talk (Hold 'Shift')** to prevent the AI from hearing its own voice through your laptop speakers and interrupting itself. For the server to detect the Shift key globally, you **must** grant Input Monitoring permissions to your terminal/CLI.
+> Go to: `System Settings` > `Privacy & Security` > `Input Monitoring` > Toggle your terminal (e.g., Cursor, iTerm, Terminal) **ON**.
+
 You must also have the required system-level audio libraries installed via [Homebrew](https://brew.sh/):
 ```bash
 brew install portaudio espeak-ng

package/config/config.yaml

@@ -11,7 +11,7 @@ defaults:
   # Available VADs: 
   #   - ptt_vad: Walkie-Talkie mode (Hold 'Shift' to talk. Instant response. Ignores TV/noise).
   #   - silero_vad: Conversational AI mode (Listens automatically. Tuned for 1-second barge-ins).
-  - vad: silero_vad
+  - vad: ptt_vad
   
   # Available STTs: mlx_whisper_large_v3 (Apple Silicon GPU), whisper_stt (Google Cloud API)
   - stt: mlx_whisper_large_v3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voice-mcp-server",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "An MCP server to allow LLMs to speak and listen via bidirectional voice loops",
   "main": "build/index.js",
   "type": "module",