MCP Simple AivisSpeech

Anglais | 日本語

🙏 Special Thanks
Ce projet est basé sur mcp-simple-voicevox de @t09tanaka.
Nous apprécions profondément leur excellent travail dans la création du serveur MCP original pour VOICEVOX, qui a servi de base à cette adaptation d'AivisSpeech.

Un serveur Model Context Protocol (MCP) pour une intégration transparente avec le moteur de synthèse vocale AivisSpeech. Ce projet permet aux assistants et applications d'IA de convertir du texte en parole japonaise à consonance naturelle avec des paramètres vocaux personnalisables.

caractéristiques

• Conversion texte-parole - Synthèse vocale japonaise de haute qualité à l'aide d'AivisSpeech
• Personnages vocaux multiples - Prise en charge de différents locuteurs et styles de voix (par défaut : Anneli ノーマル)
• Paramètres configurables - Ajustement de la vitesse, de la hauteur, du volume et de l'intonation
• Audio multiplateforme - Lecture audio automatique sur macOS, Windows et Linux
• Notifications de tâches - Notifications vocales pour l'achèvement des processus
• Intégration facile - Protocole MCP simple pour l'intégration d'un assistant d'intelligence artificielle
• Surveillance de l'état du moteur - Vérification en temps réel de l'état du moteur AivisSpeech
• Gestion intelligente des erreurs - Messages d'erreur utiles avec suggestions du locuteur

📋 Conditions préalables

• Node.js - Version 18.0.0 ou supérieure
• Moteur AivisSpeech - Exécution sur http://127.0.0.1:10101 (port par défaut)
• Système audio - Capacités audio du système pour la lecture

Configuration simple d'AivisSpeech pour MCP

Utilisation de Claude Code

Lorsque vous utilisez Claude Code, démarrez le serveur MCP manuellement avant de l'utiliser.

L'utilisation de npx permet d'obtenir automatiquement la dernière version. Aucune mise à jour manuelle n'est nécessaire.

1. Démarrez manuellement le serveur MCP d'AivisSpeech dans un terminal séparé de celui où vous utilisez Claude Code

npx @shinshin86/mcp-simple-aivisspeech@latest

2. Enregistrez le serveur MCP avec Claude Code

claude mcp add aivisspeech -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

Par défaut, le serveur est ajouté à la portée locale (projet actuel uniquement). Pour le rendre disponible dans tous les projets, utilisez l'option -s user :

claude mcp add aivisspeech -s user -e AIVISSPEECH_URL=http://127.0.0.1:10101 -- npx @shinshin86/mcp-simple-aivisspeech@latest

Vous pouvez également ajouter des notifications vocales à votre fichier CLAUDE.md pour automatiser les notifications de fin de tâche :

## Comportement à la fin des tâches - Lorsque toutes les tâches sont terminées, utilisez toujours l'outil aivisspeech mcp pour annoncer "Tâches terminées" par la voix - Lorsque l'utilisateur doit donner son avis ou prendre une décision, utilisez l'outil aivisspeech mcp pour annoncer "En attente de votre décision" par la voix ### Moments de la notification - Lorsque l'utilisateur pose une question - Lorsque toutes les tâches sont terminées - Lorsque des erreurs ou des problèmes surviennent

3. Vérifier que les outils sont reconnus

claude mcp list ## Ou lancez Claude Code et utilisez /mcp

Si aivisspeech s'affiche, l'installation a réussi.

💡 Astuce : Claude Code n'exécute pas automatiquement les commandes pour des raisons de sécurité. Si vous oubliez de démarrer le serveur, les outils n'apparaîtront pas. Pendant le développement, gardez la commande npx ci-dessus en cours d'exécution dans un terminal, ou utilisez des gestionnaires de processus comme pm2 ou systemd --user pour un fonctionnement persistant.

Utilisation de Claude Desktop

Pour une configuration manuelle avec Claude Desktop, vous pouvez simplement ajouter la configuration suivante :

