使用说明

CUDA Quantum MCP 服务器

一个全面的模型上下文协议（MCP）服务器，它利用NVIDIA的CUDA Quantum框架并支持GPU加速，提供量子计算能力。

🚀 特点

量子电路构建

创建量子核 使用参数化电路
应用量子门 (H, X, Y, Z, CNOT, 旋转门等)
构建通用电路 （贝尔对，GHZ态，量子傅里叶变换）
可视化电路 以文本格式
管理量子寄存器 以及量子比特操作

量子执行

示例量子电路 带有测量统计数据
计算期望值 哈密顿量的（集合/系统/等，根据上下文具体确定）
获取量子态向量 带有振幅分析
运行量子算法 带有自定义返回值
变分优化 用于量子机器学习

硬件后端集成

多个模拟器CPU，GPU（cuQuantum），张量网络
量子硬件IonQ、Quantinuum、Quantum Machines等
GPU加速 支持NVIDIA CUDA
目标配置 带有特定后端的参数
连接性测试 用于远程量子处理器

高级功能

Python桥 为了实现CUDA Quantum的无缝集成
异步执行 对于长时间运行的量子任务
误差缓解 以及噪声建模
多GPU支持 用于大规模模拟
全面记录 以及调试工具

📦 安装

先决条件

Node.js 18及以上版本 以及 npm
Python 3.8或更高版本 使用 pip
NVIDIA GPU（英伟达图形处理器） （可选，用于GPU加速）
CUDA工具包 （可选，针对GPU后端）

安装CUDA Quantum

# 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

安装MCP服务器

# 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

环境配置

复制示例环境文件并进行配置：

cp .env.example .env

编辑 .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

🏃‍♂️ 快速入门

1. 启动MCP服务器

npm start

2. 通过MCP客户端连接

服务器使用stdio传输进行MCP通信：

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

3. 基本量子电路示例

// 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
});

🔧 可用工具

量子电路工具

`create_quantum_kernel`

创建一个新的量子核，指定量子比特和参数。

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

`apply_quantum_gate`

对特定的量子比特应用量子门，并可选择性地使用控制量子比特。

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

支持的门（或闸门）：

单量子比特： h， x， y， z， s， t， rx， ry， rz
两量子比特： cx (CNOT)，即受控非门（Controlled NOT gate）， cy， cz， swap
多量子比特： ccx （托福利）， cswap (弗雷德金)

`create_common_circuit`

生成常用的量子电路。

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

可用电路：

bell_pair最大纠缠的两量子比特态
ghz_state格林伯格-霍恩-泽林格态（或称为GHZ态）
quantum_fourier_transformQFT（量子傅里叶变换）的实现
hadamard_testHadamard测试电路

量子执行工具

`sample_quantum_circuit`

执行量子电路并采样测量结果。

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

`observe_hamiltonian`

计算哈密顿算符的期望值。

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

`get_quantum_state`

从电路中检索量子态向量。

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

硬件后端工具

`set_quantum_target`

配置量子执行目标。

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

可用目标：

模拟器：

qpp-cpuCPU状态向量模拟器
qpp-gpuGPU加速模拟器（cuQuantum）
density-matrix-cpu密度矩阵模拟器
tensor-network张量网络模拟器

硬件供应商：

ionqIonQ量子处理器
quantinuumQuantinuum H系列
quantum_machines量子机器平台
infleqtionInflection量子处理器

`configure_gpu_acceleration`

启用/禁用量子模拟的GPU加速。

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

🧪 示例

示例1：量子隐形传态电路

// 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
});

示例2：变分量子本征求解器（VQE）

// 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}
});

示例3：GPU加速模拟

// 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'
});

🔌 硬件供应商设置

IonQ 配置

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

Quantinuum设置

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
  }
});

量子机器设置

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'
  }
});

🐛 故障排除

常见问题

CUDA 量子导入错误

Error: CUDA Quantum not available
Solution: pip install cudaq

未检测到GPU

Error: CUDA device not found
Solution: 
1. Check nvidia-smi output
2. Install NVIDIA drivers
3. Set CUDA_VISIBLE_DEVICES=0

Python桥接超时

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

注默认超时时间为300,000毫秒（5分钟）。复杂的量子操作或较慢的硬件可能需要通过（相关设置）来增加此值 PYTHON_TIMEOUT 环境变量。

调试模式

启用调试日志记录：

export LOG_LEVEL=debug
npm start

测试连接

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

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

🧪 测试

运行测试套件：

# Unit tests
npm test

# Integration tests  
npm run test:integration

# Coverage report
npm run test:coverage

📚 API 参考

MCP工具模式（或架构/框架）

所有工具均遵循MCP（模型上下文协议）规范：

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桥接API

Python桥提供了对CUDA Quantum的直接访问：

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>;
}

🚀 部署

Docker 部署

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

🤝 贡献（或“参与贡献”）

为该仓库创建分支（或：克隆该仓库）
创建特性分支： git checkout -b feature/amazing-feature
提交更改： git commit -m 'Add amazing feature'
推送到分支： git push origin feature/amazing-feature
打开拉取请求

开发环境设置

# Install development dependencies
npm install

# Run in development mode
npm run dev

# Run linting
npm run lint

# Format code
npm run format

📄 许可证

这个项目采用MIT许可证授权——详见许可证文件中有详细信息。

🙏 致谢

NVIDIA CUDA 量子团队 为卓越的量子计算框架
“Anthropic”翻译成中文是“人类中心主义的”或“以人类为中心的”，具体含义可能根据上下文有所不同。在人工智能领域，它可能指的是强调人类在设计、开发和应用人工智能技术中的核心地位和主导作用对于模型上下文协议规范
量子计算界 以获取灵感和反馈

📞 支持

为量子计算社区倾心打造