MCP 의료 예약 데모

Model Context Protocol을 위한 작동 참조 구현체입니다. 의료 예약 도메인을 중심으로 도구, 리소스, 프롬프트, 유도(elicitation), 샘플링 및 완성(completion) 기능을 포함합니다.

TypeScript, Hono, MCP SDK 및 Zod로 구축되었습니다.

기능

MCP 서버 기본 요소

기본 요소	이름	설명
도구	`search_doctors`	이름이나 전문 분야별로 의사 검색
도구	`get_available_slots`	특정 날짜의 의사 예약 가능 시간대 조회
도구	`book_appointment`	진료 예약 (유도(elicitation)를 사용하여 확인)
도구	`cancel_appointment`	진료 예약 취소 (유도(elicitation)를 사용하여 확인)
도구	`list_appointments`	필터를 사용하여 예약 목록 조회
도구	`recommend_specialist`	증상 기반 전문의 추천 (샘플링 사용)
리소스	`specialties://list`	모든 의료 전문 분야의 정적 목록
리소스	`doctor://{doctorId}/profile`	템플릿을 포함한 동적 의사 프로필
리소스	`patient://{patientId}/summary`	환자 정보 + 예약 내역
리소스	`appointment://{appointmentId}`	전체 예약 상세 정보
프롬프트	`schedule-appointment`	안내형 진료 예약 워크플로우 (완성(completion) 포함)
프롬프트	`patient-history`	환자 내역 검토 (완성(completion) 포함)
프롬프트	`triage-symptoms`	증상 분류 및 전문의 추천

MCP 클라이언트 기능

기능	사용 방법
유도(Elicitation)	`book_appointment` 및 `cancel_appointment`는 진행 전 사용자에게 확인을 요청합니다
샘플링	`recommend_specialist`는 LLM 샘플링을 사용하여 증상과 전문 분야를 매칭합니다
루트(Roots)	서버가 의료 예약 워크스페이스를 위한 루트를 등록합니다
완성(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` 프롬프트

이 스킬은 에이전트의 기본 도구 액세스를 사용하여 HTTP를 통해 REST 서비스와 직접 상호 작용합니다.

스킬 제한 사항

다음 MCP 서버 기능은 agentskills.io 사양에 대응하는 기능이 없으므로 복제되지 않았습니다:

MCP 기능	제한 사항
유도(Elicitation)	`book_appointment` 및 `cancel_appointment`는 MCP 서버에서 기본 UI 확인 대화 상자를 사용합니다. 스킬에는 대응하는 기능이 없으며, 에이전트가 대화를 통해 확인을 요청합니다.
샘플링	`recommend_specialist`는 MCP 샘플링을 통해 하위 LLM을 호출하여 증상과 전문 분야를 매칭합니다. 스킬은 에이전트 자신의 추론을 직접 사용합니다(기능적으로 동일).
인수 완성	MCP 프롬프트는 `completable()`을 사용하여 클라이언트 UI에서 전문 분야 이름과 환자 ID를 자동 제안합니다. 스킬은 대화형 완성을 제공하지 않습니다.
루트(Roots)	MCP 서버는 워크스페이스 루트(`roots/list`)를 등록합니다. 이는 스킬 대응 기능이 없는 MCP 전송 개념입니다.
VS Code 전용 스킬 필드	`argument-hint`, `user-invocable`, `disable-model-invocation`과 같은 필드는 SKILL.md 형식에 대한 VS Code Copilot 확장입니다. 이는 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

이 프로젝트는 2-프로세스 설계를 사용합니다:

Hono REST API — data/의 JSON 시드 파일에서 부트스트랩된 인메모리 데이터 저장소를 갖춘 HTTP 서비스.
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 파일을 편집하세요.

기여

기여를 환영합니다. 저장소를 포크하고, 기능 브랜치를 생성한 후 풀 리퀘스트를 보내주세요.

라이선스

MIT

MCP Medical Appointments Demo