molclaw-hdock-tool

name	molclaw-hdock-tool
description	Run HDOCKlite docking for protein complexes and return run directories with ranked models.
license	MIT license
metadata	{"skill-author":"PJLab"}

HDOCK Protein Docking

Usage

Note:

• Local files are not directly accessible by the server. Please upload them to the server using drugsda-file-transfer before execution.
• For PDB file inputs, it is recommended to preprocess them using drugsda-fix_pdb before execution.

2. HDOCK Protein Docking

The description of tool hdock_tool.

Run HDOCKlite protein docking and return the unique run directory, key files, and summary metrics for structure-based screening workflows.
Args:
    receptor (str): Receptor PDB file path.
    ligand (str): Ligand or partner PDB file path.
    nmax (int): Number of docking models to generate (default 100).
    no_complex (bool): Disable complex structure generation (default False).
    angle (int): Rotation sampling interval in degrees (default 15).
    rsite (str|None): Optional receptor binding-site residue file.
    lsite (str|None): Optional ligand binding-site residue file.
Return:
    status (str): success, partial_success, or error execution status.
    msg (str): Human-readable execution summary.
    output_dir (str): Unique run directory under tool_result/hdock_tool_result.
    receptor (str): Resolved receptor input path.
    ligand (str): Resolved ligand input path.
    nmax (int): Effective model count upper bound used.
    no_complex (bool): Effective no-complex flag used.
    angle (int): Effective angle parameter used.
    rsite (str|None): Effective receptor site file used.
    lsite (str|None): Effective ligand site file used.
    output_files (dict): Key generated file paths such as Hdock.out, topN.pdb, and best models.
    metrics (dict): Summary metrics including generated model count and best docking score when available.

Scoring Interpretation (HDOCK)

• HDOCK Docking Score is a relative ranking score. Values are usually negative, and more negative means better predicted binding.
• The score combines shape complementarity (FFT search), electrostatic interactions, and desolvation-like energy terms.
• model_1.pdb is the top-ranked pose generated by createpl; model_2.pdb to model_10.pdb are sorted from better to worse by docking score.
• Do not interpret HDOCK score as an absolute binding free energy in kcal/mol. Use it for within-run pose ranking and candidate prioritization.

How to use tool hdock_tool :

response = await client.session.call_tool(
    "hdock_tool",
    arguments={
        "receptor": "/path/to/receptor.pdb",
        "ligand": "/path/to/ligand.pdb",
        "nmax": 10,
        "angle": 15
    }
)
result = client.parse_result(response)
key_output = result["output_dir"]

Example parameter sets

# 1) Main mode: basic docking run (from README/test flow)
{
    "receptor": "/path/to/receptor.pdb",
    "ligand": "/path/to/ligand.pdb",
    "nmax": 10,
    "angle": 15,
    "no_complex": False
}

# 2) Variant mode: light sampling with complex generation disabled and defined sites
{
    "receptor": "/path/to/receptor.pdb",
    "ligand": "/path/to/ligand.pdb",
    "nmax": 5,
    "angle": 10,
    "no_complex": True,
    "rsite": "/path/to/rsite.txt",
    "lsite": "/path/to/lsite.txt"
}

# 3) Variant mode: exhaustive sampling with default complex outputs
{
    "receptor": "/path/to/receptor.pdb",
    "ligand": "/path/to/ligand.pdb",
    "nmax": 100,
    "angle": 15
}

---

⚠ Mandatory Output File Download (L3 Principle 14)

After calling this tool, you MUST download all output structure files from the MCP server to the local workspace using server_file_to_base64. A tool call is NOT considered complete until its output files have been downloaded and verified locally (ls -la <file> — size must be > 0).

import base64, os
response = await client.session.call_tool(
    "server_file_to_base64",
    arguments={"file_path": result["output_file"]}  # or relevant output field
)
dl = client.parse_result(response)
local_path = "stepNN_descriptive_name.ext"
with open(local_path, "wb") as f:
    f.write(base64.b64decode(dl["base64_string"]))
assert os.path.getsize(local_path) > 0, f"Download failed: {local_path}"

Download policy: All structure output files are Category A (user-critical) — essential for user verification, downstream analysis, and reproducibility. When in doubt, download. Over-collection is always preferred over under-collection.

Specific files to download from HDOCK output: All ranked docked complex PDB models (typically model_1.pdb through model_10.pdb). At minimum, download the top-ranked model. These are Category A files essential for downstream ProLIF protein-protein analysis.