ableton-cookbook-mcp/
├── packages/
│   ├── mcp-server/            # TypeScript MCP Server 🟢 ACTIVE
│   │   ├── src/
│   │   │   ├── index.ts       # Main MCP server (16 tools)
│   │   │   ├── archivist.ts   # Offline .als parsing
│   │   │   ├── operator.ts    # Real-time Live control
│   │   │   ├── historian.ts   # Version control bridge
│   │   │   └── analyzer.ts    # Rack/preset analysis bridge
│   │   └── dist/              # Compiled JavaScript
│   │
│   ├── python-scripts/        # Version Control System 🟢 ACTIVE
│   │   ├── ableton_version_manager.py
│   │   ├── ableton_visualizer.py
│   │   └── ableton_diff.py
│   │
│   └── php-analyzers/         # Rack/Preset Parsers 🟢 ACTIVE
│       ├── abletonRackAnalyzer/
│       ├── abletonDrumRackAnalyzer/
│       ├── abletonPresetAnalyzer/
│       └── abletonSessionAnalyzer/
│
├── .claude/                   # AI context & planning docs
│   ├── PROJECT_CONTEXT.md
│   ├── ARCHITECTURE.md
│   ├── VISION_AND_ROADMAP.md
│   └── WEEK_1_IMPLEMENTATION.md
│
├── docs/                      # GitHub Pages documentation
├── .github/
│   ├── workflows/             # CI/CD automation
│   └── ISSUE_TEMPLATE/        # Bug/feature templates
│
└── cookbook-website/          # Laravel Web Platform (symlink)
    └── → (External Laravel project)

# Clone the repository
git clone https://github.com/teamallnighter/ableton-cookbook-mcp.git
cd ableton-cookbook-mcp

# Install and build MCP server
cd packages/mcp-server
npm install
npm run build

{
  "mcpServers": {
    "ableton": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ableton-cookbook-mcp/packages/mcp-server/dist/index.js"]
    }
  }
}

cd packages/mcp-server

# Watch mode (auto-rebuild on changes)
npm run watch

# Lint and format
npm run lint
npm run format

# Manual build
npm run build

After adding the configuration, restart Claude Desktop.

## Available Tools

### Offline Analysis (Archivist)
- **scan_project_files** - Find all .als files in a directory
- **inspect_als** - Parse an .als file to extract structure

### Live Control (Operator)
- **get_live_status** - Get transport status and tempo
- **list_live_tracks** - List all tracks in the current set
- **set_track_volume** - Control track volume

### Version Control (Historian)
- **get_version_history** - Show all versions with timestamps
- **scan_versions** - Find versioned .als files (_X.Y.Z.als pattern)
- **compare_versions** - Diff two specific versions
- **get_latest_changes** - View most recent change report
- **get_change_report** - Get changes between specific versions
- **generate_timeline** - Create HTML timeline visualization

### Rack & Preset Analysis (Analyzer)
- **analyze_rack** - Extract device chains, macros, and metadata from .adg racks
- **analyze_drum_rack** - Parse drum rack pad assignments and samples
- **analyze_preset** - Inspect device preset (.adv) parameter settings
- **scan_user_library** - Index all racks, drum racks, and presets in User Library
- **search_racks_by_device** - Find racks containing specific devices (e.g., "Serum")


## Contributing

We welcome contributions! Whether you're a producer, developer, or both - your input helps make this tool better for the music production community.

**Ways to contribute:**
- 🐛 [Report bugs](https://github.com/teamallnighter/ableton-cookbook-mcp/issues/new?template=bug_report.yml)
- ✨ [Request features](https://github.com/teamallnighter/ableton-cookbook-mcp/issues/new?template=feature_request.yml)
- 📚 Improve documentation
- 🔧 Submit pull requests
- 💬 [Join discussions](https://github.com/teamallnighter/ableton-cookbook-mcp/discussions)

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## Documentation

- 📖 **[Full Documentation](https://teamallnighter.github.io/ableton-cookbook-mcp/)** - Setup guides and examples
- 🏗️ **[Architecture](.claude/ARCHITECTURE.md)** - Technical design and data models
- 🗺️ **[Vision & Roadmap](.claude/VISION_AND_ROADMAP.md)** - Product vision and future plans
- 🔧 **[Development Guide](.claude/DEVELOPMENT.md)** - Setup, debugging, and testing
- 📋 **[Project Context](.claude/PROJECT_CONTEXT.md)** - Complete project overview

## Roadmap

- [x] **Phase 1: Proof of Concept** - MCP server with 16 tools ✅
- [ ] **Phase 2: Easy Setup** - Desktop installer for non-technical users
- [ ] **Phase 3: Community** - Web platform for sharing workflow recipes
- [ ] **Phase 4: Discovery** - Search, recommendations, and integrations

See [VISION_AND_ROADMAP.md](.claude/VISION_AND_ROADMAP.md) for detailed plans.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

Built with:
- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- [ableton-js](https://github.com/leolabs/ableton-js) by Leo Bernard
- Love for music production 🎵

---

**Made with 🎵 by [Team All Nighter](https://github.com/teamallnighter)**  
*For producers who code at 3am*
## Example Usage

Once configured, you can ask Claude:

**Live Control:**
- "What tracks are in my current Ableton set?"
- "Set the volume of the Bass track to 0.5"
- "What's the current tempo and play state?"

**Version Control:**
- "Show me the version history for my project"
- "What changed between version 0.1.0 and 0.1.2?"
- "Generate a timeline visualization for this project"

**Rack Analysis:**
- "Analyze this rack and show me the device chain"
- "What devices are in my Bass Daddy rack?"
- "Find all racks in my User Library that use Serum"
- "Scan my User Library and show me all my custom racks"