L'utilisation de npx permet d'obtenir automatiquement la dernière version. Aucune mise à jour manuelle n'est nécessaire.

{ "mcpServers" : { "aivisspeech" : { "command" : "npx", "args" : ["@shinshin86/mcp-simple-aivisspeech@latest"], "env" : { "AIVISSPEECH_URL" : "http://127.0.0.1:10101" } } }

⚙️ Configuration du moteur AivisSpeech

Avant d'utiliser ce serveur MCP, effectuez ces étapes de configuration pour vous assurer qu'AivisSpeech fonctionne localement.

1. Téléchargez AivisSpeech à partir de https://aivis-project.com/
2. Lancez AivisSpeech sur votre machine locale
3. Le moteur démarre sur le port par défaut 10101
4. Vérifiez que le moteur fonctionne en visitant http://127.0.0.1:10101/docs

📖 Autres méthodes d'utilisation

Pour le développement local

# Lancer le serveur MCP npm start # Pour le développement avec rechargement à chaud npm run dev # Vérifier que tout fonctionne npm test

Pour cloner le dépôt, installer les dépendances et construire :

# Cloner le dépôt git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git cd mcp-simple-aivisspeech # Installer les dépendances npm install # Construire le projet npm run build

🛠️ Outils disponibles

🎤 speak

Convertit le texte en parole et joue de l'audio avec des paramètres vocaux personnalisables.

Cet outil accepte plusieurs paramètres de configuration, dont les options suivantes :

• texte(obligatoire): Texte à convertir en parole
• locuteur(optionnel): ID du locuteur/de la voix (par défaut : 888753760 - Anneli ノーマル)
• speedScale(optionnel): Multiplicateur de la vitesse de la parole(0,5-2,0, par défaut : 1,0)
• pitchScale(optionnel): Ajustement de la hauteur(-0.15-0.15, par défaut : 0.0)
• volumeScale(optionnel): Niveau de volume(0.0-2.0, par défaut : 1.0)
• playAudio(optionnel): Jouer ou non l'audio généré (par défaut : true)

Exemple d'utilisation :

{"text" : "こんにちは、世界！", "speaker" : 888753760, "speedScale" : 1.2, "pitchScale" : 0.05, "volumeScale" : 1.5 }

👥 get_speakers

Récupère une liste de tous les personnages vocaux disponibles et de leurs styles.

Cette fonction renvoie : Liste des locuteurs avec leur ID, leur nom et les styles vocaux disponibles.

🔔 notify_completion

Joue une notification vocale lorsque des tâches sont terminées.

Cet outil accepte plusieurs paramètres de configuration, dont les options suivantes :

• message(facultatif): Message d'achèvement à annoncer (par défaut : "処理が完了しました")
• speaker(facultatif): ID du locuteur pour la voix de notification (par défaut : 888753760 - Anneli ノーマル)

Exemple d'utilisation :

{"message" : "データ処理が完了しました", "speaker" : 888753760 }

📊 check_engine_status

Vérifier l'état actuel et la version du moteur AivisSpeech.

Cette fonction renvoie : L'état du moteur, les informations sur la version et les détails de connectivité.

🖥️ Prise en charge des plates-formes

Systèmes de lecture audio

Environnements testés

• macOS 12+ (Intel & Apple Silicon)
• Windows 10/11
• Ubuntu 20.04+
• Node.js 18.x, 20.x, 21.x

🧪 Développement

Scripts disponibles

# Développement et construction npm run dev # Exécuter avec rechargement à chaud (tsx) npm run build # Compiler TypeScript vers dist/ npm start # Exécuter le serveur compilé # Qualité du code npm run lint # Exécuter ESLint npm run test # Exécuter les tests Vitest (exécution unique) npm run test:watch # Exécuter les tests en mode watch npm run test:ui # Exécuter les tests avec UI npm run test:coverage # Exécuter les tests avec coverage # Utilitaires npm run clean # Nettoyer le répertoire dist/

Utilisation locale vs NPX

Lorsque vous utilisez des clients MCP en production, utilisez npx @shinshin86/mcp-simple-aivisspeech@latest dans votre configuration MCP. Aucune installation locale n'est nécessaire, et vous obtenez toujours la dernière version.

Pour le développement, clonez le dépôt et utilisez npm run dev pour un rechargement à chaud, ou npm run build && npm start pour tester les builds de production.

Architecture du projet

mcp-simple-aivisspeech/ ├── src/ │ ├── index.ts # MCP server & tool handlers │ └── aivisspeech-client.ts # AivisSpeech API client ├── tests/ │ └── aivisspeech-client.test.ts # Tests unitaires ├── dist/ # Sortie compilée ├── docs/ # Documentation └─── config files # TS, ESLint, Vitest configs

Architecture du client API

La classe AivisSpeechClient offre des fonctionnalités complètes, en fournissant plusieurs capacités clés :

• Client HTTP - Communication API basée sur Axios
• Gestion des erreurs - Capture et rapport d'erreurs complets
• Type Safety - Interfaces TypeScript complètes pour toutes les réponses de l'API
• Gestion des connexions - Contrôles de santé et surveillance de l'état

Ajout de nouvelles fonctionnalités

1. Nouvel outil: Ajout d'un gestionnaire dans src/index.tsCallToolRequestSchema
2. Méthodes API: Extension de la classe AivisSpeechClient
3. Types: Mise à jour des interfaces dans aivisspeech-client.ts
4. Tests: Ajouter les cas de test correspondants

🔧 Résolution des problèmes

Problèmes courants

Moteur AivisSpeech introuvable

Erreur : Failed to get version : connect ECONNREFUSED 127.0.0.1:10101

Pour résoudre ce problème, envisagez les approches de dépannage suivantes : Assurez-vous qu'AivisSpeech Engine fonctionne sur le bon port.

La lecture audio échoue

Erreur : Le lecteur audio s'est arrêté avec le code 1

Envisagez les approches de dépannage suivantes pour résoudre ce problème :

• macOS - Vérifiez si afplay est disponible
• Linux - Installer les utilitaires ALSA(sudo apt install alsa-utils)
• Windows - S'assurer que la stratégie d'exécution PowerShell autorise les scripts

Permission refusée

Erreur : spawn afplay EACCES

Envisagez les approches de dépannage suivantes pour résoudre ce problème : Vérifiez les autorisations de fichiers et les paramètres audio du système.

Mode débogage

Pour activer la journalisation verbeuse, exécutez la commande suivante :

DEBUG=mcp-aivisspeech npm run dev

licence

Ce projet est sous licence Apache 2.0 - voir le fichier LICENSE pour plus de détails.

🤝 Contribuer

Les contributions de la communauté sont les bienvenues. Les contributeurs peuvent commencer en effectuant ces étapes essentielles :

1. Mettre en place le dépôt(Fork )
2. Créer une branche de fonctionnalités(git checkout -b feature/amazing-feature)
3. Livrez vos modifications(git commit -m 'Add amazing feature')
4. Pousser vers la branche(git push origin feature/amazing-feature)
5. Ouvrir une demande d'extraction

Directives de développement

• Suivre les configurations TypeScript/ESLint existantes
• Ajouter des tests pour les nouvelles fonctionnalités
• Mettre à jour la documentation pour les changements d'API
• Assurer la compatibilité multiplateforme

🙏 Remerciements

• Projet AivisSpeech pour l'excellent moteur TTS
• Model Context Protocol pour le cadre d'intégration
• VOICEVOX MCP pour son inspiration et ses références

📞 Support

• Problèmes - GitHub Problèmes
• Discussions - Discussions GitHub
• Documentation - AivisSpeech API Docs

Réalisé avec ❤️ pour la communauté TTS japonaise