mcp-server-cantera copilot-instructions.md

mcp-server-cantera Copilot Instructions

This repository implements a Model Context Protocol (MCP) server integration for Cantera, enabling LLMs to perform chemical kinetics and thermodynamic calculations.

Architecture & Code Structure

• Core Logic: The entire server implementation resides in src/mcp_server_cantera/server.py.
• Framework: Uses FastMCP for clean, decorator-based tool definitions with Pydantic validation.
• Mechanism Discovery: The mechanisms/ directory at the project root stores custom .yaml mechanism files.
  • The server dynamically locates this folder via get_custom_mechanisms_dir().
  • resolve_mechanism() handles the logic to prefer custom mechanisms over built-ins.
• Package Layout: Standard src/ layout with pyproject.toml configuration.

Key Developer Workflows

Environment & Installation

• Package Manager: Uses uv for fast dependency resolution.
• Installation: uv pip install -e . (Editable install is CRITICAL for mechanism discovery to work).
• Python Version: Requires Python 3.10+.

Running the Server

# Run via CLI entry point
mcp-server-cantera

# Or via uv directly
uv run mcp-server-cantera

Testing

• Framework: pytest
• Location: tests/
• Run tests: uv run pytest

Coding Conventions

Cantera Usage Support

• Mechanism Loading: Always use resolve_mechanism(mech_name) before passing to ct.Solution().
• State Setting: Prefer gas.TPX = T, P, X or gas.TP = T, P for setting states.
• Units:
  • Temperature: Kelvin
  • Pressure: Pascals (Code may output bar for readability, but inputs/internal are Pa)
  • Energy: J or kJ (be explicit in output strings)

Pydantic Models for Tool Inputs

All tool inputs use Pydantic models for validation. Key models defined in server.py:

• GasStateInput: mechanism, temperature, pressure, composition
• EquilibriumInput: extends GasStateInput with equilibrium basis
• CombustionInput: fuel/oxidizer combustion setup
• SpeciesInput: species property lookup
• MechanismInput: single mechanism parameter