Сервер Model Context Protocol (MCP) для API Fast Healthcare Interoperability Resources (FHIR)

Содержание

Сервер Model Context Protocol (MCP) для API Fast Healthcare Interoperability Resources (FHIR)
- Содержание
- Обзор
- Демонстрация
- Демонстрация с сервером HAPI FHIR
- Демонстрация с песочницей EPIC
- Основные возможности
- Предварительные требования
- Установка
- Установка пакета через PyPI
- Установка из исходного кода
- Установка с помощью Docker
- Запуск MCP-сервера с помощью Docker
- Использование Docker Compose с WSO2 FHIR Server
- Настройка любого FHIR-сервера
- Интеграция с MCP-клиентами
- VS Code
- Claude Desktop
- MCP Inspector
- Конфигурация
- Параметры CLI
- Переменные окружения
- Инструменты
- Разработка и тестирование
- Установка зависимостей для разработки
- Запуск тестов

Обзор

FHIR MCP Server — это сервер Model Context Protocol (MCP), обеспечивающий удобную интеграцию с API FHIR. Он предназначен для разработчиков, интеграторов и специалистов, создающих решения в сфере здравоохранения. Сервер связывает современные инструменты AI/LLM с медицинскими данными и упрощает поиск, получение и анализ клинической информации.

Демонстрация

Демонстрация с сервером HAPI FHIR

В этом видео показана работа MCP-сервера при подключении к публичному серверу HAPI FHIR. Пример демонстрирует прямое взаимодействие с открытым FHIR-сервером, для которого не требуется авторизация.

https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf

Демонстрация с песочницей EPIC

В этом видео показаны возможности MCP-сервера в экосистеме Epic EHR. Оно демонстрирует полный процесс OAuth 2.0 Authorization Code Grant.

https://github.com/user-attachments/assets/96b433f1-3e53-4564-8466-65ab48d521de

Основные возможности

Транспорт, совместимый с MCP: предоставляет доступ к FHIR через stdio, SSE или streamable HTTP
Поддержка аутентификации на основе SMART-on-FHIR: обеспечивает безопасную аутентификацию на FHIR-серверах и клиентов
Фильтрация ответов с помощью FHIRPath: позволяет фильтровать ресурсы и пакеты, возвращаемые операциями read и search, используя пользовательские выражения FHIRPath. Это помогает получать только необходимые для задачи поля и уменьшать размер полезной нагрузки.
Интеграция с инструментами: сервер можно интегрировать с любым MCP-клиентом, например VS Code, Claude Desktop и MCP Inspector

Предварительные требования

Python 3.8+
uv для управления зависимостями
Доступный сервер API FHIR.

Установка

FHIR MCP Server можно установить как Python-пакет или запустить, клонировав этот репозиторий.

Установка пакета через PyPI

Настройка переменных окружения:

Для запуска сервера необходимо задать FHIR_SERVER_BASE_URL.

Чтобы включить авторизацию: задайте FHIR_SERVER_BASE_URL, FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET и FHIR_SERVER_SCOPES. По умолчанию авторизация включена.
Чтобы отключить авторизацию: задайте для FHIR_SERVER_DISABLE_AUTHORIZATION значение True.

По умолчанию MCP-сервер запускается по адресу http://localhost:8000. Настроить хост и порт можно с помощью переменных FHIR_MCP_HOST и FHIR_MCP_PORT.

Эти переменные можно задать, экспортировав их в окружение, как показано ниже, или создав файл .env на основе .env.example.

export FHIR_SERVER_BASE_URL=""
export FHIR_SERVER_CLIENT_ID=""
export FHIR_SERVER_CLIENT_SECRET=""
export FHIR_SERVER_SCOPES=""

export FHIR_MCP_HOST="localhost"
export FHIR_MCP_PORT="8000"

Установка пакета PyPI и запуск сервера

uvx fhir-mcp-server

Установка из исходного кода

Клонирование репозитория:

cd ">

git clone <repository_url>
cd <repository_directory>

Создание виртуального окружения и установка зависимостей:

