# CUDA Quantum MCP Server

A comprehensive Model Context Protocol (MCP) server that provides quantum computing capabilities using NVIDIA's CUDA Quantum framework with GPU acceleration support.

## 🚀 Features

### Quantum Circuit Building
- **Create quantum kernels** with parameterized circuits
- **Apply quantum gates** (H, X, Y, Z, CNOT, rotation gates, etc.)
- **Build common circuits** (Bell pairs, GHZ states, QFT)
- **Visualize circuits** in text format
- **Manage quantum registers** and qubit operations

### Quantum Execution
- **Sample quantum circuits** with measurement statistics
- **Compute expectation values** of Hamiltonians
- **Get quantum state vectors** with amplitude analysis
- **Run quantum algorithms** with custom return values
- **Variational optimization** for quantum machine learning

### Hardware Backend Integration
- **Multiple simulators**: CPU, GPU (cuQuantum), tensor networks
- **Quantum hardware**: IonQ, Quantinuum, Quantum Machines, and more
- **GPU acceleration** with NVIDIA CUDA support
- **Target configuration** with backend-specific parameters
- **Connectivity testing** for remote quantum processors

### Advanced Features
- **Python bridge** for seamless CUDA Quantum integration  
- **Asynchronous execution** for long-running quantum jobs
- **Error mitigation** and noise modeling
- **Multi-GPU support** for large-scale simulations
- **Comprehensive logging** and debugging tools

## 📦 Installation

### Prerequisites

1. **Node.js 18+** and npm
2. **Python 3.8+** with pip
3. **NVIDIA GPU** (optional, for GPU acceleration)
4. **CUDA Toolkit** (optional, for GPU backends)

### Install CUDA Quantum

```bash
# Install CUDA Quantum Python package
pip install cudaq

# For GPU support, ensure CUDA is properly installed
nvidia-smi  # Check NVIDIA driver
nvcc --version  # Check CUDA compiler
```

### Install MCP Server

```bash
# Clone the repository
git clone <repository-url>
cd mcp-quantum

# Install Node.js dependencies
npm install

# Install Python dependencies
npm run python-setup

# Build TypeScript
npm run build
```

### Environment Configuration

Copy the example environment file and configure:

```bash
cp .env.example .env
```

Edit `.env` with your settings:

```env
# Server Configuration
SERVER_PORT=3000
NODE_ENV=production

# CUDA Quantum Configuration  
CUDAQ_PYTHON_PATH=/usr/local/bin/python3
CUDAQ_DEFAULT_TARGET=qpp-cpu
CUDAQ_LOG_LEVEL=info

# Python Bridge Timeout (milliseconds)
# Default: 300000 (5 minutes)
# Increase for complex operations or slower hardware
PYTHON_TIMEOUT=300000

# GPU Configuration
CUDA_VISIBLE_DEVICES=0
CUDAQ_ENABLE_GPU=true

# Hardware Provider API Keys (optional)
QUANTUM_MACHINES_API_KEY=your_api_key_here
IONQ_API_KEY=your_api_key_here
```

## 🏃‍♂️ Quick Start

### 1. Start the MCP Server

```bash
npm start
```

### 2. Connect via MCP Client

The server uses stdio transport for MCP communication:

```bash
# Example connection via Claude Desktop
# Add to your Claude Desktop config
```

### 3. Basic Quantum Circuit Example

```javascript
// Create a Bell pair circuit
await mcp.callTool('create_quantum_kernel', {
  name: 'bell_pair',
  num_qubits: 2
});

// Apply Hadamard gate to qubit 0
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'bell_pair',
  gate_name: 'h',
  qubits: [0]
});

// Apply CNOT gate (controlled-X)
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'bell_pair', 
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

// Sample the circuit
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'bell_pair',
  shots: 1000
});
```

## 🔧 Available Tools

### Quantum Circuit Tools

#### `create_quantum_kernel`
Create a new quantum kernel with specified qubits and parameters.

```json
{
  "name": "my_kernel",
  "num_qubits": 4,
  "parameters": [
    {"name": "theta", "type": "float"},
    {"name": "angles", "type": "list[float]"}
  ]
}
```

#### `apply_quantum_gate`
Apply quantum gates to specific qubits with optional control qubits.

```json
{
  "kernel_name": "my_kernel",
  "gate_name": "rx",
  "qubits": [0],
  "parameters": [1.57],
  "controls": [],
  "adjoint": false
}
```

**Supported Gates:**
- **Single-qubit**: `h`, `x`, `y`, `z`, `s`, `t`, `rx`, `ry`, `rz`
- **Two-qubit**: `cx` (CNOT), `cy`, `cz`, `swap`
- **Multi-qubit**: `ccx` (Toffoli), `cswap` (Fredkin)

#### `create_common_circuit`
Generate commonly used quantum circuits.

```json
{
  "circuit_type": "ghz_state",
  "name": "ghz_3",
  "num_qubits": 3
}
```

