datalox-protein-mcp

Headless Protein MCP package for workspace, validation, metadata, ligand annotation, compact protein viewing, and MCP server tools.

This package intentionally does not build or install PyMOL. Live PyMOL support is an optional host adapter used from an already-running PyMOL process.

Install

Ephemeral MCP client install:

uvx --from datalox-protein-mcp protein-mcp mcp --stdio --headless

Persistent CLI install:

pipx install datalox-protein-mcp
protein-mcp doctor --json

Wheel install for validation:

python -m venv /tmp/protein-mcp-fresh
/tmp/protein-mcp-fresh/bin/python -m pip install dist/protein-mcp/datalox_protein_mcp-0.1.0-py3-none-any.whl
/tmp/protein-mcp-fresh/bin/protein-mcp doctor --json

MCP Registration

Ephemeral MCP registration:

{
  "mcpServers": {
    "protein-mcp": {
      "command": "uvx",
      "args": ["--from", "datalox-protein-mcp", "protein-mcp", "mcp", "--stdio", "--headless"]
    }
  }
}

Persistent install registration:

pipx install datalox-protein-mcp
protein-mcp mcp-config --install path --command "$(which protein-mcp)" --json

Installed wheel registration smoke:

/tmp/protein-mcp-fresh/bin/protein-mcp mcp-config \
  --install path \
  --command /tmp/protein-mcp-fresh/bin/protein-mcp \
  --json

One-Call MCP App Viewer

Use visualize_protein first when the user gives a PDB, mmCIF, or CIF file and asks to view, inspect, or change it.

Agent MCP workflow:

visualize_protein -> get_structure_context -> update_protein_view
visualize_protein -> list_ligands -> annotate_binding_site -> get_scene_annotations

By default, visualize_protein creates or reuses protein.workspace.json and returns the compact viewer MCP App resource:

ui://protein-mcp/compact-viewer-v1.html

Use open_structure -> open_protein_viewer only when an agent intentionally needs separate data and render phases.

Durable Local Viewer

For shell-only agents or hosts without MCP App rendering, request a durable local viewer URL:

visualize_protein(..., launch="localhost")

CLI durable preview:

protein-mcp preview /path/to/protein.workspace.json --detach --no-open --json

The JSON result includes url, pid, logPath, pidPath, health, and stopCommand. Stop the detached viewer when it is no longer needed:

protein-mcp stop-viewer --pid 12345 --json

open-viewer remains available as a foreground server command, but agents should use preview --detach when returning a URL to a human after the command exits.

Ligand Annotation

annotate_binding_site computes factual ligand contact residues and writes structured labels, distance measurements, and scene notes to the workspace. The compact viewer renders those annotations without requiring PyMOL.

CLI annotation path:

protein-mcp list-ligands /path/to/protein.workspace.json --structure target --json
protein-mcp annotate-binding-site /path/to/protein.workspace.json \
  --structure target \
  --ligand HEM:A:142 \
  --radius 4.5 \
  --max-contacts 24 \
  --json
protein-mcp get-scene-annotations /path/to/protein.workspace.json --json

Skill Export For CLI-Only Agents

CLI-only agents can export packaged Protein MCP instructions:

protein-mcp agent-skill --target /path/to/skills --json

The exported skill tells agents to prefer MCP tools, use visualize_protein first, use launch="localhost" for durable URLs, and clean up detached viewers with stop-viewer.

What This Package Does Not Install

The headless package does not install or require:

• PyMOL
• Qt
• Node
• Vite
• Playwright

Live PyMOL validation requires an environment where PyMOL is already importable:

protein-mcp verify-live-alpha \
  --structure /absolute/path/to/1CRN.pdb \
  --json

Live HTTP MCP binds to 127.0.0.1 by default. Public binding requires the explicit --unsafe-public-bind flag.

Maintainer Release

These commands are for release CI and maintainers only. MCP clients, agents, and end users should not run them as installation steps.

cd packages/protein-mcp-viewer
npm ci
npm run check
npm run build
npm test

cd ../..
python -m pytest testing/protein_mcp_tests -q
python -m build packages/protein-mcp