vle-mcp

Hero image generated with ChatGPT Images via OpenAI Codex (GPT-5.6 Sol).

An educational Model Context Protocol server for the vle scientific library (published on PyPI as vle-thermo).

It exposes 14 read-only tools: water and steam properties (IAPWS-IF97), a bundled pure-component database, multicomponent vapor-liquid equilibrium with cubic equations of state, and petroleum-fraction characterization. The chatbot interprets and explains the request; tested scientific software supplies the number.

Development: this repository is currently being developed using Claude Code, under Miguel Jackson's direction. See Authorship.

Status

M0 through M3 are implemented and locally verified. The tool catalogue exposes a reviewed selection of the vle-thermo 0.18 public API (see Tools). The project supports local stdio and an OAuth-protected Streamable HTTP ASGI application factory for remote deployment. Verification includes protocol round trips over both transports, a real stdio subprocess handshake, RFC 9728 metadata, bearer scope and resource binding, and remote resource limits. See PLAN.md, TODO.md, the M2 verification record, and the M3 remote guide.

Related MCP server: Agentic-AI-Planning-And-Reasoning-MCP

Why MCP?

MCP gives AI clients a standard way to discover and call typed tools. It separates natural-language reasoning from authoritative programs and data:

• the model determines intent;

• the MCP client controls connections and tool use;

• this server validates a typed request;

• vle performs the scientific calculation.

See docs/mcp-primer.md for the protocol path and docs/architecture.md for the component architecture. PLAN.md records the Python and API-granularity decisions.

Development setup

Python 3.11 or newer is required.

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/vle-mcp

The last command starts a stdio MCP server and waits for a client. It is not an interactive shell; use an MCP client or the protocol tests.

For development against a local vle checkout, install its Python package into the virtual environment according to that repository's build instructions. Do not commit a machine-specific path.

For remote clients, integrate the ASGI factory with a maintained OAuth token verifier and HTTPS ingress. The remote endpoint deliberately cannot start without those operator-owned security inputs. See docs/remote-http.md.

Tools

Every tool is read-only, deterministic, and annotated as such. Pressures are always absolute. Temperatures accept K, degC, degF, or degR; pressures accept Pa, kPa, MPa, bar, or atm. Every result carries its units and a calculation block naming the library, method, and installed vle-thermo version.

Mixture tools take 1 to 10 components from list_components, with mole fractions greater than zero that sum to one (within 0.001; the normalized composition is echoed back). The model is one cubic equation of state for both phases (PR, SRK, RK, PRSV, VdW, Schmidt-Wenzel, or Patel-Teja) with classical mixing and zero binary interaction parameters. Solver iterations are capped. The architecture guide records which parts of the vle API are deliberately not exposed and why.

Example: boiling point of water at one atmosphere.

{"pressure": 101.325, "pressure_unit": "kPa"}

water_saturation_temperature returns approximately 373.1243 K or 99.9743 °C.

Example: flash of a light-hydrocarbon mixture at 250 K and 20 bar.

{
  "component_names": ["methane", "ethane", "propane", "n-butane"],
  "mole_fractions": [0.4, 0.3, 0.2, 0.1],
  "temperature": 250,
  "pressure": 20,
  "pressure_unit": "bar"
}

With the default Peng-Robinson model, mixture_flash reports a two-phase split with a vapor fraction of about 0.486.

Verification

.venv/bin/python scripts/check_public_data.py
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pytest
.venv/bin/python scripts/verify_stdio_client.py --command .venv/bin/vle-mcp

Security

The tools remain read-only and deterministic. Stdio requires no credentials; Streamable HTTP requires a resource-bound bearer token with vle:read. Read SECURITY.md, docs/security-model.md, and docs/remote-http.md before deployment or extension.

Authorship

Miguel Jackson owns and directs the project. M0 through M3 were implemented collaboratively by OpenAI Codex using the GPT-5.6 Sol model, following Miguel's instructions and approved plan. Development now continues with Claude Code (Claude Opus 5.5), which scoped the project to vle alone and built the vle-thermo 0.18 tool catalogue. See AUTHORS.md for the precise human/AI attribution and limitations.

License

MIT