MCP Sound Tool

MCP Sound Tool

Una implementación del Model Context Protocol (MCP) que reproduce efectos de sonido para Cursor AI y otros entornos compatibles con MCP. Esta implementación en Python proporciona retroalimentación de audio para una experiencia de codificación más interactiva.

Características

• Reproduce efectos de sonido para varios eventos (finalización, error, notificación)
• Utiliza el Model Context Protocol (MCP) para una integración estandarizada con Cursor y otros IDE
• Compatibilidad multiplataforma (Windows, macOS, Linux)
• Efectos de sonido configurables

Instalación

Compatibilidad de Versiones de Python

Este paquete se prueba con Python 3.8-3.11. Si encuentras errores con Python 3.12+ (particularmente excepciones BrokenResourceError o TaskGroup), intenta usar una versión anterior de Python.

Recomendado: Instalar con pipx

La forma recomendada de instalar mcp-sound-tool es con pipx, que instala el paquete en un entorno aislado mientras hace que los comandos estén disponibles 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 asegura que la herramienta tenga su propio entorno aislado, evitando conflictos con otros paquetes.

Alternativa: Instalar con pip

También puedes instalar directamente con pip:

pip install mcp-sound-tool

Desde el Código Fuente

1. Clona este repositorio:

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

2. Instala con pipx directamente desde el directorio fuente:

   pipx install .
   

   O con pip:

   pip install -e .
   

Uso

Agregar Archivos de Sonido

Coloca tus archivos de sonido en el directorio sounds. Se esperan los siguientes archivos de sonido:

• completion.mp3 - Se reproduce después de la generación de código
• error.mp3 - Se reproduce cuando ocurre un error
• notification.mp3 - Se usa para notificaciones generales

Puedes encontrar efectos de sonido gratuitos en sitios web como freesound.org.

Ejecutar el Servidor MCP

Ejecuta el servidor MCP:

mcp-sound-tool

El servidor se iniciará y escuchará eventos de Cursor u otros clientes compatibles con MCP a través del transporte stdio.

Configuración en Cursor

Para usar este servidor con Cursor, agrégalo a tu archivo de configuración MCP:

En macOS:

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

En Windows:

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

Cuando se instala con pipx, el comando mcp-sound-tool estará disponible en tu PATH, por lo que Cursor podrá encontrarlo y ejecutarlo sin especificar la ruta completa.

Pautas de Uso de Sonido MCP para Modelos de IA

Este servidor MCP proporciona capacidades de retroalimentación de audio para interacciones de IA. Está diseñado para mejorar la experiencia del usuario proporcionando señales de audio claras que indican el estado de las operaciones sin requerir que el usuario lea texto.

Cuándo Usar Retroalimentación de Sonido

Los agentes de IA deben usar las herramientas de sonido de manera proactiva en los momentos apropiados:

1. Sonidos de Éxito (completion):

   • Después de que una tarea o comando se haya completado con éxito
   • Cuando una operación significativa ha terminado correctamente
   • Al confirmar que la solicitud de un usuario se ha cumplido

2. Sonidos de Error (error):

   • Cuando un comando ha fallado o ha encontrado un error
   • Al advertir al usuario sobre un problema
   • Cuando una operación no pudo completarse como se solicitó

3. Sonidos de Notificación (notification):

   • Al alertar al usuario sobre información importante
   • Al solicitar atención o entrada del usuario
   • Para actualizaciones de estado en operaciones de larga duración

Ejemplo 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}"

Herramientas Disponibles

1. play_sound(sound_type="completion", custom_sound_path=None): Reproducir un efecto de sonido
2. list_available_sounds(): Listar todos los archivos de sonido disponibles
3. install_to_user_dir(): Instalar archivos de sonido en el directorio de configuración del usuario

Para más detalles, conéctate al servidor MCP y consulta las descripciones de las herramientas.

Desarrollo

Para desarrollo:

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

# Run tests
pytest

Agradecimientos

• SIAM-TheLegend por crear la implementación original en JavaScript de sound-mcp que inspiró esta versión en Python
• Los desarrolladores del protocolo MCP por crear un estándar potente para las interacciones de herramientas de IA
• Contribuyentes a las pruebas y la documentación

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.