Controlador MCP de Sonic Pi

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con Sonic Pi mediante mensajes OSC. Esto permite que herramientas de IA como Claude y Cursor creen música y controlen Sonic Pi mediante programación.

Características

• Reproduce notas individuales con parámetros de sintetizador personalizables

• Ejecutar código arbitrario de Sonic Pi

• Funciona con cualquier cliente compatible con MCP (Claude Desktop, Cursor, etc.)

Related MCP server: StreamerSongList MCP Server

Prerrequisitos

• Node.js (v18 o superior)

• Sonic Pi (v4.0 o superior)

• Un cliente compatible con MCP (Cursor, Claude Desktop, etc.)

Configuración de Sonic Pi

Antes de usar el servidor MCP, debe agregar el siguiente código al búfer de Sonic Pi. Este código gestiona los mensajes OSC enviados por el servidor:

# Required Sonic Pi configuration
# Add this to a buffer in Sonic Pi and run it

live_loop :code_runner do
  use_real_time
  code = sync "/osc*/run-code"
  
  # Since we receive the code as a string, we can use eval to execute it
  # The code comes as the first element of the message
  begin
    eval(code[0].to_s)
  rescue Exception => e
    puts "Error executing code: #{e.message}"
  end
end

Asegúrese de que este código se esté ejecutando en Sonic Pi antes de usar el servidor MCP.

Integración con clientes

Cursor

Agregar a ~/.cursor/mcpServers.json :

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "name": "Sonic Pi MCP",
      "command": "npx",
      "args": ["-y", "sonic-pi-mcp", "start"],
      "transport": {
        "type": "stdio"
      }
    }
  }
}

Escritorio de Claude

Agregar a la configuración MCP de Claude:

{
  "mcpServers": {
    "sonic_pi_mcp": {
      "command": "npx",
      "args": ["-y", "sonic-pi-mcp", "start"]
    }
  }
}

Herramientas disponibles

nota de reproducción

Reproduce una sola nota con parámetros personalizables.

Parámetros:

• note (obligatoria): número de nota MIDI (0-127)

• synth (opcional): sintetizador a utilizar (por ejemplo, ":saw", ":beep", ":prophet")

• sustain (opcional): Duración de la nota en segundos (predeterminado: 1)

• cutoff (opcional): frecuencia de corte del filtro (predeterminado: 100)

Ejemplo:

// Play middle C with saw wave synth
{
  "name": "play_note",
  "parameters": {
    "note": 60,
    "synth": ":saw",
    "sustain": 0.5,
    "cutoff": 80
  }
}

código de ejecución

Ejecuta código arbitrario de Sonic Pi.

Parámetros:

• code (obligatorio): Código de Sonic Pi a ejecutar

Ejemplo:

{
  "name": "run_code",
  "parameters": {
    "code": "use_synth :prophet\nplay_pattern_timed [60, 64, 67], [0.5]"
  }
}

Ejemplo de uso

A continuación se muestran algunos ejemplos de interacciones utilizando las herramientas MCP:

Melodía sencilla

// Play a C major arpeggio
{
  "code": `
    use_synth :piano
    play_pattern_timed [60, 64, 67, 72], [0.25], release: 0.1
  `
}

Patrón complejo

// Create a rhythmic pattern
{
  "code": `
    live_loop :rhythm do
      use_synth :tb303
      play choose(chord(:C3, :minor)), release: 0.2, cutoff: rrand(60, 120)
      sleep 0.25
    end
  `
}

Solución de problemas

1. Sin sonido

   • Asegúrese de que Sonic Pi esté funcionando

   • Compruebe que el código del controlador OSC se esté ejecutando en Sonic Pi

   • Verifique que Sonic Pi esté escuchando en el puerto 4560 (predeterminado)

2. Errores de conexión

   • Comprobar si se está ejecutando otra instancia del servidor

   • Reiniciar Sonic Pi

   • Asegúrese de que ninguna otra aplicación esté utilizando el puerto 4560

3. Errores de ejecución de código

   • Consulte la ventana de registro de Sonic Pi para ver si hay mensajes de error

   • Verifique la sintaxis de su código Sonic Pi

   • Asegúrese de que todos los sintetizadores y muestras necesarios estén disponibles

Desarrollo

# Clone the repository
git clone https://github.com/abhishekjairath/sonic-pi-mcp.git
cd sonic-pi-mcp

# Install dependencies
npm install

# Build
npm run build

# Install MCP Inspector globally (for testing)
npm install -g @modelcontextprotocol/inspector

# Start Sonic Pi and run the OSC handler code (see Sonic Pi Configuration section)

# Start the server in one terminal
npm run dev

# In another terminal, start the MCP Inspector
mcp-inspector

Pruebas con MCP Inspector

1. Abra su navegador y navegue a http://localhost:3000

2. En la interfaz de usuario del Inspector de MCP, configure la conexión:

   • Comando: node

   • Argumentos: dist/server.mjs

   • Directorio de trabajo: /path/to/your/sonic-pi-mcp (use la ruta de su proyecto actual)

   • Tipo de transporte: stdio

3. Pruebe la herramienta play_note :

{
  "name": "play_note",
  "parameters": {
    "note": 60,
    "synth": ":beep",
    "sustain": 0.5
  }
}

4. Pruebe la herramienta run_code :

{
  "name": "run_code",
  "parameters": {
    "code": "use_synth :prophet\nplay_pattern_timed scale(:c4, :major), [0.25]"
  }
}

5. Verifique la ventana de registro de Sonic Pi para ver si hay mensajes de error o salida

Solución de problemas de desarrollo

1. Errores de compilación

   • Ejecute npm run build y verifique si hay errores de TypeScript

   • Asegúrese de que todas las dependencias estén instaladas correctamente

   • Verifique tsconfig.json para verificar la configuración correcta

2. Problemas de conexión del inspector MCP

   • Verifique que el servidor esté ejecutándose ( npm run dev )

   • Compruebe que la ruta del directorio de trabajo sea correcta

   • Asegúrese de que no haya otras instancias del servidor en ejecución

3. Problemas de comunicación de la OSC

   • Confirme que Sonic Pi se esté ejecutando y que el código del controlador OSC esté activo

   • Verifique los registros del servidor para detectar errores de conexión

   • Verifique que el puerto 4560 esté disponible y no esté bloqueado

Contribuyendo

1. Bifurcar el repositorio

2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

4. Empujar a la rama ( git push origin feature/amazing-feature )

5. Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.