mcp-quantum/API.md

# CUDA Quantum MCP Server - API Reference

Complete API documentation for the CUDA Quantum Model Context Protocol server.

## Table of Contents

- [Overview](#overview)
- [Quantum Circuit Tools](#quantum-circuit-tools)
- [Quantum Execution Tools](#quantum-execution-tools)
- [Hardware Backend Tools](#hardware-backend-tools)
- [Error Handling](#error-handling)
- [Examples](#examples)

## Overview

The CUDA Quantum MCP Server provides quantum computing capabilities through standardized MCP tools. Each tool accepts JSON input and returns structured results.

### Tool Response Format

All tools return responses in the MCP standard format:

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

## Quantum Circuit Tools

### create_quantum_kernel

Create a new quantum kernel (circuit) with specified qubits and parameters.

**Input Schema:**
```json
{
  "name": "string (required)",
  "num_qubits": "integer 1-32 (required)", 
  "parameters": "array (optional)",
  "description": "string (optional)"
}
```

**Parameters Array Schema:**
```json
{
  "name": "string",
  "type": "int|float|complex|list[int]|list[float]|list[complex]",
  "default": "any (optional)"
}
```

**Example:**
```json
{
  "name": "my_circuit",
  "num_qubits": 4,
  "parameters": [
    {"name": "theta", "type": "float", "default": 0.0},
    {"name": "angles", "type": "list[float]"}
  ],
  "description": "My quantum circuit"
}
```

**Response:**
```
Successfully created quantum kernel 'my_circuit' with 4 qubits.
```

---

### apply_quantum_gate

Apply a quantum gate to specified qubits in a quantum kernel.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "gate_name": "string (required)",
  "qubits": "array[integer] (required)",
  "parameters": "array[number] (optional)",
  "controls": "array[integer] (optional)",
  "adjoint": "boolean (optional, default: false)"
}
```

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

**Example:**
```json
{
  "kernel_name": "my_circuit",
  "gate_name": "rx",
  "qubits": [0],
  "parameters": [1.5708],
  "adjoint": false
}
```

**Controlled Gate Example:**
```json
{
  "kernel_name": "my_circuit",
  "gate_name": "x",
  "qubits": [1],
  "controls": [0]
}
```

**Response:**
```
Successfully applied rx gate to qubits [0] in kernel 'my_circuit'.
```

---

### create_common_circuit

Create commonly used quantum circuits with predefined structures.

**Input Schema:**
```json
{
  "circuit_type": "bell_pair|ghz_state|quantum_fourier_transform|grover_oracle|hadamard_test",
  "name": "string (required)",
  "num_qubits": "integer (optional, depends on circuit)",
  "parameters": "object (optional)"
}
```

**Circuit Types:**
- `bell_pair`: Creates |00⟩ + |11⟩ state (2 qubits)
- `ghz_state`: Creates |000...⟩ + |111...⟩ state (n qubits)  
- `quantum_fourier_transform`: QFT implementation
- `grover_oracle`: Grover's oracle template
- `hadamard_test`: Hadamard test circuit

**Example:**
```json
{
  "circuit_type": "ghz_state",
  "name": "ghz_4",
  "num_qubits": 4
}
```

**Response:**
```
Successfully created ghz_state circuit named 'ghz_4' with 4 qubits.
```

---

### list_quantum_kernels

List all available quantum kernels and their metadata.

**Input Schema:**
```json
{
  "detailed": "boolean (optional, default: false)"
}
```

**Example:**
```json
{
  "detailed": true
}
```

**Response:**
```
Available quantum kernels (2):

• my_circuit
  - Qubits: 4
  - Parameters: 2
  - Operations: 3

• ghz_4
  - Qubits: 4
  - Parameters: 0
  - Operations: 4
```

---

### visualize_circuit

Generate a text-based visualization of a quantum circuit.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "format": "text|qasm|json (optional, default: text)"
}
```

**Example:**
```json
{
  "kernel_name": "my_circuit",
  "format": "text"
}
```

**Response:**
```
Quantum Circuit: my_circuit
Qubits: 4

Operations:
1. RX(1.5708) → qubits[0]
2. H → qubits[1]
3. X → qubits[2] (ctrl: 0)
4. CNOT → qubits[1,3]
```

## Quantum Execution Tools

### sample_quantum_circuit

Execute quantum circuit and sample measurement results.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "shots": "integer 1-100000 (optional, default: 1000)",
  "parameters": "object (optional)",
  "target": "string (optional)"
}
```

**Example:**
```json
{
  "kernel_name": "bell_pair",
  "shots": 5000,
  "parameters": {"theta": 1.57},
  "target": "qpp-gpu"
}
```

**Response:**
```
Sampling Results for 'bell_pair':

Shots: 5000
Results:
  |00⟩: 2487 (49.74%)
  |11⟩: 2513 (50.26%)

Entropy: 0.999 bits
```

---

### observe_hamiltonian

Compute the expectation value of a Hamiltonian using a quantum circuit.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "hamiltonian_terms": "array (required)",
  "shots": "integer (optional, default: 1000)",
  "parameters": "object (optional)"
}
```

**Hamiltonian Terms Schema:**
```json
{
  "paulis": "array of ['I','X','Y','Z']",
  "qubits": "array[integer]",
  "coefficient": {
    "real": "number",
    "imag": "number"
  }
}
```

**Example:**
```json
{
  "kernel_name": "my_ansatz",
  "hamiltonian_terms": [
    {
      "paulis": ["Z", "Z"],
      "qubits": [0, 1],
      "coefficient": {"real": 1.0, "imag": 0.0}
    },
    {
      "paulis": ["X", "X"],
      "qubits": [0, 1],
      "coefficient": {"real": 0.5, "imag": 0.0}
    }
  ],
  "shots": 10000
}
```

**Response:**
```
Hamiltonian Expectation Value for 'my_ansatz':

Expectation Value: -0.234567
Variance: 0.012345
Standard Deviation: 0.111111
Shots: 10000

Hamiltonian Terms:
  Term 1: 1.0 × (Z_0 ⊗ Z_1)
  Term 2: 0.5 × (X_0 ⊗ X_1)
```

---

### get_quantum_state

Retrieve the quantum state vector from a quantum circuit.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "parameters": "object (optional)",
  "format": "amplitudes|probabilities|both (optional, default: amplitudes)"
}
```

**Example:**
```json
{
  "kernel_name": "bell_pair",
  "format": "both"
}
```

**Response:**
```
Quantum State for 'bell_pair':

State Vector Dimension: 4

Probability Amplitudes:
  |00⟩: 50.0000%
  |11⟩: 50.0000%

Complex Amplitudes:
  |00⟩: 0.707107 + 0.000000i
  |11⟩: 0.707107 + 0.000000i

State Properties:
  Purity: 1.000000
  Entanglement: Entangled
```

---

### run_quantum_algorithm

Execute quantum algorithms with custom return values.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "shots": "integer (optional, default: 1000)",
  "parameters": "object (optional)"
}
```

**Example:**
```json
{
  "kernel_name": "grover_algorithm",
  "shots": 1000,
  "parameters": {"target_state": "101"}
}
```

---

### variational_optimization

Perform variational quantum optimization using gradient-based methods.

**Input Schema:**
```json
{
  "kernel_name": "string (required)",
  "hamiltonian_terms": "array (required)",
  "initial_parameters": "array[number] (required)",
  "optimizer": "cobyla|l-bfgs-b|gradient-descent (optional, default: cobyla)",
  "max_iterations": "integer 1-1000 (optional, default: 100)"
}
```

**Example:**
```json
{
  "kernel_name": "vqe_ansatz",
  "hamiltonian_terms": [/* Hamiltonian definition */],
  "initial_parameters": [0.1, 0.2, 0.3],
  "optimizer": "cobyla",
  "max_iterations": 50
}
```

## Hardware Backend Tools

### set_quantum_target

Configure quantum execution target (simulator or hardware backend).

**Input Schema:**
```json
{
  "target": "string (required)",
  "configuration": "object (optional)"
}
```

**Available Targets:**
- **Simulators**: `qpp-cpu`, `qpp-gpu`, `density-matrix-cpu`, `tensor-network`
- **Hardware**: `ionq`, `quantinuum`, `quantum_machines`, `infleqtion`, `iqm`, `oqc`, `pasqal`

**Configuration Options:**
```json
{
  "shots": "integer",
  "optimization_level": "integer 0-3",
  "api_key": "string",
  "url": "string",
  "device": "string",
  "noise_model": "string",
  "error_mitigation": "boolean"
}
```

**Example:**
```json
{
  "target": "qpp-gpu",
  "configuration": {
    "shots": 10000,
    "optimization_level": 2
  }
}
```

**Response:**
```
Successfully set quantum target to: qpp-gpu

Description: GPU State Vector Simulator (cuQuantum)

Configuration:
  shots: 10000
  optimization_level: 2
```

---

### list_quantum_backends

List all available quantum backends and their capabilities.

**Input Schema:**
```json
{
  "category": "all|simulators|hardware (optional, default: all)",
  "detailed": "boolean (optional, default: false)"
}
```

**Example:**
```json
{
  "category": "simulators",
  "detailed": true
}
```

**Response:**
```
Available Quantum Backends:

🖥️  Simulators:
  • qpp-cpu: CPU State Vector Simulator
    - Local execution
    - GPU support: No
    - Max qubits: 32

  • qpp-gpu: GPU State Vector Simulator (cuQuantum)
    - Local execution
    - GPU support: Yes
    - Max qubits: 32

🔬 Hardware Providers:
  • ionq: IonQ Quantum Processors
    - Remote execution
    - Authentication required
```

---

### get_platform_info

Get information about the current quantum platform and available resources.

**Example:**
```json
{}
```

**Response:**
```
Quantum Platform Information:

Platform Name: default
Number of QPUs: 1
Is Simulator: true
Is Remote: false

System Information:
Node.js Version: v18.17.0
Platform: linux
Architecture: x64
CUDA Visible Devices: 0
```

---

### test_backend_connectivity

Test connectivity to quantum hardware providers.

**Input Schema:**
```json
{
  "backend": "string (required)",
  "credentials": "object (optional)"
}
```

**Credentials Schema:**
```json
{
  "api_key": "string",
  "url": "string", 
  "username": "string",
  "password": "string"
}
```

**Example:**
```json
{
  "backend": "qpp-gpu",
  "credentials": {}
}
```

**Response:**
```
Testing connectivity to qpp-gpu...

✅ qpp-gpu is available (local simulator)
✅ CUDA device available: 0
```

---

### configure_gpu_acceleration

Configure GPU acceleration for quantum simulations.

**Input Schema:**
```json
{
  "enable": "boolean (required)",
  "device_id": "integer (optional)",
  "memory_limit": "number (optional)",
  "target": "qpp-gpu|density-matrix-gpu (optional, default: qpp-gpu)"
}
```

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

**Response:**
```
GPU Acceleration Configuration:

✅ Enabling GPU acceleration
Target: qpp-gpu
GPU Device ID: 0
Memory Limit: 8.0 GB
✅ Successfully configured GPU target

Note: Ensure NVIDIA drivers and CUDA toolkit are installed.
```

## Error Handling

All tools return standardized error responses when failures occur:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error message describing what went wrong"
    }
  ],
  "isError": true
}
```

### Common Error Types

1. **Validation Errors**: Invalid input parameters
2. **Python Bridge Errors**: CUDA Quantum not available or timeout
3. **Execution Errors**: Quantum circuit execution failures
4. **Backend Errors**: Hardware provider connectivity issues

### Error Recovery

- **Timeout Errors**: Increase timeout in configuration
- **GPU Errors**: Check CUDA installation and device availability
- **API Errors**: Verify credentials and network connectivity
- **Memory Errors**: Reduce circuit size or enable GPU

## Examples

### Complete Quantum Algorithm Example

```json
// 1. Create parameterized ansatz
{
  "tool": "create_quantum_kernel",
  "input": {
    "name": "vqe_h2",
    "num_qubits": 4,
    "parameters": [
      {"name": "theta1", "type": "float"},
      {"name": "theta2", "type": "float"}
    ]
  }
}

// 2. Build ansatz circuit
{
  "tool": "apply_quantum_gate", 
  "input": {
    "kernel_name": "vqe_h2",
    "gate_name": "ry",
    "qubits": [0],
    "parameters": ["theta1"]
  }
}

// 3. Set GPU target
{
  "tool": "set_quantum_target",
  "input": {
    "target": "qpp-gpu"
  }
}

// 4. Compute expectation value
{
  "tool": "observe_hamiltonian",
  "input": {
    "kernel_name": "vqe_h2",
    "hamiltonian_terms": [
      {
        "paulis": ["Z", "Z", "I", "I"],
        "qubits": [0, 1, 2, 3],
        "coefficient": {"real": -1.0523732, "imag": 0.0}
      }
    ],
    "parameters": {"theta1": 0.5, "theta2": 1.2}
  }
}
```

This API reference provides comprehensive documentation for all available tools and their usage patterns in the CUDA Quantum MCP Server.