uv venv
source .venv/bin/activate
uv pip sync requirements.txt

Или с помощью pip:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Настройка переменных окружения:

Скопируйте пример файла и при необходимости внесите изменения:

cp .env.example .env

Запуск сервера:

uv run fhir-mcp-server

Установка с помощью Docker

Запуск MCP-сервера с помощью Docker

Для запуска MCP-сервера в изолированной и предсказуемой среде можно использовать Docker.

Примечание об авторизации: при локальном запуске MCP-сервера через Docker или Docker Compose авторизацию следует отключить, задав переменную окружения FHIR_SERVER_DISABLE_AUTHORIZATION=True. Это ограничение будет устранено в будущих выпусках.

Соберите Docker-образ или загрузите его из реестра контейнеров:
- Сборка из исходного кода:

docker build -t fhir-mcp-server .

Загрузка из GitHub Container Registry:

docker pull ghcr.io/wso2/fhir-mcp-server:latest

Образ latest собирается из ветки main. Чтобы использовать выпуск, загрузите образ с соответствующим тегом версии, например ghcr.io/wso2/fhir-mcp-server:0.11.0.

Настройка переменных окружения

Скопируйте пример файла окружения и при необходимости отредактируйте его:

cp .env.example .env
# Edit .env to set your FHIR server, client credentials, etc.

Также можно передавать переменные окружения напрямую с помощью флагов -e или использовать Docker secrets для конфиденциальных данных. Список доступных переменных окружения приведён в разделе «Конфигурация».

Запуск контейнера

docker run --env-file .env -p 8000:8000 ghcr.io/wso2/fhir-mcp-server:latest

Сервер запустится и будет доступен на порту 8000. При необходимости измените сопоставление портов.

Использование Docker Compose с WSO2 FHIR Server

Чтобы быстро развернуть MCP-сервер FHIR и WSO2 FHIR Server с PostgreSQL, используйте предоставленный файл docker-compose.yml. Он создаёт готовую среду для разработки и тестирования операций FHIR.

Предварительные требования:
- Установленные Docker и Docker Compose.
Настройка учётных данных базы данных:

Скопируйте пример файла окружения и задайте в .env значение DB_PASSWORD. Если файл .env уже существует, вместо этого добавьте в него строки DB_USER, DB_PASSWORD и DB_NAME из .env.example.

cp .env.example .env

Docker Compose автоматически загружает файл .env. Если значения DB_USER и DB_NAME не заданы, по умолчанию используется postgres. Файл .env исключён из Git; для производственных развёртываний используйте менеджер секретов.

Запуск стека:

docker compose up -d

Эта команда выполнит следующие действия:

Запустит контейнер базы данных PostgreSQL.
Запустит FHIR Server, подключённый к PostgreSQL и доступный по адресу http://localhost:8080/fhir/r4.
Соберёт и запустит контейнер FHIR MCP Server, доступный по адресу http://localhost:8000. Для FHIR_SERVER_BASE_URL будет задано значение http://wso2-fhir-server:8080/fhir/r4.
Доступ к сервисам:
- FHIR MCP Server: http://localhost:8000
- FHIR Server: http://localhost:8080/fhir/r4
- Чтобы остановить сервисы, выполните docker compose down.

Команда docker compose down удаляет данные базы данных. Чтобы сохранить их между запусками, используйте docker compose stop.

Настройка дополнительных переменных окружения:

Чтобы настроить OAuth или другие параметры, измените переменные окружения в docker-compose.yml. Файл Compose задаёт базовую конфигурацию; полный список параметров приведён в разделе «Конфигурация».

Настройка любого FHIR-сервера

Чтобы использовать другой FHIR-сервер, запустите контейнер сервера FHIR MCP и укажите адрес этого сервера в переменной FHIR_SERVER_BASE_URL. В примере ниже используется сервер HAPI FHIR. Если стандартный стек уже запущен, сначала остановите его (docker compose down): оба варианта используют порты 8000 и 8080.

Создайте сеть и запустите сервер HAPI FHIR:

