cfast-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server built around pycfast, a Python interface for CFAST (Consolidated Fire and Smoke Transport, NIST). It exposes tools that let an LLM build a CFAST model step by step, inspect it, run it, and read results.

The pycfast source is available at https://github.com/bewygs/pycfast. You can use gh cli to read it directly to check signatures, defaults, and validation logic.

Commands

uv sync --extra dev         # Install package + dev dependencies (Python 3.10+)
uv run cfast-mcp            # Run the server (console script)
uv run main.py              # Run the server (repo-root shim)
uv run mcp dev main.py      # MCP inspector UI
uv run ruff check --fix .   # Lint
uv run ruff format .        # Format
uv run mypy src/            # Type-check
uv run pytest               # Run all tests (CFAST-dependent ones skip if no binary)
uv run pytest -m local      # Run only the tests requiring the CFAST binary
uv run pytest --cov         # Coverage

Run a single test:

uv run pytest tests/test_model.py::test_create_model -v

Pre-commit hooks run ruff check --fix and ruff format.

Architecture

main.py                       # repo-root shim — re-exports server.mcp for `mcp dev`
src/cfast_mcp/
  server.py                   # builds FastMCP("cfast"), registers tools, main()
  registry.py                 # ModelRegistry: model_id -> ModelEntry, in memory
  errors.py                   # guard(): pycfast exceptions -> ToolError with hints
  serialization.py            # bounded DataFrame summaries (never full dumps)
  tools/                       # the 22 @mcp.tool() definitions, one module per component
    __init__.py                # register_tools(): wires all sub-registrars
    model.py                    # create_model, inspect_model, run_model, get_results, get_model_files
    simulation.py               # update_simulation
    materials.py                # add_material, update_material
    compartments.py             # add_compartment, update_compartment
    wall_vents.py                # add_wall_vent, update_wall_vent
    ceiling_floor_vents.py       # add_ceiling_floor_vent, update_ceiling_floor_vent
    mechanical_vents.py          # add_mechanical_vent, update_mechanical_vent
    fires.py                     # add_fire, update_fire
    devices.py                   # add_device, update_device
    surface_connections.py       # add_surface_connection, update_surface_connection