Metadata-Version: 2.4
Name: pythermomodels-mcp
Version: 0.1.0
Summary: PyThermoModels-MCP is a Model Context Protocol server for running selected PyThermoModels calculations, including EOS root checks, pure-component and mixture fugacity, NRTL and UNIQUAC activity coefficients, tau_ij parameters, and pyThermoDB YAML reference validation.
Author-email: Sina Gilassi <sina.gilassi@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/sinagilassi/PyThermoModels-MCP
Project-URL: Tracker, https://github.com/sinagilassi/PyThermoModels-MCP/issues
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=3.4.4
Requires-Dist: pythermomodels
Dynamic: license-file

# PyThermoModels-MCP

[![PyPI Downloads](https://static.pepy.tech/badge/pythermomodels-mcp/month)](https://pepy.tech/projects/pythermomodels-mcp)
![PyPI](https://img.shields.io/pypi/v/pythermomodels-mcp)
![Python Version](https://img.shields.io/pypi/pyversions/pythermomodels-mcp.svg)
![License](https://img.shields.io/pypi/l/pythermomodels-mcp)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-Compatible-orange)](https://modelcontextprotocol.io)

PyThermoModels-MCP is a Model Context Protocol (MCP) server for running selected
PyThermoModels thermodynamic calculations from agents and MCP-compatible clients.

## Overview 🌐

The package exposes Equation of State (EOS), activity-coefficient, tau-parameter,
and YAML reference-validation workflows as MCP tools. Each calculation receives
structured arguments, builds a `pyThermoLinkDB` `ModelSource` from caller-supplied
`pyThermoDB` YAML reference content, calls the corresponding `pyThermoModels`
core function, and returns JSON-safe data.

Use this package when an agent or MCP client needs to:

- Check pure-component or mixture EOS root behavior.
- Calculate pure-component gas or liquid fugacity.
- Calculate mixture fugacity values and fugacity coefficients.
- Calculate NRTL or UNIQUAC liquid activity coefficients.
- Calculate NRTL or UNIQUAC `tau_ij` interaction parameters.
- Validate whether YAML reference content is usable by the pyThermoDB reference pipeline.

The server does not search for, load, or assemble reference files automatically.
Callers must pass complete YAML reference content in each tool request.

## Requirements 📋

- Python `>=3.11`
- `pip` or `uv`

## Installation 📦

```bash
pip install pythermomodels-mcp
```

This installs the `pythermomodels-mcp` command.

## Running the MCP Server ▶️

The server entrypoints are:

- CLI: `pythermomodels-mcp`
- Module: `python -m pythermomodels_mcp.server`

Both support the same options.

### STDIO Transport 🧵

Use STDIO for local MCP desktop and agent clients:

```bash
pythermomodels-mcp --mode stdio
```

Equivalent module command:

```bash
python -m pythermomodels_mcp.server --mode stdio
```

### HTTP Transport 🌍

Use HTTP when a network-accessible MCP endpoint is needed:

```bash
pythermomodels-mcp --mode http --host 127.0.0.1 --port 8000 --path /mcp
```

Equivalent module command:

```bash
python -m pythermomodels_mcp.server --mode http --host 127.0.0.1 --port 8000 --path /mcp
```

## CLI Options ⌨️

- `--mode`: MCP transport mode, either `stdio` or `http` (default: `stdio`)
- `--host`: HTTP bind host (default: `127.0.0.1`)
- `--port`: HTTP bind port (default: `8000`)
- `--path`: HTTP endpoint path (default: `/mcp`)
- `-V`, `--version`: print package version

## MCP Client Configuration 🔌

### STDIO

```json
{
  "mcpServers": {
    "pythermomodels": {
      "command": "pythermomodels-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}
```

### HTTP

```json
{
  "mcpServers": {
    "pythermomodels": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## MCP Resources 📚

The server exposes two guidance resources:

- `pythermomodels://references/eos-requirements`
  - YAML guidance for EOS tools, including required reference content, supported EOS names, solver options, component keys, and root-check guidance.
- `pythermomodels://references/activity-requirements`
  - YAML guidance for activity tools, including NRTL/UNIQUAC source requirements, liquid-component requirements, tau-correlation options, and source-building behavior.

## MCP Tools 🧰

### EOS Tools 🔥

All EOS tools require `reference_content`, `pressure`, `temperature`, and component
data. Supported EOS model names are `SRK`, `PR`, `RK`, and `vdW`.

- `check_pure_component_eos_roots`
  - Checks EOS roots for one component at a specified pressure and temperature.
- `calculate_gas_fugacity`
  - Calculates pure-component gas fugacity and fugacity coefficient.
- `calculate_liquid_fugacity`
  - Calculates pure-component liquid fugacity using either the `EOS` or `Poynting` route.
- `check_mixture_eos_roots`
  - Checks EOS roots for a mixture. Mixture component mole fractions must sum to `1.0`.
- `calculate_mixture_fugacity`
  - Calculates mixture fugacity results and component fugacity coefficients.

### Activity-Model Tools 💧

Activity tools are for liquid mixtures. Every component must use `state: l`, and
the component mole fractions must sum to `1.0`.

- `calculate_nrtl_activity_coefficient`
  - Calculates NRTL activity coefficients, auxiliary model output, and excess Gibbs energy.
- `calculate_nrtl_tau_ij`
  - Calculates NRTL `tau_ij` values and returns both an array and dictionary representation.
- `calculate_uniquac_activity_coefficient`
  - Calculates UNIQUAC activity coefficients, auxiliary model output, and excess Gibbs energy. UNIQUAC activity calculations need component data such as `r` and `q` in addition to mixture interaction data.
- `calculate_uniquac_tau_ij`
  - Calculates UNIQUAC `tau_ij` values and returns both an array and dictionary representation.

### Utility Tool 🛠️

- `check_yaml_reference`
  - Validates YAML reference content with the pyThermoDB custom-reference checker and returns `true` or `false`.

## Input Model Notes 📝

Tool functions receive one Pydantic argument named `args`. Typical tool input
therefore looks like:

```json
{
  "args": {
    "reference_content": "REFERENCES:\n  ...",
    "component": {
      "name": "propane",
      "formula": "C3H8",
      "state": "g"
    },
    "temperature": {
      "value": 300.1,
      "unit": "K"
    },
    "pressure": {
      "value": 9.99,
      "unit": "bar"
    },
    "model_name": "SRK",
    "component_key": "Name-State",
    "kwargs": {
      "mode": "silent"
    }
  }
}
```

Use the resource documents for full reference-content requirements before
calling tools.

## Best Practices ✅

- Pass complete, non-empty `reference_content` in every calculation request.
- Use `check_yaml_reference` before calculations when reference content is generated dynamically.
- Keep `component_key`, `mixture_key`, separator, and delimiter choices consistent across related calls.
- For mixture tools, provide mole fractions that sum to `1.0`.
- For activity tools, use liquid-state components only.
- Use `kwargs` for advanced pyThermoModels options such as silent mode, tolerances, or phase controls.

## Development Quick Check 🧪

```bash
python -m py_compile pythermomodels_mcp/server.py
python -m py_compile pythermomodels_mcp/interface/eos_models.py
python -m py_compile pythermomodels_mcp/interface/activity_models.py
```

## Examples 🚀

Example scripts are available under:

- `examples/eos`
- `examples/activity`
- `examples/references`

They show how to create an in-process FastMCP client, pass `reference_content`,
call tools, and read JSON-safe `result.data`.

## Troubleshooting 🩺

- `pythermomodels-mcp: command not found`
  - Install the package in the active environment: `pip install -e .`
  - Confirm the active Python environment is the one used by your MCP client.
- Port already in use in HTTP mode
  - Choose another port, for example `--port 8010`.
- Empty or invalid reference errors
  - Confirm that `reference_content` is complete YAML content and includes all component or mixture data required by the selected model.
- Mole fraction validation errors
  - Confirm mixture mole fractions sum to exactly `1.0` within numerical tolerance.

## FAQ ❓

For questions, contact [Sina Gilassi on LinkedIn](https://www.linkedin.com/in/sina-gilassi/).

## License 📄

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).

## Author 👨‍💻

- [@sinagilassi](https://www.github.com/sinagilassi)
