quantum-bridge-mcp/README.md

quantum-bridge-mcp

A zero-dependency MCP server for local OpenQASM 3.0 quantum circuit simulation. Runs as a single Rust binary — no Python, no cloud account required. Includes an interactive quantum-computing tutor with a built-in curriculum.

Tools

Simulation

Tool	Description
list_backends	List available simulation backends and their capabilities
validate_circuit	Parse and validate an OpenQASM 3.0 circuit, returning structured diagnostics with line/column
run_circuit	Execute a circuit on the local statevector simulator, returning measurement counts and optionally the full statevector

Tutor

Tool	Description
get_lesson	Get a quantum-computing lesson with concept, example circuit, and the next pending exercise
check_exercise	Verify a submitted circuit against a curriculum exercise; returns pass/fail with feedback and records progress on success
explain_result	Analyze a circuit and its measurement results into structured pedagogical data (gate breakdown, key concept, outcome stats)
get_progress	Report the learner's progress through the curriculum (module status, current lesson, percent complete)

Usage with Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "quantum-bridge": {
      "command": "/path/to/quantum-bridge-mcp"
    }
  }
}

Then ask Claude things like:

"Simulate a Bell state circuit and show me the measurement counts." "Validate this OpenQASM circuit and explain any errors." "What backends are available for quantum simulation?" "Give me the next quantum-computing lesson and an exercise to try." "Check my circuit against the exercise and tell me how I did."

Example circuit

OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;

Supported gates

h, x, y, z, s, t, sdg, tdg, rx, ry, rz, cx, cz, swap, ccx, measure

Maximum: 28 qubits (statevector memory = 2ⁿ × 16 bytes; 25 qubits ≈ 512 MB).

Build

Requires Rust stable (1.70+).

cargo build --release

The binary is at target/release/quantum-bridge-mcp.

Optional: f32 mode

30% faster, supports one extra qubit at equal RAM, negligible precision loss:

cargo run --release -- --f32

Test

# Unit + integration tests
cargo test

# Property-based tests (slow — runs 256 cases per property)
cargo test --test proptest_invariants

# All checks (required before commit)
cargo fmt --check && cargo clippy -- -D warnings && cargo test

Benchmark

cargo bench

Baseline timings on a modern x86_64 (Criterion median):

• bell_1024_shots — ~74 µs
• 10_qubits_1k_shots — ~169 µs
• 20_qubits_100_shots — ~18.7 ms

All comfortably within the SLA targets (Bell < 5 ms, 20 qubits < 500 ms).

Architecture

src/
  main.rs            — tokio async entry point, rmcp stdio server
  lib.rs             — public crate API
  error.rs           — BridgeError (thiserror)
  types.rs           — QubitIndex, ShotCount, CircuitSource, ValidationResult, SimulationResult
  executor.rs        — Backend traits + LocalSimulator (spinoza statevector engine)
  validator.rs       — CircuitValidator (oq3_semantics OpenQASM 3 parser)
  circuit_analyzer.rs — AST-based gate breakdown + concept extraction for explain_result
  tutor.rs           — CurriculumLoader, lesson/exercise model (curriculum/curriculum.json)
  progress.rs        — ProgressStore (sandboxed JSON, QB_PROGRESS_PATH override)
  tools/
    mod.rs           — QuantumBridgeServer (rmcp tool_router)
    list_backends.rs
    validate_circuit.rs
    run_circuit.rs
    tutor_tools.rs   — get_lesson / check_exercise / explain_result / get_progress handlers
curriculum/
  curriculum.json    — 7 modules of lessons + exercises (embedded at compile time)
tests/
  mcp_protocol.rs    — JSON-RPC roundtrip integration tests
  proptest_invariants.rs — quantum invariants (normalisation, statevector norm, bitstring length)
  tutor_integration.rs — tutor tool roundtrips, progress persistence
  reference/tutor/   — golden pass/fail exercise submissions (JSONL)
benches/
  simulation.rs      — Criterion benchmarks

Backend trait: executor.rs defines CanIntrospect + CanValidate + CanExecute. Tools depend on &dyn Backend, never on LocalSimulator directly — adding an IBM backend in V1.5 requires no changes to tool code.

Tech stack

• rmcp — MCP SDK (stdio transport)
• oq3_semantics — Official Qiskit OpenQASM 3 parser in Rust
• spinoza — Pure Rust statevector simulator (vendored, stable Rust patch)
• tokio, serde, thiserror, tracing

Environment variables

Variable	Description
RUST_LOG=debug	Enable debug tracing to stderr
QB_PROGRESS_PATH	Override the tutor progress file (default: ~/.config/quantum-bridge-mcp/progress.json)
IBM_QUANTUM_TOKEN	IBM Quantum token (V1.5 only, unused in V1)

License

MIT