halaxy-mcp

一个用 Python 编写的 MCP 服务器，用于 Halaxy 诊所管理 API。它让 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() - 临床工作人员，每人带有其 PractitionerRole ID 和姓名，客户端可以先将"Alice 今天有什么安排"解析为角色 ID，再与 list_appointments 进行匹配。

• list_invoices_by_payer(payer_name) - 曾向特定保险公司/雇主/组织（例如"Acme Insurance"）开具的每一张发票，不限定日期——直接搜索 Halaxy 的 Invoice?recipient=，因此没有 list_invoices 的回溯窗口盲区（见下文）。

• list_referrals(flag) - 诊所内所有有效的 Referral——Halaxy 对 GP/其他转诊授权在某个资助计划下一定次数会话和/或金额的建模（最常见的是 Medicare 心理健康治疗计划——即大多数人熟知的"先给 6 次会话"——但也包括 DVA、WorkCover 等）。每条带有 sessions_total/sessions_used/sessions_remaining、amount_total/amount_used、到期时间，以及计算得出的 flags："over_limit"（已用 ≥ 授权）、"expiring_soon"（30 天内到期）、"expired"。可选地只筛选一个标志——例如"谁的会话快用完了"。

所需的 Halaxy API 密钥作用域

在 Halaxy 中创建 API 密钥（设置 → API 密钥），按需勾选以下权限——如果某个作用域未开启，服务器会优雅降级，只会在需要它的工具上报错：

在 Halaxy 自己的 API 密钥作用域界面中看起来是这样的：

患者数据

该服务器刻意最小化其暴露的患者信息。Halaxy 的 Patient 资源还带有出生日期、地址、性别、紧急联系人和转诊来源备注——这些在这里都不需要，并且在代码中强制执行（halaxy_mcp.py 中的 ALLOWED_PATIENT_FIELDS），而不仅仅是靠约定：每次患者查询在到达 MCP 客户端之前都会被过滤到仅剩 id/name/initials/telecom/patient_status/is_active_client，无论请求了什么。

临床/会话记录通过此 API 根本无法检索，任何密钥或作用域都不行。 Halaxy 自己的 /metadata 能力声明显示其临床记录资源（DocumentReference）仅支持 create/patch——不支持读取，这与 Halaxy 界面本身显示的一致（Clinical Notes 只有一个 Create 开关）。这是整个 API 的限制，不是该服务器选择不暴露的问题。

转诊和会话限制

Halaxy 将 GP 心理健康治疗计划（以及类似的——DVA、WorkCover）建模为链接到 ReferralDefinition 的 Referral（转诊类型，带有会话/金额上限——例如测试中一个真实的 ReferralDefinition 字面名称就是"Medicare: MHTP Referral"，限制为 6 次会话）。sessions_remaining 不是 Halaxy 直接返回的；这里计算为 sessions_total - sessions_used。

有几件经真实数据确认的事情，如果你进一步扩展，值得了解：

• 一个患者可以同时有多个有效 Referral（例如每个被转诊的从业者各一个）——该服务器不会猜测"那一个"；它返回全部。

• 实践中 sessions_used 可能超过 sessions_total（Medicare 不会在上限处硬性停止预约）——这就是 "over_limit" 标志的用途。

• 有些 Referral 记录根本没有结构化的类型/转诊来源，只有自由文本 comment——当这是唯一可用的线索时，按原样呈现。

• Halaxy 自己的 Referral 上的 active 字段在其期限过后似乎不会自动翻转为 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 与之通信——无需网络端口，无需单独部署。在每种情况下都使用 .venv 中 Python 和 halaxy_mcp.py 的完整绝对路径。

Claude Desktop - 添加到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "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（或在 CLI 内运行 /mcp add）：

{
  "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 块——脚本会从 halaxy_mcp.py 旁边加载自己的 .env 文件。

已知限制，值得了解

• list_invoices 的回溯窗口可能漏掉发票。 Halaxy 的 Invoice 搜索没有针对发票自身 date 字段的参数，只有 created/_lastUpdated——因此 list_invoices 获取过去 45 天内创建的发票，并在客户端侧按精确的 date 匹配进行过滤。保险公司/雇主开单的发票（例如工伤赔偿）有时在它们最终标注日期的会话之前几个月就创建了，这可能会落在窗口之外。list_appointments 没有这个问题（它直接跟随预约→发票链接），list_invoices_by_payer 也没有（它按收款方搜索，不受日期限制）——当基于日期的盲区很重要时，优先使用这些。

• session 与 meeting 是根据预约是否有关联的 Patient 参与者来推断的，而不是来自任何显式的 Halaxy 字段——在 Halaxy 中未关联患者记录就预订的真实会话会被错误归类为会议。

• 没有实现任何写操作（创建/更新任何内容），这是有意的。

• 仅支持 stdio 传输——远程/HTTP 变体（用于将服务托管在基于云的 MCP 客户端可访问的地方，例如自定义连接器）尚未构建。

它刻意不做什么

这包装了少量只读端点，匹配单一诊所自身的需求，并非通用的 Halaxy/FHIR 客户端。它不实现患者创建/更新、临床记录、排班变更，或 Halaxy 约 50 个资源的 FHIR 表面的大部分（转诊跟踪已覆盖——见上文——但不包括创建/更新转诊）。如果你需要更多 API 功能，halaxy_mcp.py 中的工具函数是一个相当简短、可读的扩展起点。

许可证

GPLv3——参见 LICENSE。