docker network create fhir-network
docker run -d --name hapi-fhir-server --network fhir-network -p 127.0.0.1:8080:8080 docker.io/hapiproject/hapi:v8.4.0-2

Сервер HAPI FHIR доступен по адресу http://localhost:8080/fhir. В примере используется встроенная база данных, поэтому при удалении контейнера данные будут потеряны.

Соберите и запустите контейнер сервера FHIR MCP:

docker build -t fhir-mcp-server .
docker run -d --name fhir-mcp-server-hapi --network fhir-network -p 127.0.0.1:8000:8000      -e FHIR_SERVER_BASE_URL=http://hapi-fhir-server:8080/fhir      -e FHIR_MCP_HOST=0.0.0.0      -e FHIR_SERVER_DISABLE_AUTHORIZATION=True      fhir-mcp-server

Сервер FHIR MCP доступен по адресу http://localhost:8000.

Остановите контейнеры и удалите сеть:

docker rm -f fhir-mcp-server-hapi hapi-fhir-server
docker network rm fhir-network

Для любого другого FHIR-сервера укажите его базовый URL в переменной FHIR_SERVER_BASE_URL. Если FHIR-сервер запущен на хосте, а не в Docker, используйте http://host.docker.internal:/... вместо localhost.

В Linux также добавьте --add-host=host.docker.internal:host-gateway в команду docker run. Убедитесь, что FHIR-сервер принимает подключения по адресу, доступному из контейнеров (например, 0.0.0.0, а не только 127.0.0.1).

Интеграция с MCP-клиентами

Сервер FHIR MCP разработан для удобной интеграции с различными MCP-клиентами.

VS Code

Добавьте следующий блок JSON в файл конфигурации MCP в VS Code (версии 1.104 и выше). Чтобы открыть его, нажмите Ctrl + Shift + P и введите MCP: Open User Configuration.

Streamable HTTP	STDIO	SSE

"servers": {
    "fhir": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
    }
}

"servers": {
    "fhir": {
        "command": "uv",
        "args": [
            "--directory",
            "/path/to/fhir-mcp-server",
            "run",
            "fhir-mcp-server",
            "--transport",
            "stdio"
        ],
        "env": {
            "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
        }
    }
}

"servers": {
    "fhir": {
        "type": "sse",
        "url": "http://localhost:8000/sse",
    }
}

Claude Desktop

Чтобы подключиться к локальному MCP-серверу, добавьте следующий блок JSON в настройки Claude Desktop.

Запустите приложение Claude Desktop, откройте меню Claude в верхней панели и выберите "Settings…".
В панели Settings выберите раздел “Developer” на боковой панели слева, затем нажмите "Edit Config". Файл конфигурации откроется в файловой системе. Если такого файла ещё нет, Claude автоматически создаст его по одному из следующих путей:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Откройте файл claude_desktop_config.json в любом текстовом редакторе. Замените его содержимое следующим блоком JSON, чтобы добавить MCP-сервер:

Streamable HTTP	STDIO	SSE

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/mcp"
            ]
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/fhir-mcp-server",
                "run",
                "fhir-mcp-server",
                "--transport",
                "stdio"
            ],
            "env": {
                "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
            }
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/sse"
            ]
        }
    }
}

MCP Inspector

Выполните следующие действия, чтобы запустить MCP Inspector:

Откройте терминал и выполните команду:

npx -y @modelcontextprotocol/inspector

В интерфейсе MCP Inspector укажите параметры подключения:

Streamable HTTP	STDIO	SSE
Тип транспорта: `Streamable HTTP` URL: `http://localhost:8000/mcp`	Тип транспорта: `STDIO` Команда: `uv` Аргументы: `--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio`	Тип транспорта: `SSE` URL: `http://localhost:8000/sse`

Перед подключением убедитесь, что MCP-сервер запущен и доступен по указанному адресу.

После подключения MCP Inspector позволит просматривать вызовы инструментов, изучать содержимое запросов и ответов, а также отлаживать реализации инструментов.

Конфигурация

Параметры командной строки

