Ejemplos por tool

Este es el front-door para usar el MCP en Cursor, Claude Desktop, Claude Code, Windsurf o Antigravity. Cada sección muestra un prompt natural que un dev chileno escribiría en el chat, lo que hace el modelo internamente y el output esperado. Para la referencia técnica completa (signatures, costos, mapa categórico) ver Tools: Referencia.

Chat de Claude usando @fhiron/mcp-connector, tool call fhiron_validate con resultado de validación CL Core — Validación de un Practitioner desde el chat: el agente llama fhiron_validate y devuelve issues con quick-fix listo para aplicar.

Atajos

Validar una MedicationRequest

El caso más frecuente. Lint + quickFix + validación contra IG en una sola petición.

Armar un Encounter ambulatorio

Scaffold CL Core + búsqueda de comuna y establecimiento DEIS sin gastar cuota.

Auditar un endpoint público

FHIR® Score 0–100 con grade A–F y recomendaciones priorizadas.

Validar

`fhiron_validate`

Cuándo: ya tienes un recurso armado y necesitas confirmación contra el IG (slicing, ValueSets remotos, terminologías). Es la tool por defecto cuando el agente entiende “valida esto”. Pídele al agente:

Valida esta MedicationRequest contra CL Core 1.9.4 y aplica los quickFix que tenga.

{
  "resourceType": "MedicationRequest",
  "status": "active",
  "subject": { "reference": "Patient/123" },
  "medicationCodeableConcept": {
    "coding": [
      { "system": "http://www.whocc.no/atc", "code": "N02BE01", "display": "paracetamol" }
    ]
  }
}

El ejemplo usa solo ATC. La Terminología Farmacéutica Chilena (TFC) queda pendiente de la publicación del canónico oficial; cuando exista, se podrá agregar como segundo coding.

Lo que hace el modelo:

fhiron_lint (offline, gratis)

Detecta cl-medreq-02 (falta intent) con quickFix.replacement = "order".

fhiron_apply_fix (offline, gratis)

Aplica el parche RFC 6901 sobre /intent. El recurso queda corregido sin tocar la cuota.

fhiron_validate (1 crédito)

Llama al servidor con el recurso corregido. HAPI valida contra el perfil completo + binding ATC.

Output (resumen + JSON):

✅ MedicationRequest válida contra FHIR R4 base.

{
  "valid": true,
  "issues": [],
  "profile": null,
  "resourceType": "MedicationRequest",
  "source": "local+server"
}

CL Core no define un perfil de MedicationRequest, por eso profile viene null: la validación de servidor corre contra el recurso base de FHIR R4 más las reglas locales cl-medreq-*.

Si quieres feedback inmediato sin gastar crédito, pide explícitamente “sólo lintea, no valides en servidor”. El modelo elige fhiron_lint y se queda offline.

`fhiron_lint`

Cuándo: estás iterando sobre un recurso y quieres feedback en milisegundos sin gastar cuota. Cubre las 60+ reglas cl-* para los 13 recursos más usados. Pídele al agente:

Lintea esta Encounter sin llamar al servidor. Necesito ver qué falta antes de gastar crédito.
{
  "resourceType": "Encounter",
  "status": "complete",
  "subject": { "reference": "Patient/123" }
}

Lo que hace el modelo:

fhiron_lint (offline, < 5 ms)

Corre las reglas locales sobre el JSON. No hay tráfico de red.

Devuelve issues con quickFix

Cada issue trae code, path, why, suggestion y, cuando aplica, un quickFix mecánico.

Output:

2 errores · 0 warnings detectados localmente.

{
  "valid": false,
  "issues": [
    {
      "code": "cl-enc-02",
      "severity": "error",
      "path": "Encounter.class",
      "message": "Falta Encounter.class (cardinalidad 1..1).",
      "why": "CL Core hereda la cardinalidad 1..1 de FHIR R4 para diferenciar AMB · IMP · EMER · HH."
    },
    {
      "code": "cl-enc-04",
      "severity": "error",
      "path": "Encounter.status",
      "message": "Encounter.status='complete' no pertenece al ValueSet EncounterStatus.",
      "quickFix": { "jsonPointer": "/status", "replacement": "finished" }
    }
  ],
  "source": "local"
}

El lint es determinístico. Mismo JSON in → mismos issues out, sin temperatura del modelo. Es la base para CI/CD: corre fhiron_lint en un pre-commit hook y bloquea el push si hay errores.

`fhiron_validate_file`

Cuándo: el recurso vive en un .json del repo y no quieres pegar 200 líneas de JSON en el chat. Pídele al agente:

Valida el archivo samples/encounter-ambulatorio.json contra CL Core.

Lo que hace el modelo:

