{
  "markdown": "# healthpoint-rs\n\n[![smithery badge](https://smithery.ai/badge/edithatogo/healthpoint-rs)](https://smithery.ai/servers/edithatogo/healthpoint-rs)\n\nRust-first tooling for the Healthpoint HL7 FHIR® API: a typed client, CLI, read-only MCP server, and future open-social-data adapter.\n\nThis repository is intentionally **code-first and data-light**:\n\n- Users bring their own Healthpoint API key/licence.\n- No real Healthpoint API payloads are committed as fixtures.\n- Synthetic FHIR fixtures live in `crates/healthpoint-testkit/fixtures/`.\n- Local exports are marked with provenance and redistribution status.\n- Open-data publication is opt-in and disabled until licensing/access terms explicitly permit it.\n\n## Project shape\n\n```text\nhealthpoint-rs/\n  crates/\n    healthpoint-core/         # domain model, query model, provenance, provider traits, URI parsing\n    healthpoint-fhir/         # FHIR Bundle/Resource mapping and typed projections\n    healthpoint-client/       # HTTP client, auth, request policy, pagination hooks\n    healthpoint-export/       # JSON/JSONL/CSV/export manifests\n    healthpoint-cli/          # `healthpoint` CLI\n    healthpoint-mcp/          # read-only MCP server over the same core/client\n    healthpoint-osd-adapter/  # future open_social_data bridge, no hard dependency yet\n    healthpoint-testkit/      # synthetic fixtures and offline fixture provider\n  conductor/                  # context-management state, decisions, checkpoints, tracks\n  docs/                       # access, licensing, MCP, exports, integration roadmap\n```\n\n## Installation\n\nInstall from crates.io after Rust is available:\n\n```bash\ncargo install healthpoint-mcp healthpoint-cli\n```\n\nInstall from source checkout:\n\n```bash\ngit clone https://github.com/edithatogo/healthpoint-rs.git\ncd healthpoint-rs\nbin/conductor-setup\ncargo install --path crates/healthpoint-mcp\ncargo install --path crates/healthpoint-cli\n```\n\nInstall through Smithery from the published listing: [edithatogo/healthpoint-rs](https://smithery.ai/servers/edithatogo/healthpoint-rs). The Smithery package starts in synthetic mode unless live Healthpoint credentials are supplied.\n\n## Usage\n\nFirst commands\n\n```bash\ncp .env.example .env\n$EDITOR .env\nbin/conductor-setup\ncargo run -p healthpoint-cli -- doctor\ncargo run -p healthpoint-cli -- fixture services --format json\ncargo run -p healthpoint-cli -- inspect search-url --text \"cervical screening\" --snomed 171149006\ncargo run -p healthpoint-cli -- search services --text \"cervical screening\" --format json\ncargo run -p healthpoint-cli -- search services --snomed 171149006 --format json\ncargo run -p healthpoint-cli -- get service <id> --format json\ncargo run -p healthpoint-cli -- get uri healthpoint://service/<id> --format json\ncargo run -p healthpoint-mcp\n```\n\nThe 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.\n\n## Configuration\n\n```bash\nexport HEALTHPOINT_MODE=\"synthetic\"                       # synthetic | live\nexport HEALTHPOINT_API_KEY=\"...\"                         # optional; required only for live mode\nexport HEALTHPOINT_BASE_URL=\"https://uat.healthpointapi.com/baseR4/\"\nexport HEALTHPOINT_AUTH_SCHEME=\"x-api-key\"               # bearer | x-api-key | header:<name> | none\nexport HEALTHPOINT_GEO_SEARCH_MODE=\"healthpoint-lat-lon\" # healthpoint-lat-lon | fhir-near\nexport HEALTHPOINT_TIMEOUT_SECS=\"30\"\nexport HEALTHPOINT_EXPORT_POLICY=\"local-only\"            # local-only | licensed-share | open-approved\n```\n\nHealthpoint 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.\n\n## CLI examples\n\n```bash\nhealthpoint doctor\nhealthpoint policy show\n\nhealthpoint fixture services --format human\nhealthpoint schema service-record\nhealthpoint schema resource-uri\n\nhealthpoint inspect search-url \\\n  --text \"cervical screening\" \\\n  --snomed 171149006 \\\n  --limit 10\n\nhealthpoint search services \\\n  --text \"cervical screening\" \\\n  --snomed 171149006 \\\n  --limit 10 \\\n  --format json\n\nhealthpoint search services \\\n  --lat -36.8485 \\\n  --lon 174.7633 \\\n  --radius-km 10 \\\n  --format csv\n\nhealthpoint get service <service-id> --format json\nhealthpoint get location <location-id> --format json\nhealthpoint get organization <organization-id> --format json\nhealthpoint get uri healthpoint://service/<service-id> --format json\n\nhealthpoint export manifest --output .healthpoint/manifest.json\nhealthpoint export services \\\n  --text \"cervical screening\" \\\n  --limit 25 \\\n  --format jsonl \\\n  --output .healthpoint/cervical-screening.jsonl\n```\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `healthpoint.diagnostic.status` | Show redacted runtime mode, configuration, and readiness. |\n| `healthpoint.access.notes` | Show non-secret endpoint, auth, and documentation notes. |\n| `healthpoint.access.policy` | Show the conservative access/export policy before reuse. |\n| `healthpoint.services.search` | Search HealthcareService records by text, codes, region filters, cursor, and limit. |\n| `healthpoint.services.search_snomed` | Search HealthcareService records by SNOMED CT code in type, category, or specialty. |\n| `healthpoint.services.nearby` | Find HealthcareService records near a latitude/longitude point. |\n| `healthpoint.service.get` | Read one HealthcareService by FHIR id. |\n| `healthpoint.location.get` | Read one Location by FHIR id. |\n| `healthpoint.organization.get` | Read one Organization by FHIR id. |\n| `healthpoint.resource.read` | Read a supported `healthpoint://` resource URI. |\n\nThe 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.\n\nClaude Desktop source-checkout example:\n\n```json\n{\n  \"mcpServers\": {\n    \"healthpoint-dev\": {\n      \"command\": \"cargo\",\n      \"args\": [\"run\", \"-p\", \"healthpoint-mcp\"],\n      \"env\": {\n        \"HEALTHPOINT_MODE\": \"synthetic\"\n      }\n    }\n  }\n}\n```\n\nLive Healthpoint mode requires a licensed API key:\n\n```json\n{\n  \"mcpServers\": {\n    \"healthpoint-live\": {\n      \"command\": \"healthpoint-mcp\",\n      \"env\": {\n        \"HEALTHPOINT_MODE\": \"live\",\n        \"HEALTHPOINT_API_KEY\": \"...\",\n        \"HEALTHPOINT_BASE_URL\": \"https://uat.healthpointapi.com/baseR4/\",\n        \"HEALTHPOINT_AUTH_SCHEME\": \"x-api-key\"\n      }\n    }\n  }\n}\n```\n\n## Integration contracts\n\nThe CLI can emit JSON Schema for the core contracts:\n\n```bash\nhealthpoint schema access-policy\nhealthpoint schema service-query\nhealthpoint schema service-record\nhealthpoint schema service-page\nhealthpoint schema location-record\nhealthpoint schema organization-record\nhealthpoint schema resource-uri\nhealthpoint schema export-manifest\n```\n\nThose 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.\n\n\n## Offline readiness tools\n\nThese commands work before any live Healthpoint validation and are useful in sandboxes or CI metadata jobs:\n\n```bash\nCONDUCTOR_ALLOW_NO_CARGO=1 bin/conductor-setup\nbin/conductor-status\nscripts/static-preflight.py\nscripts/generate-contract-schemas.py\nbin/mock-healthpoint-server --port 8787\n```\n\nAfter Rust is available, the mock server gives the CLI a synthetic HTTP target:\n\n```bash\nexport HEALTHPOINT_BASE_URL=\"http://127.0.0.1:8787/\"\nexport HEALTHPOINT_AUTH_SCHEME=\"none\"\ncargo run -p healthpoint-cli -- search services --snomed 171149006 --format json\n```\n\nSee `docs/mock-server.md`, `docs/static-preflight.md`, and `docs/live-contract-capture.md`.\n\n## Development environment\n\nSee `docs/development-environment.md` for native Rust and devcontainer setup.\n\n## Design principles\n\n1. **FHIR-first**: preserve raw FHIR while exposing typed domain records.\n2. **Read-only by default**: no writes, no scraping fallback, no public proxy mode.\n3. **Bring-your-own-key**: releasing code does not bundle access or data rights.\n4. **Provenance everywhere**: exports carry retrieval time, source, licence status, and tool version.\n5. **Integratable later**: stable Rust traits make it possible to plug into `open_social_data`, MCP clients, and future data/catalog engines.\n6. **Conductor-managed context**: implementation tracks, decisions, and repo state live alongside the code.\n7. **Synthetic fixtures only**: offline testing is done with testkit resources, never real Healthpoint payloads.\n\n## MCP Registry metadata\n\n- MCP Registry name: `mcp-name: io.github.edithatogo/healthpoint-rs`\n\nThis visible marker is required for Cargo/crates.io ownership verification by the official MCP Registry.\n\n## Safety boundary\n\nThis 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.\n\n## Current status\n\nImplementation 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.\n",
  "bytes": 9670,
  "sha": "19489ec6b6fe609a42e89599ebfeb7280be294548ed657e140d68575d503669f",
  "repo_slug": "edithatogo/healthpoint-rs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_edithatogo_healthpoint_rs_f1edea2f/readme"
}