QML-MCP

# QML-MCP: Quantum Machine Learning MCP Server A Model Context Protocol (MCP) server for Quantum Machine Learning using Qiskit. ## Features - **Quantum Circuit Execution**: Run quantum circuits with configurable shots - **Quantum Kernel Computation**: Compute quantum kernels for ML tasks - **Variational Quantum Classifier (VQC)**: Train quantum classifiers - **Model Evaluation**: Evaluate trained quantum ML models - **Safety Limits**: Configurable limits on qubits and shots - **Structured Logging**: Comprehensive logging for debugging - **Error Handling**: Detailed error messages with tracebacks ## Installation ```bash pip install -e . ``` For development: ```bash pip install -e ".[dev]" ``` ## Requirements - Python >= 3.10 - Qiskit >= 1.0.0, < 2.0.0 (Note: Qiskit Machine Learning 0.8.4 requires Qiskit 1.x) - Qiskit Machine Learning >= 0.8.4 - MCP >= 0.9.0 **Note on Qiskit Version**: While Qiskit 2.0+ is available, Qiskit Machine Learning 0.8.4 (the latest stable version) requires Qiskit 1.x. This implementation uses Qiskit 1.4.5+ which provides all necessary quantum ML features. ## Configuration The server can be configured via environment variables: - `QML_MCP_QUANTUM_MAX_SHOTS`: Maximum shots per circuit (default: 100000) - `QML_MCP_QUANTUM_MAX_QUBITS`: Maximum qubits allowed (default: 10) - `QML_MCP_QUANTUM_DEFAULT_SHOTS`: Default shots for circuits (default: 1024) - `QML_MCP_LOG_LEVEL`: Logging level (default: INFO) - `QML_MCP_ENABLE_DETAILED_ERRORS`: Include detailed error traces (default: true) ## Usage ### Running the Server ```bash python server.py ``` ### Available Tools #### 1. run_quantum_circuit Execute a quantum circuit and get measurement results. **Parameters:** - `qasm` (required): Quantum circuit in QASM3 format - `shots` (optional): Number of measurement shots (default: 1024) **Example:** ```json { "qasm": "OPENQASM 3.0;\ninclude \"stdgates.inc\";\nqubit[2] q;\nbit[2] c;\nh q[0];\ncx q[0], q[1];\nc[0] = measure q[0];\nc[1] = measure q[1];", "shots": 1000 } ``` #### 2. compute_quantum_kernel Compute quantum kernel matrix for ML tasks using ZZ feature map. **Parameters:** - `train_data` (required): Training data as 2D array - `test_data` (optional): Test data as 2D array - `feature_dimension` (optional): Number of features **Example:** ```json { "train_data": [[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]], "test_data": [[0.7, 0.8]] } ``` #### 3. train_vqc Train a Variational Quantum Classifier. **Parameters:** - `X_train` (required): Training features as 2D array - `y_train` (required): Training labels as 1D array - `feature_dimension` (optional): Number of features - `max_iter` (optional): Maximum optimization iterations (default: 100) **Example:** ```json { "X_train": [[0.1, 0.2], [0.2, 0.3], [0.8, 0.9], [0.9, 0.8]], "y_train": [0, 0, 1, 1], "max_iter": 50 } ``` Returns a base64-encoded trained model. #### 4. evaluate_model Evaluate a trained quantum ML model. **Parameters:** - `model` (required): Base64-encoded trained model - `X_test` (required): Test features as 2D array - `y_test` (optional): Test labels for accuracy computation **Example:** ```json { "model": "gASVPAIAAA...", "X_test": [[0.15, 0.25], [0.85, 0.95]], "y_test": [0, 1] } ``` ## Testing Run tests: ```bash pytest tests/ ``` Run with coverage: ```bash pytest --cov=. --cov-report=html tests/ ``` ## Project Structure ``` qml-mcp/ ├── server.py # Main MCP server ├── config.py # Configuration with Pydantic ├── qml/ # Quantum ML utilities │ ├── __init__.py │ └── utils.py # Core QML functions ├── tools/ # Additional tools ├── resources/ # MCP resources ├── prompts/ # Prompt templates ├── tests/ # Test suite │ ├── test_config.py │ └── test_qml_utils.py └── pyproject.toml # Project metadata ``` ## Safety and Limits The server implements several safety mechanisms: - **Qubit Limits**: Maximum number of qubits per circuit (default: 10) - **Shot Limits**: Maximum measurement shots (default: 100000) - **Input Validation**: All inputs are validated before processing - **Error Handling**: Comprehensive error messages with optional tracebacks ## License MIT License - see LICENSE file for details.