Metadata-Version: 2.4
Name: datalox-protein-mcp
Version: 0.1.0
Summary: Headless Protein MCP workspace, compact viewer, and MCP server tools.
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/Oshawott324/datalox-protein-mcp
Project-URL: Repository, https://github.com/Oshawott324/datalox-protein-mcp
Project-URL: Issues, https://github.com/Oshawott324/datalox-protein-mcp/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.11
Requires-Dist: gemmi>=0.7.5
Requires-Dist: mcp>=1.27.0
Provides-Extra: live
Requires-Dist: numpy>=2.0; extra == "live"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"

# 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:

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

Persistent CLI install:

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

Wheel install for validation:

```bash
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:

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

Persistent install registration:

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

Installed wheel registration smoke:

```bash
/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:

```text
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:

```text
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:

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

CLI durable preview:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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
```