Verifica el sandbox

Resuelve la ruta contra FHIRON_MCP_ALLOWED_ROOT. Rechaza paths fuera del root, symlinks, archivos ≥ 5 MB y extensiones distintas de .json / .fhir.json.

Lee el archivo y delega

Si es un Bundle, delega a fhiron_validate_bundle. Si no, a fhiron_validate.

Output:

samples/encounter-ambulatorio.json (Encounter): válido ✅

{
  "valid": true,
  "issues": [],
  "profile": "https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/EncounterCL",
  "resourceType": "Encounter",
  "source": "local+server"
}

Para apuntar a otro directorio: export FHIRON_MCP_ALLOWED_ROOT=/ruta/a/tu/proyecto/fhir antes de iniciar el conector. La tool nunca modifica el archivo.

`fhiron_validate_bundle`

Cuándo: tienes un Bundle (transaction, batch, collection o document) y necesitas saber qué entries pasan y cuáles fallan. Cobra 1 crédito por entry validada, con un cap default de 50 para protegerte. Pídele al agente:

Audita este Bundle entry-por-entry y dame una matriz pass/fail agrupada por resourceType.

Lo que hace el modelo:

Linteo local de cada entry

Si una entry tiene errores locales, no llega al servidor (no consume crédito).

Validación servidor de las entries que pasan el lint

Hasta max_server_calls (default 50). El resto queda como local-only.

Agregación

Devuelve totales, agrupado por resourceType, y el detalle por entry.

Output:

12 entries · 9 OK · 3 fallaron · 9 créditos consumidos.

{
  "valid": false,
  "totals": { "entries": 12, "passed": 9, "failed": 3, "creditsUsed": 9, "serverCalls": 9 },
  "byResourceType": [
    { "resourceType": "Patient", "total": 4, "passed": 4, "failed": 0 },
    { "resourceType": "Encounter", "total": 4, "passed": 3, "failed": 1 },
    { "resourceType": "MedicationRequest", "total": 4, "passed": 2, "failed": 2 }
  ],
  "perEntry": [
    {
      "entryIndex": 7,
      "resourceType": "MedicationRequest",
      "valid": false,
      "errorCount": 1,
      "issues": [{ "code": "cl-medreq-02", "path": "MedicationRequest.intent", "severity": "error" }]
    }
  ]
}

Si tu Bundle tiene cientos de entries, sube el cap explícitamente: “valida hasta 200 entries”. El modelo le pasa max_server_calls: 200 (límite duro 200).

`fhiron_score_endpoint`

Cuándo: quieres evaluar la madurez FHIR de un endpoint público de tercero (proveedor, partner, organismo público) sin tener que leerte el CapabilityStatement a mano. Pídele al agente:

Dame un FHIR Score del endpoint https://api.partner-salud.cl/fhir y explícame qué le falta para llegar a A.

Lo que hace el modelo:

Validación SSRF

Bloquea loopback, redes privadas, link-local, metadata cloud y resuelve DNS para detectar rebind a IPs internas.

GET /metadata

Descarga el CapabilityStatement con cap de 10 MB.

Scoring sobre 5 dimensiones

fhirVersion · core resources · profiles declarados · interactions soportadas · sistemas terminológicos referenciados. 20 puntos cada una.

Output:

api.partner-salud.cl → 72 / 100 (B) · FHIR R4.0.1 · 8/10 core · 2 perfiles declarados.

{
  "url": "https://api.partner-salud.cl/fhir",
  "score": 72,
  "grade": "B",
  "fhirVersion": "4.0.1",
  "coreResourcesPresent": ["Patient", "Practitioner", "Encounter", "Observation", "Condition", "MedicationRequest", "AllergyIntolerance", "Bundle"],
  "profilesDeclared": [
    "http://hl7.org/fhir/StructureDefinition/Patient",
    "https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CorePacienteCl"
  ],
  "dimensions": {
    "fhirVersion":      { "score": 20, "max": 20, "note": "R4.0.1 vigente" },
    "coreResources":    { "score": 16, "max": 20, "note": "8/10 core resources presentes" },
    "profilesDeclared": { "score": 10, "max": 20, "note": "2 perfiles declarados" },
    "interactions":     { "score": 16, "max": 20 },
    "terminology":      { "score": 10, "max": 20 }
  },
  "recommendations": [
    "Declarar perfiles CL Core en supportedProfile para cada recurso",
    "Faltan core resources: Immunization, DiagnosticReport"
  ]
}

La tool no llama al motor de Fhiron. El scoring corre localmente sobre el CapabilityStatement. No consume crédito.

Explorar

`fhiron_get_example`

