molclaw-interaction-visualizer

Files (2)

• SKILL.md
• molclaw_interaction_visualizer.py

SKILL.md (first lines)

# Interaction Visualizer — MCP and Local Analysis

## Invocation

Use the exact tool name and parameter schema exposed by the current harness. Tool names in SDK examples below are raw MCP names, not model-facing aliases. Local files must be uploaded with `molclaw-file-transfer` before a server tool can use them. Repair PDB inputs first when the workflow requires it.

> [!NOTE]
> The current MolClaw server exposes this capability as the MCP tool
> `interaction_visualizer`. The bundled `molclaw_interaction_visualizer.py` remains
> available as an optional local CLI; it does not need to be uploaded to the server.

## When To Use This Skill

> **This is the PRIMARY tool for all single-structure interaction analysis.**
> ProLIF is only needed for batch docking fingerprint comparison or MD trajectory dynamics.

| Scenario | Use this skill | Use ProLIF instead |
|----------|:--------------:|:------------------:|
| **Single complex structure interaction analysis** | ✅ **PRIMARY** | Only if this tool unavailable |
| **Peptide or protein-protein interface analysis (single structure)** | ✅ **PRIMARY** | Only if this tool unavailable |
| Need Schrödinger-style 2D interaction diagram | ✅ | ❌ |
| Need PyMOL 3D multi-angle renderings | ✅ | ❌ |
| Need residue role annotations (Hinge/Gatekeeper/DFG) | ✅ | ❌ |
| Need decision-ready JSON with top residues + hot sites | ✅ | ❌ |
| Need `partner_site.csv` for ligand atom modification diagnosis | ✅ | ❌ |
| Need interaction fingerprint across MD trajectory frames | ❌ | ✅ `prolif_md` |
| Need batch docking pose fingerprint comparison (≥ 2 poses) | ❌ | ✅ `prolif_docking` |
| Need protein-protein trajectory interface profiling | ❌ | ✅ `prolif_protein_protein` |

## Interaction Types Detected

| # | Type | Key Geometry | Default Cutoff |
|---|------|-------------|----------------|
| 1 | Hydrogen bond | D-H···A angle ≥ 130° | 3.5 Å |
| 2 | Hydrophobic contact | C···C distance | 4.5 Å |
| 3 | π-π stacking (Face-to-Face) | Ring plane ∠ ≤ 35° | 5.5 Å |
| 4 | π-π stacking (Edge-to-Face) | Ring plane ∠ 50°–90° | 6.5 Å |
| 5 | Salt bridge | Charge center distance | 5.5 Å |
| 6 | Cation-π | Cation-centroid + normal ∠ | 6.0 Å |
| 7 | Halogen bond | X···A with A-X-D geometry | 3.5 Å |
| 8 | Metal coordination | Metal···coordinating atom | 3.0 Å |
| 9 | van der Waals | Sum of VdW radii + tolerance | +0.5 Å |

## Three Analysis Modes

- **`ligand`** (default): Small-molecule ligand vs protein. Partner identified by HETATM
  records or `--ligand_resname`. Produces 2D diagram + residue bar + partner site CSV.
- **`peptide`**: One protein chain as partner peptide. Requires `--partner_chain`.
  Produces interface heatmap + interface network + residue bar.
- **`protein`**: Two full protein chains. Requires `--chain_a` and `--chain_b`.
  Produces interface heatmap + interface network + residue bar.

## Input Source Mapping

| Parameter | Source Guidance |
|-----------|----------------|
| `--complex` | Pre-merged complex PDB from docking output, Boltz-2/Chai-1 predicted structure, MD extracted frame, or crystal structure |
| `--receptor` | Protein PDB from `molclaw-protein-structure-retrieve` → `molclaw-fix-pdb`, or predicted structure |
| `--ligand` | Docking pose file from `molclaw-quickvina-docking` (.pdbqt), `molclaw-karmadock-tool` (.sdf), an externally supplied DiffDock SDF, or any .mol/.mol2/.xyz |
| `--partner_pdb` | Partner protein PDB for peptide/protein modes (from `molclaw-extract-chains` or separate structure) |
| `--resid_offset` | PDB→UniProt offset computed from sequence alignment (L3 Principle 17) |
| `--residue_roles_json` | User-provided or literature-derived residue functional annotations |
| `--score` | Docking affinity from upstream docking tool (kcal/mol) |
| `--smiles` | Ligand SMILES from user input or molecule retrieval |

## MCP Invocation

```python
response = await client.session.call_tool(
    "interaction_visualizer",
    arguments={
        "mode": "ligand",
        "receptor_path": "/server/path/receptor_fixed.pdb",
        "ligand_path": "/server/path/docking_pose.pdbqt",
        "resid_offset": 0,
        "score": -8.3,
        "skip_pymol3d": True
    }
)
result = client.parse_result(response)
output_dir = result["output_dir"]
key_files = result["key_files"]
```

`mode` is required and must be one of `ligand`, `peptide`, or `protein`. Input paths
must be server-side paths; use `molclaw-file-transfer` for local input files.

## Bundled Local CLI Usage Patterns

### Pattern 1: Single Complex File (Ligand Mode)

For a pre-merged complex PDB containing both protein and ligand:

```bash
python molclaw_interaction_visualizer.py \
    --complex complex.pdb \
    --mode ligand \
    --ligand_resname LIG \
    --out_dir viz_out \
    --resid_offset 0 \
    --title "EGFR–Erlotinib" \
    --score -8.3 \
    --smiles "C=Cc1cccc(Nc2ncnc3cc(OCCOC)c(OCCOC)cc23)c1"
```

### Pattern 2: Separate Receptor + Ligand Files (Auto-Merge)

When receptor and ligand come from different upstream tools (e.g., PDBFixer output + docking pose PDBQT/SDF). The script automatically converts the ligand format and merges into a single complex.

```bash
python molclaw_interaction_visualizer.py \
    --receptor receptor_fixed.pdb \
    --ligand docking_pose_best.sdf \
    --mode ligand \
    --out_dir viz_out \
    --resid_offset 574 \
    --residue_roles_json roles.json \
    --title "CDK2–Compound_7" \
    --score -9.1 \

From InternScience/MolClaw, MIT.

More from InternScience/MolClaw