Psi-MCP: Advanced Quantum Systems MCP Server

🌟 Overview

Psi-MCP is an advanced Model Context Protocol (MCP) server specifically designed for quantum systems analysis and simulation. It provides comprehensive tools for quantum computing, quantum chemistry, many-body physics, quantum machine learning, and quantum field theory calculations.

Key Features

• 🔬 Quantum Circuit Operations: Create, simulate, optimize, and visualize quantum circuits
• ⚛️ Open Quantum Systems: Solve master equations, analyze decoherence, compute steady states
• 🧪 Quantum Chemistry: Molecular Hamiltonians, VQE, electronic structure calculations
• 🔗 Many-Body Physics: DMRG, tensor networks, phase transitions, correlation functions
• 🤖 Quantum Machine Learning: QNNs, variational classifiers, quantum kernels
• 🌊 Quantum Field Theory: Field quantization, path integrals, RG flow, anomalies
• 📊 Advanced Visualization: Bloch spheres, density matrices, Wigner functions
• 🚀 Smithery Compatible: Easy deployment and integration

🛠 Installation

Prerequisites

• Python 3.11 or higher
• Docker (for containerized deployment)
• Git

Core vs Optional Dependencies

Core Dependencies (always installed):

• FastAPI, Uvicorn (MCP server framework)
• Qiskit, Cirq, PennyLane (quantum computing)
• QuTiP (open quantum systems)
• OpenFermion (quantum chemistry)
• NumPy, SciPy, Matplotlib (numerical computing)

Optional Dependencies (install separately if needed):

• PySCF (advanced quantum chemistry)
• TensorFlow Quantum (quantum ML)
• NetKet (neural quantum states)
• Additional quantum libraries

Quick Start with Smithery

# Install via Smithery CLI
npx @smithery/cli install psi-mcp --client cursor

# Or deploy via GitHub integration
git clone https://github.com/manasp21/Psi-MCP.git
cd Psi-MCP
# Push to your GitHub repository and connect to Smithery

Local Development

# Clone the repository
git clone https://github.com/manasp21/Psi-MCP.git
cd Psi-MCP

# Install dependencies
pip install -r requirements.txt

# Run the server
python src/server.py

Docker Deployment

# Build the container
docker build -t psi-mcp .

# Run with configuration
docker run -p 8000:8000 \
  -e computing_backend=simulator \
  -e max_qubits=20 \
  -e precision=double \
  psi-mcp

🔧 Configuration

Smithery Configuration

Configure via the Smithery dashboard or query parameters:

computing_backend: "simulator"  # qasm_simulator, statevector_simulator
max_qubits: 20                  # Maximum qubits (1-30)
precision: "double"             # single, double, extended
enable_gpu: false               # GPU acceleration
timeout_seconds: 300            # Calculation timeout
memory_limit_gb: 4              # Memory limit

Environment Variables

PORT=8000                       # Server port
HOST=0.0.0.0                   # Server host
COMPUTING_BACKEND=simulator     # Default backend
MAX_QUBITS=20                  # Default max qubits

🚀 Usage

Quantum Circuit Operations

Create Quantum Circuits

# Create a Bell state circuit
create_quantum_circuit(
    num_qubits=2,
    circuit_type="bell",
    backend="qasm_simulator"
)

# Create a GHZ state
create_quantum_circuit(
    num_qubits=4,
    circuit_type="ghz",
    backend="statevector_simulator"
)

# Create quantum Fourier transform
create_quantum_circuit(
    num_qubits=3,
    circuit_type="qft",
    backend="simulator"
)

Simulate Circuits

# Simulate with measurements
simulate_quantum_circuit(
    circuit_definition="circuit_1",
    shots=1024,
    backend="qasm_simulator"
)

# Get statevector
simulate_quantum_circuit(
    circuit_definition="circuit_2",
    shots=1,
    backend="statevector_simulator"
)

Optimize Circuits

