Content
# Synesthesia MCP Server (TypeScript)
TypeScript implementation of the Model Context Protocol (MCP) server for controlling **Synesthesia** lighting and visual software. This provides a type-safe, modern alternative to the Python implementation with identical functionality.
## ✨ Features
- **Type-Safe**: Full TypeScript implementation with strict typing
- **11 MCP Tools**: Complete control over Synesthesia via OSC protocol
- **Modern Architecture**: Promise-based async/await patterns throughout
- **Robust Error Handling**: Comprehensive validation and error recovery
- **Development Tools**: Hot reload, linting, testing, and debugging
- **OSC Communication**: Efficient bidirectional OSC message handling
- **Connection Management**: Automatic reconnection and connection pooling
## 🏗️ Architecture
This project consists of two main components:
1. **OSC Daemon** (`src/osc-daemon.ts`): Bridges TCP connections to OSC communication with Synesthesia
2. **MCP Server** (`src/mcp-server.ts`): Provides 11 tools for Claude Desktop integration
## ⚡ Quick Start
```bash
# Install dependencies
npm install
# Start OSC daemon (in one terminal)
npm run daemon
# Test connection (in another terminal)
npm run test-connection
# Start MCP server for development
npm run dev
```
See [QUICK_SETUP.md](docs/QUICK_SETUP.md) for detailed setup instructions.
## 🛠️ Available MCP Tools
| Tool | Description | Example Usage |
|------|-------------|---------------|
| `control_synesthesia` | Direct OSC control | Set brightness, colors, positions |
| `launch_scene` | Launch scenes with presets | Launch "hexarray" scene |
| `control_playlist` | Playlist navigation | Next, previous, play, stop |
| `control_media` | Media selection | Select by name or position |
| `randomize_controls` | Randomize control banks | Randomize scene or meta controls |
| `set_rendering` | Enable/disable rendering | Pause or resume output |
| `trigger_preset` | Activate presets | Load saved control states |
| `create_preset` | Save current state | Create new presets |
| `trigger_favslot` | Activate favslots | Quick scene access |
| `reset_controls` | Reset to defaults | Clear current values |
| `test_connection` | Validate setup | Check daemon connectivity |
## 📝 Development
[Development Tips](./DEVELOPMENT_TIPS.md)
### Scripts
```bash
# Quick Start (Recommended)
npm run all # Run both daemon and MCP server together
npm run all:dev # Run both in development mode with hot reload
# Development
npm run dev # Start MCP server with hot reload
npm run daemon # Start OSC daemon only
npm run build # Build for production
npm start # Run production build
# Testing & Validation
npm test # Run test suite
npm run test-connection # Test daemon connection
npm run validate # Validate setup
# Code Quality
npm run lint # Check code style
npm run lint:fix # Fix linting issues
npm run format # Format code
```
### Project Structure
```
src/
├── mcp-server.ts # Main MCP server with 11 tools
├── osc-daemon.ts # OSC daemon service
├── synesthesia-client.ts # Client for daemon communication
├── types/
│ ├── osc.ts # OSC protocol types
│ ├── synesthesia.ts # Synesthesia-specific types
│ └── mcp.ts # MCP-related types
└── utils/
├── validation.ts # Zod schemas for input validation
└── logging.ts # Structured logging utilities
```
## 🔧 Configuration
### Default Ports
- **MCP ↔ Daemon**: TCP port 7654
- **Daemon → Synesthesia**: UDP port 7000 (OSC output)
- **Synesthesia → Daemon**: UDP port 7001 (OSC input)
### Environment Variables
```bash
LOG_LEVEL=1 # 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
```
### Custom Configuration
Modify the configuration objects in the source files:
```typescript
// In src/mcp-server.ts
const clientConfig: ConnectionConfig = {
host: '127.0.0.1',
port: 7654,
timeoutMs: 5000,
};
// In src/osc-daemon.ts
const config: OSCDaemonConfig = {
socketHost: '127.0.0.1',
socketPort: 7654,
synesthesiaHost: '127.0.0.1',
synesthesiaPort: 7000,
receivePort: 7001,
};
```
## 🧪 Testing
### Unit Tests
```bash
npm test
```
### Manual Testing
```bash
# Test daemon connection
npm run test-connection
# Validate full setup
npm run validate
```
### Integration Testing
Start the daemon and test with Claude Desktop or direct tool calls.
## 📚 API Reference
### Example Tool Usage
```javascript
// Control brightness
await control_synesthesia({
address: "/controls/meta/brightness",
value: 0.75
});
// Launch scene with preset
await launch_scene({
scene_name: "hexarray",
preset_name: "warm"
});
// Control playlist
await control_playlist({
action: "next"
});
// Randomize scene controls
await randomize_controls({
bank: "scene",
group: "color"
});
```
See the [Python documentation](../SYNESTHESIA_OSC_API.md) for complete OSC API reference.
## 🔄 Differences from Python Version
### Advantages
- **Type Safety**: Compile-time error checking and IntelliSense
- **Modern Async**: Native Promise-based async/await patterns
- **Better Tooling**: Hot reload, advanced debugging, comprehensive linting
- **Performance**: Efficient V8 JavaScript engine
- **Ecosystem**: Rich Node.js ecosystem and packages
### Compatibility
- **Identical Functionality**: All 11 MCP tools work exactly the same
- **Same OSC Protocol**: Compatible with existing Synesthesia setups
- **Same Configuration**: Uses identical port numbers and setup process
## 🚀 Deployment
### Production Build
```bash
npm run build
npm start
```
### Claude Desktop Configuration
Run `npm run daemon` in background (to do: combine into single node script if possible)
```json
{
"mcpServers": {
"Synesthesia Controller": {
"command": "node",
"args": ["C:/full/path/to/synesthesia-mcp/dist/mcp-server.js"]
}
}
}
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make changes with proper TypeScript typing
4. Add tests for new functionality
5. Ensure all tests pass: `npm test`
6. Lint and format: `npm run lint:fix && npm run format`
7. Commit changes: `git commit -m 'Add amazing feature'`
8. Push to branch: `git push origin feature/amazing-feature`
9. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
## 🙏 Acknowledgments
- Original Python implementation by the Synesthesia MCP team
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) specification
- [node-osc](https://github.com/MylesBorins/node-osc) for OSC protocol implementation
- [Zod](https://zod.dev) for runtime type validation
- TypeScript and Node.js communities
## 📞 Getting Help
- **Setup Issues**: Check [QUICK_SETUP.md](docs/QUICK_SETUP.md)
- **OSC Commands**: Reference [SYNESTHESIA_OSC_API.md](../SYNESTHESIA_OSC_API.md)
- **Development**: Run `npm run validate` for setup verification
- **Connection Problems**: Run `npm run test-connection`
---
**Status**: ✅ Ready for production use
**TypeScript Version**: 5.3+
**Node.js Version**: 18+
**MCP Protocol**: Compatible with Claude Desktop
