# 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`:

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

```qasm
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+).

```bash
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:

```bash
cargo run --release -- --f32
```

## Test

```bash
# 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

```bash
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`](https://github.com/modelcontextprotocol/rust-sdk) — MCP SDK (stdio transport)
- [`oq3_semantics`](https://crates.io/crates/oq3_semantics) — Official Qiskit OpenQASM 3 parser in Rust
- [`spinoza`](https://github.com/QuState/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