sharp-fhir-mcp

一个符合 SHARP-on-MCP 标准的纯净版 FHIR R4 MCP 服务器，带有交互式 MCP-UI 临床仪表板。

专为 Prompt Opinion “构建医疗保健 AI 的未来”黑客马拉松 而构建 — 这是一个供应商中立的 MCP 服务器，任何 SMART-on-FHIR 应用、代理或 LLM 主机都可以在无需服务器端 OAuth、API 密钥或专有身份验证流程的情况下接入。

为什么选择 SHARP？

SHARP（标准化医疗保健代理远程协议）规范描述了一种用于医疗保健领域 MCP 服务器的基于标头的上下文模型：

标头	用途
`X-FHIR-Server-URL`	患者 FHIR R4 端点的基础 URL
`X-FHIR-Access-Token`	由代理主机预先生成的承载令牌
`X-Patient-ID`	可选的默认 `Patient` 资源 ID

根据 SHARP §3.2，MCP 服务器本身从不执行 OAuth 流程。代理主机（例如 SMART-on-FHIR 启动容器）获取令牌并在每次调用时转发它。这意味着此服务器的单个部署可以针对 Epic、Cerner、MEDITECH、athenahealth、eClinicalWorks、ConnectEHR、HAPI 或任何其他 FHIR R4 端点工作 — 没有特定于供应商的内容。

服务器在每次初始化响应时都会通告 capabilities.experimental.fhir_context_required = true，以便支持 SHARP 的客户端知道自动转发这些标头。

包含的内容

🩺 临床 FHIR 工具

fhir_get_capability_statement — 发现已连接的 FHIR 服务器
fhir_get_patient, fhir_search, fhir_read, fhir_patient_everything — 通用 R4 访问
clinical_search_patients, clinical_get_patient_summary
clinical_get_appointments, clinical_get_encounters
clinical_get_problems, clinical_get_medications, clinical_get_allergies, clinical_get_immunizations
clinical_get_health_record — 一次性整合记录
clinical_get_context — 并行获取完整的就诊上下文（人口统计数据 + 过敏史 + 用药史 + 问题列表 + 实验室检查 + 生命体征 + 就诊记录 + 警报）

🔬 实验室、生命体征与影像

lab_get_results, lab_get_vital_signs, lab_get_diagnostic_reports
imaging_get_documents — DocumentReference 搜索

🧠 可选的持久化内存 (SimpleMem)

当设置了 SIMPLEMEM_API_URL 和 SIMPLEMEM_ACCESS_TOKEN 时：

memory_store_encounter — 保存就诊摘要
memory_store_alert — 为下次就诊标记临床关注点
memory_search_history — 跨过往就诊记录进行语义搜索
memory_get_patient_history — 列出当前患者的所有已存储记忆

📊 MCP-UI 可视化

visualize_lab_trend — 单项实验室指标随时间变化的 Chart.js 折线图
visualize_vitals — 多图表生命体征仪表板
visualize_patient_dashboard — 完整的 HTML 临床页面（人口统计数据、警报、过敏史、用药史、问题列表、实验室检查、就诊记录、免疫接种 + Chart.js 趋势图）

所有可视化工具都会返回 MCP-UI ui:// 资源，由主机在其检查器面板中渲染。

快速入门

1. 安装

git clone https://github.com/your-org/sharp-fhir-mcp.git
cd sharp-fhir-mcp
pip install -e .

2. 运行服务器

sharp-fhir-mcp                     # streamable-http on 0.0.0.0:8000
sharp-fhir-mcp --port 9000         # custom port
sharp-fhir-mcp --strict-context    # 403 on non-handshake without FHIR headers

MCP 端点为 http://localhost:8000/mcp。

注意： 此处的 localhost 指的是运行服务器的机器的本地主机。要远程访问它，请部署服务器（见下文）或将端口转发到您的本地实例。

3. 从任何支持 SHARP 的 MCP 客户端连接

在每个 JSON-RPC 请求上发送这些标头：

