clinical-mcp

Сервер MCP для клинических рабочих процессов: поиск и обобщение синтетических записей пациентов FHIR R4, получение литературы из PubMed и деидентификация свободного текста — всё это из Claude (или любого MCP-клиента).

Создан как эталонный MCP-сервер: реализует полную поверхность спецификации (инструменты, ресурсы и промпты — большинство публичных серверов ограничиваются инструментами), поставляется с набором тестов, проверяющих сетевой протокол, и работает через stdio или аутентифицированный потоковый HTTP.

Все данные пациентов синтетические, сгенерированы с помощью Synthea. В этом проекте нет реальной PHI.

Архитектура

[Claude / MCP client]
        |  stdio  or  streamable-http (+ bearer auth)
        v
[clinical-mcp  (MCPServer)]
   |-- tools ------ search_patients, get_patient_summary, get_observations,
   |                search_pubmed, get_pubmed_abstract, deidentify_text
   |-- resources -- fhir://patients            (roster)
   |                fhir://patients/{id}       (full record, URI template)
   |-- prompts ---- clinical_summary, literature_review
   |
   +-- FhirStore ----------- in-memory index over Synthea FHIR R4 bundles
   +-- PubMedClient -------- NCBI E-utilities, rate-limited (3/s, 10/s w/ key)
   +-- deidentify() -------- HIPAA Safe Harbor regex redaction

Быстрый старт

pip install clinical-mcp

Конфигурация Claude Desktop / Claude Code (запись mcpServers):

{
  "clinical": {
    "command": "clinical-mcp",
    "env": { "CLINICAL_MCP_DATA_DIR": "/path/to/fhir/bundles" }
  }
}

Из исходников:

git clone https://github.com/sarathi-aiml/clinical-mcp
cd clinical-mcp
pip install -e ".[dev]"
clinical-mcp                       # stdio, serves the bundled 10-patient sample
pytest                             # 33 tests, no network needed

Затем спрашивайте Claude, например:

«Найдите пациенток старше 50 лет с гипертонией, обобщите первую из них и получите три самых свежих статьи PubMed, релевантных её списку лекарств».

Инструменты

Ресурсы предоставляют те же данные по адресу (fhir://patients/{id}), поэтому клиенты могут прикрепить полную запись пациента как контекст без обращения к инструменту. Промпты кодируют два наиболее часто используемых рабочих процесса — обобщение карты и обзор литературы на основе данных пациента — как переиспользуемые шаблоны.

HTTP-транспорт с аутентификацией

CLINICAL_MCP_API_KEY=$(openssl rand -hex 32) clinical-mcp --transport http --port 8000

Каждый запрос должен содержать Authorization: Bearer <key>; сервер отказывается запускаться без аутентификации по HTTP. stdio (по умолчанию) не требует ключа — транспорт сам является границей доверия.

Данные

В репозитории поставляются 10 урезанных синтетических пациентов в data/sample/. Для большего корпуса:

python scripts/fetch_data.py --out data/full            # ~1,100 patients
CLINICAL_MCP_DATA_DIR=data/full clinical-mcp

--trim сокращает пакеты до типов ресурсов, которые сервер реально читает (Patient, Condition, MedicationRequest, Observation, AllergyIntolerance, Encounter, Immunization, Procedure, DiagnosticReport, CarePlan), и ограничивает высокообъёмные типы.

Деидентификация: область применения и ограничения

deidentify_text — это регулярное выражение на основе Safe Harbor: оно распознаёт форматы идентификаторов, встречающиеся в структурированном клиническом тексте, и дополнительно редактирует все имена пациентов, загруженные в хранилище. Это не сертифицированный конвейер деидентификации — свободные имена без обращений, опечатки и редкие контекстные идентификаторы могут пройти. Для реальной PHI нужен обученный NER-проход (например, Philter или LLM-проход с проверкой человеком) поверх этого; данный инструмент — детерминированный первый фильтр, а его счётчики по категориям делают аудит дешёвым.

Что ломается при 500K документов в неделю

Этот сервер намеренно рассчитан на свою задачу — эталонную реализацию на синтетическом корпусе. Вот что выходит из строя первым при производственной нагрузке и путь обновления для каждого пункта:

1. Хранилище в памяти. Всё загружается в ОЗУ при запуске; ~10K пациентов — комфортно, ~100K — уже нет, и время запуска растёт линейно. Первое исправление: SQLite/DuckDB с индексами по имени, дате рождения и кодам состояний за тем же интерфейсом FhirStore. Настоящее исправление: направить хранилище на реальную конечную точку FHIR (HAPI или облачный FHIR API) и сделать инструменты тонкими слоями перевода поверх параметров поиска FHIR.

2. Один пациент на пакет. Загрузчик предполагает структуру Synthea. Смешанные пакеты требуют разрешения ссылок (subject.reference) вместо группировки на уровне файлов.

3. Ограничения скорости PubMed. 3 запроса/с (10 с ключом) — нормально для интерактивной работы и бесполезно в пакетном режиме. При объёме нужен локальный кэш с ключом по хэшу запроса и TTL, а также пакетный efetch (до 200 PMID на запрос) вместо вызовов по каждой статье.

4. Полнота деидентификации регулярными выражениями. При 500K документов в неделю даже 99% полноты пропускает тысячи идентификаторов. Вывод счётчиков предназначен именно для этого измерения: выборка, аудит и контроль по измеренной полноте — затем добавьте NER-модель в конвейер.

5. Однопроцессный HTTP. Потоковый HTTP под uvicorn на одном процессе обслуживает команду, а не флот. Горизонтальное масштабирование требует сессий без состояния (хранилище только для чтения, так что это почти бесплатно) за балансировщиком нагрузки и ограничения скорости на клиента на шлюзе.

Разработка

pip install -e ".[dev]"
pytest              # protocol-level + unit tests, PubMed mocked
ruff check .

Docker:

docker build -t clinical-mcp .
docker run --rm -i clinical-mcp                                   # stdio
docker run --rm -p 8000:8000 -e CLINICAL_MCP_API_KEY=secret \
  clinical-mcp --transport http --host 0.0.0.0

Лицензия

MIT