sharp-fhir-mcp

Чистый, соответствующий стандарту SHARP-on-MCP FHIR R4 MCP-сервер с интерактивными клиническими дашбордами MCP-UI.

Создан для хакатона Prompt Opinion "Build the Future of Healthcare AI" — это независимый от вендора MCP-сервер, к которому может подключиться любое приложение SMART-on-FHIR, агент или хост LLM без OAuth на стороне сервера, API-ключей или проприетарных потоков аутентификации.

Почему SHARP?

Спецификация SHARP (Standardised Healthcare Agent Remote Protocol) описывает контекстную модель на основе заголовков для MCP серверов в здравоохранении:

Согласно 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. Подключение из любого MCP-клиента с поддержкой SHARP

Отправляйте эти заголовки при каждом 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-приложения

Публичная FHIR R4 песочница HAPI доступна только для чтения и не требует аутентификации — полезно для ознакомления:

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 serverless)

Этот сервер работает как stateless Streamable-HTTP эндпоинт, который отлично работает на Vercel «из коробки». Вы можете повторно использовать существующий Next.js MCP scaffold, либо:

1. Добавив 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"}]
   }

2. Или запустив его как sidecar за вашим существующим фронтендом Vercel и настроив обратный прокси /mcp на более долгоживущий хост (Fly.io, Railway, Render).

Сервер учитывает переменную окружения PORT, внедряемую Vercel.

Локальная разработка

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 / …)

См. CLAUDE.md для подробных заметок по модулям и контрольного списка соответствия SHARP.

Контрольный список соответствия SHARP

Лицензия

MIT — см. LICENSE.