# Optimize for specific backend
optimize_quantum_circuit(
    circuit_definition="circuit_1",
    optimization_level=2,
    target_backend="qasm_simulator"
)

Open Quantum Systems

Master Equation Solving

# Solve Lindblad master equation
solve_master_equation(
    hamiltonian="pauli_z",
    collapse_operators="spontaneous_emission",
    initial_state="excited",
    time_span="0,10,100",
    solver_method="mesolve"
)

# Analyze decoherence
analyze_decoherence(
    system_hamiltonian="pauli_x",
    environment_coupling="dephasing",
    temperature=0.1,
    analysis_type="dephasing"
)

Quantum Chemistry

Molecular Calculations

# Generate molecular Hamiltonian
generate_molecular_hamiltonian(
    molecule="H2",
    basis="sto-3g",
    charge=0,
    multiplicity=1
)

# Run VQE for electronic structure
vqe_chemistry(
    molecule="H2O",
    basis="6-31g",
    ansatz="uccsd",
    optimizer="cobyla"
)

# Simulate chemical reactions
simulate_chemical_reaction(
    reactants=["H2", "O2"],
    products=["H2O"],
    method="vqe"
)

Quantum Algorithms

Shor's Algorithm

# Factor integers
shors_algorithm(
    N=15,
    backend="qasm_simulator",
    shots=1024
)

Grover's Search

# Search marked items
grovers_search(
    marked_items=[3, 7],
    search_space_size=16,
    backend="simulator"
)

VQE Optimization

# Variational quantum eigensolver
vqe_optimization(
    hamiltonian="ising",
    ansatz_type="ry",
    optimizer="cobyla",
    max_iterations=100
)

Many-Body Physics

DMRG Simulations

# Run DMRG for spin chains
dmrg_simulation(
    hamiltonian_type="heisenberg",
    system_size=20,
    bond_dimension=100,
    max_sweeps=10
)

# Phase transition analysis
phase_transition_analysis(
    model_type="ising",
    parameter_range=[0.0, 2.0],
    n_points=20,
    system_size=16
)

Quantum Machine Learning

Neural Networks

# Train quantum neural network
quantum_neural_network(
    input_data=[[0.1, 0.2], [0.3, 0.4]],
    labels=[0, 1],
    n_qubits=4,
    n_layers=2,
    epochs=50
)

# Variational classifier
variational_classifier(
    training_data=train_X,
    training_labels=train_y,
    test_data=test_X,
    ansatz_type="hardware_efficient"
)

Visualization

Quantum States

# Bloch sphere visualization
visualize_quantum_state(
    state_definition="superposition",
    visualization_type="bloch_sphere"
)

# Density matrix plot
visualize_quantum_state(
    state_definition="bell",
    visualization_type="density_matrix"
)

# Wigner function
visualize_quantum_state(
    state_definition="coherent",
    visualization_type="wigner_function"
)

📚 API Reference

Core Tools

Tool Name	Description	Parameters
create_quantum_circuit	Create quantum circuits	num_qubits, circuit_type, backend
simulate_quantum_circuit	Simulate circuits	circuit_definition, shots, backend
solve_master_equation	Solve open system dynamics	hamiltonian, collapse_operators, initial_state
vqe_optimization	Variational quantum eigensolver	hamiltonian, ansatz_type, optimizer
dmrg_simulation	Many-body simulations	hamiltonian_type, system_size, bond_dimension
quantum_neural_network	Train QNNs	input_data, labels, n_qubits, n_layers

Supported Backends

• Qiskit: qasm_simulator, statevector_simulator, unitary_simulator
• Cirq: cirq_simulator
• PennyLane: default.qubit, default.qubit.torch

Circuit Types

• empty: Empty circuit
• bell: Bell state preparation
• ghz: GHZ state preparation
• qft: Quantum Fourier transform
• random: Random circuit

🏗 Architecture

