clinic-mcp

一个用于诊所预约和预检的参考 Model Context Protocol 服务器。使用 TypeScript 构建，具有严格的类型检查、结构化错误处理，并在数据层强制执行租户隔离。数据均为合成数据。这不是临床软件。

其目标是展示一个生产级 MCP 服务器在需要数据隔离和扎实输出的垂直领域中应有的形态：这与我在 Rentive 编写的代码形态相同，但使用了模拟数据和不同的领域，以便在不泄露任何专有信息的情况下对模式进行审查。

为什么选择 MCP

LLM 应用程序一直在重复造轮子：每个提供商都有特定的函数定义、定制的参数解析、没有共享传输层、没有一致的错误模型。MCP 是一个小型开放协议，旨在修复连接层。服务器通过 stdio（或 HTTP）公开一系列类型化的工具，任何支持 MCP 的客户端（Claude Desktop、IDE 集成、自定义代理）都可以使用相同的机制发现并调用它们。

对于领域后端而言，这意味着你只需编写一次工具，它们就能在任何地方工作。对于代理构建者而言，这意味着你无需再手动编写工具模式，而是开始组合服务器。

Related MCP server: MCP Healthcare Server

架构

flowchart LR
    Client["MCP client<br/>(Claude Desktop, custom agent)"]
    Server["clinic-mcp server"]
    Tools["Tools<br/>find_available_slot<br/>book_appointment<br/>record_intake<br/>search_protocols<br/>escalate_to_oncall"]
    Store["ClinicStore<br/>tenant-scoped accessors"]
    Seed[("seed.json<br/>synthetic clinics, providers,<br/>patients, protocols")]

    Client -->|stdio JSON-RPC| Server
    Server --> Tools
    Tools --> Store
    Store --> Seed

每个工具都接收一个 clinic_id，存储层强制要求所有读写操作都限定在该诊所范围内。跨租户访问会抛出 TenantMismatchError，而不是静默返回错误的数据行。这反映了生产部署在 Postgres 中强制执行的行级安全模式，此处将其呈现在应用程序代码中，以便在单个文件中审查该保证 (src/store/index.ts)。

本地运行

需要 Node 20+ 和 pnpm。

git clone https://github.com/dominikstefanski/clinic-mcp.git
cd clinic-mcp
pnpm install
pnpm test          # 29 tests
pnpm typecheck
pnpm dev           # boots the server on stdio

服务器在启动时读取 src/store/seed.json 并为两个合成诊所提供服务：clinic_north（全科、心脏科、皮肤科）和 clinic_west（儿科、全科）。

连接到 Claude Desktop

将其添加到你的 Claude Desktop 配置中（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）。将路径替换为你本地的克隆路径。

{
  "mcpServers": {
    "clinic-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/clinic-mcp/src/server.ts"]
    }
  }
}

重启 Claude Desktop。这五个工具将出现在连接菜单下。尝试输入类似 "Find a general practice opening at clinic_north next Monday morning." 的提示。

工具参考

所有工具在成功时返回 { ok: true, ...result }，在失败时返回 { ok: false, error: { code, message } }。输入使用 zod 进行验证；MCP 级别的参数错误将作为带有字段详细信息的 validation 错误返回。

find_available_slot

查找指定日期范围内某专业的空闲预约时段，跳过冲突。

book_appointment

创建预约。需要调用者提供 idempotency_key；重试请求将返回原始预约而不是重复预订。语音代理会进行重试，因此此项为必填。

返回 { appointment, idempotent_replay }。

record_intake

持久化结构化的预检记录并分配分诊级别。

分诊规则：严重程度 >= 8 为 urgent（紧急），>= 5 为 elevated（加急），否则为 routine（常规）。

search_protocols

对诊所的协议库进行关键词搜索。返回模型在回答时可以引用的排名片段。

当前的实现是一个带有标题加权（3 倍）的简单 TF 分数。它旨在演示检索工具的接口；生产部署会将后端替换为向量搜索（参见设计说明）。

escalate_to_oncall

将现有预约标记为紧急并重新分配给诊所的随叫随到（on-call）提供者。

返回 { appointment, on_call_provider, reassigned }。

设计说明

租户隔离在存储层强制执行，而非工具层。 工具接收 clinic_id 并将其向下传递。存储层在每次访问时验证所有权，并在不匹配时抛出 TenantMismatchError。如果你明天添加一个新工具，你不可能意外地跨诊所泄露数据；存储层不会允许你这样做。

写入幂等性。 book_appointment 需要一个 idempotency_key。真实的调用者（语音代理、重试循环、网络抖动）会重复请求，而一个通过创建重复预约来响应重试的医疗系统，是一个在第一天就会失去信任的系统。

结构化错误优于抛出字符串。 每个领域故障都是一个带有稳定 code 的类型化 DomainError 子类。MCP 包装器将其转换为 { ok: false, error: { code, message } }。客户端可以根据 code 进行分支处理，而不是通过正则匹配 message。

检索工具是一个占位符。 search_protocols 使用内存中的 TF 分数，因此仓库无需外部服务即可运行。在生产环境中，这是你接入 Pinecone、pgvector 或你选择的检索后端的接口。工具的输入/输出契约保持不变。

时间处理已简化。 为清晰起见，提供者的工作时间以 UTC 解释。真正的部署会尊重每个诊所的时区（已在模式中）。明确指出这一点是为了让审查者知道这是故意的，而不是疏忽。

这不是什么

• 不是临床软件。分诊规则只是一个玩具，协议语料库是手写的散文。不要将其用于任何涉及真实患者的场景。

• 不符合 HIPAA 标准。数据是假的，存储在内存中，没有审计日志。生产环境需要所有这些以及更多功能。

• 不是完整的 EMR 或预约后端。重点是展示 MCP 服务器的形态，而不是发布一个诊所系统。

许可证

MIT。参见 LICENSE。