ovito-mcp 2026.1.dev2__py3-none-any.whl

ovito_mcp/__init__.py

@@ -0,0 +1,1275 @@
+"""MCP server for interactive work in an OVITO Jupyter kernel.
+
+This server uses ``jupyter_client`` to talk to an OVITO ipykernel and exposes
+tools that execute Python code in that live, persistent kernel session. Because
+OVITO is importable in the kernel, an LLM can drive a real OVITO session
+interactively (load files, apply modifiers, inspect results) while a human
+watches the same session.
+
+The standard mode of operation is to attach to a kernel that OVITO Pro has
+already started: the *AI Agent* panel in OVITO Pro's data inspector launches the
+coding agent with a startup prompt carrying the kernel's connection-file path,
+and the agent passes that path to connect_kernel(). No configuration is required
+for this flow. start_kernel() is the fallback for standalone use without a
+running OVITO Pro session; only that path needs OVITO_EXE.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import queue
+import re
+import subprocess
+import uuid
+from pathlib import Path
+
+from jupyter_client.blocking.client import BlockingKernelClient
+from jupyter_client.kernelspec import NoSuchKernel
+from jupyter_client.manager import KernelManager
+from jupyter_core.paths import jupyter_runtime_dir
+from mcp.server.fastmcp import FastMCP, Image
+
+from ovito_mcp import rag
+
+# Advanced override: path to the OVITO Pro executable. Only start_kernel() needs it,
+# to launch OVITO itself; the standard connect_kernel() flow never does. Deliberately
+# not validated at import time, so the server always starts without configuration.
+OVITO_EXE: str | None = os.environ.get("OVITO_EXE")
+KERNEL_NAME: str = "ovito-pro"
+RUNTIME_DIR = jupyter_runtime_dir()
+
+# Advanced override: path to the documentation database. Normally left unset — the
+# database ships inside OVITO Pro and is located next to the 'ovito' package via the
+# connected kernel (see _discover_rag_db()). Set it only to point the doc tools at a
+# different database, e.g. one built by hand during development.
+RAG_DB: str | None = os.environ.get("OVITO_RAG_DB")
+# Lazily constructed ovito_mcp.rag.DocsIndex; see _docs_index().
+_docs_index_instance = None
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+_MISSING_OVITO_EXE = (
+    "start_kernel() needs the OVITO_EXE environment variable — the path to the OVITO "
+    "Pro executable — so this server can launch OVITO itself. In the standard setup "
+    "you do not need it: start the coding agent from the 'AI Agent' panel in OVITO "
+    "Pro's data inspector, then call connect_kernel(<connection_file>) with the path "
+    "given in the startup prompt to attach to the already-running session."
+)
+
+
+# ---------------------------------------------------------------------------
+# Session state (the stdio server is a single long-lived process, so the
+# kernel connection persists across tool calls).
+# ---------------------------------------------------------------------------
+
+
+class _Session:
+    def __init__(self) -> None:
+        self.kc: BlockingKernelClient | None = None
+        # km is set only for kernels this server started itself. When we merely
+        # connect to an already-running kernel via its connection file, kc is set
+        # but km stays None (we do not own that kernel's lifecycle).
+        self.km: KernelManager | None = None
+        self.connection_file: str | None = None
+        self.window_open: bool = False
+
+
+_session = _Session()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _id_from_path(path: str | os.PathLike) -> str:
+    name = Path(path).name
+    if name.startswith("kernel-") and name.endswith(".json"):
+        return name[len("kernel-") : -len(".json")]
+    return name
+
+
+def _require_active() -> BlockingKernelClient:
+    if _session.kc is None:
+        result = start_kernel()
+        if _session.kc is None:
+            raise RuntimeError(f"Failed to start kernel: {result}")
+    return _session.kc
+
+
+def _ensure_ipykernel_installed() -> str | None:
+    """Install ``ipykernel`` into OVITO_EXE's Python environment if it is missing.
+
+    The kernelspec launches ``OVITO_EXE --kernel <connection_file>``, which imports
+    ipykernel internally — OVITO does not bundle it. OVITO_EXE has no real ``-m``
+    passthrough (it silently ignores the flag), so pip must be driven through its
+    internal API via ``--exec`` instead of ``OVITO_EXE -m pip install ...``.
+
+    This is the first point on the launch path that actually needs the OVITO
+    executable, so it is where OVITO_EXE is checked — nothing else in the server
+    requires it.
+
+    Returns:
+        None if ipykernel is present (or was just installed), otherwise an
+        error message describing the failure.
+
+    Raises:
+        ValueError: If OVITO_EXE is not set.
+    """
+    if not OVITO_EXE:
+        raise ValueError(_MISSING_OVITO_EXE)
+
+    check = subprocess.run(
+        [OVITO_EXE, "--nogui", "--exec", "import ipykernel"],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if check.returncode == 0:
+        return None
+
+    install = subprocess.run(
+        [
+            OVITO_EXE,
+            "--nogui",
+            "--exec",
+            "from pip._internal.cli.main import main; "
+            "raise SystemExit(main(['install', 'ipykernel']))",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=300,
+    )
+    if install.returncode != 0:
+        return (
+            "Failed to install ipykernel into the OVITO_EXE Python environment:\n"
+            f"{install.stdout}{install.stderr}"
+        )
+    return None
+
+
+def _teardown_current() -> None:
+    """Tear down the active session before starting or connecting to another kernel.
+
+    A kernel this server started (km set) is shut down; a kernel we merely connected
+    to (km None, kc set) is left running — we only drop our client channels.
+    """
+    if _session.km is not None:
+        _close_window_if_open()
+        _session.km.shutdown_kernel(now=True)
+    if _session.kc is not None:
+        _session.kc.stop_channels()
+    _session.kc = None
+    _session.km = None
+    _session.connection_file = None
+    _session.window_open = False
+
+
+def _close_window_if_open() -> None:
+    """Close the OVITO GUI window in the kernel before a restart or shutdown.
+
+    Acts only when this server opened a window itself (window_open is set True
+    exclusively by create_window() after it actually opens a new window — never when
+    reusing a pre-existing one), so a window that already existed before this server
+    attached is not closed. Note that the window actually closed is whichever one
+    MainWindow.get_current() reports as active, not a handle retained from
+    create_window().
+    """
+    if not _session.window_open or _session.kc is None:
+        return
+    try:
+        # Wrapped in a function so the reference to the window is dropped as soon as the
+        # cell finishes. A name left bound in the kernel namespace would keep the closed
+        # window object alive until the next tool call rebinds it.
+        execute(
+            "def _ovito_mcp_close():\n"
+            "    import ovito.gui\n"
+            "    win = ovito.gui.MainWindow.get_current()\n"
+            "    if win is not None:\n"
+            "        win.widget.close()\n"
+            "_ovito_mcp_close()\n"
+            "del _ovito_mcp_close\n",
+            timeout=5.0,
+        )
+    except Exception:
+        pass
+    _session.window_open = False
+
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "ovito-mcp",
+    instructions=(
+        "Interactive access to an OVITO Jupyter kernel. State (variables, imports, the "
+        "OVITO pipeline) carries across calls, and the 'ovito' package is importable in "
+        "the kernel. "
+        "\n\n"
+        "CONNECTING — The normal case is that OVITO Pro is already running and started "
+        "the kernel for you: your startup prompt contains a connection-file path, so "
+        "call connect_kernel(<that path>) first and work in that live session, which a "
+        "human is watching and can interact with. Only if you were given no connection "
+        "file should you fall back to start_kernel(), which launches a separate OVITO "
+        "process and requires the OVITO_EXE environment variable to be set. Calling "
+        "execute(code) with no active kernel attempts start_kernel() implicitly — so if "
+        "a connection file was provided, connect first rather than letting that happen. "
+        "Use interrupt_kernel/restart_kernel/shutdown_kernel for lifecycle control. "
+        "Call create_window() to open OVITO's full graphical main window so a human can "
+        "watch — and interact with — the scene the kernel is building, live. "
+        "Call screenshot_window() by default for any visual check — verifying a modifier's "
+        "effect, camera framing, or general progress — not just when the user explicitly "
+        "asks to see the window. It is a cheap window grab, not a real render, though "
+        "screenshots are still large and consume many tokens, so don't call it gratuitously. "
+        "It also captures any dialog windows currently open on top of the main window, so a "
+        "modal dialog blocking the GUI is visible to you rather than silently missing. "
+        "Call set_current_frame(frame) to navigate the animation timeline — do NOT set "
+        "ovito.scene.anim.current_frame directly in execute(), as the tool is the canonical "
+        "way to advance the timeline and keeps the GUI in sync. "
+        "Call list_pipeline_status() to check every pipeline, modifier, and visual element "
+        "for the yellow/red warning or error triangles shown in the GUI. "
+        "\n\n"
+        "DOCUMENTATION — If the result shows an error or unexpected output, "
+        "do NOT retry blindly — consult the documentation first: call "
+        "search_ovito_docs(query) to run a full-text search across the OVITO manual and "
+        "Python API stubs and return the most relevant full pages/docstrings. Use it "
+        "whenever you need exact parameter names, allowed values, step-by-step procedures, "
+        "or code examples. Do not guess at OVITO APIs — search the docs first. When in "
+        "doubt, search — it is cheaper than a failed execute() call. Results are always "
+        "the complete manual page or docstring, not a truncated summary or excerpt, so "
+        "you should not need a separate follow-up fetch in the common case."
+        "\n\n"
+        "GUI ERRORS (yellow or red triangle) — If the OVITO GUI shows a warning or error "
+        "indicator (yellow or red triangle on a pipeline or modifier), call "
+        "list_pipeline_status() first to see the exact status_code/status_text behind every "
+        "triangle (pipelines, modifiers, and visual elements alike) before doing anything "
+        "else — this is the fastest way to identify which node is failing and why. Use that "
+        "output together with the documentation to diagnose the issue. Only if it still "
+        "cannot be resolved after consulting the documentation, call restart_kernel(). "
+        "OVITO's scene is stateful and some error conditions are caused by accumulated state "
+        "that only a kernel restart can clear. After restarting, rebuild the pipeline from "
+        "scratch."
+        "\n\n"
+        "PREFER OVITO BUILT-INS — Always prefer OVITO's own modifiers, utilities, and "
+        "helper functions over custom implementations, and prefer higher-level abstractions "
+        "over lower-level ones. Examples:\n"
+        "- Use DisplacementVectors modifier instead of manually computing atom displacements.\n"
+        "- Use SimulationCell.delta_vector() to compute minimum-image distances/vectors "
+        "instead of writing custom periodic boundary condition logic.\n"
+        "- Use PolyhedralTemplateMatchingModifier.calculate_misorientation(a, b, "
+        "symmetry='none'|'cubic'|'hexagonal') for grain misorientation/disorientation angles "
+        "instead of custom quaternion math — it already does the lattice-symmetry "
+        "reduction into the fundamental zone (see below).\n"
+        "- Use CommonNeighborAnalysis, IdentifyDiamond, or other structure identification "
+        "modifiers instead of re-implementing crystal structure detection.\n"
+        "Before writing any geometry, distance, or crystallography calculation from scratch, "
+        "search the docs to see if OVITO already provides it — it almost certainly does, "
+        "and the built-in version handles edge cases (PBC, triclinic cells, etc.) correctly."
+        "\n\n"
+        "SILENT-FAILURE RISK: SYMMETRY / QUATERNION MATH — Never hand-roll a crystal-"
+        "symmetry reduction (e.g. minimizing a misorientation angle over the 24/48 cubic "
+        "point-group operators to find a disorientation) directly in execute() code. This "
+        "class of bug does NOT raise an error or show a pipeline warning triangle — it "
+        "silently returns a plausible-looking but wrong number (e.g. a spuriously small "
+        "angle that happens to land near a well-known CSL value), so the normal 'if it "
+        "errors, check the docs' reflex never fires and the wrong answer gets reported as "
+        "fact. Treat any orientation/misorientation/disorientation/CSL question as a hard "
+        "requirement to search the docs for the built-in first (start with "
+        "PolyhedralTemplateMatchingModifier.calculate_misorientation) — do not attempt "
+        "your own quaternion symmetry loop even if it looks like a small, self-contained "
+        "calculation. If you ever do end up trusting a self-derived numeric result for "
+        "something OVITO might already compute, say so explicitly and flag it as "
+        "unverified rather than reporting it with full confidence."
+        "\n\n"
+        "RENDERING TO DISK — Do NOT render images or videos to disk (e.g. via "
+        "Viewport.render_image(), Viewport.render_anim(), or any file export that produces "
+        "image/video output) unless the user explicitly asks for it in that turn. This "
+        "applies every time, not just the first time in a session — do not render again "
+        "later in the same conversation just because a render happened once before. "
+        "Rendering is slow and may produce large files the user does not want. Always use "
+        "screenshot_window() for visual inspection instead."
+        "\n\n"
+        "WRITING SCRIPTS TO DISK — Do NOT save the Python code you run through execute() "
+        "to a .py file (or any other file) unless the user explicitly asks you to keep or "
+        "export a script. Pass the code straight to execute() instead. The kernel already "
+        "persists state across calls, so there is no need for a script file just to "
+        "re-run or iterate on code."
+    ),
+)
+
+
+@mcp.tool()
+def start_kernel() -> str:
+    """Start a new OVITO Jupyter kernel and make it the active session.
+
+    This launches a *separate* OVITO process and therefore requires the OVITO_EXE
+    environment variable. Prefer connect_kernel() when OVITO Pro is already running
+    and has supplied a connection file — that is the standard flow and needs no
+    configuration.
+
+    If a kernel is already running it is shut down first. The kernelspec's
+    launcher is normalized to OVITO's interpreter so the kernel runs under
+    OVITO regardless of PATH. Before launching, ``ipykernel`` is installed into
+    OVITO_EXE's Python environment if it isn't already present.
+
+    Returns:
+        Confirmation with the new kernel's id.
+
+    Raises:
+        ValueError: if OVITO_EXE is not set.
+    """
+    if (err := _ensure_ipykernel_installed()) is not None:
+        return err
+
+    _teardown_current()
+    try:
+        km = KernelManager(kernel_name=KERNEL_NAME, transport="ipc")
+    except NoSuchKernel:
+        return (
+            f"Kernelspec '{KERNEL_NAME}' not found. Run `jupyter kernelspec list` under "
+            "ovitos to confirm it is installed."
+        )
+
+    # Write the connection file into the Jupyter runtime dir with a standard
+    # kernel-<id>.json name, so the kernel shows up in `jupyter console --existing`.
+    os.makedirs(RUNTIME_DIR, exist_ok=True)
+    km.connection_file = os.path.join(RUNTIME_DIR, f"kernel-{uuid.uuid4()}.json")
+
+    # Use ZMQ IPC transport (Unix-domain socket files) so kernel messaging stays
+    # local and does not open a network port.
+    assert km.kernel_spec is not None
+    km.kernel_spec.argv = [
+        OVITO_EXE,
+        "--kernel",
+        "{connection_file}",
+    ]
+
+    km.start_kernel()
+    kc = km.client()
+    kc.start_channels()
+    try:
+        kc.wait_for_ready(timeout=60)
+    except RuntimeError as exc:
+        km.shutdown_kernel(now=True)
+        return f"Kernel started but did not become ready: {exc}"
+
+    _session.kc = kc
+    _session.km = km
+    _session.connection_file = km.connection_file
+    return f"Started OVITO kernel (id {_id_from_path(km.connection_file)})."
+
+
+@mcp.tool()
+def connect_kernel(connection_file: str) -> str:
+    """Connect to an already-running Jupyter kernel via its connection file.
+
+    Attaches to a kernel that was started outside this server (e.g. one launched from
+    an already running OVITO GUI session) instead of starting a new
+    one. State in that kernel (variables, imports, the OVITO pipeline) is shared: code
+    run via execute() executes in the same live session a human may also be driving.
+
+    Because this server does not own an externally-started kernel, it will not shut that
+    kernel down — start_kernel(), connect_kernel(), or shutdown_kernel() only detach our
+    client. Any kernel this server had started itself is shut down first.
+
+    Args:
+        connection_file: Path to the kernel's JSON connection file. May be an absolute
+            path, or just the file name (e.g. "kernel-<id>.json"), in which case it is
+            looked up in the Jupyter runtime directory. Run `jupyter console --existing`
+            or check the runtime dir to find running kernels' connection files.
+
+    Returns:
+        Confirmation or an error if the file is missing or the kernel does not respond. 
+    """
+    path = Path(connection_file).expanduser()
+    if not path.is_file():
+        candidate = Path(RUNTIME_DIR) / path.name
+        if candidate.is_file():
+            path = candidate
+    if not path.is_file():
+        return (
+            f"Connection file not found: {connection_file}. Provide an absolute path, "
+            f"or a kernel-<id>.json name present in the runtime dir ({RUNTIME_DIR})."
+        )
+
+    _teardown_current()
+
+    kc = BlockingKernelClient()
+    try:
+        kc.load_connection_file(str(path))
+        kc.start_channels()
+        kc.wait_for_ready(timeout=60)
+    except Exception as exc:  # noqa: BLE001 - surface any connection failure to the LLM
+        kc.stop_channels()
+        return f"Failed to connect to kernel at {path}: {exc}"
+
+    _session.kc = kc
+    _session.connection_file = str(path)
+    return (
+        f"You are now connected to existing OVITO session. Ask the user what they'd like to do with OVITO unless they have already specified an action."
+    )
+
+
+@mcp.tool()
+def execute(code: str, timeout: float = 60.0) -> str:
+    """Execute Python code in the active OVITO kernel and return its output.
+
+    State persists across calls (variables, imports, the OVITO pipeline). The 'ovito'
+    package is importable. Captures stdout/stderr, the result value, and tracebacks.
+    Binary outputs (e.g. images from display) are summarized, not returned as bytes.
+
+    Do NOT call Viewport.render_image(), Viewport.render_anim(), or export_file(...)
+    with an image/video format through this tool unless the user explicitly asked for
+    a render or export. For any "let me check what this looks like" need — verifying
+    a modifier's effect, camera framing, progress on a pipeline — call
+    screenshot_window() instead; it's a cheap window grab, not a real render.
+
+    If the result shows an error or unexpected output, do NOT retry blindly — consult
+    the documentation first: call search_ovito_docs(query) to look up the correct API.
+    Guessing at fixes without checking the docs wastes attempts and risks deeper confusion.
+
+    Do NOT write the code you intend to run out to a .py file on disk first — just pass
+    it directly as the `code` argument. Only save code to a file if the user explicitly
+    asks for a script to be kept or exported.
+
+    Args:
+        code: Python source to run in the kernel.
+        timeout: Max seconds to wait for output before returning partial results
+                 (the kernel keeps running).
+
+    Returns:
+        A text report: status, captured streams, result value, and any error.
+    """
+    kc = _require_active()
+    msg_id = kc.execute(code)
+
+    stdout: list[str] = []
+    stderr: list[str] = []
+    results: list[str] = []
+    error: str | None = None
+    extras: list[str] = []
+    count: int | None = None
+    timed_out = False
+
+    # Drain IOPub until the kernel reports idle for our request.
+    while True:
+        try:
+            msg = kc.get_iopub_msg(timeout=timeout)
+        except queue.Empty:
+            extras.append(
+                f"[timed out after {timeout:.0f}s waiting for output; "
+                "the kernel is still running]"
+            )
+            timed_out = True
+            break
+        if msg.get("parent_header", {}).get("msg_id") != msg_id:
+            continue
+        mtype = msg["msg_type"]
+        content = msg["content"]
+        if mtype == "status":
+            if content.get("execution_state") == "idle":
+                break
+        elif mtype == "execute_input":
+            count = content.get("execution_count", count)
+        elif mtype == "stream":
+            (stdout if content.get("name") == "stdout" else stderr).append(
+                content.get("text", "")
+            )
+        elif mtype in ("execute_result", "display_data"):
+            data = content.get("data", {})
+            if "text/plain" in data:
+                results.append(data["text/plain"])
+            for mime in data:
+                if mime != "text/plain":
+                    extras.append(f"[{mime} output omitted]")
+        elif mtype == "error":
+            tb = _ANSI_RE.sub("", "\n".join(content.get("traceback", [])))
+            error = tb or f"{content.get('ename')}: {content.get('evalue')}"
+
+    # Shell reply: authoritative overall status + execution count. Read until we find the
+    # reply for our request (other queued replies, if any, are skipped).
+    status = "error" if error else "ok"
+    if not timed_out:
+        for _ in range(5):
+            try:
+                reply = kc.get_shell_msg(timeout=10)
+            except queue.Empty:
+                break
+            if reply.get("parent_header", {}).get("msg_id") == msg_id:
+                rc = reply["content"]
+                status = rc.get("status", status)
+                count = rc.get("execution_count", count)
+                break
+
+    out: list[str] = []
+    header = f"[{status}]" + (f" (In[{count}])" if count is not None else "")
+    out.append(header)
+    if stdout:
+        out.append("--- stdout ---\n" + "".join(stdout).rstrip())
+    if stderr:
+        out.append("--- stderr ---\n" + "".join(stderr).rstrip())
+    if results:
+        out.append("--- result ---\n" + "\n".join(r.rstrip() for r in results))
+    if error:
+        out.append("--- error ---\n" + error.rstrip())
+    if extras:
+        out.append("\n".join(extras))
+    if len(out) == 1:
+        out.append("(no output)")
+    return "\n".join(out)
+
+
+@mcp.tool()
+def create_window(contents: str | None = None) -> str:
+    """Open OVITO's graphical main window so the user can watch what the kernel does.
+
+    Launches the full OVITO GUI (interactive pipeline editor, viewports, data inspector)
+    in the active kernel via ovito.gui.MainWindow(). Changes made to the scene,
+    pipelines, or viewports from execute() are synchronized with the window in both
+    directions, so a human can see — and interact with — the live session in real time.
+    Use this when the user wants to visually follow along with the work.
+
+    Requirements:
+      * An OVITO Pro Jupyter kernel. The standalone PyPI 'ovito' package has no GUI and
+        will raise a RuntimeError.
+      * A running Qt event loop in the kernel. The OVITO Pro kernel provides this; in a
+        plain ipykernel run execute("%gui qt") first if the window appears frozen.
+
+    If a window is already open in the kernel — including one that existed before this
+    server attached via connect_kernel() — and contents is omitted, the existing window
+    is reused instead of opening a duplicate. Note: reusing a pre-existing window does
+    NOT make this server its owner — close_window() stays a no-op unless this server
+    actually opened a window itself.
+
+    Args:
+        contents: Optional name (or expression) of a Pipeline or Viewport already defined
+                  in the kernel to display, e.g. "pipeline". If omitted, the current
+                  ovito.scene (all added pipelines) is shown.
+
+    Returns:
+        The kernel's report from opening (or reusing) the window.
+    """
+    # The new window is not bound to a name: it stays alive because Qt owns the shown
+    # top-level widget, and leaving no reference behind lets it be released on close.
+    arg = contents.strip() if contents else ""
+    if arg:
+        code = (
+            "import ovito.gui\n"
+            f"ovito.gui.MainWindow({arg})\n"
+            "print('OVITO main window opened.')"
+        )
+    else:
+        code = (
+            "import ovito.gui\n"
+            "if ovito.gui.MainWindow.get_current() is not None:\n"
+            "    print('Reusing already-open OVITO main window.')\n"
+            "else:\n"
+            "    ovito.gui.MainWindow()\n"
+            "    print('OVITO main window opened.')\n"
+        )
+    # create_window() returns immediately only if the kernel has an integrated Qt event
+    # loop; otherwise it runs the GUI loop inline and the cell never reaches idle. Use a
+    # short timeout so the tool reports back quickly instead of blocking the agent for the
+    # full default. A timeout here means the window opened but the kernel is now busy
+    # driving its own event loop (no integrated %gui qt) — see the docstring requirements.
+    result = execute(code, timeout=5.0)
+    # Only claim ownership (and thus become eligible for close_window()) when this call
+    # actually created a new window — never for the "reusing" branch, so a pre-existing
+    # window is never later closed by this server.
+    if "OVITO main window opened." in result:
+        _session.window_open = True
+    return result
+
+
+@mcp.tool()
+def close_window() -> str:
+    """Close the OVITO GUI window this server opened.
+
+    A no-op unless this server itself opened a window via create_window(): a window that
+    already existed before this server attached (e.g. via connect_kernel()), even if
+    create_window() later reused it for display, is left alone.
+
+    Returns:
+        Confirmation that the window was closed, or a message if no window was open.
+    """
+    if not _session.window_open:
+        return "No OVITO window is open."
+    _close_window_if_open()
+    return "OVITO window closed."
+
+
+@mcp.tool(structured_output=False)
+def screenshot_window() -> list[str | Image]:
+    """Capture a screenshot of the open OVITO GUI window and return it as an image.
+
+    This is the default, preferred way to inspect the scene visually — a cheap
+    window grab, not a real render. Use it for any "let me check what this looks
+    like" need: verifying a modifier's effect, camera framing, or general progress.
+    Prefer this over Viewport.render_image()/render_anim() or image/video export,
+    which are slow and should only run when the user explicitly asks for a render.
+
+    Grabs the current visual state of the OVITO main window (viewports, pipeline
+    editor, data inspector) as a PNG. Any dialog windows belonging to the main window
+    that are currently visible are captured as well, so a modal dialog blocking the GUI
+    shows up here instead of silently going unnoticed.
+
+    Requires an open OVITO window — call create_window() first. Also finds a window
+    that was already open before this server attached (e.g. via connect_kernel()),
+    not just one opened by create_window().
+
+    Returns:
+        One PNG image per captured window — the main window first, then any visible
+        dialogs — each preceded by a line naming that window's title.
+    """
+    # Wrapped in a function so the window object and the captured pixmaps are released as
+    # soon as the cell finishes, rather than lingering as names in the kernel namespace.
+    code = (
+        "def _ovito_mcp_screenshot():\n"
+        "    import base64, ovito.gui\n"
+        "    from PySide6.QtCore import QBuffer, QIODevice\n"
+        "    win = ovito.gui.MainWindow.get_current()\n"
+        "    if win is None:\n"
+        "        print('ERROR: No OVITO window open. Call create_window() first.')\n"
+        "        return\n"
+        "    for pixmap, title in win.take_screenshot():\n"
+        "        buf = QBuffer()\n"
+        "        buf.open(QIODevice.OpenModeFlag.WriteOnly)\n"
+        "        pixmap.save(buf, 'PNG')\n"
+        "        print('SHOT\\t' + ' '.join(str(title).split()) + '\\t'\n"
+        "              + base64.b64encode(bytes(buf.data())).decode('ascii'))\n"
+        "_ovito_mcp_screenshot()\n"
+        "del _ovito_mcp_screenshot\n"
+    )
+    result = execute(code, timeout=15.0)
+    shots = re.findall(r"^SHOT\t([^\t]*)\t([A-Za-z0-9+/=]+)$", result, re.M)
+    if not shots:
+        raise RuntimeError(f"Screenshot failed: {result}")
+    images: list[str | Image] = []
+    for title, encoded in shots:
+        try:
+            png_bytes = base64.b64decode(encoded)
+        except Exception as exc:
+            raise RuntimeError(
+                f"Screenshot decode failed: {exc}\nRaw output:\n{result}"
+            ) from exc
+        images.append(f"Window: {title}" if title else "Window: (untitled)")
+        images.append(Image(data=png_bytes, format="png"))
+    return images
+
+
+@mcp.tool()
+def list_pipelines() -> str:
+    """List all pipelines currently in the OVITO scene.
+
+    Use this to inspect the current program state — call it to discover what data is
+    pipelines are currently in the scene. Returns each pipeline's integer hash (use this
+    as a stable key to refer to a specific pipeline in subsequent calls) and its display
+    name (object_title). Requires an active kernel with an OVITO scene loaded.
+
+    Returns:
+        A table of pipeline keys and names, or a message if the scene is empty.
+    """
+    code = (
+        "import ovito\n"
+        "_pipelines = list(ovito.scene.pipelines)\n"
+        "if not _pipelines:\n"
+        "    print('No pipelines in the scene.')\n"
+        "else:\n"
+        "    print(f'{len(_pipelines)} pipeline(s) in scene:')\n"
+        "    print('key | name')\n"
+        "    for _p in _pipelines:\n"
+        "        print(f'{hash(_p)} | {_p.object_title}')\n"
+    )
+    return execute(code)
+
+
+@mcp.tool()
+def list_modifiers(pipeline_key: str) -> str:
+    """List all modifiers in a specific OVITO pipeline.
+
+    Use this to inspect the current program state — call it to see which modifiers are
+    applied to a pipeline before modifying or reordering them. Obtain pipeline_key from
+    list_pipelines() first.
+
+    Args:
+        pipeline_key: The integer hash of the pipeline as returned by list_pipelines().
+
+    Returns:
+        A table of modifier keys, types, and names, or an error if the pipeline is not found.
+    """
+    code = (
+        "import ovito\n"
+        f"_target_key = {pipeline_key}\n"
+        "_found = False\n"
+        "for _p in ovito.scene.pipelines:\n"
+        "    if hash(_p) == _target_key:\n"
+        "        _found = True\n"
+        "        _mods = list(_p.modifiers)\n"
+        "        if not _mods:\n"
+        "            print('Pipeline has no modifiers.')\n"
+        "        else:\n"
+        "            print(f'{len(_mods)} modifier(s) in pipeline {_p.object_title!r}:')\n"
+        "            print('key | type | name')\n"
+        "            for _m in _mods:\n"
+        "                print(f'{hash(_m)} | {type(_m).__name__} | {_m.object_title}')\n"
+        "        break\n"
+        "if not _found:\n"
+        f"    print('Error: No pipeline with key {pipeline_key} found. Call list_pipelines() to see available pipelines.')\n"
+    )
+    return execute(code)
+
+
+@mcp.tool()
+def inspect_pipeline_data(pipeline_key: int) -> str:
+    """Return a structured overview of all data objects in a pipeline's current output.
+
+    Use this to inspect the current program state — call it to discover what data objects,
+    property containers, attributes, and simulation cell a pipeline currently produces
+    before writing analysis or export code. Obtain pipeline_key from list_pipelines().
+
+    Args:
+        pipeline_key: The integer hash of the pipeline as returned by list_pipelines().
+
+    Returns:
+        Markdown tables listing global attributes, data objects (with numeric IDs and
+        types), property containers with their properties, and the simulation cell.
+    """
+    code = f"""
+import io
+import ovito
+import ovito.data
+from ovito.data import DataCollection, DataObject
+
+def _fmt(s):
+    return f'"{{s}}"' if isinstance(s, str) else repr(s)
+
+def _data_collection_dir(data):
+    output = io.StringIO()
+    print("Global Attributes:\\n", file=output)
+    print("| Name      | Value        |", file=output)
+    print("|-----------|--------------|", file=output)
+    for attr in data.attributes:
+        print(f"| {{attr}} | {{_fmt(data.attributes[attr])}} |", file=output)
+    containers = []
+    def print_data_object(obj, path_prefix=""):
+        if isinstance(obj, ovito.data.AttributeDataObject):
+            return
+        print(f"| {{hash(obj)}} | {{type(obj).__name__}} | {{_fmt(path_prefix + obj.identifier)}} |", file=output)
+        if isinstance(obj, ovito.data.SurfaceMesh):
+            for subobj in [obj.vertices, obj.faces, obj.regions]:
+                print_data_object(subobj, path_prefix=obj.identifier + '/')
+        if isinstance(obj, ovito.data.PropertyContainer):
+            containers.append((obj, path_prefix + obj.identifier))
+    print("\\nData Objects:\\n", file=output)
+    print("| Numeric ID | Type | Identifier |", file=output)
+    print("|------------|------|------------|", file=output)
+    for obj in data.objects:
+        print_data_object(obj)
+    print("\\nProperty Containers:\\n", file=output)
+    for container, path in containers:
+        print(f"\\nNumeric ID: {{hash(container)}} - Path: {{_fmt(path)}} - Type: {{type(container).__name__}} - Element count: {{container.count}}\\n", file=output)
+        print("| Property name | Dtype     | Vector components |", file=output)
+        print("|---------------|-----------|-------------------|", file=output)
+        for prop in container.properties:
+            cnames = prop.component_names if len(prop.component_names) > 0 else ''
+            print(f"| {{prop.identifier}} | {{prop.dtype}} | {{cnames}} |", file=output)
+    if data.cell:
+        print("\\nSimulation cell:\\n", file=output)
+        print(f"  Vector a: {{data.cell[:,0]}}", file=output)
+        print(f"  Vector b: {{data.cell[:,1]}}", file=output)
+        print(f"  Vector c: {{data.cell[:,2]}}", file=output)
+        print(f"  Origin:   {{data.cell[:,3]}}", file=output)
+        print(f"  PBC: {{data.cell.pbc}}", file=output)
+    return output.getvalue()
+
+_target_key = {pipeline_key}
+_found = False
+for _p in ovito.scene.pipelines:
+    if hash(_p) == _target_key:
+        _found = True
+        _data = _p.compute()
+        print(_data_collection_dir(_data))
+        break
+if not _found:
+    print(f"Error: No pipeline with key {pipeline_key} found. Call list_pipelines() to see available pipelines.")
+"""
+    return execute(code)
+
+
+@mcp.tool()
+def list_pipeline_status() -> str:
+    """Report the status of every pipeline, modifier, and visual element in the scene.
+
+    Surfaces the same information as the yellow/red warning and error triangles shown in
+    the OVITO GUI next to a pipeline, modifier, or visual element. Use this to discover
+    and diagnose pipeline errors or warnings — it is the first thing to check when the
+    GUI shows a triangle indicator, and before deciding whether restart_kernel() is
+    necessary.
+
+    Returns:
+        A pretty-printed structure per pipeline: its nodes (pipeline source and
+        modifiers, each with type, id, title, modifier_type, modifier_id, status_code,
+        status_text, and enabled state) and its visual elements (title, type,
+        status_code, status_text, enabled, id).
+    """
+    code = (
+        "import pprint\n"
+        "import ovito\n"
+        "from ovito.pipeline import ModificationNode\n"
+        "for pipeline in ovito.scene.pipelines:\n"
+        "    pipeline_status = {\n"
+        "        'pipeline_id': hash(pipeline),\n"
+        "        'pipeline_title': pipeline.object_title,\n"
+        "        'nodes': [],\n"
+        "        'visual_elements': [],\n"
+        "    }\n"
+        "    node = pipeline.head\n"
+        "    while node is not None:\n"
+        "        pipeline_status['nodes'].append(\n"
+        "            {\n"
+        "                'type': type(node).__name__,\n"
+        "                'id': hash(node),\n"
+        "                'title': node.object_title,\n"
+        "                'modifier_type': type(node.modifier).__name__ if isinstance(node, ModificationNode) else None,\n"
+        "                'modifier_id': hash(node.modifier) if isinstance(node, ModificationNode) else None,\n"
+        "                'status_code': node.status.type.name,\n"
+        "                'status_text': node.status.text,\n"
+        "                'enabled': node.modifier.enabled if isinstance(node, ModificationNode) else True,\n"
+        "            }\n"
+        "        )\n"
+        "        node = node.input if isinstance(node, ModificationNode) else None\n"
+        "    for vis in pipeline.vis_elements:\n"
+        "        pipeline_status['visual_elements'].append(\n"
+        "            {\n"
+        "                'title': vis.object_title,\n"
+        "                'type': type(vis).__name__,\n"
+        "                'status_code': vis.status.type.name,\n"
+        "                'status_text': vis.status.text,\n"
+        "                'enabled': vis.enabled,\n"
+        "                'id': hash(vis),\n"
+        "            }\n"
+        "        )\n"
+        "    pprint.pprint(pipeline_status)\n"
+    )
+    return execute(code)
+
+
+@mcp.tool()
+def get_timeline_info() -> str:
+    """Return the current frame and frame range of the OVITO scene timeline.
+
+    Use this to inspect the current program state — call it to learn the animation extent
+    and which frame is currently active.
+
+    Returns:
+        The current frame, first frame, and last frame as reported by ovito.scene.anim.
+    """
+    code = (
+        "import ovito\n"
+        "_anim = ovito.scene.anim\n"
+        "print('current_frame | first_frame | last_frame')\n"
+        "print(f'{_anim.current_frame} | {_anim.first_frame} | {_anim.last_frame}')\n"
+    )
+    return execute(code)
+
+
+@mcp.tool()
+def set_current_frame(frame: int) -> str:
+    """Set the current animation frame in the OVITO scene. Always use this tool to navigate
+    the timeline — do NOT set ovito.scene.anim.current_frame directly in execute().
+
+    This is the canonical way to change the active frame. It keeps the GUI viewport in sync
+    and ensures all pipelines recompute consistently. Calling pipeline.compute(frame) alone
+    does not advance the scene timeline and will leave the GUI out of step.
+
+    Args:
+        frame: The frame number to set as the current frame.
+
+    Returns:
+        Confirmation of the new current frame.
+    """
+    code = (
+        "import ovito\n"
+        f"ovito.scene.anim.current_frame = {frame}\n"
+        f"print(f'Current frame set to {frame}.')\n"
+    )
+    return execute(code)
+
+
+def _ovito_file_from_kernel() -> str | None:
+    """Ask an already-connected kernel for ``ovito.__file__``, or None if unavailable.
+
+    Preferred over spawning OVITO_EXE in a subprocess when a kernel is already active
+    (self-started or externally connected via connect_kernel()): it reuses the live
+    session's own 'ovito' import instead of launching a second OVITO process, and works
+    even when OVITO_EXE isn't set (e.g. after connect_kernel() to an externally-started
+    kernel).
+    """
+    if _session.kc is None:
+        return None
+    kc = _session.kc
+    try:
+        msg_id = kc.execute("import ovito; print(ovito.__file__)")
+        stdout: list[str] = []
+        while True:
+            try:
+                msg = kc.get_iopub_msg(timeout=15.0)
+            except queue.Empty:
+                return None
+            if msg.get("parent_header", {}).get("msg_id") != msg_id:
+                continue
+            mtype = msg["msg_type"]
+            content = msg["content"]
+            if mtype == "status" and content.get("execution_state") == "idle":
+                break
+            if mtype == "stream" and content.get("name") == "stdout":
+                stdout.append(content.get("text", ""))
+            elif mtype == "error":
+                return None
+    except Exception:
+        return None
+    text = "".join(stdout).strip()
+    return text or None
+
+
+def _ovito_file_from_subprocess() -> str | None:
+    """Run a one-off ``import ovito; print(ovito.__file__)`` under OVITO_EXE.
+
+    Fallback used when no kernel is currently connected (see _ovito_file_from_kernel()).
+    """
+    if not OVITO_EXE:
+        return None
+    try:
+        result = subprocess.run(
+            [OVITO_EXE, "--nogui", "--exec", "import ovito; print(ovito.__file__)"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    lines = [line for line in result.stdout.splitlines() if line.strip()]
+    return lines[-1].strip() if lines else None
+
+
+def _discover_rag_db() -> str | None:
+    """Find rag.sqlite3 next to the active 'ovito' installation.
+
+    This is the normal way the documentation database is located — OVITO Pro ships it
+    inside the 'ovito' package, so no configuration is needed. Asks the connected
+    kernel for ``ovito.__file__`` (see _ovito_file_from_kernel()), which works without
+    OVITO_EXE and is why the standard connect_kernel() flow needs no setup. Only if no
+    kernel is connected does it fall back to spawning OVITO_EXE (see
+    _ovito_file_from_subprocess()).
+
+    Looks for ``rag.sqlite3`` next to the resolved package directory (e.g. alongside
+    ``.../site-packages/ovito/__init__.py``).
+    """
+    ovito_file = _ovito_file_from_kernel() or _ovito_file_from_subprocess()
+    if not ovito_file:
+        return None
+    candidate = Path(ovito_file).parent / "rag.sqlite3"
+    return str(candidate) if candidate.is_file() else None
+
+
+def _docs_index() -> rag.DocsIndex:
+    """Lazily construct (and cache) the documentation index.
+
+    On failure the cache is deliberately left unset, so a later call retries. This
+    matters: agents routinely search the documentation *before* calling
+    connect_kernel(), and at that point there is no kernel to ask for ovito.__file__.
+    Caching that failure would permanently disable the doc tools for the session.
+    """
+    global _docs_index_instance
+    if _docs_index_instance is None:
+        db_path = RAG_DB or _discover_rag_db()
+        if not db_path:
+            raise ValueError(
+                "Could not locate the OVITO documentation database. It ships with OVITO "
+                "Pro and is found automatically next to the 'ovito' package, but that "
+                "requires an active kernel: call connect_kernel(<connection_file>) "
+                "first (or start_kernel(), which needs OVITO_EXE), then retry. To use a "
+                "different database, set the OVITO_RAG_DB environment variable."
+            )
+        _docs_index_instance = rag.DocsIndex(db_path)
+    return _docs_index_instance
+
+
+class _RagError(Exception):
+    """Carries a message that's safe to return to the LLM as-is."""
+
+
+def _call_rag(fn):
+    """Run ``fn(index)`` behind stdout-redirect + the standard error handling.
+
+    sentence-transformers prints during model load; redirect to stderr so it can never
+    corrupt the stdio JSON-RPC stream. Raises _RagError with an LLM-facing message on
+    any failure.
+    """
+    import contextlib
+    import sys
+
+    try:
+        with contextlib.redirect_stdout(sys.stderr):
+            return fn(_docs_index())
+    except (ValueError, RuntimeError) as exc:
+        # Raised for a missing/undiscoverable database or an empty index.
+        raise _RagError(str(exc)) from exc
+    except Exception as exc:  # noqa: BLE001 - surface any retrieval failure to the LLM
+        raise _RagError(f"RAG operation failed: {exc}") from exc
+
+
+def _format_rag_hits(results: list[dict], query: str, noun: str) -> str:
+    """Render a list of search() / search_docs() / search_symbols() hits as text."""
+    if not results:
+        return f'No OVITO {noun} found for: "{query}"'
+
+    out = [f'Top {len(results)} OVITO {noun} result(s) for: "{query}"\n']
+    for i, r in enumerate(results, 1):
+        header = f"[{i}] score {r['score']:.3f}"
+        if r.get("source"):
+            header += f"  —  {r['source']}"
+        if r.get("full_page_id") is not None:
+            header += f"  (page id {r['full_page_id']})"
+        if r.get("doc_string_id") is not None:
+            header += f"  (docstring id {r['doc_string_id']})"
+        out.append(header)
+        if r.get("symbol"):
+            out.append(
+                f"    symbol: {r['symbol']}  ({r.get('symbol_type') or ''})".rstrip()
+            )
+        if r.get("section"):
+            out.append(f"    section: {r['section']}")
+        text = r["text"]
+        out.append("")
+        out.append(text)
+        out.append("-" * 60)
+    return "\n".join(out)
+
+
+@mcp.tool()
+def search_ovito_docs(query: str, top_k: int = 5) -> str:
+    """Search the OVITO documentation knowledge base (user manual + Python API reference).
+
+    A local RAG index over the OVITO user manual, the Python interface class docs, and
+    the API stub signatures. Use it to look up how OVITO features work, the names and
+    signatures of modifiers / pipeline objects / data classes and their properties and
+    methods, and example usage — ideally *before* writing or debugging code with
+    execute(). This is reference retrieval only; it does not run code.
+
+    Searches both the manual and the API symbols together. Use search_ovito_manual()
+    or search_ovito_api_symbols() instead if you only want one or the other. Manual
+    hits are resolved to their complete source page (not just the matching chunk),
+    and API symbol hits include their full docstring.
+
+    Args:
+        query: Natural-language question or keywords, e.g. "how to apply a slice
+               modifier", "SliceModifier parameters", "compute coordination number",
+               "export to LAMMPS dump file".
+        top_k: Number of documentation results to return (default 5).
+
+    Returns:
+        The most relevant full manual pages / API symbols ranked by similarity, each
+        with its qualified name and kind (for API symbols). Returns guidance instead
+        if the knowledge base is unavailable or empty.
+    """
+    try:
+        results = _call_rag(lambda backend: backend.search(query, top_k=top_k))
+    except _RagError as exc:
+        return str(exc)
+    return _format_rag_hits(results, query, "documentation")
+
+
+@mcp.tool()
+def search_ovito_manual(query: str, top_k: int = 5) -> str:
+    """Search only the OVITO user manual (markdown documentation), skipping API symbols.
+
+    Narrower than search_ovito_docs() — use this when you want conceptual/how-to
+    manual content only and don't want Python API stub signatures mixed in. Each
+    hit is resolved to its complete source page (not just the matching chunk),
+    so you get the full page automatically — full_page_id is still included for
+    reference (e.g. to fetch it again directly via get_ovito_manual_page()).
+
+    Args:
+        query: Natural-language question or keywords, e.g. "how to apply a slice
+               modifier", "export to LAMMPS dump file".
+        top_k: Number of manual snippets to return (default 5).
+
+    Returns:
+        The most relevant manual excerpts ranked by similarity. Returns guidance
+        instead if unavailable or empty.
+    """
+    try:
+        results = _call_rag(lambda backend: backend.search_docs(query, top_k=top_k))
+    except _RagError as exc:
+        return str(exc)
+    return _format_rag_hits(results, query, "manual")
+
+
+@mcp.tool()
+def search_ovito_api_symbols(query: str, top_k: int = 5) -> str:
+    """Search only the OVITO Python API symbols (classes, methods, properties, functions).
+
+    Narrower than search_ovito_docs() — use this when you want API stub
+    signatures/docstrings only and don't want user-manual prose mixed in.
+
+    Args:
+        query: Natural-language question or keywords, e.g. "SliceModifier parameters",
+               "coordination analysis modifier constructor".
+        top_k: Number of symbols to return (default 5).
+
+    Returns:
+        The most relevant API symbols ranked by similarity, each with its qualified
+        name and kind. Returns guidance instead if unavailable or empty.
+    """
+    try:
+        results = _call_rag(lambda backend: backend.search_symbols(query, top_k=top_k))
+    except _RagError as exc:
+        return str(exc)
+    return _format_rag_hits(results, query, "API symbol")
+
+
+@mcp.tool()
+def get_ovito_manual_page(full_page_id: int) -> str:
+    """Fetch the complete text of an OVITO manual page by its full_page_id.
+
+    full_page_id values come from search_ovito_manual() results (each hit is tagged
+    with the id of the page it was chunked from). Use this when a matching chunk
+    isn't enough context and you need the entire source page.
+
+    Args:
+        full_page_id: The manual page's database id, as returned by
+                       search_ovito_manual().
+
+    Returns:
+        The full manual page text, or guidance if the id doesn't exist.
+    """
+    try:
+        page = _call_rag(lambda backend: backend.get_manual_page(full_page_id))
+    except _RagError as exc:
+        return str(exc)
+    if page is None:
+        return f"No manual page found with full_page_id={full_page_id}."
+    return f"# page id {page['full_page_id']}\n\n{page['full_manual_page']}"
+
+
+@mcp.tool()
+def get_ovito_docstring(
+    doc_string_id: int | None = None, symbol: str | None = None
+) -> str:
+    """Fetch the complete docstring of an OVITO Python API symbol.
+
+    Provide exactly one of:
+      - doc_string_id: the docstring's database id, if already known.
+      - symbol: the exact, fully-qualified symbol name, e.g.
+        "ovito.modifiers.SliceModifier" (the bare name "SliceModifier" will
+        NOT match — this is an exact-match lookup, not a search). Use this
+        when you already know the qualified name and want to skip a search
+        round-trip.
+
+    Args:
+        doc_string_id: The docstring's database id.
+        symbol: The exact fully-qualified symbol name.
+
+    Returns:
+        The full docstring text, or guidance if the lookup doesn't match anything
+        or both/neither argument was given.
+    """
+    if (doc_string_id is None) == (symbol is None):
+        return "Provide exactly one of doc_string_id or symbol."
+
+    def run(backend):
+        if symbol is not None:
+            return backend.get_docstring_by_symbol(symbol)
+        return backend.get_docstring(doc_string_id)
+
+    try:
+        doc = _call_rag(run)
+    except _RagError as exc:
+        return str(exc)
+    if doc is None:
+        which = (
+            f"symbol={symbol!r}"
+            if symbol is not None
+            else f"doc_string_id={doc_string_id}"
+        )
+        return f"No docstring found with {which}."
+    return doc["doc_string"]
+
+
+@mcp.tool()
+def get_kernel_id() -> str:
+    """Return the UUID of the currently active kernel."""
+    if _session.connection_file is None:
+        return "No active kernel."
+    return _id_from_path(_session.connection_file)
+
+
+@mcp.tool()
+def kernel_status() -> str:
+    """Report the active kernel: its id, ownership, and liveness."""
+    if _session.kc is None or _session.connection_file is None:
+        return "No active kernel. Call start_kernel() or connect_kernel()."
+    kid = _id_from_path(_session.connection_file)
+    if _session.km is not None:
+        owned, alive = "started by this server", _session.km.is_alive()
+    else:
+        owned, alive = "connected (externally owned)", _session.kc.is_alive()
+    return f"Active kernel: {kid}\nOwnership: {owned}\nAlive: {alive}"
+
+
+@mcp.tool()
+def interrupt_kernel() -> str:
+    """Interrupt the active kernel (e.g. to stop a long-running execution)."""
+    if _session.km is None:
+        if _session.kc is not None:
+            return (
+                "The active kernel was connected via connect_kernel and is owned "
+                "externally; interrupt it from the process that started it."
+            )
+        return "No active kernel."
+    _session.km.interrupt_kernel()
+    return f"Sent interrupt to kernel {_id_from_path(_session.km.connection_file)}."
+
+
+@mcp.tool()
+def restart_kernel() -> str:
+    """Restart the active kernel (clears all state)."""
+    if _session.km is None:
+        if _session.kc is not None:
+            return (
+                "The active kernel was connected via connect_kernel and is owned "
+                "externally; it cannot be restarted from here. Restart it from the "
+                "process that started it, then call connect_kernel again."
+            )
+        return "No active kernel."
+    _close_window_if_open()
+    _session.km.restart_kernel(now=True)
+    if _session.kc is not None:
+        _session.kc.stop_channels()
+    kc = _session.km.client()
+    kc.start_channels()
+    kc.wait_for_ready(timeout=60)
+    _session.kc = kc
+    return f"Restarted kernel {_id_from_path(_session.km.connection_file)}. All state cleared."
+
+
+@mcp.tool()
+def shutdown_kernel() -> str:
+    """Shut down the active kernel, or detach from an externally-connected one.
+
+    A kernel this server started is shut down. A kernel attached via connect_kernel is
+    owned externally, so it is left running and only this server's client is detached.
+    """
+    if _session.kc is None or _session.connection_file is None:
+        return "No active kernel."
+    kid = _id_from_path(_session.connection_file)
+    external = _session.km is None
+    _teardown_current()
+    if external:
+        return f"Detached from externally-owned kernel {kid} (left running)."
+    return f"Shut down kernel {kid}."