AivisSpeech

Um servidor para geração de texto em fala usando o motor AivisSpeech.

Documentação

MCP Simple AivisSpeech

Project Logo

🙏 Agradecimentos Especiais
Este projeto é baseado em mcp-simple-voicevox por @t09tanaka.
Agradecemos profundamente pelo excelente trabalho na criação do servidor MCP original para VOICEVOX, que serviu como base para esta adaptação para AivisSpeech.

Um servidor Model Context Protocol (MCP) para integração perfeita com o mecanismo de síntese de fala AivisSpeech. Este projeto permite que assistentes de IA e aplicativos convertam texto em fala japonesa com som natural e parâmetros de voz personalizáveis.

✨ Recursos

Conversão de Texto para Fala - Síntese de fala japonesa de alta qualidade usando AivisSpeech
Múltiplos Personagens de Voz - Suporte para vários locutores e estilos de voz (padrão: Anneli ノーマル)
Parâmetros Configuráveis - Ajuste de velocidade, tom, volume e entonação
Áudio Multiplataforma - Reprodução automática de áudio em macOS, Windows e Linux
Notificações de Tarefas - Notificações por voz para conclusão de processos
Integração Fácil - Protocolo MCP simples para integração com assistentes de IA
Monitoramento de Status do Mecanismo - Verificação em tempo real do status do mecanismo AivisSpeech
Tratamento Inteligente de Erros - Mensagens de erro úteis com sugestões de locutores

📋 Pré-requisitos

Node.js - Versão 18.0.0 ou superior
Mecanismo AivisSpeech - Executando em http://127.0.0.1:10101 (porta padrão)
Sistema de Áudio - Capacidades de áudio do sistema para reprodução

Configuração do MCP Simple AivisSpeech

Usando Claude Code

Ao usar Claude Code, inicie o servidor MCP manualmente antes de usá-lo.

Usar npx garante que você sempre obtenha a versão mais recente automaticamente. Nenhuma atualização manual é necessária.

Inicie o servidor MCP AivisSpeech manualmente em um terminal separado daquele onde você está usando Claude Code

npx @shinshin86/mcp-simple-aivisspeech@latest

Registre o servidor MCP com Claude Code

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

Por padrão, o servidor é adicionado ao escopo local (apenas o projeto atual). Para disponibilizá-lo em todos os projetos, use a opção -s user:

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

Você também pode adicionar notificações por voz ao seu arquivo CLAUDE.md para automatizar notificações de conclusão de tarefas:

## Task Completion Behavior
- When all tasks are completed, always use the aivisspeech mcp tool to announce "Tasks completed" via voice
- When user input or decision is needed, use the aivisspeech mcp tool to announce "Awaiting your decision" via voice

### Notification Timings
- When asking the user a question
- When all tasks are completed
- When errors or issues occur

Verifique se as ferramentas são reconhecidas

claude mcp list

# Or launch Claude Code and use
/mcp

Se aivisspeech for exibido, a configuração foi bem-sucedida.

💡 Dica: Claude Code não executa comandos automaticamente por segurança. Se você esquecer de iniciar o servidor, as ferramentas não aparecerão. Durante o desenvolvimento, mantenha o comando npx acima em execução em um terminal, ou use gerenciadores de processos como pm2 ou systemd --user para operação contínua.

Usando Claude Desktop

Para configuração manual com Claude Desktop, você pode simplesmente adicionar a seguinte configuração:

Usar npx garante que você sempre obtenha a versão mais recente automaticamente. Nenhuma atualização manual é necessária.

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

⚙️ Configuração do Mecanismo AivisSpeech

Antes de usar este servidor MCP, conclua estas etapas de configuração para garantir que o AivisSpeech esteja rodando localmente.

Baixe o AivisSpeech de https://aivis-project.com/
Inicie o AivisSpeech na sua máquina local
O mecanismo iniciará na porta padrão 10101
Verifique se o mecanismo está rodando visitando http://127.0.0.1:10101/docs

📖 Outros Métodos de Uso

Para Desenvolvimento Local

# Run the MCP server
npm start

# For development with hot reload
npm run dev

# Check if everything is working
npm test

Para clonar o repositório, instalar dependências e compilar:

# Clone repository
git clone https://github.com/shinshin86/mcp-simple-aivisspeech.git
cd mcp-simple-aivisspeech

# Install dependencies
npm install

# Build the project
npm run build

🛠️ Ferramentas Disponíveis

🎤 `speak`

Converta texto em fala e reproduza áudio com parâmetros de voz personalizáveis.

Esta ferramenta aceita vários parâmetros de configuração, incluindo as seguintes opções:

text (obrigatório): Texto para converter em fala
speaker (opcional): ID do locutor/voz (padrão: 888753760 - Anneli ノーマル)
speedScale (opcional): Multiplicador de velocidade da fala (0.5-2.0, padrão: 1.0)
pitchScale (opcional): Ajuste de tom (-0.15-0.15, padrão: 0.0)
volumeScale (opcional): Nível de volume (0.0-2.0, padrão: 1.0)
playAudio (opcional): Se deve reproduzir o áudio gerado (padrão: true)

