MCP 医疗预约演示

一个关于 Model Context Protocol 的工作参考实现——涵盖工具、资源、提示词、启发式交互、采样和补全——围绕医疗预约调度领域构建。

功能

MCP 服务器原语

原语	名称	描述
工具	`search_doctors`	按姓名或专业搜索医生
工具	`get_available_slots`	获取医生在某日的可预约时间段
工具	`book_appointment`	预订预约（使用启发式交互进行确认）
工具	`cancel_appointment`	取消预约（使用启发式交互进行确认）
工具	`list_appointments`	带过滤条件列出预约
工具	`recommend_specialist`	基于症状的专家推荐（使用采样）
资源	`specialties://list`	所有医疗专业的静态列表
资源	`doctor://{doctorId}/profile`	带有模板的动态医生资料
资源	`patient://{patientId}/summary`	患者信息 + 预约历史
资源	`appointment://{appointmentId}`	完整的预约详情
提示词	`schedule-appointment`	指导式预约调度工作流（带有补全）
提示词	`patient-history`	患者历史记录回顾（带有补全）
提示词	`triage-symptoms`	症状分诊和专家推荐

MCP 客户端功能

功能	使用方式
启发式交互	`book_appointment` 和 `cancel_appointment` 在执行前要求用户确认
采样	`recommend_specialist` 使用 LLM 采样将症状与专业匹配
根目录	服务器为医疗预约工作区注册一个根目录
补全	提示词使用 `completable()` 在客户端 UI 中自动补全专业名称和患者 ID

代理技能

此领域的 SKILL.md 位于 .github/skills/medical-appointments/SKILL.md。它镜像了 MCP 服务器的功能，而无需 MCP 协议——任何兼容的代理（GitHub Copilot、Claude Code 等）都可以按需加载它。

技能涵盖内容

技能工作流	等效的 MCP 原语
查找医生	`search_doctors` 工具
检查空闲时间段	`get_available_slots` 工具
预订预约	`book_appointment` 工具
取消预约	`cancel_appointment` 工具
列出预约	`list_appointments` 工具
推荐专家	`recommend_specialist` 工具
调度预约	`schedule-appointment` 提示词
患者历史记录	`patient-history` 提示词
症状分诊	`triage-symptoms` 提示词

该技能使用代理的原生工具访问权限，直接通过 HTTP 与 REST 服务交互。

技能限制

以下 MCP 服务器功能在 agentskills.io 规范中没有等效项，因此未进行复制：

MCP 功能	限制
启发式交互	`book_appointment` 和 `cancel_appointment` 在 MCP 服务器中使用原生 UI 确认对话框。技能没有等效项；代理改为通过对话请求确认。
采样	`recommend_specialist` 通过 MCP 采样调用子 LLM 来匹配症状与专业。技能直接使用代理自身的推理（功能上等效）。
参数补全	MCP 提示词使用 `completable()` 在客户端 UI 中自动建议专业名称和患者 ID。技能不提供交互式补全。
根目录	MCP 服务器注册工作区根目录 (`roots/list`)。这是一个 MCP 传输概念，没有技能等效项。
VS Code 特定技能字段	`argument-hint`、`user-invocable` 和 `disable-model-invocation` 等字段是 VS Code Copilot 对 SKILL.md 格式的扩展。它们不是 agentskills.io 规范的一部分，为了保持技能的可移植性，已将其省略。

快速入门

前置要求

Node.js >= 22.0.0
安装了 GitHub Copilot 的 VS Code（用于 MCP 集成）

1. 安装并启动 REST API

npm install
npm run dev:service

你应该看到：

Bootstrapped: 8 specialties, 12 doctors, 5 patients
Medical Appointment Service running on http://localhost:3000

2. 在 VS Code 中连接 MCP 服务器

.vscode/mcp.json 文件已配置好。VS Code 将自动检测并提示启动 MCP 服务器。或者，手动运行它：

npm run dev:mcp

3. 试用

在 VS Code 的 Copilot Chat（代理模式）中，尝试：

“搜索心脏病专家”
“Sarah Chen 医生下周一有哪些空闲时间段？”
“为患者 pat-1 预订 doc-3 的预约”
“向我展示 Alice Johnson 的预约历史”
“我一直头痛和头晕——我应该看什么科室的医生？”

