halaxy-mcp

Сервер MCP для API практики-менеджмента Halaxy, написанный на Python. Он позволяет MCP-клиенту (Claude, GitHub Copilot и т.д.) отвечать на вопросы вроде «что у меня сегодня в календаре», «какие из сегодняшних приёмов ещё не выставлены в счёт» или «какие счета ожидают оплаты от такого-то страховщика», общаясь с вашим собственным аккаунтом Halaxy.

Это небольшой однопользовательский инструмент, созданный для нужд одной практики, а не универсальный Halaxy SDK — см. Что он намеренно не делает ниже.

Инструменты

• list_invoices(date) — счета, датированные указанным днём (по умолчанию — сегодня). Каждый счёт содержит payer_name (присутствует всегда) и объект patient (присутствует только если плательщик — реальный пациент, а не страховщик/работодатель).

• list_appointments(date, appointment_type) — приёмы за указанный день, каждый помечен как "session" (реальный приём клиента) или "meeting" (блокировка, напоминание, внутренняя заметка — всё, что не связано с пациентом). Сеансы также содержат:

  • session_mode — "F2F" или "Telehealth", определяется из HealthcareService, на которую записан приём

  • patient — id/name/initials/telecom/patient_status/is_active_client (см. Данные пациента ниже)

  • invoice — связанный счёт, если он уже выставлен, через прямую ссылку Halaxy приём→счёт (надёжнее, чем сопоставление по дате — см. примечания в коде)

  • awaiting_insurer_invoice — заполняется только когда счёта ещё нет и у пациента есть активное покрытие (Coverage) с пометкой «выставлять счёт организации» — т.е. помечает сеанс, который ожидается к оплате страховщиком/работодателем, но ещё не выставлен

  • referrals — активные направления (Referral) пациента (см. list_referrals ниже), чтобы текущее количество сеансов было сразу под рукой без дополнительного запроса

• list_practitioners() — клинический персонал, каждый с ID роли практикующего специалиста (PractitionerRole) и именем, чтобы клиент мог сопоставить «что там у Алисы сегодня» с ID роли перед сопоставлением с list_appointments.

• list_invoices_by_payer(payer_name) — все счета, когда-либо выставленные конкретному страховщику/работодателю/организации (например, «Acme Insurance»), не привязанные к дате — напрямую ищет по Invoice?recipient=, поэтому у него нет «слепой зоны» окна поиска, как у list_invoices (см. ниже).

• list_referrals(flag) — все активные направления (Referral) в практике. В Halaxy это модель направления от врача общей практики/другого специалиста, разрешающего определённое количество сеансов и/или сумму по программе финансирования (чаще всего это план лечения психического здоровья Medicare — «6 сеансов для начала», как многие его знают, — но также DVA, WorkCover и т.д.). Каждое направление содержит sessions_total/sessions_used/sessions_remaining, amount_total/amount_used, срок действия и вычисляемые flags: "over_limit" (использовано ≥ разрешённого), "expiring_soon" (заканчивается в течение 30 дней), "expired". Можно дополнительно отфильтровать по одному флагу — например, «у кого скоро закончатся сеансы».

Требуемые области действия API-ключа Halaxy

Создайте API-ключ в Halaxy (Настройки → API-ключи) с нужными вам областями — сервер корректно работает, даже если какая-то область отключена: просто инструменты, которым она нужна, будут выдавать ошибку:

Пример того, как это выглядит на экране областей API-ключа Halaxy:

Данные пациента

Этот сервер намеренно минимизирует объём данных о пациенте, которые он раскрывает. Ресурс Patient в Halaxy также содержит дату рождения, адрес, пол, контактное лицо для экстренной связи и примечания об источнике направления — ничего из этого здесь не нужно, и это закреплено в коде (ALLOWED_PATIENT_FIELDS в halaxy_mcp.py), а не просто по соглашению: каждый запрос данных о пациенте фильтруется до id/name/initials/telecom/patient_status/is_active_client до того, как данные попадут к MCP-клиенту, независимо от запроса.

Клинические заметки/заметки о сеансах вообще нельзя получить через этот API, ни с каким ключом или областью. Собственный оператор возможностей /metadata Halaxy показывает, что ресурс клинических заметок (DocumentReference) поддерживает только create/patch — без чтения, что соответствует тому, что показывает сам интерфейс Halaxy (у клинических заметок есть только переключатель «Создать»). Это ограничение всего API, а не то, что этот сервер просто решил не раскрывать.

Направления и лимиты сеансов

Halaxy моделирует план лечения психического здоровья врача общей практики (и аналогичные — DVA, WorkCover) как Referral, связанный с ReferralDefinition (тип направления, который несёт лимит сеансов/суммы — например, одно реальное ReferralDefinition при тестировании буквально называлось «Medicare: MHTP Referral» с лимитом в 6 сеансов). sessions_remaining не возвращается Halaxy напрямую; здесь оно вычисляется как sessions_total - sessions_used.

