# Cardinal MCP Server

MCP (Model Context Protocol) server for Cardinal/VCV Rack patch manipulation with AI.

**World's first AI integration for modular synthesizer patching!**

## Features

- **Analyze patches** - Understand what a patch does
- **Create patches** - Generate patches from templates
- **Add modules** - Insert new modules into patches
- **Connect modules** - Wire up modules with cables
- **Suggest modules** - Get recommendations based on your goal
- **Modify parameters** - Adjust knobs and settings

## Installation

```bash
# Clone this repository
git clone https://github.com/YOUR_USERNAME/cardinal-mcp-server.git
cd cardinal-mcp-server

# Install dependencies
npm install

# Build
npm run build
```

## Usage with Claude Code

Add to your Claude Code settings (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "cardinal": {
      "command": "node",
      "args": ["/path/to/cardinal-mcp-server/dist/index.js"]
    }
  }
}
```

Then restart Claude Code.

## Available Tools

### analyze_patch
Analyze a .vcv patch file and explain what it does.

```
"Analyze the patch at /path/to/my-patch.vcv"
```

### create_patch
Create a new patch from a template.

Templates:
- `basic-synth` - Simple VCO → ADSR → VCA → Output
- `ambient-pad` - VCO → VCF (with LFO) → ADSR → VCA → Output
- `empty` - Blank patch

```
"Create an ambient pad patch at ~/Desktop/my-ambient.vcv"
```

### suggest_modules
Get module suggestions for what you want to create.

```
"Suggest modules for a bass sound"
"Suggest modules for an ambient pad"
"Suggest modules for drum sounds"
```

### add_module
Add a module to an existing patch.

```
"Add a Fundamental:VCF filter to my patch"
```

### connect_modules
Connect two modules with a cable.

```
"Connect module 2 output 0 to module 3 input 1"
```

### list_modules
List available modules in the database.

```
"List all oscillator modules"
"List all filter modules"
```

### modify_parameter
Change a parameter value on a module.

```
"Set the attack (param 0) on module 3 to 0.5"
```

## Example Conversation

**You:** Create a basic synth patch for me

**Claude:** I'll create a basic-synth patch with VCO → ADSR → VCA → Audio Out...

**You:** Make the attack longer

**Claude:** I'll modify the ADSR attack parameter...

**You:** Add a filter between the VCO and VCA

**Claude:** Adding a Fundamental:VCF and reconnecting the signal flow...

## Supported Modules

Currently includes definitions for:

- **Oscillators**: Fundamental VCO, Bogaudio VCO
- **Filters**: Fundamental VCF
- **Envelopes**: Fundamental ADSR
- **VCAs**: Fundamental VCA-1
- **Modulation**: Fundamental LFO
- **Sequencers**: Fundamental SEQ-3
- **Effects**: Valley Plateau
- **Utilities**: Fundamental Mixer
- **I/O**: Cardinal HostMIDI, HostAudio2

More modules can be added to the MODULE_DATABASE in the source code.

## Contributing

PRs welcome! To add more modules:

1. Add entries to `MODULE_DATABASE` with description, category, inputs, and outputs
2. Optionally add new patch templates to `PATCH_TEMPLATES`

## License

MIT

## Links

- [Cardinal](https://github.com/DISTRHO/Cardinal) - The free and open-source virtual modular synthesizer
- [VCV Rack](https://vcvrack.com/) - The original virtual Eurorack
- [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol specification