clincalc 0.2.1

Open, auditable clinical calculators: a pure scoring engine plus the `clincalc` CLI in one crate. The engine is a serde-only leaf (build with default-features = false); the default `cli` feature adds the `clincalc` binary.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

# clincalc - open clinical calculators

Open source, community-auditable clinical calculators in a `stdio` CLI and MCP tool, on top of a fast, Rust-based core engine.

A clinical calculation score is computed in the core Rust library, so the result is identical wherever it appears. Every calculator cites primary literature, is tested against published vectors, and records the licence it is distributed under.

## Why

Clinicians need clinical digital tools to provide good care, but the incentives to build them into EHRs are weak and the compliance barriers are high. The result is a patchwork of calculators scattered across the web, often behind paywalls or implemented inconsistently. This project makes them **open source, free to use, evidence-based, and auditable** - each cites primary literature, is tested against published vectors, and records the licence it is distributed under.

### 'Soft interoperability'

'Soft interoperability' is a phrase coined by Marcus Baw (@pacharanero) to describe the everyday copy-and-paste interop which is used by clincians as a substitute for 'proper' interoperability: it lets clinicians use the tools they want without being constrained by their EHR. Copy-and-paste is derided as a kludge, but it is what clinicians actually use, so every calculator produces a clean, editable text summary as a first-class output - while also dispatching structured results when embedded in a host.

## Install and use the `clincalc` CLI

After the first GitHub Release is published, the docs site hosts cargo-dist installer proxies:

```bash
curl -LsSf https://pacharanero.github.io/clincalc/install.sh | sh
```

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://pacharanero.github.io/clincalc/install.ps1 | iex"
```

Until then, install from source:

```bash
cargo install --git https://github.com/pacharanero/clincalc clincalc
```

There are no per-calculator flags. Every calculator is driven the same way - ask for a template, fill it in, pass it back:

```bash
clincalc list                       # list calculators (add --format json for licences)
clincalc <name>                     # print a fillable input TEMPLATE (JSON)
clincalc <name> --schema            # the JSON Schema (full input contract)
clincalc <name> --license           # the algorithm's distribution licence + evidence URL
clincalc <name> --input -           # compute, reading JSON from stdin
clincalc <name> --input data.json   # ...or from a file
clincalc <name> --input '{...}'     # ...or inline
```

```console
$ clincalc curb65 --input '{"confusion":false,"urea_mmol_l":8,"respiratory_rate":32,"systolic_bp":85,"diastolic_bp":55,"age":72}'
curb65 = 4
High severity ... consider hospital admission and assessment for intensive care.
```

The template printed by `clincalc <name>` has the same shape as the input it expects, so it is a clean round-trip. Output, schema, and template are JSON on stdout; hints go to stderr.

## MCP server

`clincalc` can also run as a local stdio MCP server when installed with the optional `mcp` feature:

```bash
cargo install --git https://github.com/pacharanero/clincalc clincalc --features mcp
clincalc mcp
```

The MCP server exposes every calculator as a typed tool named `clincalc_<name>` using the calculator's own JSON Schema. See [`docs/mcp.md`](docs/mcp.md) for host configuration and safety notes.

## The library

The full UK-focused 50-tool roadmap (`spec/calculator-roadmap.md`) is implemented across five tiers, from QRISK3, PHQ-9, GAD-7, eGFR and FIB-4 through NEWS2, CURB-65, the Wells scores, CHA2DS2-VASc and HAS-BLED, to DAS28, SOFA, MELD, CHALICE and Gleason. Run `clincalc list` for the current set.

### Proprietary tools are named, not hidden

A handful of tools cannot be shipped because they are proprietary or licence-locked (FRAX, MMSE, ELF, ACQ, the Oxford Hip/Knee Scores, CAT, MUST, CFS, LANSS). Rather than omit them silently, each is registered as a calculator that returns a structured explanation - the owner, why it cannot be shipped, open alternatives (often one shipped here), and how to advocate for open clinical tools:

```console
$ clincalc frax --input '{}'
frax = unavailable: proprietary
FRAX ... is not available because it is proprietary or licence-locked. Owner:
University of Sheffield ... Open alternatives: qfracture ...
```

## Architecture: one core, many surfaces

The dependency arrows all point **into** the core, which never depends on anything above it:

- **`clincalc`** - one crate, two surfaces. With `default-features = false` it is the pure scoring engine and result schema: a strict leaf depending only on `serde` and `serde_json`, never on an async runtime or any host - which makes the calculators detachable and embeddable.
- The default **`cli` feature** adds the `clincalc` binary and the reusable `clincalc::cli` module (`run` + `CalcCommand`). A host CLI such as GitEHR's `gitehr calc` subcommand calls this same module, so nothing is reimplemented.
- The optional **`mcp` feature** adds `clincalc mcp`, a local stdio MCP server for LLM hosts. Each MCP tool is generated from `clincalc::all()` and uses the calculator's own `input_schema()`.
- **`clincalc-web`** - single-file HTML calculators with a shared context-detection bridge.

Adding a calculator to `clincalc::all()` surfaces it everywhere - CLI, MCP, web - with no per-surface code.

### Input definitions

Several inputs are clinician-asserted predicates whose TRUE/FALSE conditions are easy to get subtly wrong (for example, "vascular disease" in CHA2DS2-VASc is arterial and excludes venous thromboembolism). Each such input carries a machine-readable definition - includes, excludes, a cited source, and a draft SNOMED ECL - that travels in the schema to every surface. See `spec/calculator-input-definitions.md`.

## Embedding in a host (for example, GitEHR)

Any application can embed these crates. GitEHR ([gitehr/gitehr](https://github.com/gitehr/gitehr)) is one consumer: its CLI forwards `gitehr calc` to `clincalc::cli::run`, and a host MCP server can expose each calculator from `clincalc::all()` as a `clincalc_<name>` tool whose input schema is the calculator's own JSON Schema. The calculators are the engine; a host wires them into its own surfaces.

## Develop

```bash
cargo test                                      # all calculators
cargo clippy --all-targets -- -D warnings
cargo fmt --all --check
```

CI enforces all three. Adding a calculator: implement it in `clincalc` (typed input, pure `compute`, `build_response`, a `Calculator` impl with `input_schema()` and `license()`, and literature-vector tests), register it in `all()`, and that is the only Rust work - the CLI and MCP surfaces pick it up automatically. See `spec/calculators.md` and `skills/build-calculator/`.

## Licensing

- `clincalc`: AGPL-3.0-or-later. This work is deliberately not available for subsumption into proprietary EHRs; if that service needs to exist, it can be offered as a hosted Calc-API.
- Clinical algorithms are implemented from primary literature (most scores are public-domain methods); QRISK3 and QFracture are ported from ClinRisk's LGPL-3.0 source and carry the required disclaimer. Each calculator records its own distribution licence via `clincalc <name> --license`.
- Clinical content (source references) under CC-BY-SA-4.0.

## Roadmap

See [`spec/roadmap.md`](spec/roadmap.md) for engineering, infrastructure, distribution, GUI, and product-level work, and [`spec/calculator-roadmap.md`](spec/calculator-roadmap.md) for the clinical-calculator backlog.