agent-voice-mcp-minus

agent-voice-mcp Erweiterte Version · Lokaler MCP-Sprachansagedienst, der KI-Programmierassistenten (Trae / Claude Desktop / Cursor usw.) Sprachansagen zum Aufgabenfortschritt bietet und tiefgreifend an das 火山引擎豆包语音合成大模型 (seed-tts) angepasst ist.

Dieses Projekt ist ein Fork von al96169/agent-voice-mcp (Autor Antonio Liang, MIT-Lizenz). Darauf aufbauend wurden umfangreiche praktische Optimierungen für die 火山引擎-v3-Schnittstelle und reale Nutzungsszenarien vorgenommen. Das Original ist der Kern, dieses Projekt ist der Kern + praxisnahe Erweiterungen. Alle Erweiterungen können über Konfigurationsschalter deaktiviert werden und fallen auf ein Verhalten nahe dem Original zurück.

Erweiterte Funktionen (gegenüber Original 1.2.0)

1. Installation

Voraussetzungen

• Node.js ≥ 18 (Herunterladen)

• Windows (Cloud-Synthese ist plattformübergreifend verfügbar; SAPI-Fallback und Hinweis-Pieptöne sind Windows-exklusiv, auf anderen Plattformen erfolgt automatisch eine Herabstufung)

• 火山引擎-Konto (Der Sprachsynthese-Großmodell-Dienst muss aktiviert sein, siehe Schritt 2)

Schritt 1: MCP-Client konfigurieren

Variante A · Direkt mit npx ausführen (empfohlen, kein Klonen nötig)

Fügen Sie in der MCP-Client-Konfiguration Folgendes hinzu (bei Trae: .trae/mcp.json im Projektverzeichnis; bei Claude Desktop: claude_desktop_config.json; bei Cursor: .cursor/mcp.json):

{
  "mcpServers": {
    "agent-voice": {
      "command": "npx",
      "args": ["-y", "github:doer1296/agent-voice-mcp-minus"]
    }
  }
}

Variante B · Repository klonen und lokal ausführen (empfohlen für Benutzer, die Code ändern möchten)

git clone https://github.com/doer1296/agent-voice-mcp-minus.git
cd agent-voice-mcp-minus
npm install

Stellen Sie die MCP-Konfiguration auf eine direkte Node-Verbindung um (schnellerer Start und unabhängig von der npm-Registry):

{
  "mcpServers": {
    "agent-voice": {
      "command": "node",
      "args": ["D:/your/path/agent-voice-mcp-minus/dist/index.js"]
    }
  }
}

Nach Abschluss der Konfiguration starten Sie den Client neu / öffnen eine neue Sitzung. Der MCP-Dienst sagt beim Start „agent-voice-Dienst gestartet“, um die Bereitschaft anzuzeigen.

Schritt 2: 火山引擎-Zugangsdaten abrufen

1. Registrieren/Anmelden bei 火山引擎

2. In der Konsole nach „Sprachtechnologie“ suchen → Dienst „Sprachsynthese-Großmodell“ aktivieren (neue Benutzer erhalten ein kostenloses Kontingent)

3. Auf der Seite „API Key-Verwaltung“ einen X-Api-Key erstellen und abrufen

4. Hinweis: Es muss die zur verwendeten Stimme passende Modellressource aktiviert sein (seed-tts-1.0 oder seed-tts-2.0, siehe Großmodelleinstellung)

Kostenlose Alternative: Das Original enthält eine integrierte Edge TTS-Engine (kostenlose Online-Synthese von Microsoft, kein API-Key erforderlich, Hunderte von Stimmen). Setzen Sie engine auf "edge-tts", um sie zu verwenden. Details finden Sie in der README des Originals.

Schritt 3: Konfigurationsdatei erstellen

Kopieren Sie config.example.json aus diesem Repository nach:

Windows: C:\Users\<你的用户名>\.agent-voice\config.json
macOS / Linux: ~/.agent-voice/config.json

Dann ersetzen Sie das Feld apiKey durch Ihren X-Api-Key (eine von zwei Optionen):

• Direkt im Klartext: "apiKey": "你的key"

• Umgebungsvariable verwenden (empfohlen): "${VOLCANO_API_KEY}" beibehalten und dann die Systemumgebungsvariable VOLCANO_API_KEY=你的key setzen (die Konfigurationsdatei unterstützt die Syntax ${任意环境变量名}, um zu vermeiden, dass der Key im Klartext gespeichert wird)

2. Aufruf (Agent-seitige Verwendung)

Der MCP-Dienst registriert das Tool speak; der Agent kann es aufrufen, um Ansagen abzuspielen:

Empfehlung: Nutzen Sie Projektregeln, damit der Agent den Aufgabenlebenszyklus automatisch ansagt. Fügen Sie in .trae/rules/project_rules.md von Trae (oder in CLAUDE.md von Claude) Folgendes hinzu:

