README.md•4.55 kB
# moku-mcp
Model Context Protocol (MCP) server for Moku device control.
## Overview
This MCP server provides LLM-friendly tools for controlling Moku devices:
- **Device Discovery**: Find Moku devices on the network
- **Connection Management**: Attach/detach with graceful ownership handoff
- **Configuration Deployment**: Push `MokuConfig` models to hardware
- **Routing Control**: Configure MCC signal routing
- **Metadata Queries**: Get device info and slot status
## Architecture
**Session Model**: Stateful connection management
- `attach(device_id)` → Connect and maintain ownership
- `detach()` → Release ownership (allows iPad/CLI handoff)
**Graceful Handoff**: Supports common workflow where ownership moves between:
- Machine A (CLI) → iPad (GUI) → Machine B (LLM) → ...
**MokuConfig-Driven**: Uses `moku-models` package for type-safe configuration.
## Installation
```bash
# Clone repository
git clone https://github.com/sealablab/moku-mcp.git
cd moku-mcp
# Install with uv (recommended)
uv pip install -e .
# Or with pip
pip install -e .
```
## Usage
### Running the MCP Server
```bash
# Run server via stdio (MCP standard)
python -m moku_mcp
# Or with uv
uv run python -m moku_mcp
```
### Integration with Claude Desktop
Add to your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"moku": {
"command": "uv",
"args": ["run", "python", "-m", "moku_mcp"],
"cwd": "/path/to/moku-mcp"
}
}
}
```
### Using the Session Context Manager
For safe device management with automatic cleanup:
```python
from moku_mcp.session import MokuSession
async def deploy_config_safely(device_id: str, config: dict):
async with MokuSession(device_id) as moku:
# Device is automatically connected
result = await moku.push_config(config)
# Device is automatically released even if error occurs
return result
```
## MCP Tools
### 1. discover_mokus()
Discover Moku devices on network via zeroconf.
**Returns**: List of devices with IP, name, serial number
### 2. attach_moku(device_id)
Connect to Moku device and assume ownership.
**Args**:
- `device_id` (str): IP address, device name, or serial number
**Returns**: Connection status and device metadata
### 3. release_moku()
Disconnect and release ownership.
**Returns**: Disconnect status
### 4. push_config(config)
Deploy MokuConfig to connected device.
**Args**:
- `config` (dict): MokuConfig serialized as dictionary
**Returns**: Deployment status
**Example**:
```python
config = {
"platform": {...},
"slots": {
1: {
"instrument": "CloudCompile",
"bitstream": "path/to/bitstream.tar"
}
},
"routing": [
{"source": "Slot1OutA", "destination": "Output1"}
]
}
```
### 5. get_config()
Retrieve current device configuration.
**Returns**: MokuConfig as dict
### 6. set_routing(connections)
Configure MCC signal routing.
**Args**:
- `connections` (list): List of MokuConnection dicts
**Example**:
```python
connections = [
{"source": "Input1", "destination": "Slot1InA"},
{"source": "Slot1OutA", "destination": "Output1"}
]
```
### 7. get_device_info()
Query device metadata.
**Returns**: Dict with name, serial, IP, platform type
### 8. list_slots()
List configured instrument slots.
**Returns**: Dict of slot numbers to instrument info
## Implementation Status
✅ **Core Implementation Complete**
All 8 MCP tools are fully implemented:
- Device discovery via zeroconf
- Connection management with singleton pattern
- Configuration deployment (CloudCompile & Oscilloscope)
- Signal routing configuration
- Device metadata queries
- Session context manager for safe cleanup
## Development
```bash
# Install dev dependencies
uv pip install -e ".[dev]"
# Run tests (when implemented)
pytest
# Format code
black src/
ruff check src/
```
## Dependencies
**1st Party**:
- `moku-models` - Pydantic models for Moku configuration
- `moku` - Official Moku hardware API
**3rd Party**:
- `mcp` - Model Context Protocol SDK
- `pydantic` - Data validation
- `loguru` - Logging
- `zeroconf` - Device discovery via mDNS/Bonjour
## Next Steps
See `IMPLEMENTATION_GUIDE.md` for:
- MCP SDK setup
- Tool implementation patterns
- Testing strategies
- Deployment workflows
## License
MIT License - see LICENSE file for details.