内容
# healthpoint-rs
[](https://smithery.ai/servers/edithatogo/healthpoint-rs)
基于 Rust 的 Healthpoint HL7 FHIR® API 工具集：类型化的客户端、命令行界面、只读 MCP 服务器和未来的开放社交数据适配器。
本仓库故意采用 **代码优先和数据轻量** 的方式：
- 用户需自行提供 Healthpoint API 密钥/许可证。
- 不提交真实的 Healthpoint API 有效载荷作为固定数据。
- 合成 FHIR 固定数据位于 `crates/healthpoint-testkit/fixtures/`。
- 本地导出数据附带来源和重新分发状态。
- 开放数据发布需用户选择开启，并且仅在许可/访问条款明确允许时才启用。
## 项目结构
```text
healthpoint-rs/
crates/
healthpoint-core/ # 领域模型、查询模型、来源、提供者特征、URI 解析
healthpoint-fhir/ # FHIR Bundle/Resource 映射和类型化投影
healthpoint-client/ # HTTP 客户端、身份验证、请求策略、分页钩子
healthpoint-export/ # JSON/JSONL/CSV/导出清单
healthpoint-cli/ # `healthpoint` 命令行界面
healthpoint-mcp/ # 基于相同核心/客户端的只读 MCP 服务器
healthpoint-osd-adapter/ # 未来的开放社交数据桥接，目前无硬依赖
healthpoint-testkit/ # 合成固定数据和离线固定数据提供者
conductor/ # 上下文管理状态、决策、检查点、跟踪
docs/ # 访问、许可、MCP、导出、集成路线图
```
## 安装
在 Rust 可用后，从 crates.io 安装：
```bash
cargo install healthpoint-mcp healthpoint-cli
```
从源代码安装：
```bash
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](https://smithery.ai/servers/edithatogo/healthpoint-rs)。Smithery 包在没有提供 live Healthpoint 凭证时默认启动于合成模式。
## 使用
首批命令
```bash
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 "宫颈筛查" --snomed 171149006
cargo run -p healthpoint-cli -- search services --text "宫颈筛查" --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 可以独立演化，同时共享相同的 crate。当没有提供 API 密钥时，它以合成固定数据模式启动；设置 `HEALTHPOINT_MODE=live` 并提供 `HEALTHPOINT_API_KEY` 以进行授权的实时 API 调用。
## 配置
```bash
export HEALTHPOINT_MODE="synthetic" # synthetic | live
export HEALTHPOINT_API_KEY="..." # 可选；仅实时模式需要
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
```
Healthpoint 门户验证于 2026-06-30 确认 UAT 调用使用 `x-api-key` 头部针对 `https://uat.healthpointapi.com/baseR4/`。参见 `docs/healthpoint-api-access.md` 获取观察到的端点和许可说明。
## 命令行界面示例
```bash
healthpoint doctor
healthpoint policy show
healthpoint fixture services --format human
healthpoint schema service-record
healthpoint schema resource-uri
healthpoint inspect search-url \
--text "宫颈筛查" \
--snomed 171149006 \
--limit 10
healthpoint search services \
--text "宫颈筛查" \
--snomed 171149006 \
--limit 10 \
--format json
healthpoint search services \
--lat -36.8485 \
--lon 174.7633 \
--radius-km 10 \
--format csv
healthpoint get service <服务 ID> --format json
healthpoint get location <位置 ID> --format json
healthpoint get organization <组织 ID> --format json
healthpoint get uri healthpoint://service/<服务 ID> --format json
healthpoint export manifest --output .healthpoint/manifest.json
healthpoint export services \
--text "宫颈筛查" \
--limit 25 \
--format jsonl \
--output .healthpoint/宫颈筛查.jsonl
```
## 工具
| 工具 | 目的 |
| --- | --- |
| `healthpoint.diagnostic.status` | 显示删减的运行时模式、配置和准备情况。 |
| `healthpoint.access.notes` | 显示非机密端点、身份验证和文档说明。 |
| `healthpoint.access.policy` | 显示在重用前的保守访问/导出策略。 |
| `healthpoint.services.search` | 按文本、代码、区域过滤器、光标和限制搜索医疗服务记录。 |
| `healthpoint.services.search_snomed` | 按 SNOMED CT 代码在类型、类别或专业中搜索医疗服务记录。 |
| `healthpoint.services.nearby` | 查找纬度/经度点附近的医疗服务记录。 |
| `healthpoint.service.get` | 通过 FHIR ID 读取医疗服务记录。 |
| `healthpoint.location.get` | 通过 FHIR ID 读取位置记录。 |
| `healthpoint.organization.get` | 通过 FHIR ID 读取组织记录。 |
| `healthpoint.resource.read` | 读取支持的 `healthpoint://` 资源 URI。 |
MCP 服务器还公开了 3 个静态资源、4 个资源模板和 2 个提示。参见 `docs/mcp-tools.md` 和 `docs/integrations/mcp-client-configs.md` 获取启动示例。
Claude Desktop 源代码检查示例：
```json
{
"mcpServers": {
"healthpoint-dev": {
"command": "cargo",
"args": ["run", "-p", "healthpoint-mcp"],
"env": {
"HEALTHPOINT_MODE": "synthetic"
}
}
}
}
```
实时 Healthpoint 模式需要授权的 API 密钥：
```json
{
"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 模式：
```bash
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
```
这些模式旨在帮助未来与 `open_social_data`、MCP 客户端和任何跨仓库数据目录层集成，而不会过早地将 Healthpoint 的 FHIR 图强制转换为以数据帧为中心的结构。
## 离线准备工具
这些命令在任何实时 Healthpoint 验证之前都有效，在沙盒或 CI 元数据作业中非常有用：
```bash
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 目标：
```bash
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`。
## 开发环境
参见 `docs/development-environment.md` 获取原生 Rust 和 devcontainer 设置。
## 设计原则
1. **FHIR 优先**：在公开类型化的领域记录的同时保留原始 FHIR。
2. **默认只读**：无写入、无爬取回落、无公共代理模式。
3. **自带密钥**：发布代码不包含访问或数据权限。
4. **处处有来源**：导出包含检索时间、来源、许可状态和工具版本。
5. **可集成**：稳定的 Rust 特性使得可以插入 `open_social_data`、MCP 客户端和未来的数据/目录引擎。
6. **导演管理上下文**：实现跟踪、决策和仓库状态与代码一起生活。
7. **仅合成固定数据**：离线测试使用测试工具资源，从不使用真实的 Healthpoint 有效载荷。
## MCP 注册表元数据
- MCP 注册表名称：`mcp-name: io.github.edithatogo/healthpoint-rs`
此可见标记是官方 MCP 注册表所需的 Cargo/crates.io 所有权验证。
## 安全边界
这不是临床决策支持系统。它为授权用户检索和格式化来自 Healthpoint 的目录/服务信息。任何下游使用都应保留 Healthpoint 属性、货币、警告和许可义务。
## 当前状态
在初始框架后实施激增。存在 `HealthcareService`、`Location` 和 `Organization` 的合成映射，包括更丰富的服务字段，例如资格、可用性、服务提供代码、特征、注释、端点、标识符和响应来源。公共 Healthpoint 材料确认 HL7 FHIR 和 SNOMED CT 导向，但完整的端点/身份验证详细信息在验证为授权的 API 文档之前故意视为可配置。
