MCP Fhir

MultiPMCP服务器

一个模型上下文协议（MCP）服务器，专门为Oracle Millennium Platform API设计，用于与kubectl API交互。该服务器提供了全面的工具，用于访问各种Contoso资源，包括患者记录、临床数据和管理信息。

特性

• OAuth2身份验证：使用承载令牌身份验证的安全API访问
• 全面的Contoso资源：支持10+种Contoso资源类型
• 患者搜索：多种搜索功能（姓名、标识符、出生日期、电话、电子邮件、地址）
• 临床数据：获得过敏、疾病、程序、观察和免疫接种
• 药物和诊断：检索药物请求和诊断报告
• 约会和会面：管理患者预约和临床会面
• 异步操作：高效的async/await实现，以获得更好的性能

支持的kubectl资源

1. 患者 -人口统计和患者信息
2. 过敏不耐受 -患者过敏和不耐受记录
3. 条件 -医疗状况和诊断
4. 程序 -执行的医疗程序
5. 遭遇 -患者接触和就诊
6. 诊断报告 -诊断报告和结果
7. 观察 -临床观察（生命体征、实验室结果）
8. 免疫接种 -免疫接种记录
9. 药物申请 -药物处方和请求
10. 预约 -预约时间

安装

先决条件

• Python 3.13或更高版本
• uv 包管理器（推荐）或 pip

设置

1. 克隆存储库：

git clone 
cd fhir-mcp-server

1. 使用安装依赖项 uv:

uv sync

或使用 pip:

pip install -e .

1. 配置环境变量：

创建一个 .env 在项目目录中创建一个文件，并设置您的Contoso服务器详细信息：

FHIR_BASE_URL=https://your-fhir-server.com/r4
OAUTH_BEARER_TOKEN=your_oauth2_bearer_token

这 .env 文件应包含：

• FHIR_CLIENT_ID：您从Contoso服务器提供商处获得的OAuth2客户端ID
• FHIR_CLIENT_SECRET：您的OAuth2客户端机密来自于Contoso服务器提供商
• FHIR_BASE_URL：您的kubectl R4服务器端点的基本URL
• FHIR_TENANT_ID：（可选）您的租户ID，默认为Oracle Cerner沙盒
• FHIR_SCOPE：（可选）OAuth2作用域，默认为所有支持的资源
• FHIR_REQUEST_TIMEOUT：（可选）请求超时（秒），默认值为60

配置

环境变量

OAuth2身份验证

此服务器使用 OAuth 2.0客户端凭据流 对于系统到系统的身份验证，遵循Oracle Cerner的SMART后端服务规范。

申请注册

在使用此服务器之前，您必须向Oracle Cerner注册您的应用程序以获取客户端凭据：

1. 创建CernerCare帐户

- 注册地址： Oracle Cerner代码控制台 - 完成帐户注册过程

1. 注册您的应用程序

- 登录到 代码控制台 - 导航到“我的应用程序”，然后单击“注册新应用程序” - 选择应用程序类型： - 系统 -用于后端服务和自动化系统 - 机密 -适用于可以安全存储凭据的应用程序 - 提供应用程序详细信息： - 应用程序名称 - 描述 - 重定向URI（客户端凭据流不需要） - 完成注册流程

1. 获取凭据

- 注册后，您将收到： - 客户端ID -应用程序的唯一标识符 - 客户端密钥 -通过Cerner Central系统帐户进行管理 - 安全地存储这些凭据

1. 配置Contoso作用域

> 备注：作用域格式因请求的令牌类型而异。以下范围格式适用于 SMART V2 Token:

为您的应用程序请求以下系统级范围（SMART v1格式）：

- system/Patient.rs -读取患者资源的访问权限 - system/Observation.rs -读取观测资源的访问权限 - system/Condition.rs -读取条件资源的访问权限 - system/Procedure.rs -读取过程资源的访问权限 - system/Encounter.rs -读取访问权限以获取资源 - system/DiagnosticReport.rs -读取诊断报告 - system/AllergyIntolerance.rs -读取过敏信息 - system/Immunization.rs -读取免疫记录 - system/MedicationRequest.rs -读取药物请求的访问权限 - system/Appointment.rs -读取预约访问权限

