ovito-mcp 2026.1__tar.gz

ovito_mcp-2026.1/.gitignore

@@ -0,0 +1,266 @@
+# 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/
+
+# 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/.gitlab-ci.yml

@@ -0,0 +1,95 @@
+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:
+    # Upgrade pip before anything else. The python:3.10 image ships a pip old enough to
+    # reject a wheel whose metadata Name differs from the requested name only by
+    # normalization ('typing_extensions' vs 'typing-extensions'). It discards every wheel
+    # candidate, falls back to the sdist, and then cannot install that sdist's build
+    # dependency (flit_core) because --index-url below has replaced PyPI with the
+    # PyTorch-only index. Newer pip canonicalizes both names and uses the wheel, which is
+    # why the 3.14 entry was unaffected.
+    - pip install --upgrade pip
+    # 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/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/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: ovito-mcp
+Version: 2026.1
+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<3,>=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.                                                                            |
+
+## Workflow examples
+
+### Prompt: 
+
+*"Analyze the grain boundary in this sample and highlight repeating structural units in the boundary."*
+
+**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_gb_analysis.mp4
+
+- Identified the sample as a 2D-periodic bicrystal grain boundary
+- Ran structure identification via polyhedral template matching
+- Determined the boundary plane, tilt angle, and tilt axis
+- Measured periodicity along the boundary with an FFT
+- Color-coded the repeating structural units and aligned the camera
+
+### Prompt:
+
+*"Import the ethene molecule and show the electron density along a representative slice — then add bond orders, a colorbar, and color the bonds by particle type."*
+
+**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_electron_density.mp4
+
+- Loaded the molecule's charge-density file and computed the molecular plane
+- Sliced along the plane and aligned the camera to it
+- Switched to a logarithmic color scale after spotting oversaturation
+- Added a color legend in preview mode
+- Computed bond orders and colored bonds to match particle colors
+
+### Prompt:
+
+*"Recreate the analysis and view from this reference figure using my data already loaded in OVITO — don't manipulate the data for better agreement."*
+
+**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_nano_indentation.mp4
+
+- Identified the sample as SrTiO₃ with a free surface
+- Selected the BCC-like cation sublattice for dislocation analysis
+- Applied the Dislocation Extraction Algorithm (DXA)
+- Matched line and defect-mesh coloring to the reference figure
+- Adjusted the camera to match the reference viewport
+
+### Prompt:
+
+*"Read this trajectory and compute the diffusion constant — then plot the result."*
+
+**Video:** https://www.ovito.org/download/data/videos/ai_agent_demo_diffusion.mp4
+
+- Loaded a 1,000-frame trajectory in a 5 Å cubic periodic box
+- Unwrapped trajectories to avoid MSD saturation from periodic boundaries
+- Computed the mean squared displacement (MSD) over time
+- Fit MSD vs. time using the Einstein–Smoluchowski relation
+- Plotted the result: D = 0.0490 Ų/ps (R² = 0.995)
+
+## Support
+
+Questions and bug reports: <support@ovito.org>