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

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:

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

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

Until then, install from source:

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:

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

$ 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:

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 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:

$ 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) 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

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 for engineering, infrastructure, distribution, GUI, and product-level work, and spec/calculator-roadmap.md for the clinical-calculator backlog.