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

Рабочий эталон для Model Context Protocol — инструменты, ресурсы, промпты, получение данных (elicitation), выборка (sampling) и автодополнение — построенный вокруг домена планирования медицинских приемов.

Создано с использованием TypeScript, Hono, MCP SDK и Zod.

Содержание

Возможности

Примитивы MCP-сервера

Примитив	Название	Описание
Инструмент	`search_doctors`	Поиск врачей по имени или специальности
Инструмент	`get_available_slots`	Получение доступных временных слотов для врача на дату
Инструмент	`book_appointment`	Бронирование приема (использует elicitation для подтверждения)
Инструмент	`cancel_appointment`	Отмена приема (использует elicitation для подтверждения)
Инструмент	`list_appointments`	Список приемов с фильтрами
Инструмент	`recommend_specialist`	Рекомендация специалиста на основе симптомов (использует sampling)
Ресурс	`specialties://list`	Статический список всех медицинских специальностей
Ресурс	`doctor://{doctorId}/profile`	Динамический профиль врача с шаблоном
Ресурс	`patient://{patientId}/summary`	Информация о пациенте + история приемов
Ресурс	`appointment://{appointmentId}`	Полные детали приема
Промпт	`schedule-appointment`	Управляемый рабочий процесс планирования приема (с completion)
Промпт	`patient-history`	Просмотр истории пациента (с completion)
Промпт	`triage-symptoms`	Триаж симптомов и рекомендация специалиста

Возможности MCP-клиента

Возможность	Как это используется
Elicitation	`book_appointment` и `cancel_appointment` запрашивают подтверждение пользователя перед продолжением
Sampling	`recommend_specialist` использует LLM-выборку для сопоставления симптомов со специальностями
Roots	Сервер регистрирует корень (root) для рабочей области медицинских приемов
Completion	Промпты используют `completable()` для автодополнения названий специальностей и 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`

Навык взаимодействует с REST-сервисом напрямую по HTTP, используя встроенный доступ агента к инструментам.

Ограничения навыка

Следующие функции MCP-сервера не имеют эквивалента в спецификации agentskills.io и поэтому не воспроизведены:

Функция MCP	Ограничение
Elicitation	`book_appointment` и `cancel_appointment` используют нативный диалог подтверждения UI в MCP-сервере. У навыков нет эквивалента; агент запрашивает подтверждение через диалог.
Sampling	`recommend_specialist` вызывает вспомогательную LLM через MCP-выборку для сопоставления симптомов со специальностями. Навык использует собственные рассуждения агента напрямую (функционально эквивалентно).
Завершение аргументов	MCP-промпты используют `completable()` для автоподсказок названий специальностей и ID пациентов в UI клиента. Навыки не предоставляют интерактивное автодополнение.
Roots	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
VS Code с GitHub Copilot (для интеграции 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. Подключите MCP-сервер в VS Code

Файл .vscode/mcp.json уже настроен. VS Code автоматически обнаружит и предложит запустить MCP-сервер. Альтернативно, запустите его вручную:

npm run dev:mcp

3. Попробуйте в действии

В чате Copilot в VS Code (режим Agent) попробуйте:

"Search for cardiologists"
"What slots does Dr. Sarah Chen have available next Monday?"
"Book an appointment with doc-3 for patient pat-1"
"Show me Alice Johnson's appointment history"
"I've been having severe headaches and dizziness — what specialist should I see?"

Или используйте промпты из выбора промптов:

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-сервис с хранилищем данных в оперативной памяти, загружаемым из JSON-файлов в data/.
MCP-сервер — подключается через stdio и предоставляет REST API через примитивы MCP (инструменты, ресурсы, промпты).

MCP-сервер никогда не обращается к хранилищу данных напрямую — он вызывает REST API через HTTP-клиент, сохраняя четкое разделение двух уровней.

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`	Запуск MCP-сервера в режиме stdio
`npm run build`	Компиляция TypeScript в `dist/`
`npm run typecheck`	Проверка типов без создания файлов

Доменная модель

Сущность	Описание
Specialty	Медицинская специальность (кардиология, дерматология и т.д.)
Doctor	Имеет специальность, доступные дни, рабочие часы и длительность слота
Patient	Имя, email, телефон, дата рождения
Appointment	Связывает пациента с врачом в конкретную дату/время с причиной и статусом
TimeSlot	Доступное или забронированное временное окно для врача в конкретный день

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

REST API по умолчанию слушает порт 3000. MCP-сервер общается с API через http://localhost:3000 и подключается к VS Code через stdio.

Начальные данные (специальности, врачи, пациенты) загружаются из директории data/ при запуске. Редактируйте эти JSON-файлы для настройки демонстрационного набора данных.

Участие в разработке

Вклад приветствуется. Сделайте форк репозитория, создайте ветку для функции и откройте pull request.

Лицензия

MIT

MCP Medical Appointments Demo