ovito-mcp 2026.1.dev2__tar.gz

ovito_mcp-2026.1.dev2/.gitignore

@@ -0,0 +1,271 @@
+# Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,python,macos,linux,windows
+# Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,python,macos,linux,windows
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,python,macos,linux,windows
+
+.claude

ovito_mcp-2026.1.dev2/.gitlab-ci.yml

@@ -0,0 +1,87 @@
+default:
+  image: python:3.11
+
+stages:
+  - test
+  - publish
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip
+
+test:
+  stage: test
+  parallel:
+    matrix:
+      # The floor and ceiling of requires-python. This package needs
+      # torch, so every extra matrix entry is expensive; the two ends catch the version
+      # incompatibilities that matter.
+      - PYTHON_VERSION: ["3.10", "3.14"]
+  image: python:${PYTHON_VERSION}
+  script:
+    # Install the CPU-only torch build first so the sentence-transformers dependency
+    # below is already satisfied and pip never pulls the ~2.5GB CUDA wheel. CI has no GPU.
+    - pip install torch --index-url https://download.pytorch.org/whl/cpu
+    - pip install -e ".[test]"
+    - pytest -q
+
+publish-pypi:
+  stage: publish
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+/
+  variables:
+    HATCH_INDEX_USER: __token__
+    # HATCH_INDEX_AUTH holds the PyPI API token. It is not defined here: set it as a
+    # masked CI/CD variable in the GitLab project settings (see RELEASING.md).
+    # Disable keyring, which otherwise hangs waiting for a backend on a headless runner.
+    PYTHON_KEYRING_BACKEND: keyring.backends.null.Keyring
+  script:
+    # Fail fast, and legibly, when the token never reached the job. Without this the
+    # symptom is an opaque "403 Forbidden" from PyPI at the very end of the pipeline,
+    # which looks like a bad token rather than a missing one.
+    - |
+      if [ -z "$HATCH_INDEX_AUTH" ]; then
+        echo "HATCH_INDEX_AUTH is empty or unset in this job." >&2
+        echo "A 'Protected' CI/CD variable is only exposed to protected refs. Either add a" >&2
+        echo "protected-tag rule covering 'v*' under Settings > Repository > Protected tags," >&2
+        echo "or clear the Protected flag on the variable." >&2
+        exit 1
+      fi
+      case "$HATCH_INDEX_AUTH" in
+        pypi-*) ;;
+        *)
+          echo "HATCH_INDEX_AUTH does not look like a PyPI API token." >&2
+          echo "Expected it to start with 'pypi-'; got ${#HATCH_INDEX_AUTH} characters." >&2
+          echo "Check for a truncated paste, surrounding quotes, or trailing whitespace." >&2
+          exit 1
+          ;;
+      esac
+    - pip install hatch
+    # Fail on a tag that disagrees with the packaged version. PyPI refuses re-uploads of
+    # a version, so a mismatch has to be caught before `hatch publish`, not after.
+    #
+    # The tag is compared against the PEP 440 *normalized* version, because that is what
+    # ends up in the artifact filename and on PyPI. `hatch version` echoes the literal
+    # string from pyproject.toml, so a non-canonical spelling like "2026.1-rc1" would
+    # otherwise satisfy a literal comparison while publishing as "2026.1rc1".
+    # `packaging` is available here as a hatchling dependency.
+    - |
+      RAW_VERSION="$(hatch version)"
+      VERSION="$(python -c 'import sys; from packaging.version import Version; print(Version(sys.argv[1]))' "$RAW_VERSION")"
+      if [ "v$VERSION" != "$CI_COMMIT_TAG" ]; then
+        echo "Tag $CI_COMMIT_TAG does not match the version that would be published ($VERSION)." >&2
+        if [ "$RAW_VERSION" != "$VERSION" ]; then
+          echo "Note: pyproject.toml says '$RAW_VERSION', which normalizes to '$VERSION'." >&2
+          echo "Write the version in canonical PEP 440 form to avoid this." >&2
+        fi
+        echo "Retag as v$VERSION, or bump the version to match the tag." >&2
+        exit 1
+      fi
+    - hatch build
+    - hatch publish
+  environment:
+    name: pypi
+    url: https://pypi.org/project/ovito-mcp/

ovito_mcp-2026.1.dev2/LICENSE

@@ -0,0 +1,39 @@
+# OVITO Pro Add-on Package License
+Copyright (c) 2026 OVITO GmbH. All rights reserved.
+
+This software (the "Software") is a copyrighted work of OVITO GmbH ("Licensor"). The Software is made available in source form on the Python Package Index (PyPI) for distribution convenience only. Making the source code accessible does not constitute a grant of open-source rights, and no rights are granted to any person except as expressly set out below.
+
+## 1. Grant of License
+Subject to the terms of this License, Licensor grants you a limited, non-exclusive, non-transferable, non-sublicensable license to install, execute, and use the Software, solely if and for so long as you hold a valid, active license to OVITO Pro issued by OVITO GmbH ("OVITO Pro License").
+This license to use the Software:
+- is granted only to the same individual, group, or organization holding the corresponding OVITO Pro License, subject to the same installation limits as that OVITO Pro License;
+- terminates automatically upon expiration, termination, or non-renewal of the underlying OVITO Pro License, without notice;
+- does not include any right to use the Software independently of, or separately from, OVITO Pro.
+
+## 2. Restrictions
+Except as expressly permitted under Section 1, you may not:
+
+a. use the Software without holding a valid, active OVITO Pro License;
+b. copy, distribute, sublicense, sell, rent, lease, or otherwise make the Software available to any third party;
+c. modify, adapt, translate, or create derivative works based on the Software;
+d. reverse engineer, decompile, or disassemble the Software, except to the extent such restriction is prohibited by applicable mandatory law;
+e. remove or alter any copyright, trademark, or other proprietary notices contained in the Software;
+f. use the Software for any purpose other than in conjunction with your licensed use of OVITO Pro.
+
+## 3. Ownership
+The Software is licensed, not sold. Licensor retains all right, title, and interest in and to the Software, including all intellectual property rights therein. No rights are granted other than those expressly set forth in this License.
+
+## 4. No Warranty
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+## 5. Limitation of Liability
+IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE, TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW.
+
+## 6. Termination
+This License terminates automatically, without notice from Licensor, upon any breach of its terms, or upon expiration or termination of the underlying OVITO Pro License. Upon termination, you must cease all use of the Software and delete all copies in your possession.
+
+## 7. Governing Law
+This License shall be governed by the laws of the Federal Republic of Germany, without regard to its conflict-of-law provisions. The place of jurisdiction shall be Darmstadt, Germany, to the extent permitted by law.
+
+## 8. Contact
+For questions regarding this License, contact: mail@ovito.org

ovito_mcp-2026.1.dev2/PKG-INFO

@@ -0,0 +1,240 @@
+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"
+  }
+}
+```