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

ovito_mcp-2026.1.dev3/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: ovito-mcp
+Version: 2026.1.dev3
+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
+Project-URL: Repository, https://gitlab.com/ovito-org/ovito-mcp-server
+Project-URL: Bug Tracker, https://gitlab.com/ovito-org/ovito-mcp-server/-/issues
+Author-email: OVITO GmbH <support@ovito.org>
+License: Proprietary
+License-File: LICENSE
+Keywords: mcp,molecular-dynamics,ovito,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: jupyter-client>=8.0
+Requires-Dist: jupyter-core>=5.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: sentence-transformers>=5.6.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# OVITO Pro MCP Server
+
+Connects an AI coding agent to a running **OVITO Pro** session, so you can work with your
+simulation data by describing what you want in plain language. The agent operates inside
+the session you already have open — it can load files, build and adjust pipelines, analyze
+results, and look things up in the OVITO documentation, while you watch each step happen
+live in the GUI and keep working in the same window yourself.
+
+Works with Claude Code, GitHub Copilot CLI, OpenAI Codex, OpenCode, Google Antigravity, and
+other coding agents that support MCP.
+
+## Requirements
+
+- **OVITO Pro 3.16 or later**, with a valid license
+- **Python 3.10 or later**
+- A supported coding agent, installed and set up separately (see
+  [Agent configuration](#agent-configuration))
+
+## Installation
+
+Install the server:
+
+```sh
+pip install ovito-mcp
+```
+
+Verify the installation and check the version with:
+
+```sh
+ovito-mcp --version
+```
+
+The documentation-search tools provided by the OVITO MCP server use two small sentence-transformers models that are downloaded
+once from the Hugging Face Hub (~180 MB total) and cached locally. The server downloads them
+automatically in the background the first time it starts, and never touches the network for
+them again. If you would rather do this one-time download up front — recommended on a slow or
+restricted network, so it can't slow down the first search — run:
+
+```sh
+ovito-mcp --download-models
+```
+
+Then register it with your coding agent, using the **absolute path** to the `ovito-mcp` console
+script. For Claude Code:
+
+```powershell
+# Windows (PowerShell)
+claude mcp add ovito-mcp --scope user -- (Get-Command ovito-mcp).Source
+```
+
+```sh
+# macOS / Linux
+claude mcp add ovito-mcp --scope user -- "$(which ovito-mcp)"
+```
+
+See [Agent configuration](#agent-configuration) below for the other agents.
+
+## Using it
+
+In OVITO Pro, open the
+[**AI Agent**](https://docs.ovito.org/reference/data_inspector/coding_agent.html) tab in
+the data inspector panel at the bottom of the main window, pick your coding agent, and
+press **Start**.
+
+OVITO launches the agent and connects it to the session in front of you. Anything the agent
+does appears live in the GUI, and you can keep interacting with the same scene while it
+works.
+
+No further setup is needed — the agent finds everything it needs from the running OVITO Pro
+session.
+
+See the [AI Agent manual page](https://docs.ovito.org/reference/data_inspector/coding_agent.html)
+for the OVITO-side documentation, including security considerations.
+
+## Agent configuration
+
+Register `ovito-mcp` by its **absolute path** in the configurations below. Find that path with:
+
+```powershell
+# Windows (PowerShell)
+(Get-Command ovito-mcp).Source
+```
+
+```sh
+# macOS / Linux
+which ovito-mcp
+```
+
+and substitute it for `/path/to/ovito-mcp` in the snippets below.
+
+### Claude Code / Claude Desktop
+
+Add this to your `~/.claude.json`:
+
+```json
+"mcpServers": {
+  "ovito-mcp": {
+    "type": "stdio",
+    "command": "/path/to/ovito-mcp"
+  }
+}
+```
+
+### OpenCode
+
+Add this to your `~/.opencode.json`:
+
+```json
+"mcp": {
+  "ovito-mcp": {
+    "type": "local",
+    "command": ["/path/to/ovito-mcp"],
+    "enabled": true
+  }
+}
+```
+
+### Google Antigravity
+
+Add this to your `~/.antigravity/config.json`:
+
+```json
+"mcpServers": {
+  "ovito-mcp": {
+    "command": "/path/to/ovito-mcp"
+  }
+}
+```
+
+### OpenAI Codex
+
+Add this to your `$HOME/.codex/config.toml`:
+
+```toml
+[mcp_servers.ovito-mcp]
+command = "/path/to/ovito-mcp"
+```
+
+### GitHub Copilot
+
+Add this to your `~/.copilot/mcp-config.json`:
+
+```json
+"mcpServers": {
+  "ovito-mcp": {
+    "command": "/path/to/ovito-mcp"
+  }
+}
+```
+
+## Advanced configuration
+
+Neither setting below is needed for normal use. Both are environment variables, intended
+for development and unusual setups.
+
+| Env var        | Purpose                                                                                                                                                                                                       |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OVITO_EXE`    | Path to the OVITO Pro executable (`ovito.exe` on Windows, `ovito` on Linux, `Ovito.app/Contents/MacOS/ovito` on macOS). Only needed to let the agent start OVITO Pro itself, instead of connecting to a session you already have running. |
+| `OVITO_RAG_DB` | Path to an alternative documentation database. Overrides the one that ships with OVITO Pro, for developing against a custom build.                                                                            |
+
+## Support
+
+Questions and bug reports: <support@ovito.org>

ovito_mcp-2026.1.dev3/README.md

@@ -0,0 +1,163 @@
+# OVITO Pro MCP Server
+
+Connects an AI coding agent to a running **OVITO Pro** session, so you can work with your
+simulation data by describing what you want in plain language. The agent operates inside
+the session you already have open — it can load files, build and adjust pipelines, analyze
+results, and look things up in the OVITO documentation, while you watch each step happen
+live in the GUI and keep working in the same window yourself.
+
+Works with Claude Code, GitHub Copilot CLI, OpenAI Codex, OpenCode, Google Antigravity, and
+other coding agents that support MCP.
+
+## Requirements
+
+- **OVITO Pro 3.16 or later**, with a valid license
+- **Python 3.10 or later**
+- A supported coding agent, installed and set up separately (see
+  [Agent configuration](#agent-configuration))
+
+## Installation
+
+Install the server:
+
+```sh
+pip install ovito-mcp
+```
+
+Verify the installation and check the version with:
+
+```sh
+ovito-mcp --version
+```
+
+The documentation-search tools provided by the OVITO MCP server use two small sentence-transformers models that are downloaded
+once from the Hugging Face Hub (~180 MB total) and cached locally. The server downloads them
+automatically in the background the first time it starts, and never touches the network for
+them again. If you would rather do this one-time download up front — recommended on a slow or
+restricted network, so it can't slow down the first search — run:
+
+```sh
+ovito-mcp --download-models
+```
+
+Then register it with your coding agent, using the **absolute path** to the `ovito-mcp` console
+script. For Claude Code:
+
+```powershell
+# Windows (PowerShell)
+claude mcp add ovito-mcp --scope user -- (Get-Command ovito-mcp).Source
+```
+
+```sh
+# macOS / Linux
+claude mcp add ovito-mcp --scope user -- "$(which ovito-mcp)"
+```
+
+See [Agent configuration](#agent-configuration) below for the other agents.
+
+## Using it
+
+In OVITO Pro, open the
+[**AI Agent**](https://docs.ovito.org/reference/data_inspector/coding_agent.html) tab in
+the data inspector panel at the bottom of the main window, pick your coding agent, and
+press **Start**.
+
+OVITO launches the agent and connects it to the session in front of you. Anything the agent
+does appears live in the GUI, and you can keep interacting with the same scene while it
+works.
+
+No further setup is needed — the agent finds everything it needs from the running OVITO Pro
+session.
+
+See the [AI Agent manual page](https://docs.ovito.org/reference/data_inspector/coding_agent.html)
+for the OVITO-side documentation, including security considerations.
+
+## Agent configuration
+
+Register `ovito-mcp` by its **absolute path** in the configurations below. Find that path with:
+
+```powershell
+# Windows (PowerShell)
+(Get-Command ovito-mcp).Source
+```
+
+```sh
+# macOS / Linux
+which ovito-mcp
+```
+
+and substitute it for `/path/to/ovito-mcp` in the snippets below.
+
+### Claude Code / Claude Desktop
+
+Add this to your `~/.claude.json`:
+
+```json
+"mcpServers": {
+  "ovito-mcp": {
+    "type": "stdio",
+    "command": "/path/to/ovito-mcp"
+  }
+}
+```
+
+### OpenCode
+
+Add this to your `~/.opencode.json`:
+
+```json
+"mcp": {
+  "ovito-mcp": {
+    "type": "local",
+    "command": ["/path/to/ovito-mcp"],
+    "enabled": true
+  }
+}
+```
+
+### Google Antigravity
+
+Add this to your `~/.antigravity/config.json`:
+
+```json
+"mcpServers": {
+  "ovito-mcp": {
+    "command": "/path/to/ovito-mcp"
+  }
+}
+```
+
+### OpenAI Codex
+
+Add this to your `$HOME/.codex/config.toml`:
+
+```toml
+[mcp_servers.ovito-mcp]
+command = "/path/to/ovito-mcp"
+```
+
+### GitHub Copilot
+
+Add this to your `~/.copilot/mcp-config.json`:
+
+```json
+"mcpServers": {
+  "ovito-mcp": {
+    "command": "/path/to/ovito-mcp"
+  }
+}
+```
+
+## Advanced configuration
+
+Neither setting below is needed for normal use. Both are environment variables, intended
+for development and unusual setups.
+
+| Env var        | Purpose                                                                                                                                                                                                       |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OVITO_EXE`    | Path to the OVITO Pro executable (`ovito.exe` on Windows, `ovito` on Linux, `Ovito.app/Contents/MacOS/ovito` on macOS). Only needed to let the agent start OVITO Pro itself, instead of connecting to a session you already have running. |
+| `OVITO_RAG_DB` | Path to an alternative documentation database. Overrides the one that ships with OVITO Pro, for developing against a custom build.                                                                            |
+
+## Support
+
+Questions and bug reports: <support@ovito.org>

{ovito_mcp-2026.1.dev2 → ovito_mcp-2026.1.dev3}/RELEASING.md

@@ -60,15 +60,19 @@ PEP 440 pre-release — a dev release (`2026.1.dev1`), alpha (`2026.1a1`), beta
 (`2026.1b1`), or release candidate (`2026.1rc1`). The procedure is identical to above;
 the tag pattern in `.gitlab-ci.yml` already matches these.
 
-Pre-releases are **invisible to ordinary installs**: `pip install ovito-mcp` ignores
-them. Installing one is explicit:
+Once at least one stable version exists, pre-releases are skipped by an ordinary
+`pip install ovito-mcp`, and reaching one is explicit:
 
 ```sh
 pip install --pre ovito-mcp          # newest, including pre-releases
-pip install ovito-mcp==2026.1.dev1   # or pin it exactly
+pip install ovito-mcp==2026.1.dev2   # or pin it exactly
 ```
 
-So `2026.1.dev1` can be published while `2026.1` stays unreleased and unaffected.
+**Caveat while no stable release exists.** pip falls back to pre-releases when a project
+has *no* stable version to choose from, so until `2026.1` is published, a plain
+`pip install ovito-mcp` resolves to the newest pre-release. A pre-release is therefore not
+a private one before the first stable release — it is publicly installable by anyone who
+knows the name.
 
 **Write versions in canonical PEP 440 form.** `2026.1-rc1` and `2026.1.rc1` are accepted
 by the build but normalize to `2026.1rc1` in the artifact and on PyPI, which would make

ovito_mcp-2026.1.dev3/ovito_mcp/__main__.py

@@ -0,0 +1,47 @@
+"""Entry point for ``python -m ovito_mcp`` and the ``ovito-mcp`` console script."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from . import mcp, shutdown_kernel
+from .rag import db as ragdb
+
+
+def main() -> None:
+    # `ovito-mcp --version` prints the installed package version and exits. Handy
+    # for bug reports and for confirming that a registered (possibly absolute) path
+    # resolves to the expected install.
+    if "--version" in sys.argv[1:]:
+        from importlib.metadata import version
+        print(version("ovito-mcp"))
+        return
+
+    # `ovito-mcp --download-models` pre-downloads the retrieval models and exits,
+    # so the one-time Hub download can be done deterministically (e.g. right after
+    # `pip install ovito-mcp`) instead of during the first search tool call.
+    if "--download-models" in sys.argv[1:]:
+        logging.basicConfig(level=logging.INFO, format="%(message)s")
+        print("Downloading OVITO MCP retrieval models (one-time)...", file=sys.stderr)
+        try:
+            ragdb.ensure_models()
+        except ragdb.ModelsUnavailableError as exc:
+            print(f"Failed: {exc}", file=sys.stderr)
+            raise SystemExit(1)
+        print("Done. Models are cached locally.", file=sys.stderr)
+        return
+
+    # Warm the retrieval models in the background at startup so the first
+    # search_ovito_* call doesn't pay the load (and possible one-time download)
+    # cost on the request path, where it would risk the MCP client's tool timeout.
+    ragdb.warm_models_in_background()
+
+    try:
+        mcp.run()
+    finally:
+        shutdown_kernel()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -64,13 +64,30 @@ on each call — see `ovito_mcp.rag.DocsIndex` for that caching.
 
 from __future__ import annotations
 
-import functools
+import logging
+import os
 import sqlite3
+import threading
 from pathlib import Path
 from typing import Any
 
 import numpy as np
 
+logger = logging.getLogger(__name__)
+
+# Shorten the per-request Hugging Face Hub metadata timeout. This only affects the
+# code path that actually downloads models (the warmup thread and
+# ``ovito-mcp --download-models``, via allow_download=True); it trims each metadata
+# request from the default 10s to 5s. It is a best-effort nicety, NOT the mechanism
+# that keeps searches responsive: the Hub client still retries and does not bound
+# the repo-listing call or DNS resolution, so a fully unreachable Hub can still take
+# a while to give up. User-facing searches don't depend on any of that -- they load
+# offline-only and never touch the network (see get_model/get_cross_encoder), and
+# the load runs outside the model lock so a slow/stuck warmup download can't block
+# them either. Set as a default only, before any HF import, so a deployer can still
+# override it.
+os.environ.setdefault("HF_HUB_ETAG_TIMEOUT", "5")
+
 EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
 EMBED_DIM = 384
 
@@ -153,12 +170,93 @@ def connect(db_path: str | Path) -> sqlite3.Connection:
 # ── Embedding ──────────────────────────────────────────────────────────────────
 
 
-@functools.lru_cache(maxsize=1)
-def get_model():
-    """Load (and cache) the sentence-transformers embedding model."""
+class ModelsUnavailableError(RuntimeError):
+    """Raised when a retrieval model is neither cached locally nor downloadable.
+
+    A RuntimeError subclass so _call_rag() surfaces its (already user-facing)
+    message verbatim to the agent, rather than wrapping it as an opaque failure.
+    """
+
+
+_MODELS_UNAVAILABLE_MSG = (
+    "OVITO documentation search is unavailable because its search models are not "
+    "installed. OVITO ships the documentation database itself, but the two small "
+    "sentence-transformers models used to search it (~180 MB total) are downloaded "
+    "once from the Hugging Face Hub and cached locally -- and this machine has no "
+    "cached copy and cannot reach the Hub. To enable documentation search, run "
+    "'ovito-mcp --download-models' once on a machine with internet access (under the "
+    "same user account), or copy an existing Hugging Face cache directory "
+    "(~/.cache/huggingface) into place. Everything else -- running code, screenshots, "
+    "and pipeline inspection -- works without these models."
+)
+
+
+# Each model is loaded at most once per process and then reused. The loaded
+# instance is *published* under a lock (double-checked), but the load itself runs
+# OUTSIDE the lock -- see get_model()/get_cross_encoder() for why: a download on
+# the warmup path can stall (or, on a broken network, hang) for a long time, and
+# holding the lock across it would block a concurrent offline-only search behind
+# it, defeating the fast-fail guarantee. Because only ensure_models() ever passes
+# allow_download=True (and the CLI download runs in its own process), there is at
+# most one downloader, so loading outside the lock cannot start two parallel
+# downloads; at worst two threads redundantly load the *cached* files and the
+# first published instance wins.
+_model = None
+_model_lock = threading.Lock()
+_cross_encoder = None
+_cross_encoder_lock = threading.Lock()
+
+
+def _load_st_model(cls, name: str, *, allow_download: bool):
+    """Load a sentence-transformers model, preferring the local HF cache.
+
+    Always tries the local cache first (``local_files_only=True``): that path is
+    instant and never issues a network request, so a warm process makes no HTTP
+    HEAD calls to huggingface.co on load (those add seconds of latency even when
+    the files are cached, and fail outright on a slow/offline/rate-limited
+    connection -- the original cause of ``search_ovito_*`` timing out).
+
+    ``allow_download`` controls the not-cached case:
+
+    * False (the default for user-facing searches via get_model/get_cross_encoder)
+      -- raise ModelsUnavailableError immediately. The search path therefore never
+      touches the network and never hangs, whatever the connection state.
+    * True (only the warmup thread and ``ovito-mcp --download-models``) -- attempt
+      a one-time download from the Hub, bounded by HF_HUB_ETAG_TIMEOUT so an
+      unreachable Hub fails in a few seconds rather than hanging. Still raises
+      ModelsUnavailableError if the download can't complete.
+    """
+    try:
+        return cls(name, local_files_only=True)
+    except Exception as cache_miss:
+        if not allow_download:
+            raise ModelsUnavailableError(_MODELS_UNAVAILABLE_MSG) from cache_miss
+    # allow_download and not cached: attempt a one-time (bounded) Hub download.
+    try:
+        return cls(name)
+    except Exception as exc:
+        raise ModelsUnavailableError(_MODELS_UNAVAILABLE_MSG) from exc
+
+
+def get_model(*, allow_download: bool = False):
+    """Load (and cache) the sentence-transformers embedding model.
+
+    Offline-only by default: raises ModelsUnavailableError if the model isn't
+    already cached. Only ensure_models() passes allow_download=True to permit the
+    one-time download. The load runs outside _model_lock (the lock only guards
+    publication) so an offline-only caller is never blocked behind a slow or
+    hanging download on the warmup path.
+    """
+    global _model
+    if _model is not None:  # atomic reference read under the GIL
+        return _model
     from sentence_transformers import SentenceTransformer
 
-    return SentenceTransformer(EMBED_MODEL)
+    loaded = _load_st_model(SentenceTransformer, EMBED_MODEL, allow_download=allow_download)
+    with _model_lock:
+        if _model is None:
+            _model = loaded
+    return _model
 
 
 def embed(texts: list[str]) -> np.ndarray:
@@ -174,12 +272,84 @@ def embed_one(text: str) -> np.ndarray:
     return embed([text])[0]
 
 
-@functools.lru_cache(maxsize=1)
-def get_cross_encoder():
-    """Load (and cache) the cross-encoder used to re-rank candidate passages."""
+def get_cross_encoder(*, allow_download: bool = False):
+    """Load (and cache) the cross-encoder used to re-rank candidate passages.
+
+    Offline-only by default: raises ModelsUnavailableError if the model isn't
+    already cached. Only ensure_models() passes allow_download=True to permit the
+    one-time download. The load runs outside _cross_encoder_lock (the lock only
+    guards publication) so an offline-only caller is never blocked behind a slow
+    or hanging download on the warmup path.
+    """
+    global _cross_encoder
+    if _cross_encoder is not None:  # atomic reference read under the GIL
+        return _cross_encoder
     from sentence_transformers import CrossEncoder
 
-    return CrossEncoder(RERANK_MODEL)
+    loaded = _load_st_model(CrossEncoder, RERANK_MODEL, allow_download=allow_download)
+    with _cross_encoder_lock:
+        if _cross_encoder is None:
+            _cross_encoder = loaded
+    return _cross_encoder
+
+
+def ensure_models() -> None:
+    """Download (once) and load both retrieval models into this process.
+
+    Idempotent: after the first successful call both models are cached in memory
+    (and on disk, in the HF cache) and later calls are no-ops. This is the single
+    place a model download from huggingface.co is expected to happen; running it
+    up front -- at server startup via warm_models_in_background(), or explicitly
+    via ``ovito-mcp --download-models`` -- keeps that one-time cost out of the
+    first search_ovito_* tool call, where it would otherwise surface as a timeout.
+    Loading is deferred to the getters, so this also warms the in-memory singletons.
+
+    This is the only place allowed to download the models (allow_download=True);
+    user-facing searches load offline-only and never hit the network. Raises
+    ModelsUnavailableError if a model is neither cached nor downloadable.
+
+    NB: this must NOT wrap the loads in contextlib.redirect_stdout(). Unlike the
+    on-demand _call_rag() path -- which runs after mcp.run() has already captured
+    the real stdout buffer for the JSON-RPC transport -- ensure_models() is called
+    from warm_models_in_background() *before/while* mcp.run() sets that transport
+    up. A process-global sys.stdout swap here races that capture and can bind the
+    protocol stream to stderr, breaking the MCP handshake entirely. The model
+    libraries send their progress/log output to stderr on their own, so no redirect
+    is needed for correctness on this path.
+    """
+    get_model(allow_download=True)
+    get_cross_encoder(allow_download=True)
+
+
+def warm_models_in_background() -> threading.Thread:
+    """Kick off ensure_models() in a daemon thread and return it immediately.
+
+    The retrieval models take several seconds to import+load (and, on a machine
+    that has never run the server before, a one-time download). Doing that lazily
+    inside the first search_ovito_* call makes that call slow enough to hit the
+    MCP client's tool timeout. Warming at startup instead moves the cost off the
+    request path: by the time a search arrives the models are usually ready, and
+    if one races the warmup it simply blocks on the same lock rather than starting
+    a second load. Failures here are non-fatal -- they are logged and the getters
+    retry on demand -- so a transient network problem at startup never prevents
+    the server from running (or from serving non-search tools).
+    """
+
+    def _warm() -> None:
+        try:
+            ensure_models()
+            logger.info("OVITO MCP: retrieval models ready.")
+        except ModelsUnavailableError as exc:
+            # Expected on an offline machine with no cached models: documentation
+            # search will report the same actionable message when called. All other
+            # tools keep working, so this is a warning, not a fatal error.
+            logger.warning("OVITO MCP: %s", exc)
+        except Exception as exc:  # noqa: BLE001 - warmup must never crash the server
+            logger.warning("OVITO MCP: model warmup failed unexpectedly (%s).", exc)
+
+    thread = threading.Thread(target=_warm, name="ovito-mcp-model-warmup", daemon=True)
+    thread.start()
+    return thread
 
 
 def _vec_to_blob(vec: np.ndarray) -> bytes:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ovito-mcp"
-version = "2026.1.dev2"
+version = "2026.1.dev3"
 description = "MCP server for interactive work in OVITO Pro"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,7 +17,7 @@ dependencies = [
 ]
 license = { text = "Proprietary" }
 authors = [{ name = "OVITO GmbH", email = "support@ovito.org" }]
-keywords = ["ovito", "mcp", "molecular-dynamics", "visualization", "jupyter"]
+keywords = ["ovito", "mcp", "molecular-dynamics", "visualization"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",

ovito_mcp-2026.1.dev2/PKG-INFO

@@ -1,240 +0,0 @@
-Metadata-Version: 2.4
-Name: ovito-mcp
-Version: 2026.1.dev2
-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
-Project-URL: Repository, https://gitlab.com/ovito-org/ovito-mcp-server
-Project-URL: Bug Tracker, https://gitlab.com/ovito-org/ovito-mcp-server/-/issues
-Author-email: OVITO GmbH <support@ovito.org>
-License: Proprietary
-License-File: LICENSE
-Keywords: jupyter,mcp,molecular-dynamics,ovito,visualization
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.10
-Requires-Dist: jupyter-client>=8.0
-Requires-Dist: jupyter-core>=5.0
-Requires-Dist: mcp>=1.2.0
-Requires-Dist: numpy>=1.26
-Requires-Dist: sentence-transformers>=5.6.0
-Provides-Extra: test
-Requires-Dist: pytest; extra == 'test'
-Description-Content-Type: text/markdown
-
-# OVITO MCP Server
-
-An MCP server that connects a coding agent to a live **OVITO Pro** session, so an LLM can
-do interactive OVITO work — execute Python in a persistent kernel, inspect the scene,
-drive the GUI window, and look up documentation. Runs as a stdio MCP server in Claude
-Code, GitHub Copilot CLI, Codex, OpenCode, Antigravity, or any other MCP host.
-
-## Quick start
-
-```sh
-pip install ovito-mcp
-```
-
-Register it with your coding agent — for Claude Code:
-
-```sh
-claude mcp add ovito-mcp --scope user -- ovito-mcp
-```
-
-See [Agent configuration](#agent-configuration) below for the equivalent config in other
-agents.
-
-Then, in OVITO Pro, open the **AI Agent** tab in the data inspector panel at the bottom
-of the main window, pick your coding agent, and press **Start**. OVITO launches the agent
-and hands it the connection details of its own embedded Python kernel, so the agent
-attaches to the session you are looking at — anything it does shows up live in the GUI,
-and you can keep interacting with the same scene yourself.
-
-That's the whole setup. **No environment variables are required**, and you do not need to
-tell the server where OVITO is installed: it is already talking to a running OVITO Pro.
-
-See the [AI Agent manual page](https://docs.ovito.org/reference/data_inspector/coding_agent.html)
-for the OVITO-side documentation, including security considerations.
-
-## How it works
-
-- `ovito_mcp/__init__.py` uses `jupyter_client` to attach to (or, as a fallback, start) an
-  OVITO kernel, and exposes tools to `execute` code and manage the kernel lifecycle. State
-  persists across calls — variables, imports, and the OVITO pipeline carry over.
-- OVITO Pro's *AI Agent* panel starts an embedded kernel and passes its connection-file
-  path to the agent in the startup prompt; the agent calls `connect_kernel()` with it.
-  The same kernel can also be attached from JupyterLab to watch along.
-- `start_kernel()` is the fallback for standalone use with no OVITO Pro session running.
-  It launches a separate OVITO process and is the only part of the server that needs
-  `OVITO_EXE` — see [Advanced configuration](#advanced-configuration).
-- GUI tools (`create_window`, `close_window`, `screenshot_window`) drive OVITO Pro's Qt
-  main window inside the kernel, so a human can watch and interact with the same scene.
-- Scene-inspection tools (`list_pipelines`, `list_modifiers`, `inspect_pipeline_data`,
-  `get_timeline_info`, `set_current_frame`) let the LLM read back pipeline/data state
-  without hand-writing introspection code.
-- The documentation tools (`search_ovito_docs` and friends) perform semantic search over a
-  local SQLite index of the OVITO manual and Python API docs, so the LLM can look up
-  correct usage instead of guessing at APIs. The index ships inside OVITO Pro and is found
-  automatically — nothing to configure.
-
-```
-connect_kernel(<connection_file>)   # the normal path: attach to OVITO Pro's own kernel
-        \-> start_kernel()          # fallback: launch a separate OVITO process (needs OVITO_EXE)
-        \-> execute("import ovito; print(ovito.version_string)")
-```
-
-## Advanced configuration
-
-Neither variable below is needed for the standard flow described in
-[Quick start](#quick-start). Set them only for the cases described.
-
-| Env var        | Purpose                                                                                                                                                                  |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `OVITO_EXE`    | Path to the OVITO Pro executable (`ovito.exe` on Windows, `ovito` on Linux, `Ovito.app/Contents/MacOS/ovito` on macOS). Required *only* by `start_kernel()`, i.e. when you want the agent to launch OVITO itself instead of connecting to a running session. |
-| `OVITO_RAG_DB` | Path to an alternative documentation database (`.sqlite3`). Overrides the copy that ships with OVITO Pro — useful when developing against a hand-built database.          |
-
-Both are read at import time but never validated there, so the server always starts
-without configuration. `start_kernel()` raises `ValueError` if `OVITO_EXE` is unset, and
-the documentation tools report a message telling you to connect a kernel first if the
-database cannot be located.
-
-By default the documentation database is discovered by asking the connected kernel for
-`ovito.__file__` and looking for `rag.sqlite3` next to the resolved `ovito` package. That
-works without `OVITO_EXE`, which is why the standard flow needs no setup at all.
-
-## Tools
-
-**Kernel lifecycle**
-
-| Tool                              | Purpose                                                                                                       |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `connect_kernel(connection_file)` | Attach to an already-running kernel via its connection file; state is shared with whoever else is driving it. |
-| `start_kernel()`                  | Launch a new OVITO kernel and make it active (tears down any current session first). Requires `OVITO_EXE`.    |
-| `get_kernel_id()`                 | UUID of the active kernel.                                                                                    |
-| `kernel_status()`                 | Active kernel id, ownership (started here vs. externally connected), liveness.                                |
-| `interrupt_kernel()`              | Interrupt a running execution (kernels started by this server only).                                          |
-| `restart_kernel()`                | Restart and clear all state (kernels started by this server only).                                            |
-| `shutdown_kernel()`               | Shut down an owned kernel, or detach from an externally-connected one (left running).                         |
-
-**Execution**
-
-| Tool                        | Purpose                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------ |
-| `execute(code, timeout=60)` | Run Python in the active kernel; returns status, stdout/stderr, result, and any traceback. |
-
-**GUI window**
-
-| Tool                           | Purpose                                                                                         |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `create_window(contents=None)` | Open (or reuse) OVITO's graphical main window in the kernel so a human can watch/interact live. |
-| `close_window()`               | Close a window this server itself created — never one it merely reused.                         |
-| `screenshot_window()`          | Return a PNG screenshot of the open OVITO main window.                                          |
-
-**Scene inspection**
-
-| Tool                                  | Purpose                                                                                                                    |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `list_pipelines()`                    | List pipelines in the scene with their keys and names.                                                                     |
-| `list_modifiers(pipeline_key)`        | List modifiers on a given pipeline.                                                                                        |
-| `inspect_pipeline_data(pipeline_key)` | Markdown overview of a pipeline's computed output: attributes, data objects, property containers, simulation cell.         |
-| `list_pipeline_status()`              | Status (including warning/error triangles) of every pipeline, modifier, and visual element in the scene.                   |
-| `get_timeline_info()`                 | Current frame and frame range.                                                                                             |
-| `set_current_frame(frame)`            | Set the current animation frame (keeps the GUI in sync; use instead of setting `ovito.scene.anim.current_frame` directly). |
-
-**Documentation**
-
-| Tool                                                   | Purpose                                                                 |
-| ------------------------------------------------------ | ------------------------------------------------------------------------- |
-| `search_ovito_docs(query, top_k=5)`                    | Semantic search across the OVITO manual and Python API docs.             |
-| `search_ovito_manual(query, top_k=5)`                  | Semantic search over manual pages only.                                  |
-| `search_ovito_api_symbols(query, top_k=5)`             | Semantic search over Python API symbols only.                            |
-| `get_ovito_manual_page(full_page_id)`                  | Fetch a manual page's full text by id (from a manual search result).     |
-| `get_ovito_docstring(doc_string_id=None, symbol=None)` | Fetch a Python symbol's full docstring by id or exact qualified name.    |
-
-These are backed by `ovito_mcp.rag` — a single inspectable SQLite file (`rag.sqlite3`)
-searched with a two-stage strategy: bi-encoder retrieval over stored embeddings, then
-cross-encoder re-ranking of the candidates. No vector-store service is required. Manual
-hits are resolved to their complete source page rather than the matching chunk, so results
-are not truncated excerpts.
-
-If no database can be located, these tools return a configuration hint instead of crashing
-the server; every other tool is unaffected.
-
-## Agent configuration
-
-All configurations below assume `ovito-mcp` is on your `PATH` (it is installed as a
-console script by `pip install ovito-mcp`). If you installed into an environment that
-isn't active when the agent runs, use the absolute path to the script instead —
-`/path/to/env/bin/ovito-mcp`. No `env` block is needed.
-
-### Claude Code / Claude Desktop
-
-```sh
-claude mcp add ovito-mcp --scope user -- ovito-mcp
-```
-
-Or add this to your `~/.claude.json`:
-
-```json
-"mcpServers": {
-  "ovito-mcp": {
-    "type": "stdio",
-    "command": "ovito-mcp"
-  }
-}
-```
-
-### OpenCode
-
-Add this to your `~/.opencode.json`:
-
-```json
-"mcp": {
-  "ovito-mcp": {
-    "type": "local",
-    "command": ["ovito-mcp"],
-    "enabled": true
-  }
-}
-```
-
-### Google Antigravity
-
-Add this to your `~/.antigravity/config.json`:
-
-```json
-"mcpServers": {
-  "ovito-mcp": {
-    "command": "ovito-mcp"
-  }
-}
-```
-
-### OpenAI Codex
-
-Add this to your `$HOME/.codex/config.toml`:
-
-```toml
-[mcp_servers.ovito-mcp]
-command = "ovito-mcp"
-```
-
-### GitHub Copilot
-
-Add this to your `~/.copilot/mcp-config.json`:
-
-```json
-"mcpServers": {
-  "ovito-mcp": {
-    "command": "ovito-mcp"
-  }
-}
-```

ovito_mcp-2026.1.dev2/README.md

@@ -1,208 +0,0 @@
-# OVITO MCP Server
-
-An MCP server that connects a coding agent to a live **OVITO Pro** session, so an LLM can
-do interactive OVITO work — execute Python in a persistent kernel, inspect the scene,
-drive the GUI window, and look up documentation. Runs as a stdio MCP server in Claude
-Code, GitHub Copilot CLI, Codex, OpenCode, Antigravity, or any other MCP host.
-
-## Quick start
-
-```sh
-pip install ovito-mcp
-```
-
-Register it with your coding agent — for Claude Code:
-
-```sh
-claude mcp add ovito-mcp --scope user -- ovito-mcp
-```
-
-See [Agent configuration](#agent-configuration) below for the equivalent config in other
-agents.
-
-Then, in OVITO Pro, open the **AI Agent** tab in the data inspector panel at the bottom
-of the main window, pick your coding agent, and press **Start**. OVITO launches the agent
-and hands it the connection details of its own embedded Python kernel, so the agent
-attaches to the session you are looking at — anything it does shows up live in the GUI,
-and you can keep interacting with the same scene yourself.
-
-That's the whole setup. **No environment variables are required**, and you do not need to
-tell the server where OVITO is installed: it is already talking to a running OVITO Pro.
-
-See the [AI Agent manual page](https://docs.ovito.org/reference/data_inspector/coding_agent.html)
-for the OVITO-side documentation, including security considerations.
-
-## How it works
-
-- `ovito_mcp/__init__.py` uses `jupyter_client` to attach to (or, as a fallback, start) an
-  OVITO kernel, and exposes tools to `execute` code and manage the kernel lifecycle. State
-  persists across calls — variables, imports, and the OVITO pipeline carry over.
-- OVITO Pro's *AI Agent* panel starts an embedded kernel and passes its connection-file
-  path to the agent in the startup prompt; the agent calls `connect_kernel()` with it.
-  The same kernel can also be attached from JupyterLab to watch along.
-- `start_kernel()` is the fallback for standalone use with no OVITO Pro session running.
-  It launches a separate OVITO process and is the only part of the server that needs
-  `OVITO_EXE` — see [Advanced configuration](#advanced-configuration).
-- GUI tools (`create_window`, `close_window`, `screenshot_window`) drive OVITO Pro's Qt
-  main window inside the kernel, so a human can watch and interact with the same scene.
-- Scene-inspection tools (`list_pipelines`, `list_modifiers`, `inspect_pipeline_data`,
-  `get_timeline_info`, `set_current_frame`) let the LLM read back pipeline/data state
-  without hand-writing introspection code.
-- The documentation tools (`search_ovito_docs` and friends) perform semantic search over a
-  local SQLite index of the OVITO manual and Python API docs, so the LLM can look up
-  correct usage instead of guessing at APIs. The index ships inside OVITO Pro and is found
-  automatically — nothing to configure.
-
-```
-connect_kernel(<connection_file>)   # the normal path: attach to OVITO Pro's own kernel
-        \-> start_kernel()          # fallback: launch a separate OVITO process (needs OVITO_EXE)
-        \-> execute("import ovito; print(ovito.version_string)")
-```
-
-## Advanced configuration
-
-Neither variable below is needed for the standard flow described in
-[Quick start](#quick-start). Set them only for the cases described.
-
-| Env var        | Purpose                                                                                                                                                                  |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `OVITO_EXE`    | Path to the OVITO Pro executable (`ovito.exe` on Windows, `ovito` on Linux, `Ovito.app/Contents/MacOS/ovito` on macOS). Required *only* by `start_kernel()`, i.e. when you want the agent to launch OVITO itself instead of connecting to a running session. |
-| `OVITO_RAG_DB` | Path to an alternative documentation database (`.sqlite3`). Overrides the copy that ships with OVITO Pro — useful when developing against a hand-built database.          |
-
-Both are read at import time but never validated there, so the server always starts
-without configuration. `start_kernel()` raises `ValueError` if `OVITO_EXE` is unset, and
-the documentation tools report a message telling you to connect a kernel first if the
-database cannot be located.
-
-By default the documentation database is discovered by asking the connected kernel for
-`ovito.__file__` and looking for `rag.sqlite3` next to the resolved `ovito` package. That
-works without `OVITO_EXE`, which is why the standard flow needs no setup at all.
-
-## Tools
-
-**Kernel lifecycle**
-
-| Tool                              | Purpose                                                                                                       |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `connect_kernel(connection_file)` | Attach to an already-running kernel via its connection file; state is shared with whoever else is driving it. |
-| `start_kernel()`                  | Launch a new OVITO kernel and make it active (tears down any current session first). Requires `OVITO_EXE`.    |
-| `get_kernel_id()`                 | UUID of the active kernel.                                                                                    |
-| `kernel_status()`                 | Active kernel id, ownership (started here vs. externally connected), liveness.                                |
-| `interrupt_kernel()`              | Interrupt a running execution (kernels started by this server only).                                          |
-| `restart_kernel()`                | Restart and clear all state (kernels started by this server only).                                            |
-| `shutdown_kernel()`               | Shut down an owned kernel, or detach from an externally-connected one (left running).                         |
-
-**Execution**
-
-| Tool                        | Purpose                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------ |
-| `execute(code, timeout=60)` | Run Python in the active kernel; returns status, stdout/stderr, result, and any traceback. |
-
-**GUI window**
-
-| Tool                           | Purpose                                                                                         |
-| ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `create_window(contents=None)` | Open (or reuse) OVITO's graphical main window in the kernel so a human can watch/interact live. |
-| `close_window()`               | Close a window this server itself created — never one it merely reused.                         |
-| `screenshot_window()`          | Return a PNG screenshot of the open OVITO main window.                                          |
-
-**Scene inspection**
-
-| Tool                                  | Purpose                                                                                                                    |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `list_pipelines()`                    | List pipelines in the scene with their keys and names.                                                                     |
-| `list_modifiers(pipeline_key)`        | List modifiers on a given pipeline.                                                                                        |
-| `inspect_pipeline_data(pipeline_key)` | Markdown overview of a pipeline's computed output: attributes, data objects, property containers, simulation cell.         |
-| `list_pipeline_status()`              | Status (including warning/error triangles) of every pipeline, modifier, and visual element in the scene.                   |
-| `get_timeline_info()`                 | Current frame and frame range.                                                                                             |
-| `set_current_frame(frame)`            | Set the current animation frame (keeps the GUI in sync; use instead of setting `ovito.scene.anim.current_frame` directly). |
-
-**Documentation**
-
-| Tool                                                   | Purpose                                                                 |
-| ------------------------------------------------------ | ------------------------------------------------------------------------- |
-| `search_ovito_docs(query, top_k=5)`                    | Semantic search across the OVITO manual and Python API docs.             |
-| `search_ovito_manual(query, top_k=5)`                  | Semantic search over manual pages only.                                  |
-| `search_ovito_api_symbols(query, top_k=5)`             | Semantic search over Python API symbols only.                            |
-| `get_ovito_manual_page(full_page_id)`                  | Fetch a manual page's full text by id (from a manual search result).     |
-| `get_ovito_docstring(doc_string_id=None, symbol=None)` | Fetch a Python symbol's full docstring by id or exact qualified name.    |
-
-These are backed by `ovito_mcp.rag` — a single inspectable SQLite file (`rag.sqlite3`)
-searched with a two-stage strategy: bi-encoder retrieval over stored embeddings, then
-cross-encoder re-ranking of the candidates. No vector-store service is required. Manual
-hits are resolved to their complete source page rather than the matching chunk, so results
-are not truncated excerpts.
-
-If no database can be located, these tools return a configuration hint instead of crashing
-the server; every other tool is unaffected.
-
-## Agent configuration
-
-All configurations below assume `ovito-mcp` is on your `PATH` (it is installed as a
-console script by `pip install ovito-mcp`). If you installed into an environment that
-isn't active when the agent runs, use the absolute path to the script instead —
-`/path/to/env/bin/ovito-mcp`. No `env` block is needed.
-
-### Claude Code / Claude Desktop
-
-```sh
-claude mcp add ovito-mcp --scope user -- ovito-mcp
-```
-
-Or add this to your `~/.claude.json`:
-
-```json
-"mcpServers": {
-  "ovito-mcp": {
-    "type": "stdio",
-    "command": "ovito-mcp"
-  }
-}
-```
-
-### OpenCode
-
-Add this to your `~/.opencode.json`:
-
-```json
-"mcp": {
-  "ovito-mcp": {
-    "type": "local",
-    "command": ["ovito-mcp"],
-    "enabled": true
-  }
-}
-```
-
-### Google Antigravity
-
-Add this to your `~/.antigravity/config.json`:
-
-```json
-"mcpServers": {
-  "ovito-mcp": {
-    "command": "ovito-mcp"
-  }
-}
-```
-
-### OpenAI Codex
-
-Add this to your `$HOME/.codex/config.toml`:
-
-```toml
-[mcp_servers.ovito-mcp]
-command = "ovito-mcp"
-```
-
-### GitHub Copilot
-
-Add this to your `~/.copilot/mcp-config.json`:
-
-```json
-"mcpServers": {
-  "ovito-mcp": {
-    "command": "ovito-mcp"
-  }
-}
-```

ovito_mcp-2026.1.dev2/ovito_mcp/__main__.py

@@ -1,16 +0,0 @@
-"""Entry point for ``python -m ovito_mcp``."""
-
-from __future__ import annotations
-
-from . import mcp, shutdown_kernel
-
-
-def main() -> None:
-    try:
-        mcp.run()
-    finally:
-        shutdown_kernel()
-
-
-if __name__ == "__main__":
-    main()