Несколько моментов, подтверждённых реальными данными, о которых полезно знать, если вы будете расширять это дальше:

• У пациента может быть более одного одновременно активного направления (например, по одному на каждого специалиста, к которому он направлен) — этот сервер не пытается угадать «то самое»; он возвращает все.

• На практике sessions_used может превышать sessions_total (Medicare не жёстко блокирует запись по достижении лимита) — именно для этого и нужен флаг "over_limit".

• У некоторых записей направлений вообще нет структурированного типа/направившего специалиста, только произвольный текстовый comment — он возвращается как есть, когда это единственная доступная зацепка.

• Собственное поле active у направления в Halaxy, похоже, не переключается автоматически на false по истечении срока действия — флаги "expired"/"expiring_soon" вычисляются из period.end, а не считываются из active.

Если область не включена

Для каждого инструмента требуется, чтобы соответствующая область была включена для используемого API-ключа (см. таблицу выше). Если область отсутствует, Halaxy отвечает ошибкой 401/403 или OperationOutcome — сервер в этом случае вызывает понятное исключение HalaxyPermissionError (с указанием ресурса, HTTP-статуса и текста ошибки самого Halaxy), а не молча трактует это как «ноль результатов». Без этой проверки отсутствие области и действительно пустой результат (например, «сегодня счетов нет») выглядели бы для MCP-клиента одинаково.

Установка

Требуется Python 3.10+.

git clone https://github.com/ryanhunt/halaxy-mcp.git
cd halaxy-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# then edit .env with your Halaxy API key's client_id/client_secret

Проверьте, что всё запускается:

source .venv/bin/activate
python3 halaxy_mcp.py

Он ничего не выведет и просто будет висеть — это нормально, он ждёт, когда MCP-клиент начнёт с ним общение через stdin/stdout. Нажмите Ctrl+C для остановки.

Подключение к MCP-клиенту

Все перечисленные ниже варианты запускают один и тот же скрипт как локальный дочерний процесс и общаются с ним через stdio — никаких сетевых портов и отдельного развёртывания. В каждом случае используйте полный абсолютный путь к Python из .venv и к halaxy_mcp.py.

Claude Desktop — добавьте в claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "halaxy-mcp": {
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"]
    }
  }
}

Полностью закройте и снова откройте приложение после этого (не просто закройте окно).

VS Code (GitHub Copilot) — добавьте .vscode/mcp.json в рабочую область:

{
  "servers": {
    "halaxy-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"]
    }
  }
}

GitHub Copilot CLI — добавьте в ~/.copilot/mcp-config.json (или выполните /mcp add внутри CLI):

{
  "mcpServers": {
    "halaxy-mcp": {
      "type": "local",
      "command": "/absolute/path/to/halaxy-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/halaxy-mcp/halaxy_mcp.py"],
      "tools": ["*"]
    }
  }
}

Ни в одном из этих случаев блок env не нужен — скрипт сам загружает свой файл .env из папки, где лежит halaxy_mcp.py.

Известные ограничения, о которых стоит знать

• Окно поиска list_invoices может пропускать счета. В поиске Invoice в Halaxy нет параметра для собственного поля date счёта, только created/_lastUpdated — поэтому list_invoices получает счета, созданные за последние 45 дней, и фильтрует на стороне клиента по точному совпадению date. Счета, выставляемые страховщикам/работодателям (например, по компенсации работникам), иногда создаются за месяцы до сеанса, на который они в итоге датированы, и могут не попасть в это окно. У list_appointments этой проблемы нет (он идёт напрямую по ссылке приём→счёт), как и у list_invoices_by_payer (он ищет по получателю, без ограничения по дате) — предпочитайте их, когда «слепая зона» по дате имеет значение.

• session и meeting различаются по наличию связанного участника Patient, а не по какому-то явному полю Halaxy — реальный сеанс, записанный без привязки к карточке пациента в Halaxy, будет ошибочно отнесён к встречам.

• Никаких операций записи (создание/изменение чего-либо) намеренно не реализовано.

• Только транспорт stdio; удалённый/HTTP-вариант (для размещения где-то, доступного облачному MCP-клиенту, например, через пользовательский коннектор) пока не создан.

Что он намеренно не делает

Этот инструмент оборачивает несколько конечных точек только для чтения, соответствующих потребностям одной практики, а не универсальный клиент Halaxy/FHIR. Он не реализует создание/обновление пациентов, клинические заметки, изменение расписания или большую часть FHIR-поверхности Halaxy примерно на 50 ресурсов (отслеживание направлений покрыто — см. выше, но не создание/изменение направлений). Если вам нужно больше возможностей API, функции-инструменты в halaxy_mcp.py — достаточно короткая и читаемая отправная точка для расширения.

Лицензия

GPLv3 — см. LICENSE.