Cuándo: estás partiendo desde cero y necesitas un esqueleto válido CL Core para ese tipo de recurso. Devuelve el ejemplo y lo lintea defensivamente antes de entregarlo. Pídele al agente:

Dame un ejemplo de Encounter ambulatorio CL Core válido para usarlo de base.

Lo que hace el modelo:

fhiron_get_example('Encounter')

Devuelve un Encounter completo con class.system = v3-ActCode, subject, period ISO-8601 y narrative.

Output:

Ejemplo Encounter (CL Core v1.9.4): pasa el linter local ✅

{
  "resourceType": "Encounter",
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "subject": { "reference": "Patient/example" },
  "period": { "start": "2026-05-11T09:00:00-04:00", "end": "2026-05-11T09:30:00-04:00" }
}

Recursos disponibles: Patient, Practitioner, Encounter, Observation, Condition, MedicationRequest, AllergyIntolerance, Procedure, Coverage, Organization, Immunization, DiagnosticReport, Bundle.

`fhiron_search_terminology`

Cuándo: el modelo necesita un código real (comuna DEIS, establecimiento, TFC, CIE-10, identificador chileno) y tú no quieres que lo invente. Pídele al agente:

Busca el código DEIS de la comuna de Las Condes y ármame una Patient.address con esa comuna.

Lo que hace el modelo:

fhiron_search_terminology({ system: 'deis-comuna', query: 'las condes' })

Búsqueda case-insensitive y sin tildes sobre el catálogo del decreto 817.

Construye el address

Inyecta code + display con el system canónico correcto.

Output:

1 coincidencia en Comunas DEIS (decreto 817 / MINSAL).

{
  "system": "deis-comuna",
  "label": "Comunas DEIS (decreto 817 / MINSAL)",
  "canonical": "https://hl7chile.cl/fhir/ig/clcore/CodeSystem/CSCodComunasCL",
  "total": 1,
  "results": [
    { "code": "13114", "name": "Las Condes", "region": "Metropolitana de Santiago" }
  ]
}

Sistemas disponibles: deis-comuna, deis-establecimiento, deis (combinado), tfc (incluye ATC), cie10, identificadores (CSTipoIdentificador). Todas son listas vendorizadas en el connector, sin red.

`fhiron_explain_code`

Cuándo: te apareció un código de error (cl-medreq-02, hapi-error-terminology, mcp-quota-01) y quieres contexto pedagógico antes de tocar el JSON. Pídele al agente:

Explícame cl-medreq-02: qué significa, por qué FHIR lo exige y cómo lo arreglo.

Lo que hace el modelo:

fhiron_explain_code({ code: 'cl-medreq-02' })

Busca en el catálogo cl-* / hapi-* / mcp-* y devuelve why, suggestion, example y links.

Output:

📘 cl-medreq-02: explicación

{
  "code": "cl-medreq-02",
  "why": "MedicationRequest.intent es cardinalidad 1..1 en FHIR R4. Sin él, el sistema receptor no distingue una receta firmada (order) de una propuesta de un asistente clínico (proposal) o de un protocolo precargado (plan).",
  "profileUrl": "http://hl7.org/fhir/StructureDefinition/MedicationRequest",
  "docsUrl": "https://docs.fhiron.cl/inspect/errores#cl-medreq-02",
  "suggestion": "Agregar 'intent': 'order' para recetas firmadas. Para sugerencias IA usar 'proposal'; para protocolos, 'plan'.",
  "example": { "intent": "order" }
}

La lista completa de códigos también está expuesta como recurso MCP en fhiron://errors. El modelo la consulta cuando arma respuestas largas.

`fhiron_compare_profiles`

Cuándo: quieres saber qué restricciones agrega CL Core sobre el perfil base de FHIR R4 para un recurso. Útil cuando estás migrando un sistema que ya valida contra R4 y necesitas cuantificar el delta. Cobra 2 créditos (una validación contra R4 + una contra CL Core). Pídele al agente:

Compara este Patient contra FHIR R4 base y CL Core. Quiero ver qué errores aparecen sólo en CL Core.

Lo que hace el modelo:

Valida contra el StructureDefinition R4 base

meta.profile = http://hl7.org/fhir/StructureDefinition/Patient.

Valida en paralelo contra el CL Core

meta.profile = https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CorePacienteCl.

Diff de errores

Devuelve las restricciones que sólo aparecen en CL Core, o sea, el costo de migración.

Output:

R4: 0 errores · CL Core: 2 errores · 2 son específicos de CL Core.