在每次任务中，调用 agent-voice MCP 进行语音播报：
1. 任务开始时 — scene="task_start"
2. 每个子任务完成时 — scene="milestone"
3. 任务全部完成时 — scene="task_complete"
4. 遇到错误时 — scene="task_error"
5. 需要用户确认时 — scene="need_interaction"

Aufrufbeispiel:

speak(text="开始执行任务：重构登录模块", scene="task_start", emotion="calm")
speak(text="任务完成，测试全部通过", scene="task_complete", emotion="happy")

Weitere Tools: stop (stoppt die aktuelle Ansage und leert die Warteschlange), get_voices (listet verfügbare Stimmen auf), get_roles (listet konfigurierte Rollen auf).

3. Großmodell einstellen (Modellauswahl)

cloud.resourceId in config.json bestimmt das verwendete Sprachsynthese-Großmodell:

⚠️ Stimme und Modellversion müssen zusammenpassen: Eine _moon_bigtts-Stimme kombiniert mit seed-tts-2.0 (oder umgekehrt) führt zu HTTP 403 „Ressource nicht autorisiert“. Beim Wechsel des Modells denken Sie daran, die Stimmen-ID entsprechend mitzuändern; außerdem muss der passende Modelldienst in der 火山引擎-Konsole aktiviert sein.

Auswahlhinweis: 1.0 ist stabil, bietet viele Stimmen und ausgereifte Dokumentation; 2.0 unterstützt neue Fähigkeiten wie Stimmklonierung. Alle Optimierungen dieses Projekts basieren auf praktischen Tests mit 1.0.

4. Stimme wechseln

Ändern Sie cloud.voice in config.json (sowie die jeweiligen voice-Felder in den Szenariokonfigurationen) und stellen Sie sicher, dass es mit der resourceId-Version übereinstimmt:

seed-tts-1.0 示例：
  zh_female_daimengchuanmei_moon_bigtts   呆萌川妹（甜美女声，本项目默认）
  zh_female_qingxinnvsheng_mars_bigtts    清新女声

seed-tts-2.0 示例：
  zh_female_vv_uranus_bigtts              温柔女声
  zh_male_*.uranus_bigtts                 男声系列

Die vollständige Stimmliste finden Sie in der Dokumentation der 火山引擎-Stimmbibliothek.

5. Lautstärke / Sprechgeschwindigkeit einstellen

Lautstärke volume (Standard 1.3):

• Zuordnung: loudness_rate = (volume − 1) × 100, d. h. 1.0 = ursprüngliche Lautstärke, 1.3 = +30 % (im Test RMS-Verstärkung ca. +29 %, nahezu linear)

• Empfohlener Wertebereich 0.5 – 2.0; 2.0 = +100 % (Server-Obergrenze)

• Der globale Standardwert liegt in der obersten Ebene volume; jedes Szenario kann ihn separat überschreiben (scenes.*.volume)

Sprechgeschwindigkeit rate (Standard 200):

• Zuordnung: speech_rate = (rate / 200 − 1) × 100, d. h. 200 = Originalgeschwindigkeit, 220 = +10 %, 180 = −10 %

• Standard-Szenarioverlauf (aus praktischen Tests dieses Projekts empfohlen): Start 190 → Interaktion 200 → Meilenstein/Fehler 210 → Abschluss 220

6. Bluetooth-Vorlaufstille (wichtig)

cloud.leadingSilence (Standard 1500, also 1,5 Sekunden):

Dieser Parameter ist für Bluetooth-Kopfhörer-Benutzer gedacht. Der Aufbau der Bluetooth-Audioverbindung dauert etwa 1–2 Sekunden. Zu Beginn der Ansage sind die Kopfhörer oft noch nicht verbunden, sodass das erste Zeichen von Verbindungsgeräuschen verschluckt wird. Dieser Parameter fügt ganz am Anfang der Sprachdaten die angegebene Anzahl Millisekunden völliger Stille ein; die Sprache beginnt erst, wenn die Bluetooth-Verbindung bereit ist.

• Bluetooth-Kopfhörer-Benutzer: 1500 beibehalten (falls weiterhin Zeichen verschluckt werden, auf 2000 erhöhen)

• Benutzer mit Kabelkopfhörern / Lautsprechern: auf 0 ändern, dann sind die Ansagen kompakter

• Der Hinweiston vor der Ansage ist selbst eine Audioausgabe, die die Bluetooth-Verbindung vorzeitig aktiviert; er arbeitet mit diesem Parameter zusammen.

7. Vollständige Parameterübersicht

Ersatz-Ansagekanal (watcher, optional)

