create_circuit

Instructions

Implementation Reference

• src/quantum_mcp_demo/tools/create_circuit.py:10-28 (handler)

  The handler function that executes the create_circuit tool logic. Accepts a 'preset' name or a 'qasm' string, builds a QuantumCircuit, stores it, and returns its ID, qubit count, and name.

  def create_circuit(preset: str | None = None, qasm: str | None = None) -> str:
      if (preset is None) == (qasm is None):
          return json.dumps(mcp_error("Provide exactly one of 'preset' or 'qasm'"))
  
      if preset is not None:
          try:
              circuit = get_preset(preset)
              name = preset
          except PresetNotFoundError as e:
              return json.dumps(mcp_error(str(e)))
      else:
          try:
              circuit = qasm2.loads(qasm)
              name = "custom"
          except Exception as e:
              return json.dumps(mcp_error(f"QASM parse error: {e}"))
  
      circuit_id = store_circuit(circuit)
      return json.dumps({"circuit_id": circuit_id, "n_qubits": circuit.num_qubits, "name": name})

• src/quantum_mcp_demo/server.py:12-17 (registration)

  Registration of create_circuit as an MCP tool on the FastMCP server with a description explaining the two modes (preset or OpenQASM 2.0).

  mcp.tool(
      description=(
          "Create a quantum circuit from a named preset or an OpenQASM 2.0 string. "
          "Provide exactly one of: preset (bell|ghz_3|superposition|deutsch_jozsa|random_4) or qasm."
      )
  )(create_circuit)

• src/quantum_mcp_demo/circuits/presets.py:1-75 (helper)

  Preset circuit definitions (bell, ghz_3, superposition, deutsch_jozsa, random_4) and the get_preset lookup function used by create_circuit.

  import logging
  import numpy as np
  from qiskit import QuantumCircuit
  
  logger = logging.getLogger(__name__)
  
  
  class PresetNotFoundError(Exception):
      """Raised when preset name is not in the registry."""
  
  
  def bell() -> QuantumCircuit:
      circuit = QuantumCircuit(2, 2)
      circuit.h(0)
      circuit.cx(0, 1)
      circuit.measure([0, 1], [0, 1])
      return circuit
  
  
  def ghz_3() -> QuantumCircuit:
      circuit = QuantumCircuit(3, 3)
      circuit.h(0)
      circuit.cx(0, 1)
      circuit.cx(1, 2)
      circuit.measure([0, 1, 2], [0, 1, 2])
      return circuit
  
  
  def superposition() -> QuantumCircuit:
      circuit = QuantumCircuit(1, 1)
      circuit.h(0)
      circuit.measure(0, 0)
      return circuit
  
  
  def deutsch_jozsa() -> QuantumCircuit:
      circuit = QuantumCircuit(3, 3)
      circuit.x(2)
      circuit.h([0, 1, 2])
      circuit.cz(0, 2)
      circuit.cz(1, 2)
      circuit.h([0, 1])
      circuit.measure([0, 1, 2], [0, 1, 2])
      return circuit
  
  
  def random_4() -> QuantumCircuit:
      rng = np.random.default_rng(seed=42)
      circuit = QuantumCircuit(4, 4)
      for q in range(4):
          circuit.rx(float(rng.uniform(0, 2 * np.pi)), q)
          circuit.ry(float(rng.uniform(0, 2 * np.pi)), q)
      circuit.cx(0, 1)
      circuit.cx(2, 3)
      circuit.cx(1, 2)
      circuit.measure([0, 1, 2, 3], [0, 1, 2, 3])
      return circuit
  
  
  _PRESETS = {
      "bell": bell,
      "ghz_3": ghz_3,
      "superposition": superposition,
      "deutsch_jozsa": deutsch_jozsa,
      "random_4": random_4,
  }
  
  
  def get_preset(name: str) -> QuantumCircuit:
      if name not in _PRESETS:
          raise PresetNotFoundError(
              f"Unknown preset: {name!r}. Available: {list(_PRESETS)}"
          )
      return _PRESETS[name]()

• src/quantum_mcp_demo/circuits/store.py:1-25 (helper)

  In-memory circuit store used by create_circuit to save the built QuantumCircuit and return a unique circuit_id.

  import uuid
  import logging
  from qiskit import QuantumCircuit
  
  logger = logging.getLogger(__name__)
  
  _circuits: dict[str, QuantumCircuit] = {}
  
  
  class CircuitNotFoundError(Exception):
      """Raised when circuit_id is not found in the store."""
  
  
  def store_circuit(circuit: QuantumCircuit) -> str:
      circuit_id = str(uuid.uuid4())
      _circuits[circuit_id] = circuit
      logger.debug("stored circuit %s (%d qubits)", circuit_id, circuit.num_qubits)
      return circuit_id
  
  
  def get_circuit(circuit_id: str) -> QuantumCircuit:
      if circuit_id not in _circuits:
          raise CircuitNotFoundError(f"Circuit not found: {circuit_id!r}")
      return _circuits[circuit_id]

• src/quantum_mcp_demo/utils/errors.py:10-12 (helper)

  The mcp_error helper used by create_circuit to format error responses as JSON.

  def mcp_error(message: str) -> dict[str, bool | str]:
      logger.warning("mcp_error: %s", message)
      return {"isError": True, "content": message}