dense-evolution 8.3.0__py3-none-win_amd64.whl

mcp_server/models.py

@@ -0,0 +1,347 @@
+"""Pydantic input schemas for every dense_evolution_mcp tool, extracted
+from server.py so tool logic and schema definitions can change
+independently. Field descriptions stay here (not moved into tool
+docstrings) since MCP clients read them directly off the schema to build
+their own UI/validation -- the docstrings still carry the longer
+explanation for a human or agent reading the tool's full documentation.
+"""
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ListMoleculesInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    mapping: str = Field(
+        default="jordan_wigner",
+        description="Fermion-to-qubit mapping: 'jordan_wigner' or 'bravyi_kitaev'. Both represent "
+        "the identical physical Hamiltonian (same spectrum) in a different qubit basis.",
+    )
+
+
+class BuildCircuitInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_qubits: int = Field(..., ge=1, description="Number of qubits in the circuit.")
+    ops: list = Field(
+        ..., description="List of graphical-builder gate operations to convert into OpenQASM. "
+        "Get valid gate names from dense_evolution_list_gates first."
+    )
+
+
+class RunCircuitInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    qasm: str = Field(..., min_length=1, description="OpenQASM 2.0 circuit source to simulate.")
+    shots: int = Field(default=1000, ge=1, le=1_000_000, description="Number of measurement shots for the counts histogram.")
+    seed: int = Field(default=42, description="Random seed for sampling/noise reproducibility.")
+    noise_model: str = Field(default="ideal", description="Noise model name from dense_evolution_list_noise_models, or 'ideal'.")
+    noise_p: float = Field(default=0.0, ge=0.0, le=1.0, description="Noise channel error probability (ignored if noise_model='ideal').")
+    backend: str = Field(default="dense", description="'dense' (exact statevector, up to the safe qubit ceiling) or 'mps' "
+                         "(matrix-product-state, approximate top-k states, for larger circuits).")
+    top_k: int = Field(
+        default=25, ge=1, le=500,
+        description="How many of the largest-magnitude statevector amplitudes / highest-probability "
+        "basis states to include in the response (the rest are summarized by 'total_*'/'shown' "
+        "counts, not dropped from the kernel's own computation). Raise this if you need to see "
+        "further down the tail; lower it to save context on a circuit with many comparably-sized "
+        "amplitudes.",
+    )
+    include_visualizations: bool = Field(
+        default=False,
+        description="If true, also render and save circuit/histogram/Q-sphere/Bloch PNGs to disk and "
+        "return their file paths. Leave false unless you actually need to view an image -- "
+        "rendering costs extra time and the paths are not useful without viewing them.",
+    )
+
+    @model_validator(mode="after")
+    def _noise_p_requires_a_noise_model(self):
+        # prog.txt Sezione 3, punto 8: noise_p > 0 with noise_model='ideal'
+        # was silently ignored by the kernel (ideal = no channel applied at
+        # all) -- catch it here so the caller sees why their noise had no
+        # effect, instead of a passing-but-surprising ideal-circuit result.
+        # (The other invariant prog.txt names for this model -- backend='mps'
+        # + include_visualizations + n_qubits>24 -- needs the parsed qubit
+        # count, which only the kernel has for a raw QASM string; not
+        # checkable here without parsing QASM locally too.)
+        if self.noise_model == "ideal" and self.noise_p != 0.0:
+            raise ValueError(
+                f"noise_p={self.noise_p} has no effect with noise_model='ideal' (ideal means no "
+                "noise channel is applied at all) -- set noise_model to a real model name from "
+                "dense_evolution_list_noise_models, or leave noise_p at its default 0.0."
+            )
+        return self
+
+
+class MoleculeEnergyInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: str = Field(
+        ..., description="Catalog molecule -- short id (e.g. 'H2', 'LiH', 'HeH+') or the full catalog "
+        "name. See dense_evolution_list_molecules."
+    )
+    mapping: str = Field(default="jordan_wigner", description="'jordan_wigner' or 'bravyi_kitaev'.")
+
+
+class MixMoleculesInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name_a: str = Field(..., description="First catalog molecule -- short id or full catalog name.")
+    name_b: str = Field(..., description="Second catalog molecule -- short id or full catalog name. "
+                         "Must have the same qubit count as name_a.")
+    weight_a: float = Field(default=0.5, description="Weight of the first Hamiltonian in the mix.")
+    weight_b: float = Field(default=0.5, description="Weight of the second Hamiltonian in the mix.")
+    mapping: str = Field(default="jordan_wigner", description="'jordan_wigner' or 'bravyi_kitaev'.")
+
+    # prog.txt's third invariant for this model (same qubit count between
+    # name_a and name_b) is NOT added here: it needs a molecule-catalog
+    # lookup, which is an async kernel request (molecules.py's cache) --
+    # Pydantic's own validators are synchronous. Today that check happens
+    # only server-side, inside the kernel's /api/hamiltonian/mix endpoint
+    # (see chemistry_tools.py::dense_evolution_mix_molecules's own
+    # docstring) -- a mismatched pair is still rejected, just one round
+    # trip later than a local schema check could catch it.
+
+
+class CustomMoleculeInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    symbols: list = Field(..., min_length=1, description="Atomic symbols, e.g. ['H', 'H', 'O'].")
+    geometry: list = Field(..., min_length=1, description="[[x, y, z], ...] coordinates in Angstrom, one row per symbol.")
+    charge: int = Field(default=0, description="Total molecular charge.")
+    mapping: str = Field(default="jordan_wigner", description="'jordan_wigner' or 'bravyi_kitaev'.")
+
+
+class EnergyScanInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    symbols: list = Field(..., min_length=1, description="Atomic symbols shared by every point in the scan, e.g. ['H', 'H'].")
+    geometries: list = Field(
+        ..., min_length=1, max_length=50,
+        description="List of [[x,y,z], ...] geometries (Angstrom) to evaluate, one per scan point -- "
+        "e.g. a bond-length or angle sweep. Each geometry must have the same number of rows as `symbols`. "
+        "Capped at 50 points per call to keep one request's kernel load bounded.",
+    )
+    charge: int = Field(default=0, description="Molecular charge, shared by every point.")
+    mapping: str = Field(default="jordan_wigner", description="'jordan_wigner' or 'bravyi_kitaev'.")
+    labels: Optional[list] = Field(
+        default=None,
+        description="Optional label per point (e.g. bond lengths in Angstrom: [0.4, 0.5, ...]) shown "
+        "alongside each result. Defaults to the point's index (0, 1, 2, ...) if omitted. Must be the "
+        "same length as `geometries` if given.",
+    )
+
+
+class RunVqeInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: Optional[str] = Field(default=None, description="Catalog molecule -- short id or full catalog name. "
+                                 "Provide this OR symbols+geometry, not both.")
+    symbols: Optional[list] = Field(default=None, description="Atomic symbols for a custom molecule.")
+    geometry: Optional[list] = Field(default=None, description="[[x, y, z], ...] in Angstrom for a custom molecule.")
+    charge: int = Field(default=0, description="Molecular charge (custom molecule only).")
+    ansatz_type: str = Field(
+        default="hardware_efficient",
+        description="'hardware_efficient' (generic n_layers-deep RY+CNOT template) or 'uccsd' "
+        "(chemically-motivated, fewer parameters but much deeper circuits per iteration).",
+    )
+    n_layers: int = Field(default=8, ge=1, description="Ansatz depth (hardware_efficient only).")
+    maxiter: int = Field(default=200, ge=1, le=5000, description="Maximum Adam optimizer iterations.")
+    step_size: float = Field(default=0.1, gt=0, description="Adam optimizer learning rate.")
+    beta1: float = Field(default=0.9, description="Adam optimizer beta1.")
+    beta2: float = Field(default=0.999, description="Adam optimizer beta2.")
+    seed: int = Field(default=0, description="Random seed for the initial variational parameters.")
+
+    @model_validator(mode="after")
+    def _name_xor_custom_molecule(self):
+        has_name = self.name is not None
+        has_custom = self.symbols is not None or self.geometry is not None
+        if has_name and has_custom:
+            raise ValueError("provide `name` OR `symbols`+`geometry`, not both.")
+        if not has_name and not has_custom:
+            raise ValueError("provide either `name` (a catalog molecule) or `symbols`+`geometry` (a custom one).")
+        if has_custom and (self.symbols is None or self.geometry is None):
+            raise ValueError("a custom molecule needs both `symbols` and `geometry`, not just one.")
+        return self
+
+
+class QmmmForcesInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: str = Field(..., description="Catalog molecule -- short id or full catalog name. See dense_evolution_list_molecules.")
+    mapping: str = Field(default="jordan_wigner", description="'jordan_wigner' or 'bravyi_kitaev'.")
+
+
+class MdTrajectoryInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: str = Field(..., description="Catalog molecule -- short id or full catalog name. See dense_evolution_list_molecules.")
+    n_steps: int = Field(default=20, ge=1, le=200, description="Number of MD steps (capped at 200 to bound request cost).")
+    dt_fs: float = Field(default=0.5, gt=0, description="Timestep in femtoseconds.")
+    mapping: str = Field(default="jordan_wigner", description="'jordan_wigner' or 'bravyi_kitaev'.")
+    recompute_electronic_state: bool = Field(
+        default=False,
+        description="If true, re-solves real Hartree-Fock at every step (true ab-initio MD, much more "
+        "expensive; n_steps capped at 30 in that case). If false, holds the initial "
+        "electronic state fixed throughout (accurate only close to the starting geometry).",
+    )
+
+
+class MitigateZneInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    qasm: str = Field(..., min_length=1, description="OpenQASM circuit to run under noise and mitigate.")
+    pauli_string: str = Field(..., description="Pauli observable to measure and mitigate, e.g. 'ZZI'.")
+    noise_model: str = Field(..., description="Noise model name -- see dense_evolution_list_noise_models.")
+    noise_p: float = Field(..., ge=0.0, le=1.0, description="Base noise channel error probability.")
+    seed: int = Field(default=42, description="Random seed for the stochastic Kraus draws.")
+    extrapolation_method: str = Field(
+        default="richardson",
+        description="'richardson' (exact, through 1x/2x/3x noise_p) or 'polynomial' "
+        "(degree-2 least-squares fit through 5 noise scales).",
+    )
+
+
+class MitigateDensityMatrixInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    qasm: str = Field(..., min_length=1, description="OpenQASM circuit to run under noise and mitigate.")
+    noise_model: str = Field(..., description="Noise model name -- see dense_evolution_list_noise_models.")
+    noise_p: float = Field(..., ge=0.0, le=1.0, description="Base noise channel error probability.")
+    seed: int = Field(default=42, description="Random seed for the Monte-Carlo density-matrix estimate.")
+
+
+class CosmicRayBurstInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    baseline_gamma: float = Field(..., ge=0.0, le=1.0, description="Undisturbed per-slice decay probability.")
+    times_us: Optional[List[float]] = Field(
+        default=None,
+        description="Time points since impact, in microseconds. Defaults to the impact instant, the "
+        "~10us and ~1ms rise checkpoints, and a point well into the ~25ms recovery.",
+    )
+
+
+class OscillatingNoiseInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    base_p: float = Field(..., ge=0.0, le=1.0, description="Noise probability around which p_eff oscillates.")
+    freq: float = Field(..., gt=0.0, description="Oscillation frequency parameter (see dense_evolution.oscillating_p_eff).")
+    amp: float = Field(..., description="Oscillation amplitude, as a fraction of base_p.")
+    factors: Optional[List[float]] = Field(
+        default=None, description="Scale-factor points to evaluate p_eff at. Defaults to one full period.",
+    )
+
+
+class DensityMatrixChannelInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    qasm: str = Field(..., min_length=1, description="OpenQASM circuit whose ideal density matrix the channel is applied to.")
+    channel: str = Field(..., description="'global_depolarizing' (whole-register, SPAM-style) or "
+                          "'amplitude_damping' (single-qubit only, asymmetric energy relaxation).")
+    param: float = Field(..., ge=0.0, le=1.0, description="Channel strength: p for global_depolarizing, gamma for amplitude_damping.")
+
+
+class VectorHealingInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    vectors: list = Field(..., description="(n_steps, dim) sequence of equal-length numeric rows to heal -- "
+                           "e.g. a VQE parameter/energy trajectory, MD telemetry, or any other noisy vector "
+                           "sequence. NaN/Inf entries are sanitized automatically.")
+    radius_baseline: int | None = Field(
+        default=None,
+        description="Fixed radius for the local baseline window used to judge each step. If omitted, "
+        "computed adaptively as min(20, max(3, n_steps // 3)).",
+    )
+
+
+class WormholeSelectInstanceInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_majorana: int = Field(default=8, ge=4, description="Number of Majorana modes per side (must be even). "
+                             "8 matches arXiv:2604.10090's own experiment (4 qubits/side).")
+    k_terms: int = Field(default=10, ge=1, description="Number of sparse 4-Majorana coupling terms to keep, "
+                          "out of C(n_majorana,4) possible -- 10 matches the paper's K=10.")
+    J: float = Field(default=1.4142135623730951, description="SYK coupling strength (paper's J=sqrt(2)).")
+    n_candidates: int = Field(default=200, ge=1, le=2000, description="Number of random seeds to screen.")
+    target_commuting: int = Field(default=34, description="Target commuting-pair count out of C(k_terms,2) pairs "
+                                   "-- 34 (out of 45) is the paper's own selected instance's ratio for K=10.")
+
+
+class WormholeTeleportationInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_majorana: int = Field(default=8, ge=4, description="Number of Majorana modes per side (must be even).")
+    k_terms: int = Field(default=10, ge=1, description="Number of sparse 4-Majorana coupling terms per side.")
+    J: float = Field(default=1.4142135623730951, description="SYK coupling strength (paper's J=sqrt(2)).")
+    mu: float = Field(default=12.0, description="L-R coupling strength exp(i*mu*V). Sign matters -- the "
+                       "protocol's signature is the difference in teleported mutual information between "
+                       "+mu and -mu (call twice, or use dense_evolution_wormhole_scan for a batch sweep).")
+    t0: float = Field(default=0.3, description="Pre-coupling evolution time under H_L+H_R.")
+    t1: float = Field(default=0.6, description="Post-coupling evolution time under H_L+H_R. The known signal "
+                       "peak for seed=61/n_majorana=8/k_terms=10 is at t1=0.60.")
+    seed: int = Field(default=61, description="SYK instance seed -- use dense_evolution_wormhole_select_instance "
+                       "to find a good one for other (n_majorana, k_terms) combinations; 61 is the verified "
+                       "match for the defaults.")
+    with_message: bool = Field(default=True, description="Inject the reference qubit's message into the L "
+                                "register (swap). False = no message injected, a baseline/control run.")
+    backend: str = Field(default="exact", description="'exact' (matrix exponentiation, cheap, exact) or "
+                          "'trotter' (real Trotterized gate circuit, closer to actual hardware execution, "
+                          "verified to reproduce the exact backend's result closely).")
+    n_steps_evolution: int = Field(default=8, ge=1, description="Trotter steps for the t0/t1 evolution (trotter backend only).")
+    n_steps_coupling: int = Field(default=16, ge=1, description="Trotter steps for the mu coupling (trotter backend only).")
+
+
+class WormholeScanInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_majorana: int = Field(default=8, ge=4, description="Number of Majorana modes per side (must be even).")
+    k_terms: int = Field(default=10, ge=1, description="Number of sparse 4-Majorana coupling terms per side.")
+    J: float = Field(default=1.4142135623730951, description="SYK coupling strength (paper's J=sqrt(2)).")
+    mu_magnitude: float = Field(default=12.0, ge=0, description="Both +mu_magnitude and -mu_magnitude are "
+                                 "run at every t1 point -- this is the wormhole signal's defining comparison.")
+    t0: float = Field(default=0.3, description="Pre-coupling evolution time under H_L+H_R, shared by every point.")
+    t1_values: list = Field(..., min_length=1, max_length=20, description="List of post-coupling evolution "
+                             "times to sweep. Capped at 20 points (each point runs backend twice, +mu and "
+                             "-mu, sequentially -- unlike dense_evolution_energy_scan this is NOT cheap: "
+                             "each single teleportation call takes several seconds, so a full sweep can "
+                             "take a few minutes; see the tool's own docstring).")
+    seed: int = Field(default=61, description="SYK instance seed -- use dense_evolution_wormhole_select_instance first.")
+    with_message: bool = Field(default=True, description="Inject the reference qubit's message into L.")
+    backend: str = Field(default="exact", description="'exact' or 'trotter' -- see dense_evolution_wormhole_teleportation.")
+    n_steps_evolution: int = Field(default=8, ge=1, description="Trotter steps for t0/t1 evolution (trotter backend only).")
+    n_steps_coupling: int = Field(default=16, ge=1, description="Trotter steps for the mu coupling (trotter backend only).")
+
+
+class NativeHfDiagnosticsInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    symbols: list = Field(..., min_length=1, description="Atomic symbols, e.g. ['H', 'H', 'O'].")
+    geometry: list = Field(..., min_length=1, description="[[x, y, z], ...] coordinates in Angstrom, one row per symbol.")
+    charge: int = Field(default=0, description="Total molecular charge.")
+    active_electrons: Optional[int] = Field(default=None, description="Active-space electron count, if restricting the active space.")
+    active_orbitals: Optional[int] = Field(default=None, description="Active-space orbital count, if restricting the active space.")
+
+
+class RagSearchInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    documents: list = Field(..., min_length=1, description="[[text, source], ...] documents to index -- each a 2-element list of the document text and a source label (e.g. filename).")
+    query: str = Field(..., min_length=1, description="Search query -- natural-language for semantic search, or the literal/regex pattern when exact=True.")
+    top: int = Field(default=5, ge=1, description="Number of top results to return (semantic search only, ignored when exact=True).")
+    rerank: bool = Field(default=True, description="If true, pools TF-IDF and dense-embedding candidates then re-scores with a cross-encoder. If false, plain TF-IDF ranking only. Ignored when exact=True.")
+    exact: bool = Field(default=False, description="If true, substring/regex search over raw chunk text instead of semantic search -- for finding a specific known phrase or value semantic ranking buries.")
+    regex: bool = Field(default=False, description="Only with exact=True: treat query as a regex (case-sensitive) instead of a literal substring (case-insensitive).")
+    max_hits: int = Field(default=10, ge=1, description="Only with exact=True: stop after this many matches.")
+    context: int = Field(default=300, ge=0, description="Only with exact=True: characters of context to show around each match.")
+
+
+class MassDecompositionInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    formula: str = Field(..., min_length=1, description="Molecular formula string, e.g. 'C6H12O6'.")
+    target_mass: float = Field(..., description="Mass difference to check for chemical reachability, e.g. a peak-pair difference from a real spectrum.")
+    max_mass: Optional[float] = Field(default=None, description="Upper bound for the search space; defaults to target_mass itself if omitted.")
+
+
+class Bb84Input(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_rounds: int = Field(..., ge=1, description="Number of BB84 rounds to run.")
+    p_channel: float = Field(default=0.0, ge=0.0, le=1.0, description="Isotropic depolarizing channel error probability.")
+    eve: bool = Field(default=False, description="If true, simulates an intercept-resend eavesdropping attack instead of a clean channel.")
+    seed: Optional[int] = Field(default=None, description="Random seed for reproducibility.")
+
+
+class DiQkdGhzInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_rounds: int = Field(..., ge=1, description="Number of test rounds to run.")
+    p_dep: float = Field(default=0.0, ge=0.0, le=1.0, description="Isotropic depolarizing error probability applied to the GHZ(3) state.")
+    seed: Optional[int] = Field(default=None, description="Random seed for reproducibility.")
+
+
+class DickaInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    n_rounds: int = Field(..., ge=1, description="Number of protocol rounds to run.")
+    gamma: float = Field(..., description="Test-round selection probability.")
+    beta: float = Field(..., gt=0.75, lt=0.8535533905932737, description="Abort threshold: must sit strictly between the classical bound (0.75) and the quantum max (~0.8536) to meaningfully distinguish a device-independent channel from a classically-bound one.")
+    p_dep: float = Field(default=0.0, ge=0.0, le=1.0, description="Isotropic depolarizing error probability.")
+    seed: Optional[int] = Field(default=None, description="Random seed for reproducibility.")

mcp_server/molecules.py

@@ -0,0 +1,71 @@
+"""Molecule name resolution: short ids <-> the kernel's full catalog keys.
+
+The kernel's own catalog keys are long, human-readable strings, e.g.
+"H2 (Idrogeno) - R = 0.7414 A [equilibrio reale]" -- fine for a web page
+label, error-prone for an agent to reproduce verbatim across several tool
+calls (exact punctuation, accented characters, etc.). Rather than change
+the kernel's catalog (that key is also what the published Composer page
+uses), this adapter derives a short id from each key's leading token
+(e.g. "H2", "LiH", "HeH+") and accepts either form everywhere a molecule
+`name` is expected. Derived from the live catalog, not hardcoded, so it
+stays correct if the catalog grows.
+
+Cached per mapping via TTLCache (utils/cache.py) instead of a plain dict
+that only ever got reset by test code -- BUG FIX: the pre-Phase-2 cache
+never expired on its own, so a long-running MCP server process would
+never pick up a real catalog change (e.g. after a kernel restart with a
+different build). A failed fetch is also cached briefly, so a tight loop
+of tool calls made while the kernel is down doesn't each wait out their
+own connection/timeout error.
+
+Shared by tools/system_tools.py (dense_evolution_list_molecules) and
+tools/chemistry_tools.py (every tool taking a molecule `name`) -- lives
+in its own module rather than either of those, since Phase 3 (prog.txt
+Sezione 3) splits tools by topic and this is domain glue, not a tool
+itself.
+"""
+from .client import _request
+from .utils.cache import TTLCache
+
+_molecule_catalog_cache = TTLCache(ttl_seconds=300.0, failure_ttl_seconds=10.0)
+# cache value per mapping: (annotated_catalog_list, {short_id_lower: full_key})
+
+
+def _short_id(full_key: str) -> str:
+    return full_key.split(" (")[0].split(" -")[0].strip()
+
+
+async def _get_annotated_molecule_catalog(mapping: str) -> list:
+    """Catalog entries with a short `id` field added. See the cache note
+    in this module's docstring."""
+    cached = _molecule_catalog_cache.get(mapping)
+    if cached is not None:
+        return cached[0]
+    try:
+        catalog = await _request("GET", "/api/hamiltonians", timeout=10.0, params={"mapping": mapping})
+    except Exception as e:
+        _molecule_catalog_cache.set_failure(mapping, e)
+        raise
+    aliases = {}
+    annotated = []
+    for full_key, spec in catalog.items():
+        short = _short_id(full_key)
+        aliases[short.lower()] = full_key
+        annotated.append({"id": short, "full_name": full_key, **spec})
+    _molecule_catalog_cache.set(mapping, (annotated, aliases))
+    return annotated
+
+
+async def _resolve_molecule_name(name: str) -> str:
+    """Accept either a short id ('H2') or the full catalog key and return
+    the full catalog key the kernel expects. Falls back to returning the
+    input unchanged if it's neither -- the kernel's own 404 (with the name
+    as given) is a clearer error than silently guessing."""
+    cached = _molecule_catalog_cache.get("jordan_wigner")
+    if cached is None:
+        await _get_annotated_molecule_catalog("jordan_wigner")
+        cached = _molecule_catalog_cache.get("jordan_wigner")
+    _, aliases = cached
+    if name in aliases.values():
+        return name
+    return aliases.get(name.lower(), name)

mcp_server/server.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+MCP server for Dense-Evolution's Composer API (dense_evolution_mcp).
+
+This is a thin adapter, not a reimplementation: every tool here calls the
+same local FastAPI kernel the published Composer web page talks to
+(local_site/app/server.py, started with `dense-evolution serve`, listening
+on http://127.0.0.1:8800 by default). All computation -- circuit
+simulation, VQE, molecular Hamiltonians, QM/MM forces, ZNE mitigation --
+happens inside dense_evolution/dashboard_core exactly as it does for the
+web UI; this file only exposes those same endpoints as MCP tools so an
+agent can drive them directly instead of a browser.
+
+main() auto-starts the kernel if it isn't already running (see
+client.ensure_kernel_running) -- best-effort, and skipped if
+DENSE_EVOLUTION_KERNEL_URL points somewhere non-default. If that fails
+(e.g. the composer extra isn't installed) or you'd rather manage it
+yourself, start it separately:
+    pip install dense-evolution[composer]
+    dense-evolution serve
+(or `python -m local_site.app.server` from the repo root)
+
+Override the kernel URL with the DENSE_EVOLUTION_KERNEL_URL env var if it's
+not on the default host/port.
+
+Images (circuit diagrams, histograms, Q-sphere, Bloch vectors) come back
+from the kernel as base64 PNGs meant for a browser <img> tag -- inlining
+that into a tool's text response would flood an agent's context with a
+wall of base64 for a picture it can't even see inline. Instead this
+adapter decodes and writes each one to DENSE_EVOLUTION_MCP_IMAGE_DIR
+(default ~/.dense_evolution_mcp/images) and returns the file path, which
+Claude Code (or any agent with file access) can open directly. Large
+numeric arrays (statevector, probabilities) are similarly truncated to
+their most significant entries rather than dumped in full -- the kernel's
+own response can be tens of thousands of floats for a 20+ qubit circuit.
+
+Structure (prog.txt Sezione 3, now complete): settings live in config.py,
+the HTTP client + error handling in client.py, the Pydantic input schemas
+in models.py (Phase 1); image saving/truncation/molecule-catalog caching
+in utils/ and molecules.py (Phase 2); the 32 tools themselves (7 system +
+2 circuit + 9 chemistry + 4 mitigation + 3 wormhole + 3 noise + 3 crypto +
+1 retrieval -- counted directly from the imports below, not assumed: a
+`len(...) == N` regression test guards against drift, see
+test_mcp_server.py), split by topic, in tools/ (Phase 3,
+this file). This file's only job is to create
+the MCPServer instance, import each tools/*.py module so its `@mcp.tool`
+decorators register against it, re-export every tool function (so
+`from mcp_server.server import dense_evolution_health` keeps working for
+existing callers, including this repo's own test suite), and provide the
+`main()` console-script entry point.
+
+`mcp` is created here BEFORE the `from .tools....` imports below, and
+every tools/*.py module does `from ..server import mcp` -- Python resolves
+this correctly despite looking circular: by the time those imports run,
+`mcp_server.server` is already in `sys.modules` (registered before this
+file's body starts executing) with `mcp` already assigned, so each
+submodule's `from ..server import mcp` finds it immediately. Reordering
+the `mcp = MCPServer(...)` line to after the tool imports would break this.
+"""
+from mcp.server import MCPServer
+
+mcp = MCPServer("dense_evolution_mcp")
+
+from .tools.system_tools import (  # noqa: E402
+    dense_evolution_health, dense_evolution_kernel_status, dense_evolution_list_gates,
+    dense_evolution_list_molecules, dense_evolution_list_noise_models, dense_evolution_list_presets,
+    dense_evolution_system_limits,
+)
+from .tools.circuit_tools import dense_evolution_build_circuit, dense_evolution_run_circuit  # noqa: E402
+from .tools.chemistry_tools import (  # noqa: E402
+    dense_evolution_custom_molecule_energy, dense_evolution_energy_scan, dense_evolution_mass_decomposition,
+    dense_evolution_md_trajectory, dense_evolution_mix_molecules, dense_evolution_molecule_energy,
+    dense_evolution_native_hf_diagnostics, dense_evolution_qmmm_forces, dense_evolution_run_vqe,
+)
+from .tools.mitigation_tools import (  # noqa: E402
+    dense_evolution_mitigate_coherence, dense_evolution_mitigate_density_matrix,
+    dense_evolution_mitigate_zne, dense_evolution_vector_healing,
+)
+from .tools.wormhole_tools import (  # noqa: E402
+    dense_evolution_wormhole_scan, dense_evolution_wormhole_select_instance, dense_evolution_wormhole_teleportation,
+)
+from .tools.noise_tools import (  # noqa: E402
+    dense_evolution_cosmic_ray_burst, dense_evolution_oscillating_noise, dense_evolution_density_matrix_channel,
+)
+from .tools.crypto_tools import (  # noqa: E402
+    dense_evolution_crypto_bb84, dense_evolution_crypto_di_qkd_ghz, dense_evolution_crypto_dicka,
+)
+from .tools.retrieval_tools import dense_evolution_rag_search  # noqa: E402
+
+
+def main():
+    """Console-script entry point (`dense-evolution mcp`, see
+    dense_evolution/cli.py) -- identical to running this file directly.
+    stdio transport: this process is meant to be launched by an MCP
+    client (Claude Code, Claude Desktop, ...) as a subprocess, not run
+    standalone in a terminal."""
+    import asyncio
+    from .client import close_shared_client, ensure_kernel_running
+    try:
+        asyncio.run(ensure_kernel_running())
+    except RuntimeError:
+        pass  # best-effort only -- an event-loop hiccup here must never block startup
+    try:
+        mcp.run()  # pragma: no cover -- blocks on the real stdio transport loop
+    finally:
+        # Best-effort: mcp.run() has already torn down its own event loop
+        # by the time this runs, so close_shared_client() executes under a
+        # fresh one here -- fine for aclose() (it just closes the pool),
+        # but swallow a RuntimeError anyway rather than let cleanup crash
+        # shutdown for what's ultimately a leaked-socket warning, not a
+        # correctness issue.
+        try:
+            asyncio.run(close_shared_client())
+        except RuntimeError:
+            pass
+
+
+if __name__ == "__main__":
+    main()