Getting Started - Complete Beginner's Guide

Welcome to QPanda3 Runtime MCP Server! This guide will help you get started from scratch, even if you're new to quantum computing or MCP servers.

What is This?

QPanda3 Runtime MCP Server is a bridge that connects AI assistants (like Claude, ChatGPT, or custom AI agents) to Origin Quantum's quantum computing services. With this server, you can:

• Ask an AI assistant to run quantum circuits on real quantum computers
• Let AI manage your quantum computing tasks
• Build AI-powered quantum computing applications

Setup

If you haven't installed the server yet, follow these guides first:

1. Installation Guide - Install dependencies and configure your API key
2. Configuration Guide - Connect to your AI coding platform (Claude, Cline, Cursor, etc.)

Your First Quantum Circuit

Once connected to an AI assistant, try these prompts:

Example 1: List Available Devices

List all available QPU devices

The AI will call list_qpu_devices_tool and show you available quantum computers.

Example 2: Run a Bell State Circuit

Run a Bell state circuit on device 20 with 1000 shots

The AI will:

1. Use the Bell state circuit (creates quantum entanglement)
2. Submit it to the specified device
3. Return the measurement results

Expected results: ~50% 00 and ~50% 11 (quantum entanglement!)

Example 3: Check Task Status

Check the status of my last task

Understanding the Tools

Account Management

Tool	What It Does	When to Use
setup_origin_quantum_account_tool	Configure your credentials	First time setup
list_saved_accounts_tool	List session accounts	Check authentication
active_account_info_tool	Get current account info	Verify connection

Device Management

Tool	What It Does	When to Use
list_qpu_devices_tool	List all quantum devices	Find available QPUs
get_qpu_properties_tool	Get device details	Check device capabilities

Task Execution

Tool	What It Does	When to Use
sample_tool	Run circuit with measurements	Get measurement outcomes
estimate_tool	Calculate expectation value	Quantum chemistry, VQE
batch_sample_tool	Run multiple circuits	Compare circuits
batch_estimate_tool	Estimate multiple circuits	Optimization tasks

Task Management

Tool	What It Does	When to Use
get_task_status_tool	Check if task is done	Monitor progress
get_task_results_tool	Get task results	Retrieve output
cancel_task_tool	Cancel a task	Stop execution
list_my_tasks_tool	List recent tasks	Review history

Multi-Objective Decisions

Tool	What It Does	When to Use
create_circuit_observable_binding_tool	Create binding	Multi-objective optimization
add_product_rule_tool	Add all combinations	Test all pairs
add_zip_rule_tool	Add specific pairs	Custom combinations
estimate_with_binding_tool	Execute binding	Run estimation
list_bindings_tool	List bindings	Manage bindings
delete_binding_tool	Delete binding	Cleanup

Pre-Built Circuit Resources

The server provides ready-to-use quantum circuits:

Resource	Description	Qubits	Expected Results
circuits://bell-state	Quantum entanglement	2	50% 00, 50% 11
circuits://ghz-state	Multi-qubit entanglement	3	50% 000, 50% 111
circuits://random	Random number generator	4	Equal distribution
circuits://superposition	Single qubit demo	1	50% 0, 50% 1

Writing Your Own Circuits

Circuits use the OriginIR format:

QINIT <number_of_qubits>
CREG <number_of_classical_bits>
<gate_operations>
MEASURE q[i],c[i]

Common Gates

Gate	Syntax	Description
Hadamard	H q[0]	Superposition
Pauli-X	X q[0]	Bit flip
Pauli-Y	Y q[0]	Bit+Phase flip
Pauli-Z	Z q[0]	Phase flip
CNOT	CNOT q[0],q[1]	Controlled-NOT
CZ	CZ q[0],q[1]	Controlled-Z
Measure	MEASURE q[0],c[0]	Measure to classical bit

Example: Custom Circuit

# A 3-qubit GHZ-like circuit
circuit = """QINIT 3
CREG 3
H q[0]
CNOT q[0],q[1]
CNOT q[1],q[2]
MEASURE q[0],c[0]
MEASURE q[1],c[1]
MEASURE q[2],c[2]"""

Understanding Observables

For estimation tasks, you need to define observables (what to measure):

Dictionary Format

observable = {
    "Z0 Z1": 1.0,   # Measure Z on qubits 0 and 1
    "X0": 0.5       # Measure X on qubit 0
}

Pauli String Format

observable = "IIXY"  # 4-qubit observable

Task Workflow

graph LR
    A[Submit Task] --> B[Check Status]
    B --> C{Status?}
    C -->|PENDING| B
    C -->|RUNNING| B
    C -->|DONE| D[Get Results]
    C -->|FAILED| E[Handle Error]

Complete Example

# 1. Submit task
result = await sample_tool(
    circuit=bell_state_circuit,
    device_id="20",
    shots=1000
)
task_id = result["task_id"]

# 2. Poll for completion
import asyncio
while True:
    status = await get_task_status_tool(task_id)
    if status["task_status"] == "DONE":
        break
    elif status["task_status"] == "FAILED":
        raise Exception("Task failed!")
    await asyncio.sleep(2)

# 3. Get results
results = await get_task_results_tool(task_id)
print(f"Results: {results['results']}")

Security Tips

1. Never commit .env files - Add to .gitignore
2. Use environment variables for credentials in production
3. Restrict file permissions: chmod 600 .env

Next Steps

• Account Management - Detailed account management
• Working with Quantum Devices - Working with quantum devices
• Managing Quantum Tasks - Managing quantum tasks
• Complete Examples - Complete examples
• Contributing - Contributing to the project

Getting Help

• Documentation: https://originquantum.github.io/qpanda3-runtime-mcp-server/
• Issues: GitHub Issues
• Origin Quantum: support@originqc.com