Initial import

2026-06-09 16:14:55 +02:00
commit 9af114e391
87 changed files with 20848 additions and 0 deletions
@@ -0,0 +1,157 @@
+# 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