X-FHIR-Server-URL: https://hapi.fhir.org/baseR4
X-FHIR-Access-Token: <bearer token from your SMART launch>
X-Patient-ID: 12345          # optional

4. 在不编写 SMART 应用的情况下尝试公共沙箱

HAPI 公共 FHIR R4 沙箱是只读的且不需要身份验证 — 非常适合初步体验：

curl -X POST http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'X-FHIR-Server-URL: https://hapi.fhir.org/baseR4' \
  -H 'X-FHIR-Access-Token: anonymous' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

部署

Vercel (Python 无服务器)

此服务器作为无状态 Streamable-HTTP 端点运行，可在 Vercel 上开箱即用。您可以通过以下方式重用现有的 Next.js MCP 脚手架：

添加 Python ASGI 处理程序 — 将 app Starlette 实例放入 api/index.py：

# api/index.py
from sharp_fhir_mcp.server import app  # noqa: F401

以及一个最小化的 vercel.json：

{
  "builds": [{"src": "api/index.py", "use": "@vercel/python"}],
  "routes": [{"src": "/(.*)", "dest": "api/index.py"}]
}

或者将其作为 Sidecar 运行，放在您现有的 Vercel 前端之后，并将 /mcp 反向代理到更长期的主机（Fly.io、Railway、Render）。

服务器遵循 Vercel 注入的 PORT 环境变量。

本地开发

cp .env.example .env             # set FHIR_SERVER_URL etc. for fallbacks
sharp-fhir-mcp                   # http://localhost:8000/mcp

Docker (可选)

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -e .
EXPOSE 8000
CMD ["sharp-fhir-mcp", "--host", "0.0.0.0", "--port", "8000"]

架构

┌─────────────────────────────────────────────────────────────┐
│  MCP Client / Agent / LLM host (Claude, Cursor, custom)     │
│  • Knows the patient's FHIR endpoint + access token         │
│  • Sends X-FHIR-Server-URL, X-FHIR-Access-Token headers     │
└────────────────────────┬────────────────────────────────────┘
                         │ Streamable HTTP (SHARP-on-MCP)
            POST /mcp + JSON-RPC + SHARP headers
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  sharp-fhir-mcp                                             │
│                                                             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ SharpContextMiddleware                                 │ │
│  │ • Parses X-FHIR-Server-URL / X-FHIR-Access-Token       │ │
│  │ • Stores in ContextVar for the request scope           │ │
│  └─────────────────────────┬──────────────────────────────┘ │
│                            ▼                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ FastMCP tool registry                                  │ │
│  │ ├─ fhir_*           (generic R4 search/read)           │ │
│  │ ├─ clinical_*       (patient/encounter/medication/…)   │ │
│  │ ├─ lab_* / imaging_*(observations, reports, docs)      │ │
│  │ ├─ memory_*         (optional SimpleMem)               │ │
│  │ └─ visualize_*      (MCP-UI Chart.js dashboards)       │ │
│  └─────────────────────────┬──────────────────────────────┘ │
│                            ▼                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Vendor-neutral FHIR R4 client (httpx, async)           │ │
│  └─────────────────────────┬──────────────────────────────┘ │
└────────────────────────────┼────────────────────────────────┘
                             ▼
            FHIR R4 server (Epic / Cerner / HAPI / …)

有关详细的模块说明和 SHARP 合规性检查清单，请参阅 CLAUDE.md。

SHARP 合规性检查清单

要求	状态
Streamable-HTTP 传输（stdio 不在范围内）	✅
从 `X-FHIR-Server-URL` 标头读取 FHIR 端点	✅
从 `X-FHIR-Access-Token` 标头读取承载令牌	✅
用于默认患者上下文的可选 `X-Patient-ID` 标头	✅
通告 `capabilities.experimental.fhir_context_required`	✅
无服务器端 OAuth / 令牌存储	✅
供应商中立的 FHIR R4 客户端	✅
缺少标头时结构化的 `fhir_context_required` 错误	✅
可选的严格 403 执行 (`--strict-context`)	✅

许可证

MIT — 见 LICENSE。

sharp-on-fhir-mcp