title: QuantumArchitect MCP emoji: ⚛️ colorFrom: indigo colorTo: purple sdk: gradio sdk_version: 6.0.1 app_file: app.py pinned: false license: mit short_description: Quantum Circuit Architect & MCP Server for AI Agents tags:
- building-mcp-track-enterprise
- building-mcp-track-consumer
- building-mcp-track-creative
- Google-Gemini-API
VIDEO: https://youtu.be/E1Ailx1X1YE SOCIAL: https://www.linkedin.com/posts/nicolas-larenas_quantumarchitect-mcp-a-hugging-face-space-activity-7401024993893044225-RF-R?utm_source=share&utm_medium=member_desktop&rcm=ACoAADmu0wIBjvA0DVdHvqncNUVTEW72gbiGUps
QuantumArchitect-MCP 🔬⚛️
A Python-based MCP (Model Context Protocol) Server for Quantum Circuit creation, validation, and evaluation. This serves as a "Quantum Logic Engine" that AI Agents can call upon to validate, score, and execute quantum logic.
🚀 Features
- Circuit Creation: Generate Bell States, GHZ States, QFT, Grover's Algorithm, and VQE Ansatz circuits
- Circuit Validation: Syntax checking, connectivity validation for real hardware, unitarity verification
- Circuit Evaluation: Statevector simulation, noise estimation, resource estimation
- Circuit Scoring: Complexity metrics, expressibility scores, hardware fitness evaluation
- MCP Endpoints: Full MCP protocol support for AI Agent integration
- Hardware Profiles: Support for IBM, Rigetti, and other quantum hardware topologies
📦 Installation
For Hugging Face Spaces
This project is designed to run directly on Hugging Face Spaces. Simply clone and deploy!
Local Installation
pip install -r requirements.txt
python app.py
🚀 Quick Start
1. Start the Application
python app.py
The app will start at http://127.0.0.1:7861
2. Build Your First Circuit
- Open the web interface in your browser
- Go to the "Circuit Builder" tab
- Click the "H" button to add a Hadamard gate
- Click "Simulate" to see the results
- View the Bloch sphere visualization of the qubit state
3. Try a Bell State
- Go to the "Templates" tab
- Select "Bell State" from the dropdown
- Click "Load Template"
- Click "Simulate" to see entangled output (50/50 probabilities)
4. Validate a Circuit
- Go to the "Validate" tab
- Paste or enter QASM code
- Select target hardware (e.g., "ibm_eagle")
- Click "Validate" to check syntax, connectivity, and unitarity
🔧 Project Structure
QuantumArchitect-MCP/
├── app.py # Main entry point (Gradio + MCP)
├── requirements.txt # Dependencies
├── pyproject.toml # Project configuration
├── src/
│ ├── mcp_server/ # MCP Protocol handling
│ │ ├── server.py # MCP capabilities definition
│ │ ├── schemas.py # JSON schemas for I/O
│ │ └── context_provider.py # Resource providers
│ ├── core/ # Quantum engine core
│ │ ├── circuit_parser.py # QASM/circuit parsing
│ │ ├── dag_representation.py # Internal DAG model
│ │ └── exceptions.py # Custom exceptions
│ ├── plugins/ # Modular components
│ │ ├── creation/ # Circuit generation
│ │ ├── validation/ # Circuit validation
│ │ ├── evaluation/ # Circuit evaluation
│ │ └── scoring/ # Circuit scoring
│ └── data/ # Knowledge base
│ ├── hardware_profiles/ # Hardware topology configs
│ └── reference_circuits/ # Standard algorithm references
└── tests/ # Test suite
🎯 MCP Endpoints
Creation Tools
create_bell_state: Generate a 2-qubit Bell state circuitcreate_ghz_state: Generate an N-qubit GHZ statecreate_qft: Generate Quantum Fourier Transform circuitcreate_grover: Generate Grover's search algorithmcreate_vqe_ansatz: Generate VQE variational ansatz
Validation Tools
validate_syntax: Check circuit syntax validityvalidate_connectivity: Verify hardware topology compatibilityvalidate_unitarity: Check if circuit is properly unitary
Evaluation Tools
simulate_statevector: Get ideal simulation resultsestimate_noise: Estimate circuit noise accumulationestimate_resources: Calculate required shots and resources
Scoring Tools
score_complexity: Get circuit depth, gate count, widthscore_expressibility: Evaluate VQC expressibility (QML)score_hardware_fitness: Rate circuit for specific hardware
🖥️ Usage
Web Interface
Access the Gradio UI at the deployed URL or http://localhost:7860 for local runs.
MCP Integration
Connect your AI Agent to the MCP endpoints:
# Example: Claude Desktop configuration
{
"mcpServers": {
"quantum-architect": {
"url": "https://your-space.hf.space/mcp"
}
}
}
📚 Learning Path Integration
This tool follows the "Zero to Hero" quantum computing curriculum:
- Level 0 (Beginner): Use creation templates (Bell, GHZ states)
- Level 1 (Practitioner): Validate circuits against real hardware
- Level 2 (Advanced): Evaluate noise and optimize for NISQ devices
- Level 3 (PhD/Hero): Score expressibility and develop new algorithms
🤖 AI Agent Integration
Available MCP Tools
| Tool | Description | Parameters |
|---|---|---|
mcp_create_circuit | Create from template | template_name, num_qubits, parameters_json |
mcp_parse_qasm | Parse OpenQASM code | qasm_code, qasm_version |
mcp_build_circuit | Build custom circuit | num_qubits, gates_json, measurements_json |
mcp_validate_circuit | Validate circuit | qasm_code, hardware_target, check_connectivity, check_unitary |
mcp_check_hardware | Check hardware compatibility | qasm_code, hardware_name |
mcp_simulate | Simulate circuit | qasm_code, shots, include_statevector, noise_model |
mcp_get_statevector | Get ideal statevector | qasm_code |
mcp_estimate_fidelity | Estimate hardware fidelity | qasm_code, hardware_name |
mcp_score_circuit | Score circuit | qasm_code, hardware_name |
mcp_compare_circuits | Compare multiple circuits | circuits_json, hardware_name |
mcp_get_gate_info | Gate documentation | gate_name |
mcp_get_algorithm_info | Algorithm explanation | algorithm_name |
mcp_list_hardware | List hardware profiles | - |
mcp_list_templates | List circuit templates | - |
mcp_get_learning_path | Get learning resources | level |
Supported Hardware Profiles
- IBM Eagle (127 qubits, heavy-hex topology)
- Rigetti Aspen (80 qubits, octagonal topology)
- IonQ Aria (25 qubits, all-to-all connectivity)
Circuit Templates
bell_state- Maximally entangled 2-qubit stateghz_state- N-qubit GHZ entangled statew_state- N-qubit W statesuperposition- Uniform superpositionqft- Quantum Fourier Transformgrover- Grover's search algorithmvqe- VQE variational ansatzqaoa- QAOA optimization circuit
🧪 Running Tests
pytest tests/ -v
📄 License
MIT License - See LICENSE file for details.
🙏 Acknowledgments
Built with: