qudi MCP Integration

🔬 qudi MCP Integration

Model Context Protocol (MCP) integration for qudi quantum photonics experiments

Enable natural language control of quantum experiments through Claude Desktop!

🚀 Quick Start

1. Installation Options

📋 Standalone Mode (Recommended for Testing)

# Clone this repository
git clone https://github.com/dirkenglund/qudi-mcp-integration.git
cd qudi-mcp-integration

# Install minimal dependencies (simulation only)
pip install -r requirements-standalone.txt

🖼️ With Plot Extraction Capabilities

# Install standalone + plot extraction
pip install -r requirements-standalone.txt
pip install -r requirements-plot-extraction.txt

🔬 Full qudi Integration (For Hardware Control)

# For real quantum hardware control
pip install -r requirements-full.txt

# Additional setup required:
# 1. Install qudi-core separately
# 2. Configure hardware drivers  
# 3. Set up measurement modules

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "qudi-mcp": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["/path/to/qudi-mcp-integration/simple_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/qudi-mcp-integration",
        "QUDI_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

3. Test with Claude Desktop

Restart Claude Desktop and try:

"Get qudi station information"

Example Commands:

"Start a photoluminescence scan from 630-650 nm"
"Check all safety interlocks before measurement"
"Can I safely set laser power to 5 milliwatts?"

Features

🛡️ Safety First

Runlevels: dry-run → sim → live progression
Parameter Validation: All values checked against safety limits
Emergency Stop: Immediate halt capability
Interlocks: Critical system monitoring

🔧 Instrument Control

List and load qudi instruments
Get/set parameters with safety validation
Real-time status monitoring
Simulated operation for safe testing

📊 Measurement Execution

Available modules: PL scan, gate sweep, resonance scan, time trace, 2D maps
Progress monitoring and data acquisition
Configurable measurement parameters
Data export capabilities

🤖 LLM Integration

Natural language command processing
Contextual tool suggestions
Comprehensive error reporting
Audit logging for all operations

🖼️ Plot Extraction (Optional)

RKHS Spline Projection - Mathematical smoothing using reproducing kernel Hilbert spaces
Computer Vision - Extract data points from scientific plots and graphs
Spectrum Analysis - Advanced processing for spectroscopy data
Multiple Formats - Support for PNG, JPG, TIFF, and other image formats
Quantum Data - Optimized for photoluminescence and transport measurements

Plot Extraction Commands:

"Extract data from this plot image: /path/to/spectrum.png"
"Analyze spectrum with RKHS smoothing using epsilon 0.05"
"What plot extraction capabilities are available?"

Architecture

Claude ←→ MCP ←→ qudi_mcp_server ←→ qudi ←→ Instruments
           ↓
     Safety System
     Runlevel Control
     Parameter Validation

Core Components

qudi_mcp_server.py: Main MCP server and tool router
safety.py: Safety system and runlevel management
tools/: Tool implementations (instruments, measurements, safety)
claude_config/: Claude Desktop configuration templates

Safety System

Runlevels

dry-run (default): Simulation only, no hardware interaction
sim: Realistic simulation with hardware-like responses
live: Real hardware control (requires approval + safety checks)

Built-in Limits

Laser power: 0-10 mW
Gate voltages: ±2.0 V
Bias voltages: ±1.0 V
Temperature: 0.01-300 K
Magnetic field: ±9.0 T
Measurement time: 0.001-3600 s

Emergency Procedures

All emergency stop triggers:

Halt all running measurements
Force runlevel to dry-run
Log incident with timestamp
Require manual reset with confirmation

Usage Examples

System Status

# Check system status
→ Get qudi station information

# Response: runlevel, loaded instruments, active measurements, safety status

Instrument Control

# List instruments
→ List available qudi instruments

# Load an instrument  
→ Load the laser_controller instrument

# Set parameter safely
→ Set laser power to 2.5 mW

Measurements

# Start a measurement
→ Start a photoluminescence scan from 630 to 650 nm with 0.5 second integration

# Check progress
→ What's the status of running measurements?

# Get results
→ Get the measurement data for the PL scan

Safety Operations

# Check safety systems
→ Check all safety interlocks

# Change runlevel (when ready for hardware)
→ Set runlevel to sim mode for realistic testing

# Emergency procedures
→ Emergency stop all operations

Development Status

✅ Completed (Phase 1)

MCP server framework
Safety system with runlevels and limits
Tool architecture for instruments, measurements, safety
Claude Desktop integration
Comprehensive simulation mode
Documentation and setup guides

🚧 In Progress (Phase 2)

qudi core integration
Real instrument driver connections
Hardware abstraction layer
Live mode approval workflows

📋 Planned (Phase 3)

Advanced measurement protocols
Data analysis tool integration
Multi-user access control
Web-based monitoring interface

File Structure

mcp_integration/
├── __init__.py                 # Package initialization
├── qudi_mcp_server.py         # Main MCP server
├── safety.py                  # Safety and runlevel system
├── tools/                     # MCP tool implementations
│   ├── __init__.py
│   ├── instrument_tools.py    # Instrument control tools
│   ├── measurement_tools.py   # Measurement execution tools  
│   └── safety_tools.py        # Safety and emergency tools
├── claude_config/             # Claude configuration templates
├── README.md                  # This file
└── requirements.txt           # Python dependencies

Development Guidelines

Adding New Tools

Implement in appropriate tools/ module
Register in qudi_mcp_server.py tool list
Add safety validation for parameters
Test thoroughly in dry-run mode
Document in tool docstrings

Safety Requirements

All write operations must validate parameters
Critical operations need explicit approval in live mode
Comprehensive error handling and logging required
Emergency stop must work from any state

Testing Protocol

Dry-run: Logic validation without hardware
Simulation: Realistic behavior testing
Hardware: Real instrument validation (when available)
Safety: Verify all safety mechanisms
Integration: End-to-end workflow testing

Troubleshooting

Common Issues

"MCP package not found"

pip install mcp

"Tool not found" errors

Check tool registration in qudi_mcp_server.py
Verify tool implementation in tools/ modules

Safety validation failures

Check parameter values against limits in safety.py
Use safety.get_limits to see current constraints

Claude Desktop not seeing tools

Verify absolute paths in configuration file
Restart Claude Desktop completely
Check Python path and MCP server execution

Getting Help

Check logs: MCP server logs to stderr
Test tools directly: Run python qudi_mcp_server.py
Validate config: Check Claude Desktop config file syntax
Start simple: Begin with station.info and safety.check_interlocks

Contributing

This integration is part of the MIT QPG development branch. To contribute:

Fork the repository
Create feature branches from dev/llm-mcp-automation
Follow safety-first development practices
Include comprehensive tests
Update documentation for new features

Repository: https://github.com/dirkenglund/qudi-iqo-modules-QPG
Branch: dev/llm-mcp-automation
Documentation: See docs/LLM_MCP_INTEGRATION.md for full details

qudi MCP Integration