# Molclaw Interaction Visualizer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-internscience-molclaw-molclaw-interaction-visualizer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [InternScience](https://agentstack.voostack.com/s/internscience)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [InternScience](https://github.com/InternScience)
- **Source:** https://github.com/InternScience/MolClaw/tree/main/skills/L1_tools/molclaw-interaction-visualizer

## Install

```sh
agentstack add skill-internscience-molclaw-molclaw-interaction-visualizer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Interaction Visualizer — Local Analysis & Visualization

Note: 
- Local files are not directly accessible by the server. Please upload them to the server using `molclaw-file-transfer` before execution. 
- For PDB file inputs, it is recommended to preprocess them using `molclaw-pdbfixer` before execution.
- Please refer to skill `molclaw-scp-server` to complete tool invocation.

> [!NOTE]
> This is a **local tool** — the Python script `molclaw_interaction_visualizer.py` runs
> directly on the compute node. No MCP server connection needed.
> **Required:** `numpy`, `matplotlib`.
> **Optional:** `rdkit` (for 2D ligand diagram + SDF/MOL2/XYZ input), `pymol` (for 3D rendering), `Pillow`.

## 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-pdbfixer`, or predicted structure |
| `--ligand` | Docking pose file from `molclaw-quickvina-docking` (.pdbqt), `molclaw-diffdock-auto` (.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 |

## Setup — Upload Script to Server

```python
# Upload the interaction visualizer script to the server
response = await client.session.call_tool(
    "upload_file",
    arguments={"local_path": "/path/to/molclaw_interaction_visualizer.py"}
)
script_path = client.parse_result(response)["remote_path"]
```

Alternatively, if the script is already present on the server at a known path, skip the upload step.

## 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 \
    --delta_score -1.2
```

Supported ligand formats for auto-merge: `.sdf`, `.mol`, `.mol2`, `.pdb`, `.pdbqt`, `.xyz`.

### Pattern 3: Peptide–Protein Interface

```bash
python molclaw_interaction_visualizer.py \
    --complex complex.pdb \
    --mode peptide \
    --partner_chain B \
    --out_dir viz_out \
    --title "PD1–PeptideBinder"
```

### Pattern 4: Protein–Protein Interface (Separate Files)

```bash
python molclaw_interaction_visualizer.py \
    --receptor chain_A.pdb \
    --partner_pdb chain_B.pdb \
    --mode protein \
    --chain_a A \
    --chain_b B \
    --out_dir viz_out \
    --title "IL6–IL6R interface"
```

### Pattern 5: Quick CSV-Only (Skip All Plots)

For agent-only consumption when visualizations are not needed:

```bash
python molclaw_interaction_visualizer.py \
    --complex complex.pdb \
    --mode ligand \
    --ligand_resname LIG \
    --out_dir viz_out \
    --skip_diagram2d --skip_bar --skip_heatmap --skip_network --skip_pymol3d
```

## Full Parameter Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `--complex` | str | — | Single PDB/PDBQT file containing receptor + partner |
| `--receptor` | str | — | Receptor-only file (used with `--ligand` or `--partner_pdb`; alternative to `--complex`) |
| `--ligand` | str | — | Ligand-only file (.sdf/.mol/.mol2/.pdb/.pdbqt/.xyz); used with `--receptor` in ligand mode |
| `--partner_pdb` | str | — | Partner protein PDB for peptide/protein modes when receptor and partner are separate files |
| `--merged_out` | str | `OUT_DIR/auto_merged.pdb` | Path to save the auto-merged complex (when using --receptor + --ligand/--partner_pdb) |
| `--mode` | str | `ligand` | Analysis mode: `ligand`, `peptide`, or `protein` |
| `--ligand_resname` | str | — | (ligand mode) Restrict partner to a specific HETATM residue name |
| `--partner_chain` | str | — | (peptide mode) Chain ID of the peptide partner |
| `--chain_a` | str | — | (protein mode) Receptor chain ID |
| `--chain_b` | str | — | (protein mode) Partner chain ID |
| `--out_dir` | str | `viz_out` | Output directory (created if missing) |
| `--resid_offset` | int | `0` | Added to receptor resid in CSV output for PDB→UniProt mapping (L3 Principle 17) |
| `--title` | str | `""` | Common title prefix for all figures |
| `--score` | float | — | Docking score (kcal/mol) displayed in 2D diagram header |
| `--delta_score` | float | — | ΔScore vs baseline displayed in 2D diagram header |
| `--smiles` | str | — | Ligand SMILES displayed in 2D diagram footer |
| `--residue_roles_json` | str | — | JSON file mapping residues to functional roles: `{"MET769":"Hinge", "THR766":"Gatekeeper", ...}` |
| `--ligand_scale` | float | `1.0` | Scale factor for ligand drawing in 2D diagram (0.8=smaller, 1.3=larger) |
| `--top_n_bar` | int | `20` | Number of residues shown in stacked bar chart |
| `--heatmap_cutoff` | float | `4.5` | Atom-pair distance cutoff (Å) for interface heatmap |
| `--skip_diagram2d` | flag | — | Skip 2D interaction diagram generation |
| `--skip_bar` | flag | — | Skip residue stacked bar chart |
| `--skip_heatmap` | flag | — | Skip interface heatmap (peptide/protein modes) |
| `--skip_network` | flag | — | Skip interface network diagram (peptide/protein modes) |
| `--skip_csv` | flag | — | Skip CSV export |
| `--skip_pymol3d` | flag | — | Skip PyMOL 3D rendering |
| `--pymol_width` | int | `1400` | Width of PyMOL ray-traced images |
| `--pymol_height` | int | `1200` | Height of PyMOL ray-traced images |

## Output Files and Download Policy

### Ligand Mode Outputs

| Output File | Format | Download Policy | Consumed By |
|-------------|--------|-----------------|-------------|
| `interactions_{label}.csv` | CSV | **A — MUST download** | L2-08 consensus ranking, L2-05 optimization diagnosis |
| `interactions_{label}_residue_summary.csv` | CSV | **A — MUST download** | Residue-level SAR analysis |
| `interactions_{label}_partner_site.csv` | CSV | **A — MUST download** | Ligand modification hotspot identification |
| `diagram2d_{label}.png` | PNG | **A — MUST download** (L3 P15) | Report, user presentation |
| `residue_bar_{label}.png` | PNG | **A — MUST download** (L3 P15) | Report |
| `scene_{label}.pml` | PML script | B — record path in log | PyMOL manual inspection |
| `pymol_{label}_{front,side,top}.png` | PNG | **A — MUST download** (if generated) | Report 3D views |
| `summary_{label}.json` | JSON | **A — MUST download** | Agent decision loop integration |

### Peptide / Protein Mode Additional Outputs

| Output File | Format | Download Policy | Consumed By |
|-------------|--------|-----------------|-------------|
| `interface_heatmap_{label}.png` | PNG | **A — MUST download** (L3 P15) | Interface quality evaluation |
| `interface_network_{label}.png` | PNG | **A — MUST download** (L3 P15) | Interface topology analysis |

## CSV Column Specification

### `interactions_{label}.csv` — Per-Interaction Detail

| Column | Description |
|--------|-------------|
| `type` | Normalized interaction type (HBond, SaltBridge, PiStacking, CationPi, Halogen, Metal, Hydrophobic, VdW) |
| `subtype` | Direction/variant (LigDonor, ProtDonor, FaceToFace, EdgeToFace, etc.) |
| `rec_res` | Receptor residue label (e.g., MET769A) |
| `rec_resid_pdb` | Receptor residue number in PDB numbering |
| `rec_resid_mapped` | Receptor residue number after applying `--resid_offset` (for UniProt mapping) |
| `rec_res_class` | Residue classification (hydrophobic, aromatic, polar, positive, negative) |
| `rec_atom` | Receptor atom name(s) involved |
| `partner_atom` | Partner atom name(s) involved |
| `distance_A` | Interaction distance in Ångströms |
| `angle_deg` | Relevant geometry angle in degrees (if applicable) |
| `strength_hint` | Qualitative label: strong / moderate / weak / packing / contact |

### `*_residue_summary.csv` — Per-Residue Rollup

One row per contacting residue, columns for each interaction type count, total count, and minimum distance.

### `*_partner_site.csv` — Ligand Atom Hotspot (Ligand Mode Only)

One row per ligand atom involved in interactions, columns for each interaction type count. Use this to identify:
- **Atoms to preserve:** high total count → critical pharmacophore points
- **Atoms to modify:** low or zero count → optimization candidates

## Interpreting `summary_{label}.json` (Agent Decision Integration)

```json
{
  "mode": "ligand",
  "label": "LIG",
  "n_interactions": 42,
  "n_contact_residues": 15,
  "interaction_type_counts": {
    "HBond": 3, "SaltBridge": 1, "PiStacking": 2,
    "CationPi": 0, "Halogen": 0, "Metal": 0,
    "Hydrophobic": 8, "VdW": 15
  },
  "top_residues": [
    {"res": "MET769A", "class": "hydrophobic", "total": 5,
     "by_type": {"HBond": 2, "Hydrophobic": 3}},
    {"res": "LEU694A", "class": "hydrophobic", "total": 4,
     "by_type": {"Hydrophobic": 4}}
  ],
  "hot_partner_sites": [
    {"partner_atom": "N3", "total": 4,
     "by_type": {"HBond": 2, "PiStacking": 2}},
    {"partner_atom": "C15", "total": 1,
     "by_type": {"Hydrophobic": 1}}
  ],
  "outputs": { ... }
}
```

**Agent decision rules:**
- `top_residues` → Verify expected key contacts match the task requirements (e.g., "confirm hinge interaction with Met793").
- `hot_partner_sites` → Atoms with high `total` and strong interaction types (HBond, SaltBridge) should be **preserved** during optimization. Atoms with low `total` are safe **modification candidates**.
- `interaction_type_counts` → A molecule with 0 HBonds to the hinge region is likely a poor kinase inhibitor candidate; flag for re-evaluation.

## Residue Numbering Reconciliation (L3 Principle 17 — MANDATORY)

Use `--resid_offset N` where `N = UniProt_number − PDB_number` for the protein.

**Example:** If PDB 1M17 has Met at position 769, but UniProt numbering is Met793, then `--resid_offset 24`.

All CSV outputs include a `rec_resid_mapped` column with the offset applied. When reporting results:

- **CORRECT:** "Interaction visualizer detected HBond at MET769 (PDB) = Met793 (UniProt, offset +24). This confirms the expected hinge interaction."
- **WRONG:** "Interaction visualizer did not find Met793." (False negative from numbering mismatch.)

For Boltz-2/Chai-1 predicted structures where the offset is non-trivial, compute the offset from sequence alignment BEFORE running this tool.

## Strength Hints (Qualitative — NOT Quantitative Energies)

| Type | "strong" | "moderate" | "weak" / "packing" / "contact" |
|------|----------|------------|--------------------------------|
| HBond | d ≤ 2.9 Å and ∠ ≥ 150° | d ≤ 3.2 Å and ∠ ≥ 130° | otherwise |
| SaltBridge | d ≤ 4.0 Å | d > 4.0 Å | — |
| PiStacking | d ≤ 4.5 Å | d > 4.5 Å | — |
| Hydrophobic | — | — | "packing" (always) |
| VdW | — | — | "contact" (always) |

These are qualitative drug-chemist-style labels. They are NOT quantitative binding energy estimates. Do not use them as substitutes for MM-PBSA or FEP calculations.

## Common Failures & Recovery

| Failure | Likely Cause | Recovery |
|---------|-------------|----------|
| `No atoms parsed from {path}` | Wrong file format, empty file, or binary format given as text | Verify file is valid PDB/PDBQT; check encoding |
| `Partner atom list empty` | Ligand resname not found in PDB, or wrong `--partner_chain` | Check `--ligand_resname` matches actual HETATM resname in PDB; verify chain IDs |
| `RDKit failed to build ligand mol` | Bond perception or sanitization issue with ligand | 2D diagram skipped; CSV and all other outputs still produced. Install/upgrade rdkit if needed |
| 2D diagram PNG not generated | RDKit not installed | `pip install rdkit`; or accept CSV-only output and use `--skip_diagram2d` |
| PyMOL images not generated | PyMOL not on system PATH | Install PyMOL (`conda install -c conda-forge pymol-open-source`); or use `--skip_pymol3d` |
| 0 interactions detected | Ligand not in binding pocket (bad docking pose) or atoms too far apart | Verify docking pose quality upstream; re-dock with larger box |
| Auto-merge PDBQT fails | PDBQT has non-standard formatting | Convert PDBQT → PDB first using OpenBabel, then use `--ligand pose.pdb` |
| `AssertionError: --partner_chain required` | Peptide mode invoked without chain specification | Inspect PDB chain IDs and provide `--partner_chain` |

## Integration with Upstream Skills

| Upstream Skill | Provides | This Skill Uses As |
|----------------|----------|--------------------|
| `molclaw-quickvina-docking` | PDBQT docking pose + affinity score | `--ligand` (PDBQT) + `--score` |
| `molclaw-diffdock-auto` | SDF docking pose + confidence | `--ligand` (SDF) + `--score` |
| `molclaw-karmadock-tool` | SDF docking pose + score | `--ligand` (SDF) + `--score` |
| `molclaw-pdbfixer` | Cleaned receptor P

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [InternScience](https://github.com/InternScience)
- **Source:** [InternScience/MolClaw](https://github.com/InternScience/MolClaw)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-internscience-molclaw-molclaw-interaction-visualizer
- Seller: https://agentstack.voostack.com/s/internscience
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.