内容
# practice-fusion-mcp
一款开源的、**优先支持 FHIR、只读**的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，适用于 **Practice Fusion**。连接 Claude（桌面版 / 代码版）、Cursor 或任何 MCP 客户端到 Practice Fusion 电子健康记录（EHR），以搜索患者、查看预约、病况、药物和实验室结果 — 运行在 Practice Fusion 的 **免费 Open FHIR 账户**上。
设计为只读。审计日志记录。无写入权限，无调度权限，无患者创建权限。
## 架构
```mermaid
flowchart LR
C["MCP 客户端<br/>Claude 桌面版 / 代码版 · Cursor"] -- stdio --> S
subgraph S["practice-fusion-mcp"]
direction TB
T["MCP 工具<br/>search_patients · get_patient<br/>appointments · conditions<br/>medications · lab_results"]
A["审计日志记录器<br/>stderr + 可选文件<br/>PHI 已编辑"]
F["FHIR 客户端<br/>Bundle 解包 · 转换器<br/>错误处理"]
TP["SMART 后端服务<br/>TokenProvider<br/>签名 JWT 声明 · token 缓存"]
T -. audited .-> A
T --> F
F --> TP
end
TP -- "OAuth2 客户端凭证" --> AUTH["PF token 端点"]
F -- "只读 FHIR R4" --> PF["Practice Fusion<br/>Open FHIR API"]
AUTH -- 访问令牌 --> F
```
每个工具调用都流经审计日志记录器；FHIR 客户端仅持有从签名 JWT 声明（SMART 后端服务）生成的短生命周期令牌，并且在记录之前会编辑长文本参数。
## 工具
| 工具 | 功能 |
|------|--------------|
| `search_patients` | 按姓名 / 出生日期 / 性别 / 标识符查找患者 |
| `get_patient` | 按 ID 获取患者的个人信息 |
| `get_appointments` | 按患者 / 状态 / 日期获取预约 |
| `get_conditions` | 获取患者的健康问题 / 诊断 |
| `get_medications` | 获取患者的药物请求 |
| `get_lab_results` | 获取患者的实验室观察结果 |
## 设置
1. 注册一个免费的 Practice Fusion **Open FHIR** 开发人员账户，并创建一个 **System / backend-services** 应用程序。记下您的 FHIR 基本 URL、令牌 URL、客户端 ID，并注册您的应用程序的公钥。
2. 提供以下环境变量。在生产环境中，使用您的 MCP 客户端的 `env` 块（如下一步所示）。在本地开发环境中，将 `.env.example` 复制到 `.env` — `pnpm dev` 会自动加载它。
3. 添加到您的 MCP 客户端配置中，例如 Claude 桌面版：
```json
{
"mcpServers": {
"practice-fusion": {
"command": "npx",
"args": ["-y", "practice-fusion-mcp"],
"env": {
"PF_FHIR_BASE_URL": "https://fhir.practicefusion.com/r4",
"PF_TOKEN_URL": "https://auth.practicefusion.com/token",
"PF_CLIENT_ID": "您的客户端 ID",
"PF_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}
}
}
}
```
### 环境变量
| 变量 | 是否必需 | 默认值 | 备注 |
|-----|----------|---------|-------|
| `PF_FHIR_BASE_URL` | 是 | — | FHIR R4 基本 URL |
| `PF_TOKEN_URL` | 是 | — | OAuth2 令牌端点 |
| `PF_CLIENT_ID` | 是 | — | 后端服务客户端 ID |
| `PF_PRIVATE_KEY` | 是 | — | PKCS8 PEM 私钥（与注册的公钥匹配） |
| `PF_SCOPES` | 否 | `system/*.read` | 请求的作用域 |
| `PF_TOKEN_ALG` | 否 | `RS384` | JWT 签名算法 |
| `PF_AUDIT_LOG` | 否 | — | 审计记录的可选文件路径（始终也会写入 stderr） |
## 安全性和 HIPAA
此服务器处理受保护的健康信息。**您**，部署者，是受覆盖的实体或商业关联方：您负责与 Veradigm/Practice Fusion 签订自己的商业关联协议（BAA），并在 HIPAA 适用的环境中运行此服务器。每个工具调用都经过审计日志记录（stderr，加上可选文件），长文本参数会被编辑。令牌和密钥永远不会被记录。此项目提供代码，而不是托管的数据服务。**不是法律建议。**
## 与其他实现的区别
另一个 Practice Fusion MCP 建立在 Practice Fusion 的*专有 Unity API*（付费 Integrator 层）上，并且是写密集型的。这个实现是 **基于 FHIR** 的（运行在 **免费** 的 Open 账户上），**只读**（较小的风险表面），并且 **审计日志记录**。
## 开发
```bash
pnpm install
pnpm test # 单元测试（模拟 FHIR）
pnpm build # 打包到 dist/
```
