Vincent Bourdon
158 lines
5.2 KiB
Markdown
158 lines
5.2 KiB
Markdown
# 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
|