Exemplo de uso:

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

👥 `get_speakers`

Recupere uma lista de todos os personagens de voz disponíveis e seus estilos.

Esta função retorna: Lista de locutores com seus IDs, nomes e estilos de voz disponíveis.

🔔 `notify_completion`

Reproduza uma notificação por voz quando as tarefas forem concluídas.

Esta ferramenta aceita vários parâmetros de configuração, incluindo as seguintes opções:

message (opcional): Mensagem de conclusão para anunciar (padrão: "処理が完了しました")
speaker (opcional): ID do locutor para a voz de notificação (padrão: 888753760 - Anneli ノーマル)

Exemplo de uso:

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

📊 `check_engine_status`

Verifique o status atual e a versão do mecanismo AivisSpeech.

Esta função retorna: Status do mecanismo, informações de versão e detalhes de conectividade.

🖥️ Suporte de Plataforma

Sistemas de Reprodução de Áudio

Plataforma	Comando de Áudio	Requisitos
macOS	`afplay`	Integrado (sem configuração adicional)
Windows	PowerShell Media.SoundPlayer	Windows PowerShell
Linux	`aplay`	Utilitários ALSA (`sudo apt install alsa-utils`)

Ambientes Testados

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

🧪 Desenvolvimento

Scripts Disponíveis

# Development & Building
npm run dev          # Run with hot reload (tsx)
npm run build        # Compile TypeScript to dist/
npm start           # Run compiled server

# Code Quality
npm run lint        # Run ESLint
npm run test        # Run Vitest tests (single run)
npm run test:watch  # Run tests in watch mode
npm run test:ui     # Run tests with UI
npm run test:coverage # Run tests with coverage

# Utilities
npm run clean       # Clean dist/ directory

Uso Local vs NPX

Ao usar clientes MCP em produção, use npx @shinshin86/mcp-simple-aivisspeech@latest na sua configuração MCP. Nenhuma configuração local é necessária, e você sempre obtém a versão mais recente.

Para desenvolvimento, clone o repositório e use npm run dev para recarga automática, ou npm run build && npm start para testar builds de produção.

Arquitetura do Projeto

mcp-simple-aivisspeech/
├── src/
│   ├── index.ts                  # MCP server & tool handlers
│   └── aivisspeech-client.ts     # AivisSpeech API client
├── tests/
│   └── aivisspeech-client.test.ts # Unit tests
├── dist/                         # Compiled output
├── docs/                         # Documentation
└── config files                  # TS, ESLint, Vitest configs

Arquitetura do Cliente de API

A classe AivisSpeechClient oferece funcionalidade abrangente, fornecendo vários recursos principais:

Cliente HTTP - Comunicação de API baseada em Axios
Tratamento de Erros - Captura e relatório abrangente de erros
Segurança de Tipos - Interfaces TypeScript completas para todas as respostas da API
Gerenciamento de Conexão - Verificações de saúde e monitoramento de status

Adicionando Novos Recursos

Nova Ferramenta: Adicione o manipulador em src/index.ts CallToolRequestSchema
Métodos de API: Estenda a classe AivisSpeechClient
Tipos: Atualize as interfaces em aivisspeech-client.ts
Testes: Adicione casos de teste correspondentes

🔧 Solução de Problemas

Problemas Comuns

Mecanismo AivisSpeech Não Encontrado

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

Considere estas abordagens de solução de problemas para resolver este problema: Certifique-se de que o Mecanismo AivisSpeech esteja rodando na porta correta.

Falha na Reprodução de Áudio

Error: Audio player exited with code 1

Considere estas abordagens de solução de problemas para resolver este problema:

macOS - Verifique se afplay está disponível
Linux - Instale os utilitários ALSA (sudo apt install alsa-utils)
Windows - Certifique-se de que a política de execução do PowerShell permita scripts

Permissão Negada

Error: spawn afplay EACCES

Considere estas abordagens de solução de problemas para resolver este problema: Verifique as permissões de arquivo e as configurações de áudio do sistema.

Modo de Depuração

Para habilitar o registro detalhado, execute o seguinte comando:

DEBUG=mcp-aivisspeech npm run dev

📄 Licença

Este projeto está licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para detalhes.

🤝 Contribuindo

Aceitamos contribuições da comunidade. Os contribuidores podem começar concluindo estas etapas essenciais:

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Diretrizes de Desenvolvimento

Siga as configurações existentes de TypeScript/ESLint
Adicione testes para novas funcionalidades
Atualize a documentação para mudanças na API
Garanta compatibilidade entre plataformas

🙏 Agradecimentos

Projeto AivisSpeech pelo excelente mecanismo de TTS
Model Context Protocol pelo framework de integração
VOICEVOX MCP pela inspiração e referência

📞 Suporte

Problemas - GitHub Issues
Discussões - GitHub Discussions
Documentação - AivisSpeech API Docs

Feito com ❤️ para a comunidade japonesa de TTS