667 líneas
14 KiB
Markdown
667 líneas
14 KiB
Markdown
# 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** |