**Available Circuits:**
- `bell_pair`: Maximally entangled two-qubit state
- `ghz_state`: Greenberger-Horne-Zeilinger state
- `quantum_fourier_transform`: QFT implementation
- `hadamard_test`: Hadamard test circuit

### Quantum Execution Tools

#### `sample_quantum_circuit`
Execute quantum circuit and sample measurement results.

```json
{
  "kernel_name": "bell_pair",
  "shots": 1000,
  "target": "qpp-gpu"
}
```

#### `observe_hamiltonian`
Compute expectation value of a Hamiltonian operator.

```json
{
  "kernel_name": "my_kernel",
  "hamiltonian_terms": [
    {
      "paulis": ["Z", "Z"],
      "qubits": [0, 1],
      "coefficient": {"real": 1.0, "imag": 0.0}
    }
  ],
  "shots": 1000
}
```

#### `get_quantum_state`
Retrieve the quantum state vector from a circuit.

```json
{
  "kernel_name": "my_kernel",
  "format": "amplitudes"
}
```

### Hardware Backend Tools

#### `set_quantum_target`
Configure quantum execution target.

```json
{
  "target": "qpp-gpu",
  "configuration": {
    "shots": 1000,
    "optimization_level": 2
  }
}
```

**Available Targets:**

**Simulators:**
- `qpp-cpu`: CPU state vector simulator
- `qpp-gpu`: GPU-accelerated simulator (cuQuantum)
- `density-matrix-cpu`: Density matrix simulator
- `tensor-network`: Tensor network simulator

**Hardware Providers:**
- `ionq`: IonQ quantum processors
- `quantinuum`: Quantinuum H-Series
- `quantum_machines`: Quantum Machines platform
- `infleqtion`: Infleqtion quantum processors

#### `configure_gpu_acceleration`
Enable/disable GPU acceleration for quantum simulations.

```json
{
  "enable": true,
  "device_id": 0,
  "memory_limit": 8.0,
  "target": "qpp-gpu"
}
```

## 🧪 Examples

### Example 1: Quantum Teleportation Circuit

```javascript
// Create quantum teleportation circuit
await mcp.callTool('create_quantum_kernel', {
  name: 'teleportation',
  num_qubits: 3
});

// Prepare Bell pair (qubits 1,2)
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'h',
  qubits: [1]
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'x',
  qubits: [2],
  controls: [1]
});

// Teleportation protocol (qubit 0 -> qubit 2)
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'h',
  qubits: [0]
});

// Sample the results
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'teleportation',
  shots: 1000
});
```

### Example 2: Variational Quantum Eigensolver (VQE)

```javascript
// Create parameterized ansatz
await mcp.callTool('create_quantum_kernel', {
  name: 'vqe_ansatz',
  num_qubits: 2,
  parameters: [
    {"name": "theta1", "type": "float"},
    {"name": "theta2", "type": "float"}
  ]
});

// Build ansatz circuit
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'vqe_ansatz',
  gate_name: 'ry',
  qubits: [0],
  parameters: ['theta1']  // Parameter reference
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'vqe_ansatz',
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

// Define H2 molecule Hamiltonian
const h2_hamiltonian = [
  {
    "paulis": ["Z", "I"],
    "qubits": [0, 1],
    "coefficient": {"real": -1.0523732, "imag": 0.0}
  },
  {
    "paulis": ["I", "Z"],
    "qubits": [0, 1], 
    "coefficient": {"real": -1.0523732, "imag": 0.0}
  },
  {
    "paulis": ["Z", "Z"],
    "qubits": [0, 1],
    "coefficient": {"real": -0.39793742, "imag": 0.0}
  }
];

// Compute expectation value
await mcp.callTool('observe_hamiltonian', {
  kernel_name: 'vqe_ansatz',
  hamiltonian_terms: h2_hamiltonian,
  parameters: {"theta1": 0.5, "theta2": 1.2}
});
```

### Example 3: GPU-Accelerated Simulation

```javascript
// Configure GPU acceleration
await mcp.callTool('configure_gpu_acceleration', {
  enable: true,
  device_id: 0,
  target: 'qpp-gpu'
});

// Create large quantum circuit
await mcp.callTool('create_quantum_kernel', {
  name: 'large_circuit',
  num_qubits: 20
});

// Apply random circuit
for (let i = 0; i < 20; i++) {
  await mcp.callTool('apply_quantum_gate', {
    kernel_name: 'large_circuit',
    gate_name: 'h',
    qubits: [i]
  });
}

// Add entangling gates
for (let i = 0; i < 19; i++) {
  await mcp.callTool('apply_quantum_gate', {
    kernel_name: 'large_circuit',
    gate_name: 'x',
    qubits: [i + 1],
    controls: [i]
  });
}

// Sample with GPU acceleration
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'large_circuit',
  shots: 10000,
  target: 'qpp-gpu'
});
```

