MCP Sound Tool

MCP Sound Tool

Uma implementação do Model Context Protocol (MCP) que reproduz efeitos sonoros para Cursor AI e outros ambientes compatíveis com MCP. Esta implementação em Python fornece feedback de áudio para uma experiência de codificação mais interativa.

Recursos

• Reproduz efeitos sonoros para vários eventos (conclusão, erro, notificação)
• Usa o Model Context Protocol (MCP) para integração padronizada com Cursor e outros IDEs
• Suporte multiplataforma (Windows, macOS, Linux)
• Efeitos sonoros configuráveis

Instalação

Compatibilidade de Versão do Python

Este pacote é testado com Python 3.8-3.11. Se você encontrar erros com Python 3.12+ (particularmente exceções BrokenResourceError ou TaskGroup), tente usar uma versão anterior do Python.

Recomendado: Instalar com pipx

A forma recomendada de instalar o mcp-sound-tool é com pipx, que instala o pacote em um ambiente isolado enquanto disponibiliza os comandos globalmente:

# Install pipx if you don't have it
python -m pip install --user pipx
python -m pipx ensurepath

# Install mcp-sound-tool
pipx install mcp-sound-tool

Este método garante que a ferramenta tenha seu próprio ambiente isolado, evitando conflitos com outros pacotes.

Alternativa: Instalar com pip

Você também pode instalar diretamente com pip:

pip install mcp-sound-tool

A partir do código-fonte

1. Clone este repositório:

   git clone https://github.com/yourusername/mcp-sound-tool
   cd mcp-sound-tool
   

2. Instale com pipx diretamente do diretório de origem:

   pipx install .
   

   Ou com pip:

   pip install -e .
   

Uso

Adicionando Arquivos de Som

Coloque seus arquivos de som no diretório sounds. Os seguintes arquivos de som são esperados:

• completion.mp3 - Reproduzido após a geração de código
• error.mp3 - Reproduzido quando ocorre um erro
• notification.mp3 - Usado para notificações gerais

Você pode encontrar efeitos sonoros gratuitos em sites como freesound.org.

Executando o Servidor MCP

Execute o servidor MCP:

mcp-sound-tool

O servidor iniciará e aguardará eventos do Cursor ou de outros clientes compatíveis com MCP através do transporte stdio.

Configuração no Cursor

Para usar este servidor com o Cursor, adicione-o ao seu arquivo de configuração MCP:

No macOS:

// ~/Library/Application Support/Cursor/mcp.json
{
  "mcpServers": {
    "sound": {
      "command": "mcp-sound-tool",
      "args": [],
      "type": "stdio",
      "pollingInterval": 5000,
      "startupTimeout": 10000,
      "restartOnFailure": true
    }
  }
}

No Windows:

// %APPDATA%/Cursor/mcp.json
{
  "mcpServers": {
    "sound": {
      "command": "mcp-sound-tool",
      "args": [],
      "type": "stdio",
      "pollingInterval": 5000,
      "startupTimeout": 10000,
      "restartOnFailure": true
    }
  }
}

Quando instalado com pipx, o comando mcp-sound-tool estará disponível no seu PATH, então o Cursor poderá encontrá-lo e executá-lo sem especificar o caminho completo.

Diretrizes de Uso do MCP de Som para Modelos de IA

Este servidor MCP fornece recursos de feedback de áudio para interações de IA. Ele foi projetado para melhorar a experiência do usuário, fornecendo sinais de áudio claros que indicam o status das operações sem exigir que o usuário leia texto.

Quando Usar Feedback de Som

Agentes de IA devem usar as ferramentas de som proativamente nos momentos apropriados:

1. Sons de Sucesso (completion):

   • Após uma tarefa ou comando ter sido concluído com sucesso
   • Quando uma operação significativa termina com sucesso
   • Ao confirmar que a solicitação do usuário foi atendida

2. Sons de Erro (error):

   • Quando um comando falhou ou encontrou um erro
   • Ao avisar o usuário sobre um problema
   • Quando uma operação não pôde ser concluída conforme solicitado

3. Sons de Notificação (notification):

   • Ao alertar o usuário sobre informações importantes
   • Ao solicitar atenção ou entrada do usuário
   • Para atualizações de status em operações de longa duração

Exemplo de Uso

# When a command completes successfully
@mcp.tool()
def execute_command(command):
    result = run_command(command)
    if result.success:
        play_sound("completion")  # Indicate success with audio
        return "Command executed successfully"
    else:
        play_sound("error")  # Indicate failure with audio
        return f"Error: {result.error_message}"

Ferramentas Disponíveis

1. play_sound(sound_type="completion", custom_sound_path=None): Reproduzir um efeito sonoro
2. list_available_sounds(): Listar todos os arquivos de som disponíveis
3. install_to_user_dir(): Instalar arquivos de som no diretório de configuração do usuário

Para mais detalhes, conecte-se ao servidor MCP e verifique as descrições das ferramentas.

Desenvolvimento

Para desenvolvimento:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

Agradecimentos

• SIAM-TheLegend por criar a implementação original em JavaScript do sound-mcp que inspirou esta versão em Python
• Os desenvolvedores do protocolo MCP por criar um padrão poderoso para interações de ferramentas de IA
• Contribuidores para os testes e documentação

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.