# 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.