Ccpp Tools

ci License: Apache-2.0 Python 3.12+

Deterministic, standards-traceable engineering calculations for combined-cycle power plant (CCPP) balance-of-plant design — exposed as an MCP server.

LLM agents are excellent at orchestrating an engineering workflow in natural language and terrible at arithmetic. This server splits the work accordingly: any MCP client (Claude Desktop, Claude mobile, Claude Code, Cursor, or an internal agent) drives the conversation, while every number comes from a pure, tested Python function that returns its evidence — the governing standard, the equation evaluated, the assumptions you must own, and the warnings you must not ignore.

"Verify this fuel-oil transfer system: 60 m³/h diesel at 40 °C,
 180 m discharge run rising 18 m, flooded suction, NPSHr 4 m…"

        Claude (orchestration, no arithmetic)
          │ tank_capacity        → 3,240 m³ working → 2 × 1,800 m³
          │ fluid_props_liquid   → ρ 819.8 kg/m³, μ 1.97 mPa·s  [ASTM D341]
          │ pipe_size_select     → NPS 4 SCH 40, 2.03 m/s ✓ (1–3 band)
          │ dp_segment_liquid    → Re 8.6e4, f 0.0205, 9.76 m    [Crane TP-410]
          │ pump_tdh             → TDH 28.8 m → rate at 32 m
          │ pump_npsha           → NPSHa 13.0 m vs NPSHr 4.0 ✓
          └ valve_cv_liquid      → Cv 11.9, not choked           [ISA 75.01]

The full conversation, produced by a real Claude client calling this server end to end, is preserved verbatim in docs/cases/case-01-transcript.md, and an interactive overview lets you step through the tool chain response by response.

Why trust the numbers

Every calculation is held by two independent legs (docs/verification.md):

1. Golden tests from the governing documents. The IAPWS-IF97 water/steam implementation is written from the release itself (regions 1/2/4 + R12-08 viscosity, stdlib only) and locked by the release's own computer-program verification tables at 8–9 significant figures.
2. Cross-validation against independent implementations. ~1,800 swept assertions compare the runtime core against fluids and iapws — which are test-only dependencies. The runtime has zero third-party calculation code, so the comparison is never circular.

The harness has already earned its keep: it caught a wall-thickness transcription error (NPS 18 SCH 80, 23.88 → 23.83 mm) and rejected five golden values written from memory instead of the document. Both incidents are kept in the verification log on purpose.

Quick start

uvx ccpp-tools-mcp                 # stdio (once published to PyPI)
# or from a checkout:
uv run ccpp-tools-mcp              # stdio
uv run ccpp-tools-mcp --transport streamable-http --port 8899   # HTTP

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ccpp-tools": {
      "command": "uvx",
      "args": ["ccpp-tools-mcp"]
    }
  }
}

Claude Code:

claude mcp add ccpp-tools -- uvx ccpp-tools-mcp

Claude mobile / web: run the HTTP transport, expose it (e.g. cloudflared tunnel --url http://localhost:8899), and add https://<your-tunnel>/mcp as a custom connector.

Then paste the demo prompt from docs/cases/case-01-fuel-oil-transfer.md and watch the tool chain run.

Tools (v1)

The response envelope

Every tool returns the same contract — a number you can defend:

{
  "result":     { "npsha_m": 12.99, "margin_m": 8.99 },
  "method":     { "standard": "Hydraulic Institute (HI 9.6.1 concepts)",
                  "equation": "NPSHa = (P_surface,abs - Pv)/(rho g) + z_static - h_f,suction" },
  "assumptions": [ "atmospheric pressure 101.325 kPa(a)",
                   "vapor pressure 0.5 kPa(a) at pumping temperature" ],
  "warnings":   [],
  "validity":   "ok"
}

Warnings are load-bearing: an undersized line answers with the number and a velocity flag; a deep-turndown case flags the laminar–turbulent transition; a near-saturation valve sizing reports choked flow. The orchestrating agent is expected to surface every warning to the user — the Case 01 transcript shows that happening.

Architecture

flowchart LR
    subgraph clients [MCP clients]
        A[Claude Desktop / mobile]
        B[Claude Code / Cursor]
        C[internal plant agent]:::private
    end
    subgraph server [ccpp-tools-mcp]
        E[slim envelope<br/>result + method + assumptions + warnings]
        subgraph core [stdlib-only calculation core]
            P[pipe: B36.10M · B31.1]
            H[hydro: Colebrook · Crane K]
            Q[equipment: pump · tank · ISA 75.01]
            F[props: ASTM D341 · IAPWS-IF97]
        end
    end
    subgraph oracles [test-only oracles]
        O1[fluids]
        O2[iapws]
        O3[official verification tables]
    end
    A & B & C -->|stdio / streamable-http| E --> core
    core -.->|cross-validated in CI| oracles
    classDef private stroke-dasharray: 5 5,stroke:#888,color:#888;

The internal orchestrating agent shown dashed is a private, out-of-scope deployment; everything demonstrated here runs on generic public MCP clients.

Scope and honest limits

• Decision support, not engineering of record. Results carry their assumptions; the responsible engineer owns criterion selection, margins, and code compliance.
• v1 is liquid-service only; compressible dP, heat-exchanger rating, and parallel-flow distribution arrive in v1.1 with their own validated cases.
• IF-97 regions 3 (near-critical) and 5 are deliberately not implemented — out-of-range inputs raise instead of extrapolating.
• The bundled diesel preset is a representative ASTM D975 sample, not project fuel data, and says so in every response.
• Full gap list: docs/verification.md.

Development

uv sync --dev
git config core.hooksPath .githooks   # forbidden-token pre-commit gate
uv run pytest -q -m "not cross"       # unit + golden
uv run pytest -q -m cross tests/cross # sweeps vs fluids / iapws
uv run ruff check . && uv run mypy    # lint + strict types

License

Apache-2.0. Crane TP-410, ASME, ISA, HI, ASTM, and IAPWS are referenced as public standards; bring your own licensed copies for engineering use.