# Solitarius MCP

MCP server exposing [REINVENT4](https://github.com/MolecularAI/REINVENT4) generative molecular-design operations as validated, LLM-callable tools. It is compatible with MCP-capable agentic coding platforms such as Claude Code, Codex CLI, Gemini CLI, and others.

`Solitarius MCP` is the **controlled execution interface** of *Solitarius*, a three-layer agentic architecture for computer-aided molecular inverse design:

1. **REINVENT4**: the molecular-generation and optimisation engine (sampling, transfer learning, staged reinforcement learning).
2. **`Solitarius MCP`** *(this repository)*: exposes REINVENT4 operations as validated tools an LLM agent can call through a common interface.
3. **[Solitarius Agentic System](https://github.com/lcmd-epfl/Solitarius-agentic-system)**: coordinates specialist agents (Planner, Formulator, Executor, Analyser) that turn a natural-language objective into a traceable molecular-generation campaign.

You can use this server on its own when an agent needs direct access to individual REINVENT4 operations, or together with the orchestration layer when a campaign needs planning, scoring-function formulation, execution, analysis, and iteration.

> **Prerequisite:** you run the server yourself — there is no hosted instance. Either in a conda environment via stdio, or as a Docker HTTP service you build locally (~10–15 min, needs nvidia-container-toolkit). REINVENT4 itself wants an NVIDIA GPU for transfer learning and RL. See [Installation](#installation).

<div align="center">
<img src="assets/mcp_tool_skill_layer.png" alt="MCP tool and skill layer for the REINVENT4 generative workflow" width="92%">
</div>

The `Solitarius MCP` interface groups callable operations into input/configuration validation, scoring-component construction and testing, execution, job management, and monitoring and analysis. These tools map agent requests onto REINVENT4 TOML configurations for sampling, transfer learning, and reinforcement learning, and return generated molecules, trained models, optimisation histories, and analysis summaries through the same interface. Lightweight [skills](#skills-lite-mode) provide a direct-instruction alternative for running the same general workflow without the MCP server.

---

## Table of Contents

1. [Key Features](#key-features)
2. [Installation](#installation)
3. [Skills: Lite Mode](#skills-lite-mode)
4. [Troubleshooting](#troubleshooting)
5. [Citation](#citation)

---

## Key Features

All long-running tools follow a **dry_run → launch** protocol that separates workflow construction from computation: the dry run resolves all parameters and returns the complete TOML config *without* starting REINVENT4, so the agent and user can inspect the model, inputs, and settings before committing resources. After explicit approval, the same validated config is launched and the tool returns the output locations plus a persistent job identifier for monitoring. Outputs land in a timestamped directory (`reinvent_runs/<type>_<timestamp>/`) with `config.toml`, `reinvent.log`, and all result files.

The tools are grouped by their role in a molecular-generation campaign.

### Input and configuration

| Tool | What it does |
|---|---|
| `reinvent_validate_input` | Check (and optionally clean) a SMILES/CSV input file for validity and format issues before it reaches a generator. |
| `reinvent_validate_toml` | Validate a complete REINVENT TOML config against the `ReinventConfig` schema before execution. |

### Scoring-component construction

| Tool | What it does |
|---|---|
| `reinvent_rl_scoring_design_guide` | Guide that maps an objective onto supported scoring components, targets, and transforms before an RL configuration is built. |
| `reinvent_custom_scoring_component` | Generate a `comp_*.py` scoring plugin from a description (e.g. "penalize reactive groups") when no built-in component fits. |
| `reinvent_test_scoring_component` | Test a custom component against example molecules before wiring it into an RL run. |

### Execution

| Tool | What it does |
|---|---|
| `reinvent_sampling` | Sample molecules from a prior or trained checkpoint. Returns SMILES + model likelihoods. |
| `reinvent_transfer_learning` | Fine-tune a prior on a focused SMILES dataset, with input validation/cleanup available before launch. |
| `reinvent_reinforcement_learning` | Goal-directed optimisation through staged RL with a multi-component scoring function. |

### Job management

| Tool | What it does |
|---|---|
| `reinvent_register_job` | Create a persistent record for a launched TL or RL job. |
| `reinvent_attach_pid` | Attach the running OS process ID to a registered job. |

### Monitoring and analysis

| Tool | What it does |
|---|---|
| `reinvent_job_status` | Poll status (running/completed/failed) of any TL or RL job from its process and log heuristics. |
| `reinvent_plot_rl_history` | Plot RL score convergence and per-component trends from a stage CSV. Works mid-run and post-run. |
| `reinvent_analyze_molecules` | Evaluate SMILES/CSV: validity, physicochemical properties, druglikeness (QED, Lipinski), scaffold diversity, structural alerts, UMAP projection, optional similarity/novelty vs a reference set. Writes `analysis_report.json` + `per_molecule.csv` + PNGs. |

Example `reinvent_analyze_molecules` output: UMAP projection of generated molecules coloured by score, overlaid on a reference set.

---

## Installation

### Option A: Local stdio

Run the server directly in a conda environment. Supported by all platforms that accept an MCP stdio server.

```bash
conda activate reinvent4
pip install -r requirements.txt

# Verify the server imports cleanly (no output = OK)
python -c "import server"
```

Register with your platform:

```bash
# Claude Code
claude mcp add reinvent4 \
  /path/to/miniconda3/envs/reinvent4/bin/python \
  /absolute/path/to/reinvent-mcp/server.py

# With custom plugins / explicit CWD
claude mcp add \
  --env PYTHONPATH=/absolute/path/to/reinvent-mcp/custom_plugins \
  --env REINVENT_CWD=/absolute/path/to/reinvent-mcp \
  reinvent4 \
  /path/to/miniconda3/envs/reinvent4/bin/python \
  /absolute/path/to/reinvent-mcp/server.py

# Codex CLI
codex mcp add reinvent4 -- \
  /path/to/miniconda3/envs/reinvent4/bin/python \
  /absolute/path/to/reinvent-mcp/server.py

# Gemini CLI: ~/.gemini/settings.json
# "mcpServers": { "reinvent4": { "command": "python", "args": ["/absolute/path/to/reinvent-mcp/server.py"] } }
```

### Option B: Docker HTTP (recommended for deployment)

#### Prerequisites

- Docker Engine with [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
- REINVENT4 cloned into this repo root:

```bash
git clone https://github.com/MolecularAI/REINVENT4.git --depth 1 REINVENT4
```

#### Build and start

```bash
# Generate .env (prompts for your data directory; run once per machine)
bash gen_env.sh

# Create output directories
mkdir -p reinvent_runs custom_plugins/reinvent_plugins/components jobs

# Build the image (~10-15 min first time)
docker compose build

# Start the server
docker compose up -d

# Confirm it's running (expect: "Uvicorn running on http://0.0.0.0:8080" — mapped to host port 8081)
docker compose logs -f
```

#### Stop / rebuild

```bash
docker compose down
docker compose up -d --build   # rebuild after code changes
```

#### Register with your platform

**Claude Code — install as a plugin (recommended).** This is the only route that also
installs the [skills](#skills-lite-mode); `claude mcp add` gives you the tools alone.

The container from the previous section must already be running — the plugin declares
the server, it does not start it. Install it first and the tools will load but every
call will fail to connect.

```
/plugin marketplace add pregHosh/Solitarius-mcp
/plugin install solitarius-mcp@solitarius
```

If host port 8081 is already taken and you changed it in `docker-compose.yml`, point the
plugin at the new port instead of editing it:

```bash
export SOLITARIUS_MCP_URL=http://127.0.0.1:8082/sse
```

**Or register the server manually** (any platform; no skills):

```bash
# Claude Code
claude mcp add --transport http reinvent4 http://localhost:8081/sse

# Codex CLI
codex mcp add reinvent4 --url http://localhost:8081/sse

# Gemini CLI
# gemini mcp add -s user --transport http reinvent4 http://localhost:8081/sse
```

> Use `--transport http` (not `--transport sse`). The server uses MCP's `streamable-http` transport (mcp ≥ 1.0); the legacy SSE flag will fail even though the URL path is `/sse`.

#### Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `REINVENT_CWD` | server directory | Base for resolving relative paths |
| `SERVER_TRANSPORT` | `stdio` | `stdio`, `sse`, or `streamable-http` |
| `SERVER_HOST` | `0.0.0.0` | Bind host (HTTP transports) |
| `SERVER_PORT` | `8080` | Bind port (HTTP transports) |
| `PYTHONPATH` | (none) | Must include parent of `reinvent_plugins/` for custom components |

---

## Skills: Lite Mode

`skills/` provides slash commands that call the `reinvent` CLI directly; no MCP server or Docker needed. Requires REINVENT4 on PATH. Supported by Claude Code, Codex CLI, Gemini CLI, and other platforms that load skill/instruction files.

`/sample` · `/rl` · `/transfer-learn` · `/analyze` · `/validate` · `/job-status` · `/custom-component`

---

## Troubleshooting

**`reinvent: command not found`**
Pass the full env PATH when registering: `--env PATH=/path/to/miniconda3/envs/reinvent4/bin:$PATH`

**`ModuleNotFoundError: mcp`**
Run `pip install -r requirements.txt` inside the `reinvent4` conda environment.

**Custom component not found**
- `PYTHONPATH` must point to the **parent** of `reinvent_plugins/`, not `reinvent_plugins/` itself.
- No `__init__.py` in `reinvent_plugins/` or `reinvent_plugins/components/`.
- Test: `python -c "from reinvent_plugins.components import comp_mycomponent"`

**Tools not appearing**
- Run `claude mcp list` / check your platform's MCP status.
- stdio: `python server.py` should print `Invalid JSON: EOF`; that confirms the import succeeded.
- Docker: `docker compose ps` should show `Up`, not `Restarting`.

**`Failed to connect` with Docker**
Confirm `--transport http` was used (not `--transport sse`). Check `docker compose ps` and `docker compose logs`.

**Port already in use**
Find the process: `ss -tlnp | grep 8081`. Kill it or change the host port in `docker-compose.yml` (`8082:8080`), then re-register with the new port.

**GPU not detected in Docker**
```bash
docker compose down
docker compose up -d          # must recreate container for GPU deploy config to apply
docker exec reinvent4-mcp nvidia-smi
```
If `nvidia-container-toolkit` is missing, install it per the [NVIDIA install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html), then `sudo systemctl restart docker`.

**Job status shows `completed` immediately**
Status is inferred from the log file. If the log doesn't exist yet, wait a moment and poll again with `reinvent_job_status`.

---

## Citation

If you use `Solitarius-MCP` or the *Solitarius* agentic system, please cite:

[![DOI](https://img.shields.io/badge/DOI-10.26434%2Fchemrxiv.15005834%2Fv2-red)](https://chemrxiv.org/doi/abs/10.26434/chemrxiv.15005834/v2)

[Solitarius: An Agentic Architecture for Computer-aided Molecular Inverse Design](https://chemrxiv.org/doi/abs/10.26434/chemrxiv.15005834/v2)

```bibtex
@article{worakul_solitarius_2026,
    title = {Solitarius: {An} {Agentic} {Architecture} for {Computer}-aided {Molecular} {Inverse} {Design}},
    url = {https://chemrxiv.org/doi/abs/10.26434/chemrxiv.15005834/v2},
    doi = {10.26434/chemrxiv.15005834/v2},
    publisher = {American Chemical Society (ACS)},
    author = {Worakul, Thanapat and Corminboeuf, Clémence},
    year = {2026},
}
```

This work builds on REINVENT4; please also cite:

```bibtex
@article{loeffler_reinvent_2024,
	title = {Reinvent 4: {Modern} {AI}–driven generative molecule design},
	volume = {16},
	issn = {1758-2946},
	shorttitle = {Reinvent 4},
	url = {https://doi.org/10.1186/s13321-024-00812-5},
	doi = {10.1186/s13321-024-00812-5},
	language = {en},
	number = {1},
	urldate = {2026-07-03},
	journal = {Journal of Cheminformatics},
	author = {Loeffler, Hannes H. and He, Jiazhen and Tibo, Alessandro and Janet, Jon Paul and Voronov, Alexey and Mervin, Lewis H. and Engkvist, Ola},
	month = feb,
	year = {2024},
	keywords = {Generative AI, Reinforcement learning, Transfer learning, Multi parameter optimization, Recurrent neural networks, Transformers},
	pages = {20},
}
```