或者使用提示词选择器中的提示词：

Schedule Appointment — 指导式调度工作流
Patient History — 回顾患者就诊记录
Triage Symptoms — 基于症状的专家匹配

架构

┌─────────────────┐     stdio      ┌───────────────────┐     HTTP     ┌──────────────────┐
│   VS Code /     │◄──────────────►│   MCP Server      │─────────────►│  Hono REST API   │
│   MCP Client    │                │   (TypeScript)    │  localhost   │  (localhost:3000)│
└─────────────────┘                └───────────────────┘              └──────────────────┘
                                     Tools, Resources,                  In-memory store
                                     Prompts                            + JSON bootstrap

该项目使用双进程设计：

Hono REST API — 带有内存数据存储的 HTTP 服务，从 data/ 中的 JSON 种子文件引导。
MCP 服务器 — 通过 stdio 连接，并通过 MCP 原语（工具、资源、提示词）暴露 REST API。

MCP 服务器从不直接接触数据存储——它通过 HTTP 客户端调用 REST API，保持两层之间的清晰分离。

REST API 端点

方法	端点	描述
`GET`	`/api/specialties`	列出所有专业
`GET`	`/api/specialties/:id`	按 ID 获取专业
`GET`	`/api/doctors`	列出医生（过滤器：`?specialtyId=`, `?name=`）
`GET`	`/api/doctors/:id`	按 ID 获取医生
`GET`	`/api/doctors/:id/slots?date=YYYY-MM-DD`	获取空闲时间段
`GET`	`/api/patients`	列出所有患者
`GET`	`/api/patients/:id`	按 ID 获取患者
`POST`	`/api/patients`	创建患者
`GET`	`/api/appointments`	列出预约（过滤器：`?patientId=`, `?doctorId=`, `?status=`, `?date=`）
`GET`	`/api/appointments/:id`	按 ID 获取预约
`POST`	`/api/appointments`	预订预约
`PATCH`	`/api/appointments/:id/cancel`	取消预约
`PATCH`	`/api/appointments/:id/complete`	完成预约

项目结构

mcp-demo/
├── data/
│   ├── specialties.json      # 8 medical specialties
│   ├── doctors.json           # 12 doctors across specialties
│   └── patients.json          # 5 sample patients
├── src/
│   ├── types.ts               # Shared domain types
│   ├── service/
│   │   ├── store.ts           # In-memory data store
│   │   ├── app.ts             # Hono app composition
│   │   ├── main.ts            # Service entry point
│   │   └── routes/            # REST route handlers
│   └── mcp/
│       ├── api-client.ts      # HTTP client for the REST API
│       ├── tools.ts           # MCP tool registrations
│       ├── resources.ts       # MCP resource registrations
│       ├── prompts.ts         # MCP prompt registrations
│       └── server.ts          # MCP server entry point
├── .vscode/
│   └── mcp.json               # VS Code MCP server config
├── package.json
└── tsconfig.json

脚本

命令	描述
`npm run dev:service`	启动带有热重载的 Hono REST API
`npm run dev:mcp`	以 stdio 模式启动 MCP 服务器
`npm run build`	将 TypeScript 编译到 `dist/`
`npm run typecheck`	进行类型检查而不生成文件

领域模型

实体	描述
Specialty	医疗专业（心脏病学、皮肤病学等）
Doctor	拥有专业、可用日期、工作时间和时间段时长
Patient	姓名、电子邮件、电话、出生日期
Appointment	将患者与医生在特定日期/时间关联，并带有原因和状态
TimeSlot	医生在特定日期的空闲或已预订时间窗口

配置

REST API 默认监听 3000 端口。MCP 服务器通过 http://localhost:3000 与 API 通信，并通过 stdio 连接到 VS Code。

种子数据（专业、医生、患者）在启动时从 data/ 目录加载。编辑这些 JSON 文件以自定义演示数据集。

贡献

欢迎贡献。Fork 仓库，创建功能分支，并提交 Pull Request。

许可证

MIT

MCP Medical Appointments Demo