{
  "resourceType": "Patient",
  "r4":     { "profile": "http://hl7.org/fhir/StructureDefinition/Patient", "valid": true,  "errors": [] },
  "clCore": {
    "profile": "https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CorePacienteCl",
    "valid": false,
    "errors": [
      "Patient.identifier requerido: al menos un identifier con system http://www.registrocivil.cl/run.",
      "Patient.address.city debe pertenecer al CodeSystem CSCodComunasCL (decreto 817)."
    ]
  },
  "clOnlyDiff": [
    "Patient.identifier requerido: al menos un identifier con system http://www.registrocivil.cl/run.",
    "Patient.address.city debe pertenecer al CodeSystem CSCodComunasCL (decreto 817)."
  ]
}

Recursos soportados para comparación: Patient, Practitioner, Encounter, Observation, Condition, MedicationRequest. Para el resto, valida directamente con fhiron_validate.

Reparar

`fhiron_apply_fix`

Cuándo: un issue.quickFix te trae el parche listo (jsonPointer + replacement) y quieres aplicarlo sin escribir el patch a mano. Es idempotente: aplicar dos veces es seguro. Pídele al agente:

Toma el quickFix de cl-enc-04 y aplícalo al recurso original.

Lo que hace el modelo:

fhiron_apply_fix(resource, quickFix)

Aplica el RFC 6901 sobre el JSON. Si el path no existe, lo crea.

Output:

{
  "ok": true,
  "applied": { "jsonPointer": "/status", "replacement": "finished" },
  "resource": {
    "resourceType": "Encounter",
    "status": "finished",
    "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB" },
    "subject": { "reference": "Patient/123" }
  }
}

Esta tool no llama al servidor. Después de aplicar el fix, pídele al agente “valida de nuevo” para que corra fhiron_validate (1 crédito) y confirme que el recurso quedó limpio contra el IG completo.

Cuándo usar cuál

Pregunta más frecuente del cookbook: ¿fhiron_validate o una de sus variantes?

Tú tienes…	Usa	Costo
Un recurso individual en memoria	`fhiron_validate`	1 crédito
El recurso en un `.json` del repo	`fhiron_validate_file`	1 crédito (5 MB max, sandbox)
Un `Bundle` con N entries	`fhiron_validate_bundle`	1 crédito por entry (cap 50 default)
Un endpoint FHIR público completo	`fhiron_score_endpoint`	Gratis (no llama al motor)
Quieres saber el delta R4 → CL Core	`fhiron_compare_profiles`	2 créditos
Sólo quieres feedback inmediato	`fhiron_lint`	Gratis (offline)

Para la categoría Explorar / Reparar, todas las tools son gratis y offline excepto fhiron_compare_profiles.

Tools: Referencia técnica

Mapa categórico, signatures, estructura del feedback y convenciones de naming.

Resources & Prompts

Recursos consultables (fhiron://...) y slash-commands (/validar-recurso, /crear-encounter-cl, …).

Reglas locales cl-*

Las 60+ reglas offline detrás de fhiron_lint.

Recetas por recurso

Ejemplos verticales por caso clínico chileno (TFC + ATC, DEIS, v3-ActCode).

Empezar

IA + MCP

Recetas

Inspect — Validación FHIR

CLI — Línea de comandos

SDK — Validación embebida

Insight — FHIR Score

Sandbox

Conceptos

Seguridad

Legal

Ejemplos por tool

Atajos

Validar una MedicationRequest

Armar un Encounter ambulatorio

Auditar un endpoint público

Validar

`fhiron_validate`

`fhiron_lint`

`fhiron_validate_file`

`fhiron_validate_bundle`

`fhiron_score_endpoint`

Explorar

`fhiron_get_example`

`fhiron_search_terminology`

`fhiron_explain_code`

`fhiron_compare_profiles`

Reparar

`fhiron_apply_fix`

Cuándo usar cuál

Siguiente

Tools: Referencia técnica

Resources & Prompts

Reglas locales cl-*

Recetas por recurso

​Atajos

Validar una MedicationRequest

Armar un Encounter ambulatorio

Auditar un endpoint público

​Validar

​fhiron_validate

​fhiron_lint

​fhiron_validate_file

​fhiron_validate_bundle

​fhiron_score_endpoint

​Explorar

​fhiron_get_example

​fhiron_search_terminology

​fhiron_explain_code

​fhiron_compare_profiles

​Reparar

​fhiron_apply_fix

​Cuándo usar cuál

​Siguiente

Tools: Referencia técnica

Resources & Prompts

Reglas locales cl-*

Recetas por recurso

Atajos

Validar

`fhiron_validate`

`fhiron_lint`

`fhiron_validate_file`

`fhiron_validate_bundle`

`fhiron_score_endpoint`

Explorar

`fhiron_get_example`

`fhiron_search_terminology`

`fhiron_explain_code`

`fhiron_compare_profiles`

Reparar

`fhiron_apply_fix`

Cuándo usar cuál

Siguiente