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을 재시작하세요. 연결 메뉴 아래에 5개의 도구가 나타납니다. *"clinic_north에서 다음 주 월요일 아침에 일반 진료 가능한 시간을 찾아줘."*와 같은 프롬프트를 시도해 보세요.

도구 참조

모든 도구는 성공 시 { ok: true, ...result }를, 실패 시 { ok: false, error: { code, message } }를 반환합니다. 입력값은 zod로 검증되며, MCP 수준의 인수 오류는 필드 세부 정보가 포함된 validation 오류로 반환됩니다.

find_available_slot

날짜 범위 내에서 특정 전문 분야의 예약 가능한 슬롯을 찾고, 충돌하는 슬롯은 건너뜁니다.

book_appointment

예약을 생성합니다. 호출자가 제공한 idempotency_key가 필요하며, 재시도 시 중복 예약 대신 원래 예약을 반환합니다. 음성 에이전트는 재시도를 수행하므로 이 값은 필수입니다.

{ appointment, idempotent_replay }를 반환합니다.

record_intake

구조화된 접수 노트를 저장하고 분류(triage) 수준을 할당합니다.

분류 규칙: 심각도 >= 8은 urgent, >= 5는 elevated, 그 외는 routine입니다.

search_protocols

클리닉의 프로토콜 라이브러리를 키워드로 검색합니다. 모델이 답변할 때 인용할 수 있는 순위가 매겨진 스니펫을 반환합니다.

현재 구현은 제목 가중치(3배)를 적용한 단순 TF 점수 방식입니다. 검색 도구의 인터페이스를 보여주기 위해 존재하며, 프로덕션 배포 시에는 백엔드를 벡터 검색으로 교체해야 합니다(설계 노트 참조).

escalate_to_oncall

기존 예약을 긴급으로 표시하고 클리닉의 당직 의료진에게 재할당합니다.

{ appointment, on_call_provider, reassigned }를 반환합니다.

설계 노트

테넌트 격리는 도구가 아닌 저장소에서 강제됩니다. 도구는 clinic_id를 받아 하위로 전달합니다. 저장소는 모든 접근자에서 소유권을 검증하고 불일치 시 TenantMismatchError를 발생시킵니다. 내일 새로운 도구를 추가하더라도 실수로 클리닉 간 데이터가 유출될 수 없습니다. 저장소가 이를 허용하지 않기 때문입니다.

쓰기 작업의 멱등성. book_appointment는 idempotency_key를 요구합니다. 실제 호출자(음성 에이전트, 재시도 루프, 네트워크 오류)는 요청을 반복할 것이며, 재시도에 대해 중복 예약을 생성하는 의료 시스템은 첫날부터 신뢰를 잃게 됩니다.

던져진 문자열 대신 구조화된 오류. 모든 도메인 오류는 안정적인 code를 가진 타입 지정된 DomainError 하위 클래스입니다. MCP 래퍼는 이를 { ok: false, error: { code, message } }로 변환합니다. 클라이언트는 message를 정규식으로 처리하는 대신 code를 기준으로 분기할 수 있습니다.

검색 도구는 대용품입니다. search_protocols는 외부 서비스 없이 저장소가 실행되도록 메모리 내 TF 점수를 사용합니다. 프로덕션 환경에서는 이곳이 Pinecone, pgvector 또는 선택한 검색 백엔드를 연결하는 지점이 됩니다. 도구의 입출력 계약은 동일하게 유지됩니다.

시간 처리는 단순화되었습니다. 의료진의 근무 시간은 명확성을 위해 UTC로 해석됩니다. 실제 배포 시에는 각 클리닉의 시간대를 준수해야 합니다(스키마에 이미 포함됨). 검토자가 이것이 간과된 것이 아니라 의도된 것임을 알 수 있도록 명시합니다.

이 프로젝트가 아닌 것

• 임상 소프트웨어가 아닙니다. 분류 규칙은 장난감 수준이며 프로토콜 코퍼스는 직접 작성한 산문입니다. 실제 환자와 관련된 어떤 용도로도 사용하지 마십시오.

• HIPAA 준수 소프트웨어가 아닙니다. 데이터는 가짜이고, 저장소는 메모리 내 방식이며, 감사 로그가 없습니다. 프로덕션 환경에서는 이 모든 것과 그 이상의 기능이 필요합니다.

• 완전한 EMR 또는 예약 백엔드가 아닙니다. 이 프로젝트의 목적은 MCP 서버의 형태를 보여주는 것이지, 클리닉 시스템을 출시하는 것이 아닙니다.

라이선스

MIT. LICENSE를 참조하세요.