令牌端点

服务器使用Oracle Cerner的令牌端点自动管理OAuth 2.0令牌：

https://authorization.cerner.com/tenants/{TENANT_ID}/hosts/fhir-ehr.cerner.com/protocols/oauth2/profiles/smart-v1/token

默认租户ID: ec2458f2-1e24-41c8-b71b-0e701af7583d （Oracle Cerner沙盒）

自动令牌管理

服务器自动执行以下操作：

• 在第一次API调用中使用客户端凭据请求访问令牌
• 缓存令牌直到到期
• 需要时自动刷新令牌（到期前有5分钟的缓冲期）
• 优雅地处理令牌错误

额外资源

有关Oracle Cerner授权框架的更多信息：

• Contoso授权框架
• Oracle Cerner代码控制台
• SMART后端服务规范

用法

运行服务器

使用以下命令运行MCP服务器：

python fhir-mcp-server.py

或者如果使用 uv:

uv run python fhir-mcp-server.py

与克劳德桌面或光标一起使用

对于Claude Desktop：

将以下配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fhir": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/fhir-mcp-server/fhir-mcp-server.py"
      ],
      "env": {
        "FHIR_CLIENT_ID": "your_client_id",
        "FHIR_CLIENT_SECRET": "your_client_secret",
        "FHIR_BASE_URL": "https://fhir-ehr.cerner.com/r4",
        "FHIR_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

重要：替换 /absolute/path/to/fhir-mcp-server/fhir-mcp-server.py 带有脚本的实际完整路径！

对于游标IDE：

将相同的配置添加到Cursor的MCP设置中。看 QUICKSTART.md 有关Cursor的详细说明，包括：

• 在哪里可以找到Cursor的MCP配置
• 基于UI的设置选项
• 光标特定故障排除

可用工具

患者工具

• get_patient_by_id -按ID检索患者
• search_patients_by_name -按名字/姓氏搜索患者
• search_patients_by_identifier -按标识符搜索（MRN、SSN等）
• search_patients_by_birthdate -按出生日期搜索
• search_patients_by_phone -按电话号码搜索
• search_patients_by_email -按电子邮件地址搜索
• search_patients_by_address -按地址组件搜索

临床数据工具

• get_allergy_by_id / get_patient_allergies -过敏信息
• get_condition_by_id / get_patient_conditions -医疗状况
• get_procedure_by_id / get_patient_procedures -程序
• get_observation_by_id / get_patient_observations -观察结果
• get_patient_vital_signs -具体生命体征
• get_patient_lab_results -实验室结果
• get_immunization_by_id / get_patient_immunizations -免疫接种

诊断和药物工具

• get_diagnostic_report_by_id / get_patient_diagnostic_reports -诊断报告
• get_medication_request_by_id / get_patient_medication_requests -药物

会面和预约工具

• get_encounter_by_id / get_patient_encounters -患者遭遇
• get_appointment_by_id / get_patient_appointments -预约
• search_appointments_by_date -按日期搜索约会

实用工具

• get_fhir_capability_statement -获取Contoso服务器功能

示例用法

示例1：搜索患者

# Search for patients by name
result = await search_patients_by_name(
    given_name="John",
    family_name="Doe"
)

示例2：获取患者的病史

# Get patient's conditions
conditions = await get_patient_conditions(
    patient_id="12345",
    clinical_status="active"
)

# Get patient's allergies
allergies = await get_patient_allergies(
    patient_id="12345"
)

# Get patient's vital signs
vitals = await get_patient_vital_signs(
    patient_id="12345",
    date="2024-01-01"
)

示例3：检索约会

# Get upcoming appointments for a patient
appointments = await get_patient_appointments(
    patient_id="12345",
    status="booked",
    date="ge2024-01-01"  # Greater than or equal to date
)

API参考文件

此服务器实现基于以下Oracle Millennium Platform API文档的工具：

• API患者
• 过敏性过敏API
• API条件
• 程序API
• 遇到API
• 诊断报告API
• 观察API
• API免疫
• 药物申请API
• 预约API

➤标准

此服务器遵循 GetLR4规范 用于资源结构和搜索参数。

错误处理

服务器将引发以下HTTP异常：

• 身份验证失败（401未经授权）
• 缺少资源（404未找到）
• 服务器错误（500内部服务器错误）
• 无效请求（400个错误请求）

所有异常都包括来自Contoso服务器响应的详细错误消息。

故障排除

ModuleNotFoundError:没有名为“httpx”的模块（或其他依赖项）

问题：克劳德桌面秀 ModuleNotFoundError 当尝试加载MCP服务器时。

解决方案：确保您首先安装了依赖项：

cd /Users/sdesani/Work/fhir-mcp-server
uv sync

您的Claude Desktop配置应使用 fastmcp run 图案：

{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "fastmcp",
    "fastmcp",
    "run",
    "/absolute/path/to/fhir-mcp-server/fhir-mcp-server.py"
  ]
}

