fhir-patient-consent-mcp-server

Un servidor MCP que permite a un modelo hacer preguntas sobre un paciente, su bomba de insulina y quién ha dado su consentimiento para ver esos datos, todo obtenido en directo desde un almacén de FHIR (R4). Este servidor no conserva ningún dato; cada respuesta es una consulta REST de FHIR en tiempo real.

Es un complemento de fhir-consent-service (una API de Spring Boot para escribir Patient/Device/Consent en FHIR), pero no tiene ninguna dependencia de código con él: este servidor solo depende del formato de transporte de FHIR, por lo que funciona con cualquier endpoint de FHIR R4.

Herramientas

Related MCP server: FHIR MCP Server

Recurso

fhir-chart://{patientId}: un «historial» JSON consolidado (datos demográficos + dispositivos + consentimientos activos) de un paciente, pensado para que la aplicación anfitriona lo adjunte directamente al contexto en lugar de que lo monte el modelo mediante varias llamadas a herramientas. Consulta docs/architecture.md para saber por qué se trata de un recurso y no de una sexta herramienta.

Configuración

npm install
npm run build

Apuntar a un servidor FHIR

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

La forma más sencilla de disponer de datos que consultar: ejecuta docker compose up -d de fhir-consent-service (inicia un servidor local de HAPI FHIR JPA en :8081) y crea un paciente, un dispositivo y un consentimiento mediante su API REST; después consulta el mismo almacén desde aquí.

Ejecutarlo directamente (para probar con stdio)

npm run dev

Registrarlo en un cliente MCP

Para Claude Desktop / Claude Code, añade esto a la configuración de 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"
      }
    }
  }
}

Ejecuta primero npm run build para que exista dist/index.js.

Preguntas de ejemplo una vez conectado

• "Busca al paciente con MRN MRN-778001."

• "¿Qué bomba de insulina tiene la paciente 123 y cuál es su número de serie?"

• "¿Se le ha dado a GlucoVue Remote Monitoring consentimiento para ver los datos de los dispositivo del paciente 123?"

• "Muéstrame el historial completo del paciente 123." (ejercita el recurso fhir-chart://)

Pruebas

npm test

Las pruebas unitarias cubren la capa de mappers (src/mappers/*.ts), incluida la lógica de autorización de consentimientos en isConsentActiveForPartner; en particular, su manejo de los consentimientos revocados, de los períodos no iniciados/caducados y de los períodos abiertos (sin end), ya que son los casos en los que es más fácil fallar de forma sutil.

No hay una prueba de integración contra un servidor FHIR real en este repositorio (a diferencia de fhir-consent-service, que usa Testcontainers), porque este servidor no tiene una ruta de escritura para sembrar los datos: dependería de ese repositorio (o duplicaría su lógica de osos de creación de recursos) únicamente para preparar los fixtures de prueba. Sieste repositorio algún día llegara a tener un script de datos de inicio, añade una.

Nota: se ha escrito en un entorno aislado sin acceso al repositorio de npm. no se han llegado a ejecutar npm install / npm run build / npm test aquí equipo. El código está dirigido a @modelcontextprotocol/sdk@^1.12; si en la versión que inst ale, las firmas de server.tool(...) / server.resource(...) del SDK han cambiado a registerTool / registeresubsante, la corrección es mecánica: consulta el README/CHANGELOG del propio SDK.

Estructura del proyecto

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

Nota de seguridad

Este servidor no realiza ninguna redacción de PHI y reenvía lo que devuelve el servidor FHIR. Si se despliega con datos reales de pacientes, pon el control de acceso primeroal del servidor FHIR (este servidor reenvía FHIR_AUTH_TOKEN como token de portador, pero no control de la forma/obtención/renovación de token) and pondera qué debería y qué no debería exponerse a un cliente MCP.

Licencia

MIT