🧪 PyThermoCalcDB-NASA-MCP

PyThermoCalcDB-NASA-MCP is a Model Context Protocol server for running selected pythermocalcdb-nasa thermodynamic calculations from agents and MCP-compatible clients.

🌐 Overview

The MCP package is an interface and orchestration layer. It validates structured requests, builds a ModelSource, calls deterministic pythermocalcdb-nasa functions, and returns JSON-safe results. It does not implement the scientific calculation itself.

The default source workflow uses the embedded NASA-9 SQLite database included by pythermocalcdb-nasa. If a component is unavailable locally, the MCP server returns a structured failure. External data search is not this MCP server's responsibility; another agent or caller should prepare complete pyThermoDB REFERENCE content and call the tool with source: "reference".

Use this package to:

• Calculate H_T, S_T, G_T, and Cp_T for one component.
• Calculate dH_rxn_STD, dS_rxn_STD, dG_rxn_STD, Keq, and Keq_vh_shortcut for reactions.
• Validate externally prepared pyThermoDB YAML reference content.

📦 Installation

pip install pythermocalcdb-nasa-mcp

For local development:

uv sync

▶️ Running

STDIO is the default transport:

pythermocalcdb-nasa-mcp --mode stdio

HTTP transport is also supported:

pythermocalcdb-nasa-mcp --mode http --host 127.0.0.1 --port 8000 --path /mcp

From a local checkout:

uv run pythermocalcdb-nasa-mcp --mode stdio

🔌 MCP Client Configuration

🧵 STDIO:

{
  "mcpServers": {
    "pythermocalcdb-nasa": {
      "command": "pythermocalcdb-nasa-mcp",
      "args": ["--mode", "stdio"]
    }
  }
}

🌍 HTTP:

{
  "mcpServers": {
    "pythermocalcdb-nasa": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

🕵️ MCP Inspector

You can test the server with the official MCP Inspector.

For direct STDIO testing from a local checkout:

npx @modelcontextprotocol/inspector uv run pythermocalcdb-nasa-mcp --mode stdio

For HTTP testing, start the server first:

uv run pythermocalcdb-nasa-mcp --mode http --host 127.0.0.1 --port 8000 --path /mcp

Then connect Inspector to:

http://127.0.0.1:8000/mcp

📚 MCP Resources

• pythermocalcdb-nasa://references/nasa-requirements
  • Source policy, NASA symbols, units, temperature ranges, and agent boundaries.
• pythermocalcdb-nasa://workflows/species-properties
  • Workflow for H_T, S_T, G_T, and Cp_T.
• pythermocalcdb-nasa://workflows/reaction-properties
  • Workflow for dH_rxn_STD, dS_rxn_STD, dG_rxn_STD, Keq, and Keq_vh_shortcut.
• pythermocalcdb-nasa://guidance/agent-checklist
  • Checklist for reliable database-first and reference-backed calls.

🧰 MCP Tools

🔥 Species tools:

• calc_H_T
• calc_S_T
• calc_G_T
• calc_Cp_T

⚗️ Reaction tools:

• calc_dH_rxn_STD
• calc_dS_rxn_STD
• calc_dG_rxn_STD
• calc_Keq
• calc_Keq_vh_shortcut

🛠️ Utility tool:

• check_yaml_reference

📝 Input Model Notes

Calculation tools receive one Pydantic argument named request. They use shared domain models from pythermodb_settings, including Component, Temperature, and ComponentKey.

🗄️ Database-backed species request:

{
  "request": {
    "component": {
      "name": "carbon dioxide",
      "formula": "CO2",
      "state": "g"
    },
    "temperature": {
      "value": 300.0,
      "unit": "K"
    },
    "source": "database",
    "component_key": "Name-Formula",
    "nasa_type": "nasa9",
    "basis": "molar"
  }
}

📄 Reference-backed species request:

{
  "request": {
    "component": {
      "name": "component name from prepared reference",
      "formula": "Formula",
      "state": "g"
    },
    "temperature": {
      "value": 300.0,
      "unit": "K"
    },
    "source": "reference",
    "reference_content": "REFERENCES:\n  ...",
    "component_key": "Name-Formula",
    "nasa_type": "nasa9",
    "basis": "molar"
  }
}

🗄️ Database-backed reaction request:

{
  "request": {
    "name": "Water-Gas Shift Reaction",
    "reaction": "CO(g) + H2O(g) => CO2(g) + H2(g)",
    "components": [
      {"name": "carbon monoxide", "formula": "CO", "state": "g"},
      {"name": "dihydrogen monoxide", "formula": "H2O", "state": "g"},
      {"name": "carbon dioxide", "formula": "CO2", "state": "g"},
      {"name": "dihydrogen", "formula": "H2", "state": "g"}
    ],
    "temperature": {
      "value": 398.15,
      "unit": "K"
    },
    "source": "database",
    "component_key": "Name-Formula",
    "nasa_type": "nasa9"
  }
}

Use the same reaction request shape with calc_Keq_vh_shortcut when a van't Hoff shortcut estimate is requested. It returns a dimensionless equilibrium constant.

Responses follow this contract:

{
  "success": true,
  "message": "H_T completed successfully.",
  "results": {
    "operation": "H_T",
    "value": 0.0,
    "unit": "J/mol"
  },
  "analysis": {
    "source": "database"
  },
  "warnings": []
}

✅ Best Practices

• Use source: "database" first for NASA-9 data in supported g, l, and s phases.
• Use source: "reference" only with complete externally prepared reference_content.
• Do not ask this MCP server to search external scientific data.
• Keep temperature inputs in Kelvin.
• Make sure every reaction species appears in both the reaction equation and components.
• Use nasa_type: "nasa9" with the database source.
• Check success, message, and warnings before reporting results.

🧪 Development Quick Check

python -m py_compile pythermocalcdb_nasa_mcp/server.py
python -m py_compile pythermocalcdb_nasa_mcp/interface/core.py
python -m py_compile pythermocalcdb_nasa_mcp/models/nasa.py
python -m unittest discover tests

🚀 Examples

Example payload shapes are available in examples/request_payloads.py.

📄 License

This project is licensed under the Apache License 2.0. See LICENSE.

👤 Author

• @sinagilassi