🔬 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

1. Implement in appropriate tools/ module
2. Register in qudi_mcp_server.py tool list
3. Add safety validation for parameters
4. Test thoroughly in dry-run mode
5. 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

1. Dry-run: Logic validation without hardware
2. Simulation: Realistic behavior testing
3. Hardware: Real instrument validation (when available)
4. Safety: Verify all safety mechanisms
5. 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

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

Contributing

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

1. Fork the repository
2. Create feature branches from dev/llm-mcp-automation
3. Follow safety-first development practices
4. Include comprehensive tests
5. 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