healthpoint-rs

healthpoint-rs

[smithery badge]

Rust-first tooling for the Healthpoint HL7 FHIR® API: a typed client, CLI, read-only MCP server, and future open-social-data adapter.

This repository is intentionally code-first and data-light:

• Users bring their own Healthpoint API key/licence.
• No real Healthpoint API payloads are committed as fixtures.
• Synthetic FHIR fixtures live in crates/healthpoint-testkit/fixtures/.
• Local exports are marked with provenance and redistribution status.
• Open-data publication is opt-in and disabled until licensing/access terms explicitly permit it.

Project shape

healthpoint-rs/  crates/    healthpoint-core/         # domain model, query model, provenance, provider traits, URI parsing    healthpoint-fhir/         # FHIR Bundle/Resource mapping and typed projections    healthpoint-client/       # HTTP client, auth, request policy, pagination hooks    healthpoint-export/       # JSON/JSONL/CSV/export manifests    healthpoint-cli/          # `healthpoint` CLI    healthpoint-mcp/          # read-only MCP server over the same core/client    healthpoint-osd-adapter/  # future open_social_data bridge, no hard dependency yet    healthpoint-testkit/      # synthetic fixtures and offline fixture provider  conductor/                  # context-management state, decisions, checkpoints, tracks  docs/                       # access, licensing, MCP, exports, integration roadmap

Installation

Install from crates.io after Rust is available:

cargo install healthpoint-mcp healthpoint-cli

Install from source checkout:

git clone https://github.com/edithatogo/healthpoint-rs.gitcd healthpoint-rsbin/conductor-setupcargo install --path crates/healthpoint-mcpcargo install --path crates/healthpoint-cli

Install through Smithery from the published listing: edithatogo/healthpoint-rs. The Smithery package starts in synthetic mode unless live Healthpoint credentials are supplied.

Usage

First commands

cp .env.example .env$EDITOR .envbin/conductor-setupcargo run -p healthpoint-cli -- doctorcargo run -p healthpoint-cli -- fixture services --format jsoncargo run -p healthpoint-cli -- inspect search-url --text "cervical screening" --snomed 171149006cargo run -p healthpoint-cli -- search services --text "cervical screening" --format jsoncargo run -p healthpoint-cli -- search services --snomed 171149006 --format jsoncargo run -p healthpoint-cli -- get service <id> --format jsoncargo run -p healthpoint-cli -- get uri healthpoint://service/<id> --format jsoncargo run -p healthpoint-mcp

The MCP server is a separate binary so CLI and MCP can evolve independently while sharing the same crates. It starts in synthetic fixture mode when no API key is supplied; set HEALTHPOINT_MODE=live and provide HEALTHPOINT_API_KEY for licensed live API calls.

Configuration

export HEALTHPOINT_MODE="synthetic"                       # synthetic | liveexport HEALTHPOINT_API_KEY="..."                         # optional; required only for live modeexport HEALTHPOINT_BASE_URL="https://uat.healthpointapi.com/baseR4/"export HEALTHPOINT_AUTH_SCHEME="x-api-key"               # bearer | x-api-key | header:<name> | noneexport HEALTHPOINT_GEO_SEARCH_MODE="healthpoint-lat-lon" # healthpoint-lat-lon | fhir-nearexport HEALTHPOINT_TIMEOUT_SECS="30"export HEALTHPOINT_EXPORT_POLICY="local-only"            # local-only | licensed-share | open-approved

Healthpoint portal validation on 2026-06-30 confirmed UAT calls use the x-api-key header against https://uat.healthpointapi.com/baseR4/. See docs/healthpoint-api-access.md for observed endpoint and license notes.

CLI examples

