Healthpoint Rs

healthpoint-rs

Healthpoint HL7 FHIR® API 向けの Rust ファーストなツール群です。型付きクライアント、CLI、読み取り専用 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

公開リスティング edithatogo/healthpoint-rs から Smithery 経由でインストールします。ライブの 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 サーバーは別のバイナリとして提供されるため、同じクレートを共有しながら、CLI と MCP を個別に進化させられます。API キーが指定されていない場合は、合成フィクスチャモードで起動します。ライセンスが適用されるライブ API 呼び出しを行うには、HEALTHPOINT_MODE=live を設定し、HEALTHPOINT_API_KEY を指定してください。

設定

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 呼び出しは https://uat.healthpointapi.com/baseR4/ に対して x-api-key ヘッダーを使用することが確認されました。確認済みのエンドポイントとライセンスに関する注記については、docs/healthpoint-api-access.md を参照してください。

CLI の例

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	type、category、specialty の SNOMED CT コードで HealthcareService レコードを検索します。
healthpoint.services.nearby	緯度／経度の地点付近にある HealthcareService レコードを検索します。
healthpoint.service.get	FHIR ID を指定して HealthcareService を 1 件読み取ります。
healthpoint.location.get	FHIR ID を指定して Location を 1 件読み取ります。
healthpoint.organization.get	FHIR ID を指定して Organization を 1 件読み取ります。
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"
      }
    }
  }
}

インテグレーションの契約

CLI では、主要な契約の 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

これらのスキーマは、Healthpoint の FHIR グラフを時期尚早にデータフレームファーストの形式へ押し込むことなく、将来的に open_social_data、MCP クライアント、リポジトリを横断するデータカタログ層と統合できるようにすることを目的としています。

オフライン対応ツール

これらのコマンドは、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 を利用できる状態になった後は、モックサーバーを使って CLI に合成 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トレイトにより、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のドキュメントで検証するまで、設定可能なものとして扱います。