heracleum-tox-mcp-server

An MCP server that reproduces the results of:

Rassabina, A.E.; Fedorov, M.V. Analysis of the Toxicological Profile of Heracleum sosnowskyi Manden. Metabolites Using In Silico Methods. Plants 2025, 14, 3253. https://doi.org/10.3390/plants14213253

The paper runs entirely on the proprietary Syntelly platform. Since Syntelly is not openly accessible, this server reproduces the same pipeline with open-source analogues of every Syntelly module — including the very models Syntelly itself uses (fingerprint-based CatBoost + fragment-based XGBoost; Sosnin et al., Molecules 2024, 29, 1826, the platform paper cited as ref. [36]), trained on the same open datasets the paper names (TOXRIC / ChemIDplus / PyTDC).

Syntelly → open-source analogue mapping

Related MCP server: Comptox MCP Server

Tools

Each tool returns {"answer": ..., "metadata": ...}. Where a tool returns an answer.finding, that string is computed from the values returned in that same call — no hardcoded conclusions. (estimate_synthesis_cost and predict_molecule_profile return raw per-molecule numbers and no finding; values under metadata.paper are the paper's published figures, quoted, not recomputed.) Figures are saved as PNG to a local artifacts dir (HERACLEUM_ARTIFACTS_DIR) or, if S3 is configured, uploaded and returned as structured presigned references with SHA-256. S3 configuration is all-or-none and checked with HeadBucket at startup; upload errors do not silently become paths inside the container unless HERACLEUM_S3_ALLOW_LOCAL_FALLBACK=true is set explicitly for development. When Docker uses http://minio:9000 for upload, set HERACLEUM_S3_PUBLIC_ENDPOINT_URL to the caller-reachable signing endpoint.

Tool naming (collision avoidance)

dataset_overview, reproduce_all and reproduce_claims exist under those exact names in the sibling servers (tox-antitargets-mcp-server, cannabis-biopesticide-mcp-server) too. When several of them are registered at once the agent sees duplicate names and mis-routes — in one observed run it invented a non-existent tool tox_reproducer instead of calling reproduce_claims. Those three tools are therefore exposed to the agent under heracleum_-prefixed names via the FastMCP @mcp.tool(name=...) parameter:

The Python function names are unchanged, so server/-level imports and the test-suite are unaffected. The other seven tool names are already unique across the servers and keep their names.

Multi-tool question routing

Tools carry their eliciting question in the docstring (which is what the RAG retriever embeds). Multi-tool questions use one forward-only canonical chain; the terminal tool alone exposes metadata.next_question, and Q4 terminates explicitly:

See REPRODUCTION_QUESTIONS.md for the full four-question scenario. Each recommended prompt explicitly asks the agent to return every generated figure artifact with its kind and SHA-256, rather than returning an orchestration log or a bare confirmation.

Reproduction fidelity

heracleum_reproduce_all and pytest tests/ assert these against the paper:

The full 225-compound dataset (standardized SMILES + SynID + cluster A–E) is reproduced exactly from the paper's Supplementary Tables S1–S5 — parsed by parse_supplementary.py into server/data/supplementary_smiles.csv, then assembled by build_dataset.py (which merges the cluster-E Table 2 toxicity values and resolves compound names via PubChem). The paper's own model-quality numbers (Supplementary Table S6) are bundled for comparison (model_quality / heracleum_reproduce_all).

Open-model endpoint validation. These results are computed and reported at call time by predict_general_toxicity (answer.endpoint_summary, answer.endpoints_diverging_from_paper) and by heracleum_reproduce_claims (C5) — the numbers below are what the bundled model cache produces today, not assertions baked into the code:

• DILI v2: the former fragment-only XGBoost called only 1/22 cluster-E compounds positive. The replacement model is a fixed soft-voting ensemble (XGBoost + ExtraTrees + logistic regression) over a hybrid ECFP4 + physicochemical-descriptor + fragment representation. On the public TDC DILI training set only (n=475), five-fold stratified Bemis–Murcko scaffold-group internal OOF evaluation gives pooled ROC-AUC ≈0.89, average precision ≈0.88, and balanced accuracy ≈0.83 at the standard 0.5 threshold, with zero scaffold overlap between train/test folds. Because the representation/ensemble were selected on this same public dataset, these are post-selection internal estimates rather than independent external validation; the API also returns the exact environment-specific pooled values plus mean±SD and sizes for the five folds (the host and locked Linux image produced ROC-AUC 0.885 and 0.887, respectively). The effective RDKit-accepted training rows, feature/AD settings, seed, estimator specification and relevant library versions are returned in metrics.dili.training_contract by model_quality (and in the endpoint model metrics embedded in prediction metadata). The raw source file, effective fitted rows and complete contract each carry SHA-256 digests. A cheap cache-identity digest over the exact source bytes, model/config specification and software versions is part of the cache filename, while the full fitted-row digest remains available for audit. A dataset, configuration or dependency change therefore cannot silently reuse an old DILI model. The 22 Heracleum labels are not used for training, threshold selection or model selection. DILI v2 calls 22/22 positive, matching the paper, but all 22 references are positive and cover only five unique scaffolds (one compound shares a training scaffold). This is therefore a positive concordance/sensitivity check: specificity and external ROC-AUC cannot be estimated. Mean applicability-domain reliability remains only 38 % (average), and no matched negative control is available, so this agreement is explicitly reported as low-evidence rather than as external model validation.

• Broader hepatotoxicity proxy: this deliberately remains separate from DILI v2 and retains the legacy TDC-DILI fragment model: 1/22 positive against the paper's 17/22, mean AD ≈ 38 %. Calling two endpoint names on the same old estimator is no longer presented as two independent models.

• Cardiotoxicity: the open hERG proxy is far more conservative than Syntelly's cardiotox model — current locked numerical platforms flag 20–21/22 furanocoumarins as hERG blockers (21/22 in the validated native arm64 image); the paper found 0/22. Because the paper reference is negative-only, this comparison can estimate negative concordance/specificity but not sensitivity or ROC-AUC; the structured paper_comparison_design reports that limitation.

• Carcinogenicity: the open model calls 0/22 carcinogenic against the paper's 10/22; the majority direction (non-carcinogenic) still agrees, at 55 % per-compound agreement and the highest AD of the four endpoints (mean ≈ 52 %, high band).

• Per-route LD50: the public TOXRIC v5 Figshare artifact contains all six mouse-route targets directly: oral 23,371; IV 16,976; IP 36,294; SC 6,769; skin 214; IM 571 usable rows after the pinned four-row SMILES quarantine. The server trains six separate hybrid XGBoost regressors and reports both duplicate-safe identity-group and strict Bemis–Murcko scaffold-group holdouts. The complete paper Figure 3 is also transcribed as 132 digest-pinned reference cells. Its 117 Syntelly outputs are reported only as concordance; its 15 experimental stars are checked against route-training identity and scaffold membership and are not called external accuracy when either overlap exists. The headline cross-route family order is descriptive: within each route the server takes the median predicted LD50 for each cluster, then ranks clusters by the equal-weight median of those six route medians. That aggregate is not a physical all-route LD50 or an exposure-weighted risk estimate; all six per-route rankings remain visible beside it.

The clustering uses a differential fingerprint (ECFP of the Bemis–Murcko scaffold) as the open analogue of SynMap's differential fingerprints + parametric t-SNE (Karlov/Sosnin/Tetko/ Fedorov, ACS Omega 2021). Emphasising the core scaffold separates furanocoumarins (E) from simple aromatics (D), recovering all five families at ~95 % agreement; set HERACLEUM_CLUSTER_FINGERPRINT=ecfp4 for the plain-molecule fallback (~86 %, merges D into E).

Run locally

git clone https://github.com/chemagents/heracleum-tox-mcp-server.git
cd heracleum-tox-mcp-server
cp .env.example .env
uv sync
uv pip install --no-deps "PyTDC==0.4.1"     # open datasets; pins old rdkit-pypi, so --no-deps
uv run python prepare_models.py             # train/cache all 10 models; DILI v2 runs scaffold CV
uv run python -m server.heracleum_server    # serves http://0.0.0.0:7331/mcp

# The 225-compound dataset is already bundled (server/data/heracleum_metabolites.csv).
# To regenerate it from the paper's Supplementary PDF:
#   pdftotext -layout plants-3875800-supplementary.pdf supp.txt
#   uv run python parse_supplementary.py supp.txt   # -> server/data/supplementary_smiles.csv
#   uv run python build_dataset.py                  # merges Table 2 refs + PubChem names

Run with Docker

cp .env.example .env
docker compose up -d --build --wait   # 127.0.0.1:7336 -> container 7331

The Docker build installs PyTDC and pre-trains exactly ten production models: six TOXRIC routes and four classifiers. Startup validates all ten cache payloads without resolving source datasets, downloading, featurizing, or training. Both the image and docker-compose.yml set HERACLEUM_REQUIRE_BAKED_MODELS=true; the compose environment value outranks the copied .env, whose false value is only the direct local-development default. A missing dependency, dataset, cache, or failed fit therefore fails build/startup rather than becoming a first-request operation. The container runs unprivileged with all Linux capabilities dropped, and the standalone port is loopback-only by default. For the CoScientist monorepo build context and its strict MinIO artifact smoke test, see COSCIENTIST_INTEGRATION.md. The CoScientist-context Dockerfile copies only server/*.py and server/data after model preparation. It therefore cannot copy a host server/model_cache over the baked models even when the parent build context does not apply this nested repository's .dockerignore rules.

Attach to CoScientist

CoScientist discovers MCP tools via RAG (Postgres + Qdrant). Register this server once:

# from the CoScientist repo root, with the RAG stack running and .env configured
python scripts/rag_tools/cli.py load mcp-servers/heracleum-tox-mcp-server/rag_registration.json
# or directly:
python scripts/rag_tools/cli.py add \
  --url http://localhost:7336/mcp \
  --name heracleum-tox \
  --description "In-silico toxicology of Heracleum sosnowskyi metabolites; LD50, hepato/DILI/cardio/carcinogenicity, furanocoumarins (Rassabina & Fedorov 2025)"

Prefer cli.py load rag_registration.json over the inline --description: the bundled registration description is written to discriminate this server from the sibling tox-antitargets-mcp-server (both are "toxicology"). The discriminators are plant secondary metabolites, Heracleum sosnowskyi / hogweed / борщевик, furanocoumarins and coumarins, route of administration, DILI / hepatotoxicity / carcinogenicity, applicability domain and synthesis cost; tox-antitargets owns antitarget/off-target protein affinity, docking and the Bowes panel.

After registration the ToolRetrieverAgent surfaces these tools for plant-metabolite / toxicity / LD50 / furanocoumarin queries, and ExperimentAgent (FEDOT.MAS) calls them by URL. If CoScientist runs in the same Docker network, register the in-network URL instead: http://heracleum-tox-mcp-server:7331/mcp.

See REPRODUCTION_QUESTIONS.md for the exact prompts to ask CoScientist — the recommended four-question scenario for the validation report, plus one prompt per paper assertion and a single "reproduce everything" fallback.

Public TOXRIC v5 route-model contract

The six mouse-route targets are public in the byte-pinned TOXRIC v5 Figshare release (10.6084/m9.figshare.27195339.v5). No author-only dataset, TOXRIC licence, or manually supplied CSV is required. The ingestion layer verifies the archive and main-table digests, exact schema and shape, target unit (-log10(mol/kg)), and the four explicitly quarantined invalid structures before training.

The server fits one fixed XGBoost regressor per route over hybrid ECFP4, physicochemical descriptors, and RDKit fragment features. It reports both normalized-identity-group and Bemis–Murcko scaffold-group holdouts with overlap audits. The TOXRIC release's published random-split files are a secondary reproducibility benchmark; they are not substituted for the stricter scaffold estimate. The paper's Figure 3 values are never used for fitting, hyperparameter selection, or threshold selection.

The overall cluster order shown by predict_ld50, C3/C8, and heracleum_reproduce_all is derived from these same six models: median predicted LD50 within cluster for each route, followed by an equal-weight median across the six route medians. It is a descriptive ordering only, while the route-specific values and rankings remain the primary model outputs.

The sealed production Docker build produced the strict metrics below. A separate deterministic audit of TOXRIC's published split files produced the repeated-70/30 benchmark column. Values are RMSE in -log10(mol/kg):

Every strict split has zero normalized-scaffold overlap. The bundled TOXRIC splits have zero exact RTECS overlap but 33–72% of test rows share a normalized scaffold with training (route-dependent), and test sets overlap one another; they are repeated holdouts, not mutually exclusive K-folds. Neither column is a head-to-head superiority test against Syntelly because the paper used a different snapshot and validation contract.

HERACLEUM_TOXRIC_CACHE_DIR controls the verified download/cache location and HERACLEUM_LD50_N_JOBS controls XGBoost parallelism. prepare_models.py and the production Docker build bake all six route models plus four classifiers, then the final image resets the route-model serving default to one worker. Worker count is a deployment resource and is excluded from cache identity, so the four-worker baked models load unchanged with the one-worker runtime limit. Serving therefore never depends on a first-request download or fit: the complete ten-model set is cache-only preflighted before the MCP transport starts. Set HERACLEUM_RETRAIN=true only when an intentional rebuild is required; cache identity includes the pinned source, estimator/configuration contract, feature contract, and relevant software versions. Model caches use Python/joblib deserialization: keep HERACLEUM_MODEL_CACHE_DIR on a trusted local volume and never mount content writable by an untrusted producer.

The complete paper Figure 3 transcription is independently digest-pinned: 22 compounds × 6 routes = 132 cells. The 117 unstarred Syntelly predictions are assessed only for model-to-model concordance. The 15 starred experimental values are reported separately, with a per-cell TOXRIC identity-and-scaffold training-membership audit; either kind of overlap prevents them from being described as external accuracy.

Tests

uv run pytest tests -v                 # all (trains models on first run, then cached)
uv run pytest tests -v -m "not slow"   # fast deterministic checks only

License / data

Open datasets via Therapeutics Data Commons (PyTDC) and TOXRIC. Please cite Rassabina & Fedorov (2025) when using these results, and TDC / the Syntelly platform paper (Sosnin et al., Molecules 2024, 29, 1826) for the methods.