watcher/voice-watcher.mjs ist ein dauerhaft laufender Listener, der nicht von der MCP-Verbindung abhängt: Er pollt ~/.trae-cn/work/.voice-reader/pending.txt und sagt markierte Inhalte mit derselben Cloud-Engine wie der Hauptdienst an (Konfiguration, Stimme und Lautstärke stammen in Echtzeit aus derselben Quelle; bei Cloud-Fehlern wird ebenfalls auf SAPI zurückgegriffen).

Zweck: Wenn MCP-Tools in der Agent-Sitzung nicht verfügbar sind (z. B. bei Modellwechsel oder MCP-Dienstabsturz), können Sie weiterhin Markierungen in diese Datei schreiben, um Ansagen auszulösen – so entsteht ein Fallback-Kanal:

[VOICE_READER_START:success]
要播报的文本
[VOICE_READER_END]

Die Typen unterstützen info / success / error / warning und bilden jeweils die Szenarioparameter von task_start / task_complete / task_error / need_interaction ab.

Aktivierung: Setzen Sie in config.json "watcher": { "enabled": true }. Der Haupt-MCP-Dienst startet es beim Start automatisch als Unterprozess und räumt es beim Beenden auf (TCP-Einzelinstanz-Wächter 47613; bei mehreren Sitzungen läuft nur eine Instanz). Es kann auch unabhängig ausgeführt werden: node watcher/voice-watcher.mjs.

Portable Pfade: Alle Pfade werden relativ abgeleitet oder mit os.homedir() zusammengesetzt; es gibt keine fest codierten absoluten Pfade. Umgebungsvariablen können überschrieben werden: AGENT_VOICE_CONFIG (Pfad zur Konfigurationsdatei), AGENT_VOICE_PENDING_DIR (Verzeichnis, in dem sich pending.txt befindet, Standard ~/.trae-cn/work/.voice-reader, anpassbar für andere MCP-Clients).

Hinweise

1. Die Konfiguration wird beim MCP-Start einmal geladen. Nach Änderungen an config.json müssen Sie den Client neu starten / eine neue Sitzung öffnen, damit sie wirksam wird (sie wird nicht bei jeder Ansage neu gelesen).

2. Abtastrate und Kanäle: Messungen zeigen, dass die tatsächliche Bandbreite dieser Stimme ≤ 12 kHz beträgt; Anfragen mit 32/44,1/48 kHz sind nur interpolierte Upsamplings ohne Klangqualitätsgewinn (durch Mehrfenster-FFT-Frequenzbandanalyse verifiziert); die API unterstützt nur Monokanal; beim Abspielen mischt das System automatisch für beide Ohren. 24000 beizubehalten ist optimal.

3. Emotion ist clientseitig implementiert: Die v3-Schnittstelle von seed-tts-1.0 unterstützt den serverseitigen emotion-Parameter nicht (im Test wird die Übergabe stillschweigend ignoriert). Dieses Projekt drückt die sechs Emotionen durch eine Kombination aus Tonhöhe (pitch ±12) + Sprechgeschwindigkeits-/Lautstärke-Offsets aus; emotionIntensity steuert die Intensität.

4. SSML nicht aktivieren: Der SSML-<break>-Pausentag hat in Tests mit der 1.0 + v3-Streaming-Schnittstelle das Audio abgeschnitten (nur der erste Satz wurde synthetisiert). Die Pausensteuerung für lange Texte ist bereits clientseitig implementiert; SSML ist nicht erforderlich.

5. Kontingent und Abrechnung: 火山引擎 rechnet nach Zeichen ab; Ansagetexte für Aufgaben sollten kurz sein (der Standardwert von 200 Zeichen für die Kürzung in diesem Projekt dient teilweise diesem Zweck). Wenn das Kontingent erschöpft ist, wird automatisch auf lokale SAPI-Sprache zurückgegriffen (die Stimme ändert sich; das ist normal).

6. Windows-Abhängigkeit: Für Hinweistöne wird System.Console::Beep verwendet, für die Sprachwiedergabe PowerShell Media.SoundPlayer – beides ist in Windows integriert; wenn PowerShell jedoch durch eine Gruppenrichtlinie deaktiviert ist, werden die entsprechenden Funktionen herabgestuft.

7. Ausgabeverzeichnis: Die synthetisierten Audiodaten werden in das temporäre Verzeichnis des Systems geschrieben und nach der Wiedergabe automatisch gelöscht; es bleiben keine Rückstände.

Danksagung

• agent-voice-mcp und der ursprüngliche Autor Antonio Liang – Dieses Projekt basiert auf dessen MIT-Open-Source-Code; Stimmenrollen, Multi-Engine-Architektur und andere Kerndesigns stammen vom Original

• 火山引擎 · 豆包语音合成大模型

License

MIT (übernimmt die Lizenz des Originalprojekts und behält die Nennung des ursprünglichen Autors bei)