# Thermophysical Data Curation MCP Server

An MCP server for auditable thermophysical data curation using five supplied
JR-MPNN checkpoints and selected UManSysProp group-contribution methods.

## What it provides

- `inspect_molecule`: validate and canonicalize a SMILES string and report domain flags.
- `predict_jrmpnn`: predict Tm, Tb, Tc, Pc, and Vc with Joback baselines.
- `assess_jrmpnn_training_similarity`: compare a query with the 10 nearest
  property-specific JR-MPNN training embeddings without returning private records.
- `estimate_umansysprop`: estimate boiling point, critical properties, density, and vapor pressure.
- `curate_thermophysical_records`: normalize, deduplicate, score, and triage records with an audit trail.
- `server_capabilities`: report available models, methods, and scientific limitations.

Predictions are diagnostic cross-checks. They do not replace accepted experimental
measurements, and the server never silently deletes submitted records.

## Install from source

Python 3.11 or newer is required. Installation may take several minutes because
PyTorch, PyTorch Geometric, RDKit, and the scientific dependencies are substantial.

```bash
git clone https://github.com/frankmtetwa/thermophysical-curator.git
cd thermophysical-curator
python -m venv .venv
```

Activate the environment:

```powershell
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
```

```bash
# macOS/Linux
source .venv/bin/activate
```

Then install and test:

```bash
python -m pip install --upgrade pip
python -m pip install .
python -m unittest discover -s tests -v
```

Run the stdio MCP server with:

```bash
thermophysical-curator
```

The process waits for an MCP client on standard input. That behavior is expected.

## Enable training-similarity assessment

The repository does not contain proprietary training compounds or generated
embedding indices. On each computer where similarity assessment is required,
create a private reference directory containing these five files:

```text
private_reference/
|-- Tm_train_smiles.csv
|-- Tb_train_smiles.csv
|-- Tc_train_smiles.csv
|-- Pc_train_smiles.csv
`-- Vc_train_smiles.csv
```

Each CSV must contain a `smiles` column. A `compound_id` column is optional:

```csv
compound_id,smiles
```

Privacy-safe header-only examples are available in `reference_templates/`. Copy
them to `private_reference/`, then populate them locally with the SMILES used to
train the corresponding property model. Do not combine calibration or test
compounds with the training set.

Build the private embedding indices after installing the project:

```bash
python -m curation_agent.similarity build
```

The default location is `private_reference/` in the repository root. To keep the
files elsewhere, set `THERMOPHYSICAL_REFERENCE_DIR` to an absolute directory
before building the indices and before launching the MCP server. Restart the MCP
client after building so it refreshes the available tool state.

The reported training-similarity percentile is an applicability-domain diagnostic,
not a calibrated uncertainty interval or a guarantee of prediction accuracy.

## Claude Desktop

### MCPB extension

This repository contains an experimental cross-platform UV manifest. Install the
MCPB CLI and build the extension from the repository root:

```bash
npm install -g @anthropic-ai/mcpb
mcpb validate manifest.json
mcpb pack . dist/thermophysical-curator-0.1.0.mcpb
```

In Claude Desktop, open **Settings > Extensions > Advanced settings > Install
Extension** and select the generated `.mcpb` file. The UV runtime downloads the
Python dependencies on first launch, so the initial startup can be slow. When
Claude asks for the **Private JR-MPNN reference directory**, select the
`private_reference` directory containing both the five CSV files and the generated
`embeddings/` directory. The private files remain outside the extension bundle.

### Manual configuration

Users who prefer a pre-created virtual environment can add this to Claude Desktop's
MCP configuration, replacing the command with the absolute path to their environment:

```json
{
  "mcpServers": {
    "thermophysical-curator": {
      "command": "C:\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "curation_agent.server"]
    }
  }
}
```

On macOS/Linux, use `/path/to/repo/.venv/bin/python` instead.

## Codex

After installing the project, register the server using the environment's Python:

```bash
codex mcp add thermophysical-curator -- /absolute/path/to/python -m curation_agent.server
```

## Example curation record

```json
{
  "smiles": "CCO",
  "property": "normal_boiling_point",
  "value": 78.37,
  "unit": "C",
  "source": "literature citation",
  "doi": "10.xxxx/example",
  "experimental": true,
  "method": "ebulliometry",
  "uncertainty": 0.1
}
```

## Privacy

The package contains model weights but no training, calibration, or proprietary
experimental records. Inputs are processed locally by the MCP server. The host AI
application may still receive tool arguments and results, subject to that application's
privacy policy.

## Redistribution checklist

Before making the repository public, verify that you have permission to redistribute
the five JR-MPNN `.pth` checkpoint files. They are required for model predictions but
their redistribution terms were not present in the supplied source directory.

UManSysProp-derived files retain their original copyright notices and GPL terms. See
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and [LICENSE](LICENSE).

## License

GPL-3.0-or-later, subject to the third-party notices and checkpoint redistribution
rights described above.