Healthpoint Rs

healthpoint-rs

面向 Healthpoint HL7 FHIR® API 的 Rust 优先工具：包含类型化客户端、命令行、只读 MCP 服务，以及未来的开放社交数据适配器。

此代码库刻意采用代码优先、数据精简的方式：

• 用户自行提供 Healthpoint API 密钥／许可证。
• 不会将真实的 Healthpoint API 响应数据作为测试固件提交。
• 合成 FHIR 测试固件位于 crates/healthpoint-testkit/fixtures/。
• 本地导出内容会标注来源和再分发状态。
• 只有在许可／访问条款明确允许后，才会选择启用开放数据发布；默认禁用。

项目结构

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

安装

Rust 可用后，从 crates.io 安装：

cargo install healthpoint-mcp healthpoint-cli

从源码检出安装：

git clone https://github.com/edithatogo/healthpoint-rs.git
cd healthpoint-rs
bin/conductor-setup
cargo install --path crates/healthpoint-mcp
cargo install --path crates/healthpoint-cli

通过已发布的列表使用 Smithery 安装：edithatogo/healthpoint-rs。除非提供 Healthpoint 实时凭据，否则 Smithery 软件包会以合成模式启动。

使用方法

初始命令

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

MCP 服务是独立的二进制程序，因此命令行和 MCP 可以独立演进，同时共享相同的 crate。未提供 API 密钥时，它会以合成测试固件模式启动；设置 HEALTHPOINT_MODE=live 并提供 HEALTHPOINT_API_KEY，即可进行符合许可要求的实时 API 调用。

配置

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

2026-06-30 的 Healthpoint 门户验证确认，UAT 调用会使用 x-api-key 请求头访问 https://uat.healthpointapi.com/baseR4/。已观察到的端点和许可说明见 docs/healthpoint-api-access.md。

命令行示例

healthpoint doctor
healthpoint policy show

healthpoint fixture services --format human
healthpoint schema service-record
healthpoint 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 json
healthpoint get location <location-id> --format json
healthpoint get organization <organization-id> --format json
healthpoint get uri healthpoint://service/<service-id> --format json

healthpoint export manifest --output .healthpoint/manifest.json
healthpoint export services \
  --text "cervical screening" \
  --limit 25 \
  --format jsonl \
  --output .healthpoint/cervical-screening.jsonl

工具

工具	用途
healthpoint.diagnostic.status	显示已脱敏的运行时模式、配置和就绪状态。
healthpoint.access.notes	显示非机密的端点、身份验证和文档说明。
healthpoint.access.policy	显示复用前的保守访问／导出策略。
healthpoint.services.search	按文本、代码、区域筛选条件、游标和限制值搜索 HealthcareService 记录。
healthpoint.services.search_snomed	按类型、类别或专科中的 SNOMED CT 代码搜索 HealthcareService 记录。
healthpoint.services.nearby	查找指定纬度／经度附近的 HealthcareService 记录。
healthpoint.service.get	按 FHIR ID 读取一条 HealthcareService 记录。
healthpoint.location.get	按 FHIR ID 读取一条 Location 记录。
healthpoint.organization.get	按 FHIR ID 读取一条 Organization 记录。
healthpoint.resource.read	读取受支持的 healthpoint:// 资源 URI。

MCP 服务还会公开 3 个静态资源、4 个资源模板和 2 个提示词。启动示例见 docs/mcp-tools.md 和 docs/integrations/mcp-client-configs.md。

Claude Desktop 源码检出示例：

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

Healthpoint 实时模式需要有许可的 API 密钥：

{
  "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"
      }
    }
  }
}

集成契约

命令行可以为核心契约生成 JSON Schema：

healthpoint schema access-policy
healthpoint schema service-query
healthpoint schema service-record
healthpoint schema service-page
healthpoint schema location-record
healthpoint schema organization-record
healthpoint schema resource-uri
healthpoint schema export-manifest

这些 Schema 旨在帮助未来与 open_social_data、MCP 客户端以及跨代码库数据目录层集成，而不会过早地强行将 Healthpoint 的 FHIR 图转换为以 dataframe 为先的结构。

离线就绪工具

这些命令可在进行任何 Healthpoint 实时验证之前使用，适用于沙盒或 CI 元数据任务：

CONDUCTOR_ALLOW_NO_CARGO=1 bin/conductor-setup
bin/conductor-status
scripts/static-preflight.py
scripts/generate-contract-schemas.py
bin/mock-healthpoint-server --port 8787

Rust 可用后，模拟服务会为命令行提供一个合成 HTTP 目标：

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

参见 docs/mock-server.md、docs/static-preflight.md 和 docs/live-contract-capture.md。

开发环境

原生 Rust 和 devcontainer 设置说明见 docs/development-environment.md。

设计原则

1. FHIR 优先：保留原始 FHIR，同时提供类型化的领域记录。
2. 默认只读：不写入、不回退到抓取方式、不提供公共代理模式。
3. 自带密钥：发布代码并不附带访问权限或数据权利。
4. 全程保留来源信息：导出内容包含检索时间、来源、许可状态和工具版本。
5. 便于后续集成：稳定的 Rust trait 便于接入 open_social_data、MCP 客户端以及未来的数据／目录引擎。
6. 由 Conductor 管理上下文：实现轨道、决策和仓库状态与代码一并维护。
7. 仅使用合成测试数据：离线测试使用 testkit 资源，绝不使用真实的 Healthpoint 负载。

MCP Registry 元数据

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

官方 MCP Registry 要求显示此标记，以验证 Cargo/crates.io 所有权。

安全边界

这不是临床决策支持系统。它为持证用户检索并整理来自 Healthpoint 的目录／服务信息。任何下游用途都应保留 Healthpoint 署名、时效信息、注意事项和许可义务。

当前状态

初始脚手架完成后，当前处于实现探索阶段。已为 HealthcareService、Location 和 Organization 实现合成映射，其中包含更丰富的服务字段，例如资格条件、可用性、服务提供代码、特征、备注、端点、标识符和响应来源信息。Healthpoint 的公开材料确认其采用 HL7 FHIR 和 SNOMED CT，但在根据获许可的 API 文档验证之前，完整的端点和身份验证详情均有意设为可配置项。