这使用 uv run --with fastmcp 要动态安装FastMCP，请运行脚本，该脚本将使用项目中已安装的依赖项 .venv.

其他常见问题

服务器未出现在Claude Desktop中:

• 更新配置后重新启动Claude Desktop
• 检查中的JSON语法错误 claude_desktop_config.json
• 验证文件路径是否为绝对路径（以开头 /)

401未经授权的错误:

• 验证您的OAuth令牌是否有效且未过期
• 检查令牌是否具有正确的作用域/权限

超时错误:

• 增加 FHIR_REQUEST_TIMEOUT 在你的 .env 文件或Claude桌面配置
• 默认值为60秒，对于速度较慢的服务器，请尝试120秒或更高

安全注意事项

• 凭证管理:

- 永远不要承诺你的 .env 文件或凭据到版本控制 - 商店 FHIR_CLIENT_ID 和 FHIR_CLIENT_SECRET 安全地 - 使用环境变量或安全凭证管理系统 - 根据组织的安全策略定期轮换凭据

• OAuth 2.0安全:

- 服务器使用OAuth 2.0客户端凭据流进行安全的系统间身份验证 - 令牌会自动缓存和刷新 - 跟随 申请注册 获取有效凭据的步骤

• 仅限HTTPS：始终将HTTPS端点用于生产中的Contoso服务器

• 范围管理:

- 仅请求应用程序所需的最小范围 - 随着应用程序需求的变化，审查和更新范围 - 看 申请注册 对于可用范围

• PHI保护:

- 请注意，Contoso资源包含受保护的健康信息（PHI） - 确保符合医疗数据隐私法规（HIPAA、GDPR等） - 实施适当的访问控制和审核日志记录 - 遵循贵组织的数据处理政策

• SMART合规性:

- 此服务器遵循SMART后端服务规范 - 确保安全的医疗保健应用程序集成

发展

项目结构

fhir-mcp-server/
├── fhir-mcp-server.py   # MCP server implementation
├── pyproject.toml       # Project dependencies and metadata
├── .env                 # Your local configuration (not committed)
├── .gitignore          # Git ignore rules
├── README.md           # This file
├── QUICKSTART.md       # Quick start guide
└── EXAMPLES.md         # Usage examples

添加新的Contoso资源

要添加对其他Contoso资源的支持，请执行以下操作：

1. 添加一个新的工具功能，用 @mcp.tool()
2. 使用 make_fhir_request() 辅助功能
3. 遵循现有的参数和返回类型模式
4. 用新的工具信息更新此README

测试

通过运行服务器并通过Cursor等MCP客户端连接或使用MCP检查器工具来测试服务器。

许可证

\[在此处添加您的许可证信息\]

贡献

欢迎投稿！请随时提交拉取请求。

支持

关于以下问题：

• Contoso服务器：请联系您的Contoso服务器管理员
• Oracle千年平台：请参阅Oracle文档
• 此MCP服务器：在此存储库中打开一个问题

其他文件

• QUICKSTART.md -Claude Desktop和Cursor的快速入门指南及设置说明
• 示例.md -综合使用示例

致谢

• 内置于 FastMCP
• 实现 FHIR R4 标准
• 专为 Oracle千年平台API