Поведение MCP-сервера можно настроить с помощью следующих параметров командной строки:

--transport
- Описание: задаёт протокол передачи данных, который MCP-сервер использует для взаимодействия с клиентами.
- Допустимые значения: stdio, sse, streamable-http
- Значение по умолчанию: streamable-http
--log-level
- Описание: задаёт уровень подробности журналирования сервера.
- Допустимые значения: DEBUG, INFO, WARN, ERROR (без учёта регистра)
- Значение по умолчанию: INFO
--help
- Описание: выводит справку с доступными параметрами сервера и завершает работу.
- Использование: параметр автоматически предоставляется интерфейсом командной строки.

Примеры использования:

uv run fhir-mcp-server --transport streamable-http --log-level DEBUG
uv run fhir-mcp-server --help

Переменные окружения

Настройки MCP-сервера:

FHIR_MCP_HOST: имя хоста или IP-адрес, на котором MCP-сервер будет принимать подключения (например, localhost для доступа только с локального компьютера или 0.0.0.0 для всех сетевых интерфейсов).
FHIR_MCP_PORT: порт, на котором MCP-сервер будет принимать входящие запросы клиентов (например, 8000).
FHIR_MCP_SERVER_URL: если переменная задана, её значение используется в качестве базового URL сервера вместо URL, сформированного на основе хоста и порта. Полезно при настройке собственного URL или работе за прокси-сервером.
FHIR_MCP_REQUEST_TIMEOUT: время ожидания ответа на запросы MCP-сервера к FHIR-серверу в секундах (по умолчанию: 30).

OAuth2 для подключения MCP-сервера к FHIR-серверу (MCP-клиент ↔ MCP-сервер):

Эти переменные настраивают защищённое подключение MCP-клиента к MCP-серверу с использованием потока OAuth2 с предоставлением кода авторизации и FHIR-сервера.

