fhir-patient-consent-mcp-server

MCP 서버로, 모델이 환자, 환자의 인슐린 펌프, 그리고 그 데이터를 볼 수 있도록 동의한 사람이 누구인지에 대해 질문할 수 있게 합니다. 모든 데이터는 FHIR(R4) 저장소에서 실시간으로 가져옵니다. 이 서버에는 데이터가 저장되지 않으며, 모든 답변은 실시간 FHIR REST 쿼리입니다.

이 서버는 Patient/Device/Consent를 FHIR에 기록하기 위한 Spring Boot API인 fhir-consent-service의 동반 도구이지만, 코드 의존성은 없습니다. 이 서버는 FHIR 와이어 형식에만 의존하므로 모든 FHIR R4 엔드포인트에서 동작합니다.

도구

Related MCP server: FHIR MCP Server

리소스

fhir-chart://{patientId} — 환자의 통합 JSON "차트"(인구통계 + 기기 + 유효한 동의)로, 모델이 여러 도구 호출에 걸쳐 조립하는 대신 호스트 애플리케이션이 컨텍스트에 직접 첨부하도록 설계된 것입니다. 이것이 여섯 번째 도구가 아닌 리소스인 이유는 docs/architecture.md를 참조하세요.

설정

npm install
npm run build

FHIR 서버에 연결하기

export FHIR_BASE_URL=http://localhost:8081/fhir   # default shown
export FHIR_AUTH_TOKEN=...                         # optional bearer token

쿼리할 데이터를 확보하는 가장 쉬운 방법: fhir-consent-service의 docker compose up -d를 실행하면(:8081에서 로컬 HAPI FHIR JPA 서버를 시작), REST API를 통해 환자, 기기, 동의를 만든 뒤 여기에서 동일한 저장소를 쿼리하는 것입니다.

직접 실행(stdio 테스트용)

npm run dev

MCP 클라이언트에 등록하기

Claude Desktop / Claude Code의 경우 MCP 설정에 다음을 추가하세요:

{
  "mcpServers": {
    "fhir-patient-consent": {
      "command": "node",
      "args": ["/absolute/path/to/fhir-patient-consent-mcp-server/dist/index.js"],
      "env": {
        "FHIR_BASE_URL": "http://localhost:8081/fhir"
      }
    }
  }
}

npm run build를 먼저 실행하여 dist/index.js가 존재하도록 하세요.

연결 후 예시 질문

• "MRN이 MRN-778001인 환자를 조회해 주세요."

• "환자 123이 사용하는 어떤 인슐린 펌프이며, 시리얼 번호는 무엇인가요?"

• "GlucoVue Remote Monitoring이 환자 123의 기기 데이터를 볼 수 있도록 동의받았나요?"

• "환자 123의 전체 차트를 보여 주세요." (fhir-chart:// 리소스를 사용)

테스트

npm test

단위 테스트는 매퍼 계층(src/mappers/*.ts)을 다루며, isConsentActiveForPartner의 동의 인가 로직을 포함합니다. 특히 철회된 콘센트, 아직 시작되지 않았거나 만료된 기간, 그리고 개방형(end 미포함) 기간을 처리합니다. 이는 미묘하게 잘못되기 쉬운 부분이기 때문입니다.

Testcontainers를 사용하는 fhir-consent-service와는 달리, 이 저장소에는 실제 FHIR 서버에 대한 통합 테스트가 없습니다. 이유는 이 서버에 테스트 데이터를 시드할 수 있는 쓰기 경로가 없기 때문이며, 테스트 픽스처를 마련하기 위해 그 저장소에 의존해야 하는 것입니다. 이 저장소에 시딩 스크립트가 생긴다면, 그때 통합 테스트를 추가하세요.

참고: npm 레지스트리에 접근할 수 없는 샌드박스 환경에서 작성되었으므로, npm install / npm run build / npm test는 실제로 여기서 실행되지 않았습니다. 코드는 @modelcontextprotocol/sdk@^1.12을 대상으로 합니다. 설치하는 버전에서 SDK의 server.tool(...) / server.resource(...) 시그니처가 registerTool/registerResource로 변경된 경우, 수정은 기계적입니다 — SDK의 README/CHANGELOG를 확인하세요.

프로젝트 구조

src/
├── index.ts              Server entry point, registers all tools/resources
├── fhirClient.ts          Thin fetch-based FHIR REST client
├── tools/                 One file per MCP tool
├── resources/             One file per MCP resource
├── mappers/                FHIR JSON -> summary objects + consent auth logic
└── util/results.ts        Shared tool-result formatting helpers

보안 유의 사항

이 서버는 PHI(보호 건강 정보)를 숨기지 않고 FHIR 서버가 반환하는 그대로를 전달합니다. 실제 환자 데이터를 대상으로 배포한다면 FHIR 서버 자체 앞에서 접근 제어를 두세요(이 서버는 FHIR_AUTH_TOKEN을 Bearer 토큰으로 전달하지만 토큰 취득/갱신은 관리하지 않습니다). 그리고 무엇을 MCP 클라이언트에 노출하고 무엇을 노출하면 안 되는지를 고려하세요.

라이선스

MIT