## 🔌 Hardware Provider Setup

### IonQ Configuration

```javascript
await mcp.callTool('set_quantum_target', {
  target: 'ionq',
  configuration: {
    api_key: process.env.IONQ_API_KEY,
    backend: 'simulator',  // or 'qpu'
    shots: 1000
  }
});
```

### Quantinuum Setup

```javascript
await mcp.callTool('set_quantum_target', {
  target: 'quantinuum',
  configuration: {
    api_key: process.env.QUANTINUUM_API_KEY,
    device: 'H1-1E',  // or other available devices
    shots: 1000
  }
});
```

### Quantum Machines Setup

```javascript
await mcp.callTool('set_quantum_target', {
  target: 'quantum_machines',
  configuration: {
    api_key: process.env.QUANTUM_MACHINES_API_KEY,
    url: 'https://api.quantum-machines.com',
    executor: 'qpu'  // or 'simulator'
  }
});
```

## 🐛 Troubleshooting

### Common Issues

#### CUDA Quantum Import Error
```bash
Error: CUDA Quantum not available
Solution: pip install cudaq
```

#### GPU Not Detected
```bash
Error: CUDA device not found
Solution: 
1. Check nvidia-smi output
2. Install NVIDIA drivers
3. Set CUDA_VISIBLE_DEVICES=0
```

#### Python Bridge Timeout
```bash
Error: Python command timeout after Xms
Solution: 
1. Increase timeout with environment variable:
   export PYTHON_TIMEOUT=600000  # 10 minutes in milliseconds
2. Check Python path in .env:
   CUDAQ_PYTHON_PATH=/usr/local/bin/python3
3. Ensure CUDA Quantum is properly installed:
   python3 -c "import cudaq; print(cudaq.__version__)"
4. Check for Python process errors in logs
```

**Note**: The default timeout is 300,000ms (5 minutes). Complex quantum operations or slower hardware may require increasing this value via the `PYTHON_TIMEOUT` environment variable.

### Debug Mode

Enable debug logging:

```bash
export LOG_LEVEL=debug
npm start
```

### Testing Connection

```javascript
// Test platform availability
await mcp.callTool('get_platform_info');

// Test backend connectivity
await mcp.callTool('test_backend_connectivity', {
  backend: 'qpp-gpu'
});
```

## 🧪 Testing

Run the test suite:

```bash
# Unit tests
npm test

# Integration tests  
npm run test:integration

# Coverage report
npm run test:coverage
```

## 📚 API Reference

### MCP Tool Schema

All tools follow the MCP (Model Context Protocol) specification:

```typescript
interface MCPTool {
  name: string;
  description: string;
  inputSchema: JSONSchema;
}

interface MCPToolResult {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    text?: string;
    data?: string;
    uri?: string;
  }>;
  isError?: boolean;
}
```

### Python Bridge API

The Python bridge provides direct access to CUDA Quantum:

```typescript
class PythonBridge {
  // Kernel management
  createKernel(name: string, numQubits: number): Promise<PythonResponse>;
  applyGate(kernel: string, gate: string, qubits: number[]): Promise<PythonResponse>;
  
  // Execution
  sample(kernel: string, shots?: number): Promise<PythonResponse>;
  observe(kernel: string, hamiltonian: any[]): Promise<PythonResponse>;
  getState(kernel: string): Promise<PythonResponse>;
  
  // Configuration
  setTarget(target: string, config?: any): Promise<PythonResponse>;
}
```

## 🚀 Deployment

### Docker Deployment

```dockerfile
FROM nvidia/cuda:11.8-runtime-ubuntu22.04

# Install Node.js and Python
RUN apt-get update && apt-get install -y \\
    nodejs npm python3 python3-pip

# Install CUDA Quantum
RUN pip3 install cudaq

# Copy and build application
COPY . /app
WORKDIR /app
RUN npm install && npm run build

# Start server
CMD ["npm", "start"]
```

### Production Configuration

```bash
# Production environment
NODE_ENV=production
MCP_SERVER_NAME=cuda-quantum-mcp-prod
CUDAQ_DEFAULT_TARGET=qpp-gpu
LOG_LEVEL=info

# GPU optimization
CUDA_VISIBLE_DEVICES=0,1,2,3
NVIDIA_VISIBLE_DEVICES=all
```

## 🤝 Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open Pull Request

### Development Setup

```bash
# Install development dependencies
npm install

# Run in development mode
npm run dev

# Run linting
npm run lint

# Format code
npm run format
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **NVIDIA CUDA Quantum Team** for the excellent quantum computing framework
- **Anthropic** for the Model Context Protocol specification
- **Quantum computing community** for inspiration and feedback

## 📞 Support

- **Documentation**: [Full API docs](./docs/)
- **Issues**: [GitHub Issues](https://github.com/mcp-quantum/mcp-quantum-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/mcp-quantum/mcp-quantum-server/discussions)

---

**Built with ❤️ for the quantum computing community**