Content
# ccpp-tools-mcp
[](https://github.com/jinhyunan/ccpp-tools-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
**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.
```text
"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](docs/cases/case-01-transcript.md), and an
**[interactive overview](https://jinhyunan.github.io/ccpp-tools-mcp/)** 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](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
```bash
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`):
```json
{
"mcpServers": {
"ccpp-tools": {
"command": "uvx",
"args": ["ccpp-tools-mcp"]
}
}
}
```
**Claude Code:**
```bash
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](docs/cases/case-01-fuel-oil-transfer.md)
and watch the tool chain run.
## Tools (v1)
| Tool | What it computes | Standard basis |
|------|------------------|----------------|
| `fluid_props_liquid` | ρ, ν/μ, Pv, SG for petroleum liquids (preset or custom 2-point fit) | API gravity / ASTM D341 |
| `fluid_props_steam` | water/steam v, h, s, cp, μ; saturation states | IAPWS-IF97 / R12-08 (own implementation) |
| `tank_capacity` | working/nominal volume, residence time | volume balance (ahead of API 650/620) |
| `pipe_size_select` | smallest NPS/SCH meeting a velocity limit | ASME B36.10M + continuity |
| `pipe_wall_thickness` | pressure-design wall vs selected schedule | ASME B31.1 §104.1.2 |
| `dp_segment_liquid` | Darcy friction + Crane fitting losses, Re/velocity flags | Crane TP-410 / Colebrook-White |
| `list_crane_fittings` | accepted fitting keys and their K basis | Crane TP-410 |
| `pump_tdh` | total dynamic head balance | Hydraulic Institute |
| `pump_npsha` | NPSH available + margin vs NPSHr | HI 9.6.1 concepts |
| `pump_power` | hydraulic / shaft power | ρgQH |
| `valve_cv_liquid` | required Cv/Kv + choked-flow check | ISA 75.01 / IEC 60534-2-1 |
## The response envelope
Every tool returns the same contract — a number you can defend:
```json
{
"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
```mermaid
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](docs/verification.md).
## Development
```bash
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.
