# Sushi MCP Server

An MCP (Model Context Protocol) server for controlling Sushi audio engine via gRPC. This allows AI assistants to interact with and control Sushi-powered audio devices and applications.

## Overview

Sushi MCP Server provides a bridge between AI assistants and the [Sushi](https://github.com/elk-audio/sushi) audio engine, enabling:

- Real-time audio processing control
- Parameter automation
- MIDI routing and control
- Track and processor management
- Preset management
- Audio routing configuration

## Features

### System Control
- Get Sushi version and build information
- Query audio channel counts

### Transport Control
- Control playback (play, stop, record)
- Set tempo and time signature
- Manage sync modes (internal, MIDI, Link)

### Track & Processor Management
- List and manage tracks
- Add/remove audio processors
- Control processor parameters
- Bypass/enable processors
- Save and load presets

### Audio Routing
- Configure input/output connections
- Route audio between tracks and engine channels

### MIDI Control
- Connect MIDI keyboards to tracks
- Map MIDI CC to parameters
- Send MIDI notes programmatically
- Configure MIDI routing

### Real-time Updates
- Subscribe to parameter changes
- Watch specific parameters for updates
- Get real-time notifications

## Prerequisites

- Python 3.13 or higher
- A running instance of Sushi with gRPC enabled
- The Sushi gRPC interface exposed (default port: 51051)

## Installation

1. Clone the repository:
```bash
git clone https://github.com/YOUR_USERNAME/sushi-mcp.git
cd sushi-mcp
```

2. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -e .
```

## Configuration

The server includes a sample configuration file `default_config_sushi.json` that demonstrates a typical Sushi setup with:
- 8 playback tracks with WAV streamers
- 2 input tracks with various effects processors
- Audio routing configurations
- Initial parameter states

You can modify this file to match your Sushi configuration.

## Usage

### Running the MCP Server

1. Start the MCP server:
```bash
python sushi_mcp_server.py
```

2. The server runs in stdio mode and waits for MCP client connections.

### Connecting from Claude Desktop

Add the following to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "sushi-control": {
      "command": "python",
      "args": ["/path/to/sushi-mcp/sushi_mcp_server.py"],
      "env": {}
    }
  }
}
```

### Basic Usage Examples

Once connected, you can use natural language to control Sushi:

- "Connect to Sushi at 192.168.1.100"
- "Show me all tracks"
- "Set the tempo to 120 BPM"
- "Add a reverb to track 1"
- "Set the gain parameter of the input processor to 0.8"
- "Connect MIDI channel 1 to the synthesizer track"
- "Save the current state as a preset"

## Available MCP Tools

### Connection
- `set_sushi_server` - Set the IP address and port of the Sushi server

### System Information
- `get_sushi_info` - Get Sushi version and system information
- `get_available_plugins` - List available internal plugins

### Transport Control
- `get_transport_info` - Get current transport state
- `set_tempo` - Set the tempo in BPM
- `set_playing_mode` - Control playback (STOPPED, PLAYING, RECORDING)

### Track Management
- `get_all_tracks` - List all tracks
- `get_track_processors` - List processors on a track
- `add_processor_to_track` - Add a processor to a track
- `remove_processor_from_track` - Remove a processor

### Parameter Control
- `get_processor_parameters` - List all parameters for a processor
- `set_parameter_value` - Set a parameter value
- `bypass_processor` - Bypass or enable a processor

### Audio Routing
- `get_track_connections` - Get audio connections for a track
- `connect_input_to_track` - Route audio input to a track
- `connect_track_to_output` - Route track to audio output

### MIDI Control
- `get_midi_ports` - Get MIDI port information
- `get_midi_keyboard_connections` - List MIDI keyboard connections
- `connect_midi_keyboard_to_track` - Connect MIDI input to track
- `connect_midi_cc_to_parameter` - Map MIDI CC to parameter
- `send_note_on` / `send_note_off` - Send MIDI notes

### Preset Management
- `save_processor_preset` - Save processor state as preset
- `load_processor_preset` - Load a saved preset
- `list_presets` - List all saved presets
- `snapshot_all_tracks` - Save complete session state
- `load_snapshot` - Restore complete session state

### Real-time Monitoring
- `subscribe_to_parameter_updates` - Enable real-time updates
- `watch_parameter` - Monitor specific parameter
- `get_parameter_updates` - Get recent parameter changes

## Project Structure

```
sushi-mcp/
├── sushi_mcp_server.py      # Main MCP server implementation
├── sushi_rpc.proto          # gRPC protocol definition
├── sushi_rpc_pb2.py         # Generated protobuf code
├── sushi_rpc_pb2_grpc.py    # Generated gRPC code
├── default_config_sushi.json   # Sample Sushi configuration
├── pyproject.toml           # Project dependencies
├── presets/                 # Saved presets directory
└── README.md                # This file
```

## Development

### Regenerating gRPC Code

If you need to update the gRPC interface:

```bash
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. sushi_rpc.proto
```

### Adding New Features

1. Add new tool functions decorated with `@mcp.tool()`
2. Implement the gRPC calls to Sushi
3. Add appropriate error handling
4. Update this README with the new functionality

## Troubleshooting

### Connection Issues
- Ensure Sushi is running with gRPC enabled
- Check that the gRPC port (default 51051) is accessible
- Verify the IP address and port with `set_sushi_server`

### Parameter Ranges
- The server validates parameter values against their defined ranges
- Use `get_processor_parameters` to see valid ranges

### MIDI Channels
- MIDI channels are 1-16 (17 for omni mode)
- Channel 0 is not valid in the MIDI specification

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

This project is licensed under the same terms as your other projects. Please add appropriate license file.

## Acknowledgments

- Built for the [Sushi](https://github.com/elk-audio/sushi) audio engine by Elk Audio
- Uses the [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) specification