ovito-mcp 2026.1.dev3__tar.gz → 2026.1.dev4__tar.gz

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/.gitignore

@@ -222,12 +222,7 @@ poetry.toml
 pyrightconfig.json
 
 ### VisualStudioCode ###
-.vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
-!.vscode/*.code-snippets
+.vscode/
 
 # Local History for Visual Studio Code
 .history/

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ovito-mcp
-Version: 2026.1.dev3
+Version: 2026.1.dev4
 Summary: MCP server for interactive work in OVITO Pro
 Project-URL: Homepage, https://www.ovito.org
 Project-URL: Documentation, https://docs.ovito.org/reference/data_inspector/coding_agent.html

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/ovito_mcp/__init__.py

@@ -25,7 +25,7 @@ import uuid
 from pathlib import Path
 
 from jupyter_client.blocking.client import BlockingKernelClient
-from jupyter_client.kernelspec import NoSuchKernel
+from jupyter_client.kernelspec import KernelSpec, KernelSpecManager, NoSuchKernel
 from jupyter_client.manager import KernelManager
 from jupyter_core.paths import jupyter_runtime_dir
 from mcp.server.fastmcp import FastMCP, Image
@@ -101,7 +101,7 @@ def _require_active() -> BlockingKernelClient:
 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
+    The kernel is launched as ``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 ...``.
@@ -149,6 +149,37 @@ def _ensure_ipykernel_installed() -> str | None:
     return None
 
 
+def _ovito_kernel_spec() -> KernelSpec:
+    """Build the OVITO kernel spec in memory, without touching the filesystem.
+
+    OVITO Pro's desktop installers do not register an ``ovito-pro`` kernelspec with
+    Jupyter — only the conda package does — and we would overwrite its argv with
+    OVITO_EXE anyway, since a registered spec cannot know where the user installed
+    OVITO. Synthesizing the spec drops that filesystem dependency entirely, so
+    start_kernel() works for every OVITO Pro edition and install location.
+
+    Raises:
+        ValueError: If OVITO_EXE is not set.
+    """
+    if not OVITO_EXE:
+        raise ValueError(_MISSING_OVITO_EXE)
+    return KernelSpec(
+        name=KERNEL_NAME,
+        argv=[OVITO_EXE, "--kernel", "{connection_file}"],
+        display_name="Python 3 + OVITO Pro (GUI)",
+        language="python",
+    )
+
+
+class _OvitoKernelSpecManager(KernelSpecManager):
+    """Serves the synthesized OVITO spec instead of searching Jupyter's data dirs."""
+
+    def get_kernel_spec(self, kernel_name: str) -> KernelSpec:
+        if kernel_name != KERNEL_NAME:
+            raise NoSuchKernel(kernel_name)
+        return _ovito_kernel_spec()
+
+
 def _teardown_current() -> None:
     """Tear down the active session before starting or connecting to another kernel.
 
@@ -309,9 +340,10 @@ def start_kernel() -> str:
     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
+    If a kernel is already running it is shut down first. The launch command is built
+    directly from OVITO_EXE rather than looked up in Jupyter's data directories, so no
+    ``ovito-pro`` kernelspec needs to be registered on the machine and 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:
@@ -324,28 +356,19 @@ def start_kernel() -> str:
         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."
-        )
+    # Use ZMQ IPC transport (Unix-domain socket files) so kernel messaging stays
+    # local and does not open a network port.
+    km = KernelManager(
+        kernel_name=KERNEL_NAME,
+        kernel_spec_manager=_OvitoKernelSpecManager(),
+        transport="ipc",
+    )
 
     # 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()
@@ -663,61 +686,149 @@ def screenshot_window() -> list[str | Image]:
 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.
+    Use this to inspect the current program state — call it to discover what data
+    pipelines are in the user-visible scene (`ovito.scene.pipelines` list). Requires an
+    active kernel.
+
+    One record per pipeline, reporting:
+
+    - `key`: integer identifier to pass to list_modifiers(), inspect_pipeline_data(), and
+      other pipeline-specific tools. Valid only within the current kernel session — keys
+      change after restart_kernel(), so re-list rather than reusing an old key.
+    - `index`: position in `ovito.scene.pipelines`, matching the top-to-bottom order of the
+      GUI pipeline selector. Use it to resolve references like "the second pipeline".
+    - `title`: the display name shown in the GUI (`object_title`). For a file-based source
+      this already embeds the bare filename and the importer type, e.g.
+      `dump.lammpstrj [LAMMPS Dump]`, but not the directory.
+    - `source`: the data source type plus its full source path(s), which disambiguates
+      pipelines whose titles are identical because they load same-named files from
+      different directories.
+    - `modifiers`: how many modifiers the pipeline has and their type names, so a separate
+      list_modifiers() call is only needed when the individual modifier keys are wanted.
+    - `status`: the worst status over the pipeline's source and modifier nodes — the same
+      condition the GUI's warning/error triangles indicate. Call list_pipeline_status()
+      for the per-node detail behind a Warning or Error.
+
+    The pipeline currently selected in the GUI is flagged, which is usually the one a user
+    means by "this pipeline" or "the current pipeline".
 
     Returns:
-        A table of pipeline keys and names, or a message if the scene is empty.
+        One labeled record per pipeline, 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"
-    )
+    # Wrapped in a function so the iteration variables don't leak into the kernel
+    # namespace, where they would show up in the user's interactive session.
+    code = '''
+def _ovito_mcp_list_pipelines():
+    import ovito
+    from ovito.pipeline import ModificationNode
+
+    pipelines = list(ovito.scene.pipelines)
+    if not pipelines:
+        print("No pipelines in the scene.")
+        return
+    selected = ovito.scene.selected_pipeline
+    print(f"{len(pipelines)} pipeline(s) in the scene.")
+    print("Keys are valid for the current kernel session only.")
+    for index, pipeline in enumerate(pipelines):
+        # Worst status over the node chain, mirroring the GUI's triangle indicators.
+        status = "OK"
+        node = pipeline.head
+        while node is not None:
+            node_status = node.status.type.name
+            if node_status == "Error":
+                status = "Error"
+            elif node_status == "Warning" and status != "Error":
+                status = "Warning"
+            node = node.input if isinstance(node, ModificationNode) else None
+        if status != "OK":
+            status += "  (call list_pipeline_status() for details)"
+
+        # source_path is a str for a single file, a list for a multi-file sequence, and
+        # absent entirely for non-file sources such as StaticSource or PythonSource.
+        source = pipeline.source
+        source_desc = type(source).__name__
+        paths = getattr(source, "source_path", None)
+        if isinstance(paths, str):
+            paths = [paths] if paths else []
+        elif paths is None:
+            paths = []
+        else:
+            paths = list(paths)
+        if paths:
+            source_desc += " " + repr(paths[0])
+            if len(paths) > 1:
+                source_desc += f"  (+{len(paths) - 1} more file(s))"
+
+        modifiers = list(pipeline.modifiers)
+        if modifiers:
+            names = [type(m).__name__ for m in modifiers[:10]]
+            if len(modifiers) > 10:
+                names.append("...")
+            mod_desc = f"{len(modifiers)}  ({', '.join(names)})"
+        else:
+            mod_desc = "0"
+
+        marker = "   <- currently selected in the GUI" if pipeline is selected else ""
+        print(f"\\n[{index}] key={hash(pipeline)}{marker}")
+        print(f"      title:     {pipeline.object_title!r}")
+        print(f"      source:    {source_desc}")
+        print(f"      modifiers: {mod_desc}")
+        print(f"      status:    {status}")
+
+_ovito_mcp_list_pipelines()
+del _ovito_mcp_list_pipelines
+'''
     return execute(code)
 
 
 @mcp.tool()
-def list_modifiers(pipeline_key: str) -> str:
+def list_modifiers(pipeline_key: int) -> 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.
+    Use this to inspect a specific pipeline — call it to see which modifiers are
+    applied to a pipeline before modifying or reordering them, or to obtain a modifier's
+    key. list_pipelines() already reports each pipeline's modifier type names, so this
+    call is only needed when the individual keys or the enabled state matter.
+
+    Modifiers are listed in pipeline order, i.e. the order in which they are applied to
+    the data, which is bottom-to-top in the GUI pipeline editor.
 
     Args:
-        pipeline_key: The integer hash of the pipeline as returned by list_pipelines().
+        pipeline_key: The integer key 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.
+        One labeled record per modifier, 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"
-    )
+    # Wrapped in a function so the iteration variables don't leak into the kernel
+    # namespace. pipeline_key is typed int, so interpolating it into the source is safe.
+    code = f'''
+def _ovito_mcp_list_modifiers():
+    import ovito
+
+    target_key = {pipeline_key}
+    for pipeline in ovito.scene.pipelines:
+        if hash(pipeline) == target_key:
+            break
+    else:
+        print(f"Error: No pipeline with key {{target_key}} found. "
+              "Call list_pipelines() to see the available pipelines.")
+        return
+    modifiers = list(pipeline.modifiers)
+    if not modifiers:
+        print(f"Pipeline {{pipeline.object_title!r}} has no modifiers.")
+        return
+    print(f"{{len(modifiers)}} modifier(s) in pipeline {{pipeline.object_title!r}}, "
+          "in the order they are applied:")
+    print("Keys are valid for the current kernel session only.")
+    for index, modifier in enumerate(modifiers):
+        disabled = "   <- DISABLED, not applied to the data" if not modifier.enabled else ""
+        print(f"\\n[{{index}}] key={{hash(modifier)}}{{disabled}}")
+        print(f"      type:  {{type(modifier).__name__}}")
+        print(f"      title: {{modifier.object_title!r}}")
+
+_ovito_mcp_list_modifiers()
+del _ovito_mcp_list_modifiers
+'''
     return execute(code)
 
 
@@ -730,7 +841,7 @@ def inspect_pipeline_data(pipeline_key: int) -> str:
     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().
+        pipeline_key: The integer key of the pipeline as returned by list_pipelines().
 
     Returns:
         Markdown tables listing global attributes, data objects (with numeric IDs and
@@ -809,69 +920,132 @@ def list_pipeline_status() -> str:
     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).
+        A pretty-printed structure per pipeline, with `pipeline_key` and `pipeline_title`,
+        a `nodes` list, and a `visual_elements` list.
+
+        `nodes` holds the pipeline source followed by the modifiers in the order they are
+        applied — the same order list_modifiers() reports. Each entry has `node_type`,
+        `node_id`, `title`, `modifier_type`, `modifier_key`, `status_code`, `status_text`,
+        and `enabled`. Each visual element has `title`, `vis_element_type`,
+        `vis_element_id`, `status_code`, `status_text`, and `enabled`.
+
+        `pipeline_key` and `modifier_key` are the same keys list_pipelines() and
+        list_modifiers() report, and are accepted by the tools that take a key.
+        `node_id` and `vis_element_id` identify the internal pipeline node and the visual
+        element instead, are NOT interchangeable with those keys, and no tool accepts
+        them — they serve only to tell otherwise identical-looking entries apart.
     """
-    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"
-    )
+    # Wrapped in a function so the iteration variables don't leak into the kernel
+    # namespace, where they would show up in the user's interactive session.
+    code = '''
+def _ovito_mcp_list_pipeline_status():
+    import pprint
+    import ovito
+    from ovito.pipeline import ModificationNode
+
+    for pipeline in ovito.scene.pipelines:
+        pipeline_status = {
+            "pipeline_key": hash(pipeline),
+            "pipeline_title": pipeline.object_title,
+            "nodes": [],
+            "visual_elements": [],
+        }
+        node = pipeline.head
+        while node is not None:
+            is_modifier = isinstance(node, ModificationNode)
+            pipeline_status["nodes"].append(
+                {
+                    "node_type": type(node).__name__,
+                    "node_id": hash(node),
+                    "title": node.object_title,
+                    "modifier_type": type(node.modifier).__name__ if is_modifier else None,
+                    "modifier_key": hash(node.modifier) if is_modifier else None,
+                    "status_code": node.status.type.name,
+                    "status_text": node.status.text,
+                    "enabled": node.modifier.enabled if is_modifier else True,
+                }
+            )
+            node = node.input if is_modifier else None
+        # The chain is walked head-first, i.e. last modifier first. Reverse it so the
+        # source comes first and the modifiers follow in the order they are applied,
+        # matching list_modifiers() rather than contradicting it.
+        pipeline_status["nodes"].reverse()
+        for vis in pipeline.vis_elements:
+            pipeline_status["visual_elements"].append(
+                {
+                    "title": vis.object_title,
+                    "vis_element_type": type(vis).__name__,
+                    "vis_element_id": hash(vis),
+                    "status_code": vis.status.type.name,
+                    "status_text": vis.status.text,
+                    "enabled": vis.enabled,
+                }
+            )
+        pprint.pprint(pipeline_status, sort_dicts=False)
+
+_ovito_mcp_list_pipeline_status()
+del _ovito_mcp_list_pipeline_status
+'''
     return execute(code)
 
 
 @mcp.tool()
 def get_timeline_info() -> str:
-    """Return the current frame and frame range of the OVITO scene timeline.
+    """Return the state of the OVITO scene timeline and per-pipeline trajectory lengths.
+
+    Use this to inspect the current program state — call it to learn the animation extent,
+    which frame is currently active, and how many trajectory frames each pipeline actually
+    has, before iterating over frames or exporting an animation.
 
-    Use this to inspect the current program state — call it to learn the animation extent
-    and which frame is currently active.
+    Reports the animation interval (`first_frame`/`last_frame` of `ovito.scene.anim`), the
+    `current_frame`, `frames_per_second`, and `auto_adjust_interval`, followed by the
+    `num_frames` of every pipeline in the scene.
+
+    The animation interval is a scene-wide property, whereas `num_frames` is per pipeline,
+    and the two need not agree. While `auto_adjust_interval` is enabled the interval tracks
+    the longest pipeline automatically, but once it is disabled — or when pipelines of
+    differing length are in the scene — a pipeline can be shorter than the interval. Asking
+    such a pipeline for a frame beyond its own last one does not fail; it yields that
+    pipeline's final frame.
 
     Returns:
-        The current frame, first frame, and last frame as reported by ovito.scene.anim.
+        The timeline state, then one line per pipeline with its trajectory length, or a
+        note if the scene has no pipelines.
     """
-    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"
-    )
+    # Wrapped in a function so the iteration variables don't leak into the kernel
+    # namespace, where they would show up in the user's interactive session.
+    code = '''
+def _ovito_mcp_get_timeline_info():
+    import ovito
+
+    anim = ovito.scene.anim
+    first, last = anim.first_frame, anim.last_frame
+    print(f"current_frame:        {anim.current_frame}")
+    print(f"animation interval:   frames {first} to {last} ({last - first + 1} frame(s))")
+    print(f"frames_per_second:    {anim.frames_per_second}  (movie export and playback rate)")
+    print(f"auto_adjust_interval: {anim.auto_adjust_interval}"
+          + ("  (interval follows the longest pipeline automatically)"
+             if anim.auto_adjust_interval else "  (interval is set manually)"))
+
+    pipelines = list(ovito.scene.pipelines)
+    if not pipelines:
+        print("\\nNo pipelines in the scene, so the interval reflects no trajectory data.")
+        return
+    print("\\nTrajectory length per pipeline:")
+    for index, pipeline in enumerate(pipelines):
+        num_frames = pipeline.num_frames
+        note = ""
+        if num_frames == 1:
+            note = "   <- static, single frame"
+        elif num_frames - 1 < last:
+            note = (f"   <- ends at frame {num_frames - 1}, before the interval does; "
+                    f"frames {num_frames} to {last} repeat its last frame")
+        print(f"  [{index}] key={hash(pipeline)}  num_frames={num_frames}  "
+              f"{pipeline.object_title!r}{note}")
+
+_ovito_mcp_get_timeline_info()
+del _ovito_mcp_get_timeline_info
+'''
     return execute(code)
 
 
@@ -884,38 +1058,132 @@ def set_current_frame(frame: int) -> str:
     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.
 
+    The frame must lie within the animation interval reported by get_timeline_info(). A
+    frame outside it is rejected rather than applied: OVITO does not clamp `current_frame`
+    to the interval, so an out-of-range value would leave the time slider past the end of
+    the timeline while pipelines keep returning their last available frame — data that
+    looks valid but does not correspond to the requested frame. Use
+    set_animation_interval() first if the interval itself is meant to be longer.
+
     Args:
-        frame: The frame number to set as the current frame.
+        frame: The frame number to set as the current frame. Zero-based, and must be
+            within the current animation interval.
 
     Returns:
-        Confirmation of the new current frame.
+        Confirmation reporting the frame actually in effect, or an error naming the valid
+        range if the frame lies outside the animation interval.
     """
-    code = (
-        "import ovito\n"
-        f"ovito.scene.anim.current_frame = {frame}\n"
-        f"print(f'Current frame set to {frame}.')\n"
-    )
+    # Read the value back rather than echoing the requested frame, so the confirmation
+    # reflects what the scene actually holds.
+    code = f'''
+def _ovito_mcp_set_current_frame():
+    import ovito
+
+    anim = ovito.scene.anim
+    frame = {frame}
+    if frame < anim.first_frame or frame > anim.last_frame:
+        print(f"Error: Frame {{frame}} is outside the animation interval "
+              f"[{{anim.first_frame}}, {{anim.last_frame}}]. Current frame left unchanged "
+              f"at {{anim.current_frame}}. Call get_timeline_info() for the trajectory "
+              "lengths, or set_animation_interval() to extend the interval.")
+        return
+    anim.current_frame = frame
+    print(f"Current frame is now {{anim.current_frame}} "
+          f"(interval: {{anim.first_frame}} to {{anim.last_frame}}).")
+
+_ovito_mcp_set_current_frame()
+del _ovito_mcp_set_current_frame
+'''
     return execute(code)
 
 
-def _ovito_file_from_kernel() -> str | None:
-    """Ask an already-connected kernel for ``ovito.__file__``, or None if unavailable.
+@mcp.tool()
+def set_animation_interval(
+    first_frame: int | None = None,
+    last_frame: int | None = None,
+    auto_adjust: bool = False,
+) -> str:
+    """Set the OVITO scene's animation interval, or restore automatic adjustment of it.
 
-    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).
+    The animation interval is the frame range the timeline spans — what the GUI's
+    *Animation settings* dialog calls the *custom animation interval*. Use this tool rather
+    than assigning to `ovito.scene.anim.first_frame`/`last_frame` in execute(), because a
+    manually assigned interval is silently overwritten again while `auto_adjust_interval`
+    is enabled; this tool disables that option as part of setting a custom interval.
+
+    Normally the interval is adjusted automatically to span the longest trajectory in the
+    scene, and no call is needed. A custom interval is for animating over a dataset whose
+    length does not drive the timeline — most commonly a camera or turntable animation over
+    a static, single-frame dataset, where the interval must be extended manually to give
+    the animation somewhere to run.
+
+    Note that extending the interval past a pipeline's own `num_frames` does not create new
+    trajectory data: the pipeline keeps yielding its last frame for the added range.
+
+    Args:
+        first_frame: New first frame of the interval, or None to leave it unchanged.
+        last_frame: New last frame of the interval, or None to leave it unchanged.
+        auto_adjust: If True, re-enable automatic adjustment of the interval to the
+            trajectory data in the scene, discarding any custom interval. The
+            first_frame/last_frame arguments are then ignored, since OVITO recomputes both.
+
+    Returns:
+        The resulting animation interval, or an error if the requested range is invalid.
+    """
+    code = f'''
+def _ovito_mcp_set_animation_interval():
+    import ovito
+
+    anim = ovito.scene.anim
+    first, last = {first_frame!r}, {last_frame!r}
+    if {auto_adjust!r}:
+        anim.auto_adjust_interval = True
+        print(f"Automatic interval adjustment re-enabled. Animation interval is now "
+              f"{{anim.first_frame}} to {{anim.last_frame}}, current frame "
+              f"{{anim.current_frame}}.")
+        return
+    if first is None:
+        first = anim.first_frame
+    if last is None:
+        last = anim.last_frame
+    if first > last:
+        print(f"Error: first_frame ({{first}}) must not exceed last_frame ({{last}}). "
+              "Animation interval left unchanged.")
+        return
+    # Must be turned off first: while it is on, OVITO recomputes the interval from the
+    # scene's trajectories and the values assigned below would not survive.
+    anim.auto_adjust_interval = False
+    anim.first_frame = first
+    anim.last_frame = last
+    print(f"Animation interval set to {{anim.first_frame}} to {{anim.last_frame}} "
+          f"({{anim.last_frame - anim.first_frame + 1}} frame(s)). "
+          "Automatic adjustment is now disabled; call set_animation_interval("
+          "auto_adjust=True) to restore it.")
+    if anim.current_frame < anim.first_frame or anim.current_frame > anim.last_frame:
+        print(f"Note: current frame {{anim.current_frame}} now lies outside the interval. "
+              "Call set_current_frame() to move it back inside.")
+
+_ovito_mcp_set_animation_interval()
+del _ovito_mcp_set_animation_interval
+'''
+    return execute(code)
+
+
+def _kernel_stdout(code: str, timeout: float = 15.0) -> str | None:
+    """Run ``code`` in the connected kernel and return its captured stdout, or None.
+
+    Returns None when no kernel is connected, the kernel raises, or it doesn't go
+    idle within ``timeout``.
     """
     if _session.kc is None:
         return None
     kc = _session.kc
     try:
-        msg_id = kc.execute("import ovito; print(ovito.__file__)")
+        msg_id = kc.execute(code)
         stdout: list[str] = []
         while True:
             try:
-                msg = kc.get_iopub_msg(timeout=15.0)
+                msg = kc.get_iopub_msg(timeout=timeout)
             except queue.Empty:
                 return None
             if msg.get("parent_header", {}).get("msg_id") != msg_id:
@@ -934,6 +1202,47 @@ def _ovito_file_from_kernel() -> str | None:
     return text or None
 
 
+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).
+    """
+    return _kernel_stdout("import ovito; print(ovito.__file__)")
+
+
+def _ovito_version_from_kernel() -> str | None:
+    """Ask an already-connected kernel for ``ovito.version_string``, or None.
+
+    Used only to enrich user-facing messages (e.g. a database-incompatibility
+    error) with the connected OVITO Pro version; never required for correctness.
+    """
+    out = _kernel_stdout("import ovito; print(ovito.version_string)")
+    return out.splitlines()[-1].strip() if out else None
+
+
+def _version_context() -> str:
+    """A short ' (Detected: OVITO Pro X, ovito-mcp Y.)' suffix for error messages.
+
+    Best-effort: omits either component it cannot determine so the caller can
+    append it unconditionally.
+    """
+    parts: list[str] = []
+    ovito_version = _ovito_version_from_kernel()
+    if ovito_version:
+        parts.append(f"OVITO Pro {ovito_version}")
+    try:
+        from importlib.metadata import version as _pkg_version
+
+        parts.append(f"ovito-mcp {_pkg_version('ovito-mcp')}")
+    except Exception:  # noqa: BLE001 - version context is purely informational
+        pass
+    return f" (Detected: {', '.join(parts)}.)" if parts else ""
+
+
 def _ovito_file_from_subprocess() -> str | None:
     """Run a one-off ``import ovito; print(ovito.__file__)`` under OVITO_EXE.
 
@@ -1016,6 +1325,9 @@ def _call_rag(fn):
     try:
         with contextlib.redirect_stdout(sys.stderr):
             return fn(_docs_index())
+    except rag.db.IncompatibleDatabaseError as exc:
+        # Append the detected product versions so the user knows what they have.
+        raise _RagError(f"{exc}{_version_context()}") from exc
     except (ValueError, RuntimeError) as exc:
         # Raised for a missing/undiscoverable database or an empty index.
         raise _RagError(str(exc)) from exc

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/ovito_mcp/rag/__init__.py

@@ -28,6 +28,14 @@ class DocsIndex:
         if not resolved.exists():
             raise ValueError(f"SQLite RAG database {resolved} does not exist.")
         self._db_path = str(resolved)
+        # Reject an incompatible database once, up front, with a clear message —
+        # before any search runs — rather than letting a schema/embedding-model
+        # mismatch surface later as an empty result or a garbage similarity score.
+        conn = ragdb.connect(self._db_path)
+        try:
+            ragdb.check_compatibility(conn)
+        finally:
+            conn.close()
         self._chunk_matrix: ragdb.Matrix | None = None
         self._symbol_matrix: ragdb.Matrix | None = None
         self._summary_matrix: dict[str, ragdb.Matrix] = {}

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/ovito_mcp/rag/db.py

@@ -91,6 +91,23 @@ os.environ.setdefault("HF_HUB_ETAG_TIMEOUT", "5")
 EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
 EMBED_DIM = 384
 
+# ── RAG database format compatibility ─────────────────────────────────────────
+# The RAG database (rag.sqlite3) is produced by OVITO Pro and read here; the two
+# components are released independently. OVITO Pro stamps the database with a
+# single integer format version (rag_meta.schema_version, mirrored into
+# PRAGMA user_version); this server accepts a database whose version lies in the
+# inclusive range below, and otherwise refuses it with a directional
+# "update OVITO Pro" / "update ovito-mcp" message.
+#
+# RAG_SCHEMA_VERSION      - the format this build natively targets.
+# MIN_READABLE_..         - oldest database format this build can still read.
+# MAX_READABLE_..         - newest database format this build understands.
+# Raise MAX_READABLE_SCHEMA_VERSION (and, for a non-backward-compatible change,
+# MIN_READABLE_SCHEMA_VERSION) whenever OVITO Pro bumps its RAG_SCHEMA_VERSION.
+RAG_SCHEMA_VERSION = 1
+MIN_READABLE_SCHEMA_VERSION = 1
+MAX_READABLE_SCHEMA_VERSION = 1
+
 # Cross-encoder used to re-rank the bi-encoder candidate pool (stage 2).
 RERANK_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
 # How many candidates semantic_search retrieves before re-ranking. Tunable:
@@ -99,6 +116,11 @@ RERANK_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
 RERANK_CANDIDATES = 25
 
 SCHEMA = """
+CREATE TABLE IF NOT EXISTS rag_meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
 CREATE TABLE IF NOT EXISTS manual_pages (
     full_page_id     INTEGER PRIMARY KEY AUTOINCREMENT,
     full_manual_page TEXT NOT NULL,
@@ -158,15 +180,113 @@ CREATE INDEX IF NOT EXISTS idx_anchors_full_page_id ON anchors(full_page_id);
 # ── Connection / schema ───────────────────────────────────────────────────────
 
 
+class IncompatibleDatabaseError(RuntimeError):
+    """Raised when the RAG database's format is not compatible with this server.
+
+    A RuntimeError subclass (like ModelsUnavailableError) so _call_rag() surfaces
+    its already-user-facing message verbatim to the agent, and so an incompatible
+    database disables only the documentation-search tools while every other MCP
+    tool keeps working.
+    """
+
+
 def connect(db_path: str | Path) -> sqlite3.Connection:
-    """Open the RAG database, creating the schema on first use."""
-    conn = sqlite3.connect(str(db_path))
+    """Open the RAG database read-only.
+
+    This is a pure reader: OVITO Pro produces the database, we only query it.
+    Opening read-only (and never running the schema DDL) guarantees we cannot
+    mutate a database — in particular we never silently create empty tables when
+    pointed at a foreign, empty, or future-format file, which would mask a real
+    incompatibility. The SCHEMA constant above is retained only as documentation
+    of the format this server expects. Compatibility is validated once up front
+    via check_compatibility() (see DocsIndex.__init__).
+    """
+    uri = f"{Path(db_path).resolve().as_uri()}?mode=ro"
+    conn = sqlite3.connect(uri, uri=True)
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA foreign_keys = ON")
-    conn.executescript(SCHEMA)
     return conn
 
 
+def read_db_meta(conn: sqlite3.Connection) -> dict[str, str]:
+    """Return the rag_meta key/value pairs as a dict (empty if the table is absent)."""
+    has_table = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'rag_meta'"
+    ).fetchone()
+    if has_table is None:
+        return {}
+    return {r["key"]: r["value"] for r in conn.execute("SELECT key, value FROM rag_meta")}
+
+
+def read_schema_version(conn: sqlite3.Connection) -> int | None:
+    """Return the database's stamped format version, or None if unstamped.
+
+    Prefers rag_meta.schema_version; falls back to PRAGMA user_version. A value of
+    0 / absent both mean "no marker" and are reported as None so the caller can
+    reject a foreign or pre-versioning database rather than defaulting it.
+    """
+    meta = read_db_meta(conn)
+    raw = meta.get("schema_version")
+    if raw is not None:
+        try:
+            return int(raw)
+        except ValueError:
+            return None
+    user_version = conn.execute("PRAGMA user_version").fetchone()[0]
+    return int(user_version) if user_version else None
+
+
+def check_compatibility(conn: sqlite3.Connection) -> None:
+    """Validate the open database's format against this server's supported range.
+
+    Raises IncompatibleDatabaseError with a directional, user-facing message when
+    the database is unstamped (foreign/corrupt/pre-versioning) or its version is
+    outside [MIN_READABLE_SCHEMA_VERSION, MAX_READABLE_SCHEMA_VERSION]. Also
+    asserts the embedding model/dimensionality match, catching a "same schema,
+    different vectors" mismatch that the version integer alone might miss.
+    """
+    version = read_schema_version(conn)
+    if version is None:
+        raise IncompatibleDatabaseError(
+            "This does not look like an OVITO documentation database, or it was "
+            "produced by an OVITO Pro version too old to carry a format marker. "
+            "Documentation search is unavailable. Update OVITO Pro to a version "
+            "that ships a versioned RAG database."
+        )
+    if version > MAX_READABLE_SCHEMA_VERSION:
+        raise IncompatibleDatabaseError(
+            f"The OVITO documentation database uses format version {version}, which "
+            f"is newer than this ovito-mcp server understands (it supports up to "
+            f"format version {MAX_READABLE_SCHEMA_VERSION}). Documentation search is "
+            f"unavailable. Update the ovito-mcp server to match your OVITO Pro "
+            f"installation."
+        )
+    if version < MIN_READABLE_SCHEMA_VERSION:
+        raise IncompatibleDatabaseError(
+            f"The OVITO documentation database uses format version {version}, which "
+            f"is older than this ovito-mcp server supports (it requires at least "
+            f"format version {MIN_READABLE_SCHEMA_VERSION}). Documentation search is "
+            f"unavailable. Update OVITO Pro to match your ovito-mcp server."
+        )
+    meta = read_db_meta(conn)
+    db_model = meta.get("embedding_model")
+    if db_model is not None and db_model != EMBED_MODEL:
+        raise IncompatibleDatabaseError(
+            f"The OVITO documentation database was built with embedding model "
+            f"'{db_model}', but this ovito-mcp server searches with '{EMBED_MODEL}'. "
+            f"Documentation search is unavailable. Update the ovito-mcp server or "
+            f"OVITO Pro so both use the same embedding model."
+        )
+    db_dim = meta.get("embedding_dim")
+    if db_dim is not None and db_dim != str(EMBED_DIM):
+        raise IncompatibleDatabaseError(
+            f"The OVITO documentation database stores {db_dim}-dimensional "
+            f"embeddings, but this ovito-mcp server expects {EMBED_DIM}. "
+            f"Documentation search is unavailable. Update the ovito-mcp server or "
+            f"OVITO Pro so both agree on the embedding dimensionality."
+        )
+
+
 # ── Embedding ──────────────────────────────────────────────────────────────────
 
 

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ovito-mcp"
-version = "2026.1.dev3"
+version = "2026.1.dev4"
 description = "MCP server for interactive work in OVITO Pro"
 readme = "README.md"
 requires-python = ">=3.10"

ovito_mcp-2026.1.dev4/tests/conftest.py

@@ -0,0 +1,65 @@
+"""Shared test fixtures for the ovito_mcp test suite.
+
+The production ``db.connect()`` opens the RAG database read-only and never
+creates the schema — OVITO Pro is the sole producer. Tests therefore need their
+own writable builder to construct fixture databases, which is what
+``make_rag_db`` provides. It also lets a test stamp an arbitrary format version /
+embedding model to exercise the compatibility checks (see test_rag_db.py).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from ovito_mcp.rag import db
+
+
+def build_rag_db(
+    path: str | Path,
+    *,
+    schema_version: int | None = None,
+    embedding_model: str | None = None,
+    embedding_dim: int | None = None,
+    stamp: bool = True,
+) -> sqlite3.Connection:
+    """Create a writable RAG database with the schema and (optionally) the marker.
+
+    Returns an open writable connection. With ``stamp=True`` (the default) the
+    compatibility marker is written using the current constants unless overridden;
+    pass ``stamp=False`` to simulate an unstamped (foreign / pre-versioning)
+    database, or override ``schema_version`` / ``embedding_*`` to simulate an
+    incompatible one.
+    """
+    if schema_version is None:
+        schema_version = db.RAG_SCHEMA_VERSION
+    if embedding_model is None:
+        embedding_model = db.EMBED_MODEL
+    if embedding_dim is None:
+        embedding_dim = db.EMBED_DIM
+
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.executescript(db.SCHEMA)
+    if stamp:
+        conn.execute(f"PRAGMA user_version = {int(schema_version)}")
+        conn.executemany(
+            "INSERT INTO rag_meta (key, value) VALUES (?, ?) "
+            "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            [
+                ("schema_version", str(schema_version)),
+                ("embedding_model", embedding_model),
+                ("embedding_dim", str(embedding_dim)),
+            ],
+        )
+    conn.commit()
+    return conn
+
+
+@pytest.fixture
+def make_rag_db():
+    """Factory fixture returning build_rag_db (see its docstring)."""
+    return build_rag_db

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/tests/test_docs_index.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import numpy as np
 import pytest
 
+from conftest import build_rag_db
 from ovito_mcp import rag
 from ovito_mcp.rag import db
 
@@ -28,7 +29,7 @@ def stub_cross_encoder(monkeypatch):
 @pytest.fixture
 def db_path(tmp_path):
     path = tmp_path / "rag.sqlite3"
-    conn = db.connect(path)
+    conn = build_rag_db(path)
     try:
         page_id = conn.execute(
             "INSERT INTO manual_pages (full_manual_page) VALUES (?)",
@@ -95,6 +96,21 @@ def test_docs_index_rejects_missing_db_path(tmp_path):
         rag.DocsIndex(tmp_path / "does-not-exist.sqlite3")
 
 
+def test_docs_index_rejects_incompatible_db_at_construction(tmp_path):
+    """An incompatible database is rejected up front, before any search runs."""
+    path = tmp_path / "rag.sqlite3"
+    build_rag_db(path, schema_version=db.MAX_READABLE_SCHEMA_VERSION + 1).close()
+    with pytest.raises(db.IncompatibleDatabaseError, match="newer than this ovito-mcp"):
+        rag.DocsIndex(path)
+
+
+def test_docs_index_rejects_unstamped_db_at_construction(tmp_path):
+    path = tmp_path / "rag.sqlite3"
+    build_rag_db(path, stamp=False).close()
+    with pytest.raises(db.IncompatibleDatabaseError, match="does not look like an OVITO"):
+        rag.DocsIndex(path)
+
+
 def test_search_docs_caches_embedding_matrix_across_calls(db_path, monkeypatch):
     monkeypatch.setattr(db, "embed_one", lambda text: np.array([1, 0], dtype=np.float32))
 

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/tests/test_docs_index_discovery.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import pytest
 
 import ovito_mcp
+from conftest import build_rag_db
 
 
 @pytest.fixture(autouse=True)
@@ -23,9 +24,8 @@ def clear_index_cache(monkeypatch):
 def test_failed_discovery_is_not_cached(monkeypatch, tmp_path):
     """A failure before a kernel exists must not disable the doc tools for good."""
     db_file = tmp_path / "rag.sqlite3"
-    from ovito_mcp.rag import db as ragdb
 
-    ragdb.connect(db_file).close()  # create an (empty but valid) database
+    build_rag_db(db_file).close()  # create an empty but valid, stamped database
 
     attempts = []
 
@@ -51,9 +51,8 @@ def test_failed_discovery_is_not_cached(monkeypatch, tmp_path):
 
 def test_rag_db_env_override_wins_over_discovery(monkeypatch, tmp_path):
     db_file = tmp_path / "custom.sqlite3"
-    from ovito_mcp.rag import db as ragdb
 
-    ragdb.connect(db_file).close()
+    build_rag_db(db_file).close()
 
     monkeypatch.setattr(ovito_mcp, "RAG_DB", str(db_file))
     monkeypatch.setattr(

ovito_mcp-2026.1.dev4/tests/test_kernel_spec.py

@@ -0,0 +1,59 @@
+"""Tests for the synthesized OVITO kernel spec.
+
+start_kernel() must not depend on an ``ovito-pro`` kernelspec being registered in
+any Jupyter data directory: OVITO Pro's desktop installers never register one, and
+the launch command has to point at whatever OVITO_EXE says anyway. These tests pin
+that down without launching OVITO — they only exercise the spec plumbing.
+"""
+
+from __future__ import annotations
+
+import pytest
+from jupyter_client.kernelspec import NoSuchKernel
+from jupyter_client.manager import KernelManager
+
+import ovito_mcp
+
+DUMMY_EXE = "/nonexistent/Ovito.app/Contents/MacOS/ovito"
+
+
+@pytest.fixture
+def ovito_exe(monkeypatch: pytest.MonkeyPatch) -> str:
+    """Point the module-level OVITO_EXE at a path that need not exist."""
+    monkeypatch.setattr(ovito_mcp, "OVITO_EXE", DUMMY_EXE)
+    return DUMMY_EXE
+
+
+def test_spec_launches_ovito_exe(ovito_exe: str) -> None:
+    spec = ovito_mcp._OvitoKernelSpecManager().get_kernel_spec(ovito_mcp.KERNEL_NAME)
+    assert spec.argv == [ovito_exe, "--kernel", "{connection_file}"]
+    assert spec.language == "python"
+
+
+def test_unknown_kernel_name_rejected(ovito_exe: str) -> None:
+    with pytest.raises(NoSuchKernel):
+        ovito_mcp._OvitoKernelSpecManager().get_kernel_spec("something-else")
+
+
+def test_kernel_manager_resolves_spec_without_filesystem(ovito_exe: str) -> None:
+    """KernelManager must obtain the spec from us, not from Jupyter's data dirs.
+
+    This is the regression guard for the actual bug, and it holds either way round:
+    on a machine with no 'ovito-pro' kernelspec a filesystem lookup would raise
+    NoSuchKernel, and on a machine that happens to have a stale one registered the
+    lookup would yield its argv (a bare 'ovito') instead of DUMMY_EXE. Only the
+    injected manager satisfies the assertion below.
+    """
+    km = KernelManager(
+        kernel_name=ovito_mcp.KERNEL_NAME,
+        kernel_spec_manager=ovito_mcp._OvitoKernelSpecManager(),
+        transport="ipc",
+    )
+    assert km.kernel_spec is not None
+    assert km.kernel_spec.argv == [ovito_exe, "--kernel", "{connection_file}"]
+
+
+def test_missing_ovito_exe_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(ovito_mcp, "OVITO_EXE", None)
+    with pytest.raises(ValueError):
+        ovito_mcp._ovito_kernel_spec()

{ovito_mcp-2026.1.dev3 → ovito_mcp-2026.1.dev4}/tests/test_rag_db.py

@@ -6,9 +6,12 @@ load the real sentence-transformers model.
 
 from __future__ import annotations
 
+import sqlite3
+
 import numpy as np
 import pytest
 
+from conftest import build_rag_db
 from ovito_mcp.rag import db
 
 
@@ -37,7 +40,7 @@ def stub_cross_encoder(monkeypatch):
 
 @pytest.fixture
 def conn(tmp_path):
-    c = db.connect(tmp_path / "rag.sqlite3")
+    c = build_rag_db(tmp_path / "rag.sqlite3")
     yield c
     c.close()
 
@@ -174,3 +177,88 @@ def test_stats_counts_rows(conn):
     assert counts["python_symbols"] == 1
     assert counts["python_docstrings"] == 0
     assert counts["summaries"] == 0
+
+
+# ── Format-compatibility marker ────────────────────────────────────────────────
+
+
+def test_read_meta_and_schema_version_roundtrip(conn):
+    meta = db.read_db_meta(conn)
+    assert meta["schema_version"] == str(db.RAG_SCHEMA_VERSION)
+    assert meta["embedding_model"] == db.EMBED_MODEL
+    assert meta["embedding_dim"] == str(db.EMBED_DIM)
+    assert db.read_schema_version(conn) == db.RAG_SCHEMA_VERSION
+
+
+def test_read_schema_version_falls_back_to_user_version(tmp_path):
+    conn = build_rag_db(tmp_path / "rag.sqlite3", stamp=False)
+    try:
+        assert db.read_schema_version(conn) is None  # no marker at all
+        conn.execute("PRAGMA user_version = 1")
+        assert db.read_schema_version(conn) == 1
+    finally:
+        conn.close()
+
+
+def test_check_compatibility_accepts_current(conn):
+    db.check_compatibility(conn)  # must not raise
+
+
+def test_check_compatibility_rejects_unstamped(tmp_path):
+    conn = build_rag_db(tmp_path / "rag.sqlite3", stamp=False)
+    try:
+        with pytest.raises(db.IncompatibleDatabaseError, match="does not look like an OVITO"):
+            db.check_compatibility(conn)
+    finally:
+        conn.close()
+
+
+def test_check_compatibility_rejects_too_new(tmp_path):
+    conn = build_rag_db(
+        tmp_path / "rag.sqlite3", schema_version=db.MAX_READABLE_SCHEMA_VERSION + 1
+    )
+    try:
+        with pytest.raises(db.IncompatibleDatabaseError, match="newer than this ovito-mcp"):
+            db.check_compatibility(conn)
+    finally:
+        conn.close()
+
+
+def test_check_compatibility_rejects_too_old(tmp_path, monkeypatch):
+    monkeypatch.setattr(db, "MIN_READABLE_SCHEMA_VERSION", db.RAG_SCHEMA_VERSION + 1)
+    monkeypatch.setattr(db, "MAX_READABLE_SCHEMA_VERSION", db.RAG_SCHEMA_VERSION + 1)
+    conn = build_rag_db(tmp_path / "rag.sqlite3", schema_version=db.RAG_SCHEMA_VERSION)
+    try:
+        with pytest.raises(db.IncompatibleDatabaseError, match="older than this ovito-mcp"):
+            db.check_compatibility(conn)
+    finally:
+        conn.close()
+
+
+def test_check_compatibility_rejects_wrong_embedding_model(tmp_path):
+    conn = build_rag_db(tmp_path / "rag.sqlite3", embedding_model="some/other-model")
+    try:
+        with pytest.raises(db.IncompatibleDatabaseError, match="embedding model"):
+            db.check_compatibility(conn)
+    finally:
+        conn.close()
+
+
+def test_check_compatibility_rejects_wrong_embedding_dim(tmp_path):
+    conn = build_rag_db(tmp_path / "rag.sqlite3", embedding_dim=128)
+    try:
+        with pytest.raises(db.IncompatibleDatabaseError, match="dimensional"):
+            db.check_compatibility(conn)
+    finally:
+        conn.close()
+
+
+def test_connect_opens_read_only(conn, tmp_path):
+    # A production connect() must refuse writes even to a valid database.
+    conn.close()
+    ro = db.connect(tmp_path / "rag.sqlite3")
+    try:
+        with pytest.raises(sqlite3.OperationalError):
+            ro.execute("INSERT INTO rag_meta (key, value) VALUES ('x', 'y')")
+    finally:
+        ro.close()