mcpymol 1.5.0__tar.gz

mcpymol-1.5.0/.claude/skills/mcpymol-guide/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: mcpymol-guide
+description: >-
+  How to drive the mcpymol MCP server well — structure prep, the view-preset
+  catalogue, PyMOL selection syntax, rendering, and 3D-print STL export.
+  TRIGGER when the user asks to visualize/fetch/render a protein structure
+  through the mcpymol tools, apply a *_view preset, or produce a 3D-printable
+  model/STL. SKIP for unrelated PyMOL-less work.
+---
+
+# Driving the mcpymol MCP server
+
+The `mcp__mcpymol__*` tools talk to a running PyMOL over a socket. Prefer the
+high-level tools (`fetch_structure`, the `*_view` presets, `show`/`color`/
+`select`) over `execute_pymol_command` — the presets do coloring,
+transparency, H-bonds and labels in one call. Reach for
+`execute_pymol_command` only when no dedicated tool covers the need.
+
+## Report first, then draw
+
+The presets make pictures; the report tools answer questions with numbers.
+When the user asks *why* or *how much* — what holds this ligand, how big is
+this interface, where do these differ — run the report and quote the numbers,
+then apply the matching view if a picture helps. Answering a quantitative
+question with only a rendering leaves the user to measure it themselves.
+
+| The question | Reach for |
+| --- | --- |
+| What is this structure? | `structure_info` |
+| What is the sequence / numbering / where are the gaps? | `get_sequence` |
+| What contacts what, and how tightly? | `contact_report` -> `ligand_view` |
+| How big is this interface, which residues matter? | `interface_report` -> `interface_view` |
+| Where do two structures differ? | `superposition_view` |
+| How far / what angle / how much area? | `distance`, `angle`, `dihedral`, `sasa`, `rms_cur` |
+| Does my selection match anything? | `count_atoms` |
+| Occupancy / altloc / per-atom B-factor? | `atom_properties` |
+
+`contact_report` classification is heavy-atom geometry (no hydrogens assumed):
+salt bridge <= 4.0 A, H-bond <= 3.5 A between N/O, hydrophobic <= 4.5 A,
+ring centroids <= 5.5 A. Report it as such — a "hydrogen bond" here is a
+donor-acceptor pair with plausible geometry, not one verified against a
+hydrogen. Aromatic detection covers the standard aromatic amino acids only;
+ligand rings appear as hydrophobic contacts.
+
+`interface_report` gives buried surface area per side. Under ~400 A^2 usually
+means crystal packing rather than a real interface; over ~1000 A^2 means a
+substantial, likely specific association. Say which regime the number is in.
+
+## Core workflow
+
+0. **Predicted structures.** `fetch_structure` also accepts a UniProt
+   accession (`P69905`, `af-P69905`) and routes it to AlphaFold DB, colouring
+   by pLDDT confidence; `fetch_alphafold` is the same thing called directly,
+   and takes `model_version` / `fragment` for older or split entries. For predicted models use `plddt_view`, never
+   `bfactor_view`/`putty_view` — pLDDT lives in the B-factor column and those
+   presets read it backwards (they assume low = rigid; low pLDDT = unreliable).
+0b. **Local files.** `load_structure(file_path, obj_name)` takes a PDB/mmCIF
+   off disk — a built model, a docking pose, an MD frame — and applies the
+   same multimer heuristic and styling as a fetch. Use it whenever the user
+   has a file rather than an accession.
+1. **`fetch_structure(pdb_code)`** — grabs the biological assembly when one
+   exists, runs a BFS chain-contact heuristic (`multimer_cutoff`, default
+   8.0 Å) so functional multimers stay whole while crystallographic copies
+   are dropped, hides waters/additives, and applies the default style. The
+   object is named after the PDB code unless `obj_name` is given.
+2. **Ground yourself before composing selections.** Use `list_objects`,
+   `list_chains(obj_name)`, `list_ligands(obj_name)` instead of guessing
+   object names, chain IDs, or 3-letter ligand codes.
+3. **Apply a view preset** (below) or build the scene manually.
+4. **Check a selection with `count_atoms`** before building a scene on it —
+   an empty selection is invisible until the render comes out blank.
+5. **Render with `render()`** — it ray-traces and returns the image directly,
+   so you can see the result and iterate. Prefer it over `ray` + `png`, which
+   only leave a file on disk. Pass `ray_trace=False` for a fast unshaded
+   check of a selection or orientation, and keep the width/height modest —
+   the image is inlined into the conversation.
+
+## View-preset catalogue
+
+All take `obj_name`. Each is a one-call scene.
+
+- **Binding / functional sites:** `ligand_view`, `pocket_view`,
+  `pharmacophore_view`, `interface_view` (chain–chain), `crosslink_view`
+  (disulfides & metal coordination), `mutation_view`.
+- **Per-residue scalar coloring:** `bfactor_view`, `putty_view` (B-factor as
+  tube width), `conservation_view` (evolutionary; first call hits the
+  ColabFold MMseqs2 API and is slow, then cached).
+- **Surface chemistry / electrostatics:** `hydrophobic_surface_view`,
+  `electrostatic_view` (approximate), `poisson_boltzmann_view` (true PB;
+  needs `apbs` + `pdb2pqr`).
+- **Illustrative:** `textbook_view` (cel-shaded; needs `ray`),
+  `cinematic_view` (fog/shadows; needs `ray`), `pointillist_view`.
+- **Predicted-model confidence:** `plddt_view` (AlphaFold pLDDT in the
+  official palette, plus a confidence breakdown).
+- **Comparing two structures:** `superposition_view(mobile, target)` —
+  superposes and colours the mobile structure by per-residue shift, so you
+  see *where* it moved rather than just an RMSD. Names the worst-shifted
+  residues.
+- **3D printing:** `print_ribbon_view` — see below.
+
+## Rendering, movies and sessions
+
+- `render(width, height, ray_trace, filename)` — the one to reach for. Returns
+  the image so you can look at it.
+- `turntable(obj_name, frames, out_dir)` — a 360° PNG sequence plus the
+  ffmpeg line to assemble it. Defaults to the fast renderer; `ray_trace=True`
+  is for finals only (36 traced frames of a big assembly can take an hour).
+- `save_session(filename)` / `load_session(filename)` — `.pse` round-trips
+  the whole scene (objects, colours, camera, scenes). Save before
+  experimenting with a scene that took effort to build.
+
+## Selection syntax (PyMOL)
+
+Selections are an algebra, not just residue lists:
+`chain A`, `resi 10-50`, `resn ATP`, `polymer.protein`, `organic`,
+`ss H` / `ss S` (helix/strand), `byres (... around 5)`, combined with
+`and`/`or`/`not` and parentheses. Cross-object selections are fine:
+`(1abc or 1abc_spine)`.
+
+## 3D-print STL export
+
+Two-step: configure the scene, then export.
+
+```
+print_ribbon_view(obj_name="1ema")
+print_export(obj_name="1ema", groups="1ema=(1ema or 1ema_spine)",
+             representation="cartoon", method="voxel", voxel_pitch=0.2)
+```
+
+`print_ribbon_view` builds chunky β-arrows + a fat helix and a separate
+`<obj>_spine` (`cartoon tube`, ignores secondary structure) that threads
+unbroken through every strand→loop junction — fused on export into one
+watertight solid, with the spine acting as internal rebar for rigidity.
+
+`print_export` key arguments:
+
+- **`representation`** — `"surface"` (default) exports the molecular
+  surface; **`"cartoon"`** exports the *currently displayed* cartoon/tube
+  geometry (what `print_ribbon_view` sets up). Using the default with a
+  ribbon scene silently gives you a surface blob.
+- **`method`** — `"voxel"` (robust for thin tubular ribbon geometry;
+  `voxel_pitch` ~0.2 keeps ribbon detail), `"poisson"` (bulky chains),
+  `"auto"`.
+- **`groups`** — `label=selection` pairs, one STL per colour. In cartoon
+  mode each group should name whole object(s).
+
+### Hard-won verification rules
+
+- **Verify the STL itself, not the viewport.** `ray`/`png` show the live
+  PyMOL scene, which can look like ribbons while the exported mesh is a
+  surface. PyMOL cannot load STL back, so inspect the file with the
+  project's own `trimesh` (already a `print`-extra dependency):
+  check `is_watertight`, `len(mesh.split())` (want **1** component), and
+  to tell ribbon from surface compare bbox-fill fraction and
+  area/volume — a ribbon is thin (low fill, high area/volume), a surface
+  is a fat shell.
+- **A printable result is watertight AND a single component.** Fragmented,
+  non-watertight output won't slice.
+- The STL is in the same coordinate frame across groups — in a slicer,
+  load the first then add others as *parts* (don't re-centre).
+
+### After editing anything under `src/mcpymol/`
+
+The MCP server imports the package at startup. Code changes are **not live**
+until the user reconnects it (`/mcp` → reconnect mcpymol, or restart Claude
+Code) — you cannot restart it yourself. After a reconnect, confirm the new
+behavior from tool output, don't assume it loaded (a stale server returns
+the old result).
+
+## Troubleshooting
+
+- *"Socket connection failed"* on every tool → PyMOL plugin not running /
+  server disconnected. Ask the user to reconnect mcpymol via `/mcp`.
+- Long `get_fastastr`/`get_chains` JSON parse errors → pre-2026-05 build.
+- `poisson_boltzmann_view` fails → missing `apbs`/`pdb2pqr`.
+- 3D-print tools say the `print` extra is missing → `uv sync --extra print`.
+- A tool reports a file "did not appear" → PyMOL and the bridge are not on the
+  same machine; they exchange files through the filesystem.
+- `render` returns a size complaint instead of an image → ask for a smaller
+  width/height, or raise `MCPYMOL_MAX_IMAGE_BYTES`.
+- A scene comes out blank → check the selection with `count_atoms` before
+  assuming the view preset failed.

