# Quantum ZX-Calculus MCP Server
**Categorical quantum circuit optimization using symmetric monoidal category theory**
Transform quantum circuits into ZX-diagrams with deterministic simplification strategies and educational visualizations. Built on the ZX-calculus framework (Coecke & Duncan, 2008-2017) with a cost-optimized architecture achieving 60-85% LLM cost reduction.
---
## Overview
The ZX-calculus is a **graphical language for quantum computing** based on symmetric monoidal categories (SMCs), where quantum circuits are represented as string diagrams with colored "spiders" (nodes) and wires. This MCP server provides:
1. **Circuit → ZX-diagram conversion** (QASM/Qiskit → spider notation)
2. **Deterministic simplification** (spider fusion, phase cancellation, Hadamard removal)
3. **Optimization strategy selection** (Clifford simplification, T-count reduction, measurement-based)
4. **Educational synthesis** (natural language explanations + SVG visualizations)
## Why Categorical?
The ZX-calculus exploits **compositional semantics**: quantum gates compose like morphisms in a category, with:
- **Serial composition**: Gate sequencing (type-safe: outputs must match inputs)
- **Parallel composition**: Tensor product (multi-qubit operations)
- **Rewrite rules**: Semantics-preserving transformations (proven sound + complete)
This categorical structure enables **deterministic optimizations** (0 LLM tokens) for 60-85% of the workflow, with LLM synthesis reserved for explanation and customization.
---
## Architecture: 4-Layer Categorical Hierarchy
### Layer 1: Foundation (Pure Taxonomy)
**Cost:** 0 tokens (static lookups)
```python
# Deterministic quantum gate → ZX spider mapping
QUANTUM_GATE_TAXONOMY = {
"h": QuantumGate(primary_spider=H_BOX, phase=0.0, is_clifford=True),
"t": QuantumGate(primary_spider=Z_SPIDER, phase=0.25, is_clifford=False),
"cx": QuantumGate(primary_spider=Z_SPIDER, phase=0.0, is_clifford=True),
# ... 15+ gates with ZX equivalents
}
```
Provides:
- Complete gate taxonomy (Clifford, Clifford+T, measurement operators)
- Spider types (Z/X/H) and phase parameters
- Basis specifications (computational, Hadamard)
- Spider fusion rules (bialgebra structure)
### Layer 2: Structure (Deterministic Operations)
**Cost:** 0 tokens (pure computation)
```python
# Parse circuit, analyze properties, select strategy
circuit = parse_qasm_circuit(qasm_code) # 0 tokens
analysis = analyze_circuit(circuit) # 0 tokens
zx_diagram = circuit_to_zx_diagram(circuit) # 0 tokens
strategy = select_simplification_strategy(...) # 0 tokens
```
Provides:
- Circuit parsing (QASM → gate sequence)
- Property analysis (T-count, entanglement, Clifford depth)
- ZX-diagram construction (spiders + wires + phases)
- Rewrite strategy selection (based on circuit properties)
### Layer 3: Relational (Compositional Rules)
**Cost:** 0 tokens (categorical logic)
Implements ZX-calculus rewrite rules:
- **Spider fusion**: Adjacent same-color spiders merge (phases add mod 2π)
- **Phase cancellation**: Phases summing to 2π disappear
- **Hadamard removal**: H · H = identity
- **Color change**: H · Z · H = X (basis transformation)
### Layer 4: Contextual (LLM Synthesis)
**Cost:** ~100-200 tokens (single LLM call)
LLM synthesizes:
- Natural language circuit explanations
- Custom optimization strategies
- Educational step-by-step visualizations
- Domain-specific simplifications
---
## Cost Optimization
Traditional approach: **LLM for entire workflow** (~500-1000 tokens)
```
User query → LLM analyzes → LLM parses → LLM optimizes → LLM visualizes
```
Categorical approach: **Deterministic layers + targeted synthesis** (~100-200 tokens)
```
User query → Parse (0) → Analyze (0) → ZX convert (0) → Select strategy (0) → LLM synthesizes explanation (100-200)
```
**Result:** 60-85% cost reduction by encoding domain expertise as categorical structure rather than prompt engineering.
---
## Features
### Circuit Conversion
- **QASM 2.0 support**: Standard quantum assembly language
- **Qiskit compatibility**: Python quantum framework integration
- **Gate coverage**: 15+ gates (Pauli, Clifford, T, CNOT, CZ, SWAP)
- **Multi-qubit circuits**: Arbitrary qubit counts with entanglement tracking
### Simplification Strategies
```python
# Automatically select optimization based on circuit analysis
strategy = select_simplification_strategy(
analysis=circuit_analysis,
desired_outcome="t_count_reduction" # or "clifford_simplification", "educational"
)
```
Available strategies:
- **Clifford simplification**: Reduce Clifford gate count (stabilizer circuits)
- **T-count reduction**: Minimize T gates (critical for fault tolerance)
- **Measurement-based**: Convert to measurement-based quantum computation
- **Educational**: Step-by-step with explanations at each transformation
### Analysis & Metrics
```python
stats = get_circuit_statistics(circuit)
# Returns:
# - Gate composition (Clifford vs T counts)
# - Entanglement score (0-1 estimate)
# - Clifford depth, estimated T-count
# - Recommended optimization strategies
```
### Educational Visualization
- SVG string diagram generation
- Step-by-step rewrite sequences
- Natural language explanations of each transformation
- LaTeX-ready mathematical notation
---
## Installation
```bash
# Clone repository
git clone https://github.com/yourusername/quantum-zx-mcp.git
cd quantum-zx-mcp
# Install with development dependencies
pip install -e ".[dev]"
# Run tests
./tests/run_tests.sh
```
### Deploy to FastMCP Cloud
```bash
fastmcp deploy
```
---
## Quick Start
### Example 1: Simple Circuit Analysis
```python
from quantum_zx_calculus import parse_qasm_circuit, analyze_circuit
qasm = """
OPENQASM 2.0;
qreg q[2];
h q[0];
cx q[0], q[1];
"""
circuit = parse_qasm_circuit(qasm)
analysis = analyze_circuit(circuit)
print(f"Total gates: {analysis.total_gates}")
print(f"Clifford gates: {analysis.clifford_gates}")
print(f"Is Clifford-only: {analysis.is_clifford_only}")
print(f"Recommended strategies: {[s.value for s in analysis.recommended_strategies]}")
```
**Output:**
```
Total gates: 2
Clifford gates: 2
Is Clifford-only: True
Recommended strategies: ['clifford_simplification', 'educational']
```
### Example 2: ZX-Diagram Conversion
```python
from quantum_zx_calculus import circuit_to_zx_diagram
zx_diagram = circuit_to_zx_diagram(circuit)
print(f"Spiders: {len(zx_diagram.spiders)}")
print(f"Wires: {len(zx_diagram.wires)}")
print(f"Phases: {zx_diagram.phases}")
```
**Output:**
```
Spiders: 4
Wires: 3
Phases: {0: 0.0, 1: 0.0, 2: 0.0, 3: 0.0}
```
### Example 3: Claude Synthesis (via MCP)
```
User: "Analyze this Bell state preparation circuit and explain what it does"
MCP Server:
1. Parses QASM → 2-qubit circuit (H, CNOT)
2. Converts to ZX → 4 spiders, 3 wires
3. Analyzes → Clifford-only, creates entanglement
4. Passes structured data to Claude
LLM (e.g., Claude) synthesizes:
"This circuit creates a Bell state (|Φ+⟩), a maximally entangled state.
The Hadamard on qubit 0 creates superposition (|0⟩+|1⟩)/√2, then the CNOT
entangles it with qubit 1. In ZX-calculus, this appears as a Z-spider
(Hadamard) connected to an X-spider (CNOT control/target), forming the
characteristic 'cup' structure of entanglement."
```
---
## Theoretical Foundation
# Structural Isomorphism: Manufacturing vs Quantum Circuits
## Categorical Correspondence Table
| **NIST Process Planning** | **ZX-Calculus MCP Server** | **Categorical Structure** |
|---------------------------|---------------------------|--------------------------|
| **Machine operations** | Quantum gates (H, T, CNOT, etc.) | Atomic morphisms in category |
| **Production line sequences** | Circuit gate sequences | Serial composition (type-safe) |
| **Parallel factory operations** | Multi-qubit tensor operations | Parallel composition (⊗) |
| **Task decomposition** | Gate → Spider conversion | Functorial mapping F: Gates → Spiders |
| **Process constraints** | Type matching (outputs → inputs) | Monoidal category coherence |
| **Resource routing** | Wire connectivity in ZX-diagram | String diagram topology |
| **Factory-level planning** | Optimization strategy selection | Higher-order morphism composition |
| **Supply chain coordination** | Educational synthesis & explanation | Contextual interpretation layer |
| **Process validation** | Semantics-preserving rewrites | Category-theoretic soundness proofs |
| **Cost optimization** | T-count reduction, Clifford simplification | Resource-aware functor selection |
| **Multi-scale hierarchy** | 4-layer architecture (Foundation → Contextual) | Compositional abstraction levels |
| **Identity processes** | Identity gates (bare wires) | Identity morphisms in category |
## Key Insight
Both systems exhibit **symmetric monoidal category (SMC) structure** where:
1. **Objects** = Resources/States (production line capacity ↔ qubit counts)
2. **Morphisms** = Processes/Gates (manufacturing tasks ↔ quantum operations)
3. **Composition** = Task sequencing (serial: ∘) and parallelization (parallel: ⊗)
4. **Rewrite rules** = Process optimization (semantics-preserving transformations)
## The Functorial Pattern
Both domains implement the same **hierarchical decomposition functor**:
```
High-level specification ────F───→ Low-level operations
↓ ↓
Sub-tasks Primitive actions
↓ ↓
Validation Semantic preservation
```
Where **F preserves compositional structure** (F(g ∘ f) = F(g) ∘ F(f)) ensuring that:
- Factory plans decompose correctly into production line tasks
- Quantum circuits decompose correctly into spider diagrams
- Optimizations at any level preserve overall semantics
## Cost Optimization Parallel
**Manufacturing (Breiner et al.):**
- High-level planning (strategic decisions) → expensive computational resources
- Low-level execution (machine operations) → deterministic, fast
- **Strategy**: Formalize relationships to enable automated reasoning at lower levels
**Quantum Circuits (This MCP):**
- High-level synthesis (natural language explanations) → expensive LLM tokens
- Low-level operations (gate taxonomy, parsing) → deterministic, 0 tokens
- **Strategy**: Encode domain expertise categorically, reserve LLM for interpretation
Both achieve cost savings through **deterministic categorical layers** rather than recalculating everything from scratch at each level.
## Generalization Potential
This pattern applies to **any compositional domain**:
- **Manufacturing**: Tasks compose into workflows
- **Quantum computing**: Gates compose into circuits
- **Creative AI**: Aesthetic parameters compose into prompts
- **Software engineering**: Functions compose into programs
- **Biological systems**: Reactions compose into pathways
The common requirement: **compositional semantics** that can be formalized as a symmetric monoidal category.
### References
1. **Bob Coecke & Aleks Kissinger.** *Picturing Quantum Processes: A First Course in Quantum Theory and Diagrammatic Reasoning.* Cambridge University Press, 2017.
- Foundational textbook on ZX-calculus and categorical quantum mechanics
2. **Bob Coecke & Ross Duncan.** "Interacting Quantum Observables: Categorical Algebra and Diagrammatics." *New Journal of Physics* 13.4 (2011): 043016.
- Original ZX-calculus formulation with completeness proof
3. **Spencer Breiner, Albert Jones & Eswaran Subrahmanian.** "Categorical Models for Process Planning." *Computer Industry* 112 (2019).
- Process hierarchy decomposition using symmetric monoidal categories
- Theoretical validation for hierarchical categorical architectures
4. **PyZX Library**: https://github.com/zxcalc/pyzx
- Python implementation of ZX-calculus (our taxonomy is compatible)
5. **ZX-Calculus Resource**: https://zxcalculus.com/
- Community portal with interactive tutorials
### Categorical Composition Theory
This server demonstrates **functorial decomposition** of quantum circuits:
```
Circuit (high-level) ──────────────────> ZX-diagram (semantic)
│ │
│ Functor F │ Functor G
↓ ↓
Gate sequence (syntax) ─────────────────> Spider graph (rewrite rules)
```
Where:
- **F**: Circuit parsing functor (syntax → structure)
- **G**: Optimization functor (semantics → strategies)
- **Composition**: G ∘ F preserves quantum semantics while enabling classical simplification
This pattern generalizes to **any domain** with compositional structure - see Lushy's framework of 50+ categorical MCP servers across diverse aesthetic domains.
---
## Use Cases
### Quantum Computing Education
- Teach ZX-calculus interactively with natural language explanations
- Visualize how quantum gates compose categorically
- Step-through circuit simplifications with mathematical justification
### Research & Development
- Rapid prototyping of quantum algorithms
- Circuit optimization with T-count minimization
- Measurement-based quantum computation experiments
### Fault-Tolerant Compilation
- Analyze resource requirements (T-count, Clifford depth)
- Optimize circuits for error correction codes
- Compare optimization strategies quantitatively
### Integration with AI Workflows
- Compositional semantics for multi-domain AI systems
- Deterministic computation layers for cost optimization
- Educational synthesis for domain knowledge transfer
---
## Relationship to Lushy.app Framework
This MCP server is part of the **Lushy categorical composition ecosystem**, which applies the same 4-layer architecture across 50+ domains:
**Common pattern:**
1. **Layer 1**: Deterministic domain taxonomy (0 tokens)
2. **Layer 2**: Compositional operations (0 tokens)
3. **Layer 3**: Strategy selection (0 tokens)
4. **Layer 4**: Claude synthesis (~100-200 tokens)
**Other Lushy domains:**
- Heraldic blazonry (visual vocabulary + tincture rules)
- Jazz improvisation (chord progressions + modal theory)
- Microscopy aesthetics (fluorescence channels + scale context)
- Nuclear explosion phases (fireball dynamics + atmospheric effects)
**Cross-domain composition:**
- Compatibility matrices determine which domains compose safely
- Graph-theoretic analysis reveals aesthetic clusters
- Frobenius ordering minimizes synthesis cost
---
## Contributing
We welcome contributions! Areas of interest:
1. **Gate coverage expansion**: Add parametric gates (Rx, Ry, Rz), controlled operations
2. **Additional rewrite rules**: Implement local complementation, phase teleportation
3. **Visualization improvements**: Interactive SVG with hover states, animation sequences
4. **Backend integrations**: Qiskit runtime, Cirq compatibility, QASM 3.0 support
5. **Educational content**: Tutorial notebooks, worked examples, proof walkthroughs
### Development Setup
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests with coverage
pytest --cov=quantum_zx_calculus tests/
# Format code
black quantum_zx_calculus/
flake8 quantum_zx_calculus/
# Type checking
mypy quantum_zx_calculus/
```
---
## Citation
If you use this server in academic work, please cite:
```bibtex
@software{quantum_zx_mcp,
author = {Marsters, Dal},
title = {Quantum ZX-Calculus MCP Server: Categorical Circuit Optimization},
year = {2025},
url = {https://github.com/dmarsters/quantum-zx-calculus-mcp},
note = {MCP server implementing ZX-calculus with hierarchical categorical architecture}
}
```
And the foundational ZX-calculus work:
```bibtex
@book{coecke2017picturing,
title={Picturing Quantum Processes},
author={Coecke, Bob and Kissinger, Aleks},
year={2017},
publisher={Cambridge University Press}
}
```
---
## License
MIT License - see LICENSE file for details.
---
## Contact
Dal Marsters
Co-founder, Lushy
dal@lushy.app
https://www.linkedin.com/in/dalmarsters/
For questions about:
- **Categorical theory**: See theoretical foundation section
- **Implementation details**: Open a GitHub issue
- **Academic collaboration**: Email directly
- **Commercial applications**: Via Lushy website
---
## Acknowledgements
- **Bob Coecke & Aleks Kissinger**: ZX-calculus theoretical foundation
- **PyZX team**: Reference implementation and community resources
- **Spencer Breiner et al.**: Categorical process planning framework (NIST)
- **Applied Category Theory community**: Compositional semantics research