FHIR_SERVER_CLIENT_ID: идентификатор OAuth2-клиента, используемый для авторизации MCP-клиентов на FHIR-сервере.
FHIR_SERVER_DISABLE_AUTHORIZATION: если задано значение True, проверки авторизации на MCP-сервере отключаются. Это позволяет подключаться к общедоступным FHIR-серверам.
FHIR_SERVER_CLIENT_SECRET: секретный ключ, соответствующий идентификатору FHIR-клиента. Используется при обмене токенами.
FHIR_SERVER_BASE_URL: базовый URL FHIR-сервера (например, https://hapi.fhir.org/baseR4). Используется для формирования URI инструментов и маршрутизации запросов к FHIR-серверу.
FHIR_SERVER_SCOPES: список областей OAuth2, разделённых пробелами, которые необходимо запросить у сервера авторизации FHIR (например, user/Patient.read user/Observation.read). Добавьте fhirUser openid, чтобы включить получение контекста пользователя для инструмента get_user. Если эти две области не заданы, инструмент get_user возвращает пустой результат, поскольку в токене ID отсутствует ссылка на ресурс FHIR пользователя.
FHIR_SERVER_ACCESS_TOKEN: токен доступа для аутентификации запросов к FHIR-серверу. Если эта переменная задана, сервер пропускает поток авторизации OAuth2 и использует этот токен для всех запросов.

Примечание

Переменная FHIR_SERVER_ACCESS_TOKEN предназначена только для локального развертывания в режиме stdio и служит для обхода интерактивной аутентификации OAuth. Не используйте её, если MCP-сервер доступен по сети или в общедоступном интернете.

Инструменты

get_capabilities: получает метаданные об указанном типе ресурса FHIR, включая поддерживаемые параметры поиска и пользовательские операции.
- type: название типа ресурса FHIR (например, "Patient", "Observation", "Encounter")
search: выполняет стандартный поиск FHIR для указанного типа ресурса и возвращает Bundle или список подходящих ресурсов.
- type: название типа ресурса FHIR (например, "MedicationRequest", "Condition", "Procedure").
- searchParam: набор параметров поиска FHIR и соответствующих значений (например, {"family":"Simpson","birthdate":"1956-05-12"}).
- response_filter_fhirpaths: (необязательно) массив выражений FHIRPath (например, ["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]), применяемых к ресурсам в Bundle ответа.
read: выполняет операцию FHIR "read" для получения отдельного экземпляра ресурса по его типу и идентификатору, при необходимости уточняя ответ с помощью параметров поиска или пользовательских операций.
- type: название типа ресурса FHIR (например, "DiagnosticReport", "AllergyIntolerance", "Immunization").
- id: логический идентификатор конкретного экземпляра ресурса FHIR.
- searchParam: набор параметров поиска и соответствующих значений (например, {"device-name":"glucometer"}).
- operation: название пользовательской операции FHIR или расширенного запроса, определённого для ресурса (например, "$everything").
- response_filter_fhirpaths: (необязательно) массив выражений FHIRPath (например, ["Patient.name", "Observation.valueQuantity"]), используемых для фильтрации возвращаемого ресурса или записей при выполнении пользовательских операций, таких как $everything.
create: выполняет операцию FHIR "create" и сохраняет новый ресурс указанного типа.
- type: название типа ресурса FHIR (например, "Device", "CarePlan", "Goal").
- payload: объект JSON с полным содержимым создаваемого ресурса FHIR.
- searchParam: набор параметров поиска и соответствующих значений (например, {"address-city":"Boston"}).
- operation: название пользовательской операции FHIR или расширенного запроса, определённого для ресурса (например, "$evaluate").
update: выполняет операцию FHIR "update", заменяя содержимое существующего экземпляра ресурса переданным объектом.
- type: название типа ресурса FHIR (например, "Location", "Organization", "Coverage").
- id: логический идентификатор конкретного экземпляра ресурса FHIR.
- payload: полное представление ресурса FHIR в формате JSON, содержащее все обязательные элементы и любые необязательные данные.
- searchParam: набор параметров поиска и соответствующих значений (например, {"patient":"Patient/54321","relationship":"father"}).
- operation: название пользовательской операции FHIR или расширенного запроса, определённого для ресурса (например, "$lastn").
delete: выполняет операцию FHIR "delete" для конкретного экземпляра ресурса.
- type: название типа ресурса FHIR (например, "ServiceRequest", "Appointment", "HealthcareService").
- id: логический идентификатор конкретного экземпляра ресурса FHIR.
- searchParam: набор параметров поиска и соответствующих значений (например, {"category":"laboratory","issued:"2025-05-01"}).
- operation: название пользовательской операции FHIR или расширенного запроса, определённого для ресурса (например, "$expand").
get_user: получает ресурс FHIR текущего аутентифицированного пользователя (например, связанный ресурс Patient) и возвращает краткий профиль с доступными демографическими данными, такими как id, name и birthDate.

Разработка и тестирование

Установка зависимостей для разработки

Чтобы запускать тесты и участвовать в разработке, установите зависимости для тестирования:

С помощью pip:

# Install project in development mode with test dependencies
pip install -e '.[test]'

# Or install from requirements file
pip install -r requirements-dev.txt

С помощью uv:

# Install development dependencies
uv sync --dev

Запуск тестов

В проект входит комплексный набор тестов, охватывающий все основные функции:

# Simple test runner
python run_tests.py

# Or direct pytest usage
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server

С помощью pytest:

pytest tests/

Команда найдёт и запустит все тесты из каталога tests/.

Возможности тестового набора:

Более 100 тестов с широким охватом функциональности
Полная поддержка async/await с использованием pytest-asyncio
Полная имитация HTTP-запросов и внешних зависимостей
Формирование отчётов о покрытии с выводом в терминал и созданием HTML-отчёта
Быстрое выполнение без реальных сетевых запросов

Тестовый набор включает:

Модульные тесты: проверка основной функциональности
Интеграционные тесты: проверка взаимодействия компонентов
Проверки граничных случаев: обработка ошибок и сценарии валидации
Имитация OAuth-процессов: реалистичное тестирование аутентификации

Подробные отчёты о покрытии создаются в файле htmlcov/index.html.