Psi-MCP/
├── src/
│   ├── server.py              # Main MCP server
│   └── quantum/               # Quantum modules
│       ├── __init__.py        # Backend initialization
│       ├── circuits.py        # Circuit operations
│       ├── systems.py         # Open quantum systems
│       ├── algorithms.py      # Quantum algorithms
│       ├── chemistry.py       # Quantum chemistry
│       ├── many_body.py       # Many-body physics
│       ├── field_theory.py    # Quantum field theory
│       ├── ml.py             # Quantum ML
│       ├── visualization.py   # Visualization tools
│       └── utils.py          # Utility functions
├── tests/                     # Test suite
├── docs/                      # Documentation
├── smithery.yaml             # Smithery configuration
├── Dockerfile               # Container configuration
├── requirements.txt         # Python dependencies
└── README.md               # This file

🧪 Examples

Complete Workflow Example

# 1. Create and simulate a quantum circuit
circuit_result = create_quantum_circuit(
    num_qubits=3,
    circuit_type="ghz",
    backend="qasm_simulator"
)

# 2. Simulate the circuit
simulation_result = simulate_quantum_circuit(
    circuit_definition=circuit_result['id'],
    shots=1000,
    backend="qasm_simulator"
)

# 3. Visualize the results
plot_result = plot_measurement_results(
    counts=simulation_result['counts'],
    title="GHZ State Measurement"
)

# 4. Analyze entanglement
entropy = calculate_entanglement_entropy(
    circuit_definition=circuit_result['id'],
    subsystem_size=1
)

Quantum Chemistry Workflow

# 1. Generate molecular Hamiltonian
hamiltonian = generate_molecular_hamiltonian(
    molecule="H2",
    basis="sto-3g"
)

# 2. Run VQE calculation
vqe_result = vqe_chemistry(
    molecule="H2",
    basis="sto-3g",
    ansatz="uccsd"
)

# 3. Compute molecular properties
properties = compute_molecular_properties(
    molecule="H2",
    method="hf",
    basis="sto-3g"
)

🔬 Advanced Features

Custom Hamiltonians

# Define custom spin chain
solve_master_equation(
    hamiltonian=json.dumps([[1, 0], [0, -1]]),
    collapse_operators="custom_operators",
    initial_state="custom_state"
)

GPU Acceleration

# Enable GPU support
configure_server(
    enable_gpu=True,
    computing_backend="gpu_simulator"
)

Parallel Processing

# Parallel circuit simulation
simulate_circuits_parallel(
    circuit_definitions=["circuit_1", "circuit_2", "circuit_3"],
    shots=1000
)

📊 Performance

Benchmarks

Operation	System Size	Execution Time	Memory Usage
Circuit Simulation	20 qubits	~2s	~100MB
VQE Optimization	H2O molecule	~30s	~200MB
DMRG Calculation	50 sites	~60s	~500MB
QNN Training	100 samples	~45s	~150MB

Scaling

• Quantum Circuits: Up to 30 qubits (simulator dependent)
• Many-Body Systems: Up to 100 sites with DMRG
• Molecular Systems: Up to 20 orbitals with VQE
• ML Training: Up to 1000 samples efficiently

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone and install development dependencies
git clone https://github.com/manasp21/Psi-MCP.git
cd Psi-MCP
pip install -r requirements.txt
pip install -e .[dev]

# Run tests
pytest tests/

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Qiskit Team for quantum computing framework
• QuTiP Developers for open quantum systems tools
• PennyLane Team for quantum machine learning
• OpenFermion Contributors for quantum chemistry tools
• Smithery Platform for MCP server hosting

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Full API documentation
• Examples: Jupyter notebooks with examples

🗺 Roadmap

v1.1.0 (Next Release)

• ITensor integration for tensor networks
• NetKet support for neural quantum states
• Advanced error mitigation tools
• Quantum error correction codes

v1.2.0 (Future)

• Hardware backend support (IBM, Google, IonQ)
• Advanced visualization dashboard
• Quantum advantage benchmarks
• Multi-user collaboration features

---