mcpymol-1.5.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  # Python dependencies (pyproject.toml + uv.lock).
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-deps:
+        patterns: ["*"]
+    open-pull-requests-limit: 5
+
+  # Keep the SHA-pinned GitHub Actions current.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns: ["*"]

mcpymol-1.5.0/.github/workflows/ci.yml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref (saves CI minutes on rapid pushes).
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lockfile:
+    name: Lockfile in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      # Fails fast and unambiguously if uv.lock drifts from pyproject.toml,
+      # instead of the error hiding inside every Tests (pyX.Y) install step.
+      - name: uv.lock matches pyproject.toml
+        run: uv lock --locked
+
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      - name: ruff check
+        run: uv run ruff check --output-format=github .
+      - name: ruff format
+        run: uv run ruff format --check --diff .
+
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      # The print extra must be installed or trimesh resolves to Any under
+      # ignore_missing_imports, and mypy silently skips the mesh-repair code —
+      # the one place in the tree doing real work against a third-party API.
+      - run: uv sync --locked --all-groups --extra print
+      - run: uv run mypy
+
+  test:
+    name: Tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      # --locked fails if uv.lock is stale relative to pyproject.toml,
+      # catching dependency drift before it reaches a release.
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+      - name: Run pytest
+        run: >
+          uv run pytest tests/ -v
+          --cov=mcpymol --cov-report=term-missing --cov-report=xml
+
+  print-extra:
+    name: Print extra imports
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      # The `print` extra pulls heavy native deps (pymeshlab, scipy). This
+      # job just proves that code path still imports — it is silent otherwise.
+      - name: Install with print extra
+        run: uv sync --locked --extra print
+      - name: Import print_export
+        run: uv run python -c "from mcpymol.server import print_export; print('print_export import OK')"
+
+  build:
+    name: Build & metadata check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Validate package metadata
+        run: uv run --with twine twine check dist/*
+
+  security:
+    name: Dependency audit (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      # Advisory: a CVE in a transitive dep should be visible but should not
+      # block unrelated PRs. Step-level continue-on-error keeps the check
+      # green; triage via the run log / Dependabot alerts.
+      - name: pip-audit
+        run: uv run --with pip-audit pip-audit
+        continue-on-error: true

mcpymol-1.5.0/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,42 @@
+name: Dependabot auto-merge
+
+# Queues Dependabot's patch and minor updates to merge themselves once every
+# required check passes. Major bumps are left for a human, because those are
+# the ones that change behaviour.
+#
+# Auto-merge does not bypass anything: main requires nine green checks and an
+# up-to-date branch, so this only removes the manual click, never the gate.
+
+on: pull_request_target
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    name: Enable auto-merge
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      # NB: pull_request_target runs with write access in the base repo's
+      # context. Nothing here checks out the PR's code, which is what makes
+      # that safe — do not add actions/checkout of the head ref.
+      - name: Inspect the update
+        id: metadata
+        uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
+
+      - name: Enable auto-merge for patch and minor updates
+        if: steps.metadata.outputs.update-type != 'version-update:semver-major'
+        run: gh pr merge --auto --rebase "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Leave major updates for review
+        if: steps.metadata.outputs.update-type == 'version-update:semver-major'
+        run: |
+          gh pr comment "$PR_URL" --body             "Major version bump — not auto-merging. Worth reading the changelog before this lands."
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mcpymol-1.5.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+# Publishing is driven by tags, not by pushes to main: the tag is the record
+# of what was released, and a PyPI version is immutable once it exists.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build & verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # A published version can never be replaced, only superseded by another
+      # release. Tagging v1.5.0 while pyproject still says 1.4.0 would upload
+      # 1.4.0 under a v1.5.0 tag and burn the version number permanently, so
+      # this checks the tag against the artefacts that are about to be
+      # uploaded rather than against the source it was built from.
+      - name: Tag matches built version
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          if [ ! -f "dist/mcpymol-${version}.tar.gz" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} implies version ${version}, but that is not what was built. Bump the version in pyproject.toml, or retag. dist/ contains:"
+            ls -1 dist/
+            exit 1
+          fi
+
+      - name: Validate package metadata
+        run: uv run --with twine twine check dist/*
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing (OIDC): PyPI verifies this exact repository, workflow
+    # filename and environment, and hands back a short-lived token. There is
+    # no API token stored in the repo to leak or rotate — but it does mean the
+    # three names below are load-bearing and must match the pending publisher
+    # registered on PyPI. Renaming this file breaks publishing.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcpymol
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

mcpymol-1.5.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+refresh/
+
+# Editor / OS / local agent artifacts
+.DS_Store
+.idea/
+.vscode/
+.claude/*
+!.claude/skills/
+.gemini/
+
+# Build artifacts
+build/
+dist/
+
+# Project stubs / leftovers
+main.py
+*.mc
+
+# Structural data (downloaded on demand)
+*.pdb
+*.cif
+*.mmtf
+
+# Media (keep README assets)
+*.mp4
+*.gif
+*.png
+!assets/*.png
+!assets/*.gif

mcpymol-1.5.0/.pre-commit-config.yaml

@@ -0,0 +1,86 @@
+# Local gates that mirror CI, so a formatting slip is caught before it becomes
+# a red pipeline (and, in a stacked branch, a rebase of everything above it).
+#
+# Run `pre-commit install` once after cloning. See CONTRIBUTING.md.
+#
+# Why the linters run through `uv run` as `language: system` rather than
+# pre-commit's own ruff/mypy repos: those would pin their own tool versions in
+# this file, giving the project two sources of truth that drift apart until a
+# hook passes locally and CI fails (or worse, the reverse). Going through uv
+# means the hooks use exactly the versions in uv.lock — the same ones CI
+# installs.
+
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      # Whitespace and newline hygiene, which otherwise shows up as noise in
+      # unrelated diffs.
+      - id: trailing-whitespace
+        # Markdown uses two trailing spaces as a hard line break.
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      # Config files that break the build if malformed.
+      - id: check-yaml
+      - id: check-toml
+      # Things that should never reach a commit.
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: debug-statements
+      - id: check-added-large-files
+        # Structures and renders are gitignored; this catches the ones that
+        # slip past, since a stray PDB or PNG is easy to add and hard to remove.
+        # Sized to catch accidents rather than curated media: a downloaded
+        # assembly or a ray-traced PNG runs to several MB, while the largest
+        # deliberate asset here is an 830 KB turntable GIF.
+        args: [--maxkb=1024]
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --force-exclude --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format --force-exclude
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      - id: mypy
+        name: mypy
+        # mypy reads `files` and its settings from pyproject.toml, so it runs
+        # over the whole package rather than the staged subset — passing
+        # filenames would silently override that config.
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+        files: ^(src/.*\.py|pyproject\.toml)$
+        require_serial: true
+
+      - id: uv-lock-check
+        name: uv.lock in sync with pyproject.toml
+        # Mirrors the CI "Lockfile in sync" job: blocks the commit if the
+        # lockfile is stale so it never reaches a push / the test matrix.
+        entry: uv lock --locked
+        language: system
+        files: ^(pyproject\.toml|uv\.lock)$
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        # Deliberately pre-push, not pre-commit: the suite takes ~16 s, which
+        # is too slow to pay on every commit but unremarkable on a push.
+        entry: uv run pytest -q
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+        require_serial: true

mcpymol-1.5.0/.python-version

@@ -0,0 +1 @@
+3.13