656
README.md
Archivo normal
656
README.md
Archivo normal
@@ -0,0 +1,656 @@
|
||||
# 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
|
||||
|
||||
# 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
|
||||
Solution:
|
||||
1. Increase timeout in config
|
||||
2. Check Python path in .env
|
||||
3. Ensure CUDA Quantum installation
|
||||
```
|
||||
|
||||
### 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**
|
||||
Referencia en una nueva incidencia
Block a user