healthpoint doctorhealthpoint policy show
healthpoint fixture services --format humanhealthpoint schema service-recordhealthpoint schema resource-uri
healthpoint inspect search-url \  --text "cervical screening" \  --snomed 171149006 \  --limit 10
healthpoint search services \  --text "cervical screening" \  --snomed 171149006 \  --limit 10 \  --format json
healthpoint search services \  --lat -36.8485 \  --lon 174.7633 \  --radius-km 10 \  --format csv
healthpoint get service <service-id> --format jsonhealthpoint get location <location-id> --format jsonhealthpoint get organization <organization-id> --format jsonhealthpoint get uri healthpoint://service/<service-id> --format json
healthpoint export manifest --output .healthpoint/manifest.jsonhealthpoint export services \  --text "cervical screening" \  --limit 25 \  --format jsonl \  --output .healthpoint/cervical-screening.jsonl

Tools

The MCP server also exposes 3 static resources, 4 resource templates, and 2 prompts. See docs/mcp-tools.md and docs/integrations/mcp-client-configs.md for launch examples.

Claude Desktop source-checkout example:

{  "mcpServers": {    "healthpoint-dev": {      "command": "cargo",      "args": ["run", "-p", "healthpoint-mcp"],      "env": {        "HEALTHPOINT_MODE": "synthetic"      }    }  }}

Live Healthpoint mode requires a licensed API key:

{  "mcpServers": {    "healthpoint-live": {      "command": "healthpoint-mcp",      "env": {        "HEALTHPOINT_MODE": "live",        "HEALTHPOINT_API_KEY": "...",        "HEALTHPOINT_BASE_URL": "https://uat.healthpointapi.com/baseR4/",        "HEALTHPOINT_AUTH_SCHEME": "x-api-key"      }    }  }}

Integration contracts

The CLI can emit JSON Schema for the core contracts:

healthpoint schema access-policyhealthpoint schema service-queryhealthpoint schema service-recordhealthpoint schema service-pagehealthpoint schema location-recordhealthpoint schema organization-recordhealthpoint schema resource-urihealthpoint schema export-manifest

Those schemas are intended to help future integration with open_social_data, MCP clients, and any cross-repo data catalogue layer without prematurely forcing Healthpoint's FHIR graph into a dataframe-first shape.

Offline readiness tools

These commands work before any live Healthpoint validation and are useful in sandboxes or CI metadata jobs:

CONDUCTOR_ALLOW_NO_CARGO=1 bin/conductor-setupbin/conductor-statusscripts/static-preflight.pyscripts/generate-contract-schemas.pybin/mock-healthpoint-server --port 8787

After Rust is available, the mock server gives the CLI a synthetic HTTP target:

export HEALTHPOINT_BASE_URL="http://127.0.0.1:8787/"export HEALTHPOINT_AUTH_SCHEME="none"cargo run -p healthpoint-cli -- search services --snomed 171149006 --format json

See docs/mock-server.md, docs/static-preflight.md, and docs/live-contract-capture.md.

Development environment

See docs/development-environment.md for native Rust and devcontainer setup.

Design principles

1. FHIR-first: preserve raw FHIR while exposing typed domain records.
2. Read-only by default: no writes, no scraping fallback, no public proxy mode.
3. Bring-your-own-key: releasing code does not bundle access or data rights.
4. Provenance everywhere: exports carry retrieval time, source, licence status, and tool version.
5. Integratable later: stable Rust traits make it possible to plug into open_social_data, MCP clients, and future data/catalog engines.
6. Conductor-managed context: implementation tracks, decisions, and repo state live alongside the code.
7. Synthetic fixtures only: offline testing is done with testkit resources, never real Healthpoint payloads.

MCP Registry metadata

• MCP Registry name: mcp-name: io.github.edithatogo/healthpoint-rs

This visible marker is required for Cargo/crates.io ownership verification by the official MCP Registry.

Safety boundary

This is not a clinical decision-support system. It retrieves and formats directory/service information from Healthpoint for licensed users. Any downstream use should preserve Healthpoint attribution, currency, caveats, and licensing obligations.

Current status

Implementation spike after initial scaffold. Synthetic mapping exists for HealthcareService, Location, and Organization, including richer service fields such as eligibility, availability, service provision codes, characteristics, comments, endpoints, identifiers, and response provenance. The public Healthpoint material confirms HL7 FHIR and SNOMED CT orientation, but full endpoint/auth details are intentionally treated as configurable until validated against licensed API documentation.