> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fhiron.cl/llms.txt
> Use this file to discover all available pages before exploring further.

# Ejemplos por tool

> Cookbook del MCP: un caso real, un prompt en español y el output esperado para cada una de las 10 herramientas fhiron_*.

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](/mcp/tools).

<Frame caption="Validación de un Practitioner desde el chat: el agente llama fhiron_validate y devuelve issues con quick-fix listo para aplicar.">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/fhiron/videos/cursor-mcp-hero.png" alt="Chat de Claude usando @fhiron/mcp-connector, tool call fhiron_validate con resultado de validación CL Core" />
</Frame>

## Atajos

<CardGroup cols={3}>
  <Card title="Validar una MedicationRequest" icon="stethoscope" href="#fhiron_validate">
    El caso más frecuente. Lint + quickFix + validación contra IG en una sola petición.
  </Card>

  <Card title="Armar un Encounter ambulatorio" icon="hospital" href="#fhiron_get_example">
    Scaffold CL Core + búsqueda de comuna y establecimiento DEIS sin gastar cuota.
  </Card>

  <Card title="Auditar un endpoint público" icon="radar" href="#fhiron_score_endpoint">
    FHIR® Score 0–100 con grade A–F y recomendaciones priorizadas.
  </Card>
</CardGroup>

***

## 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.
>
> ```json theme={null}
> {
>   "resourceType": "MedicationRequest",
>   "status": "active",
>   "subject": { "reference": "Patient/123" },
>   "medicationCodeableConcept": {
>     "coding": [
>       { "system": "https://terminologia.minsal.cl/CodeSystem/TFC", "code": "F0001520" }
>     ]
>   }
> }
> ```

**Lo que hace el modelo:**

<Steps>
  <Step title="fhiron_lint (offline, gratis)">
    Detecta `cl-medreq-02` (falta `intent`) con `quickFix.replacement = "order"`.
  </Step>

  <Step title="fhiron_apply_fix (offline, gratis)">
    Aplica el parche RFC 6901 sobre `/intent`. El recurso queda corregido sin tocar la cuota.
  </Step>

  <Step title="fhiron_validate (1 crédito)">
    Llama al servidor con el recurso corregido. HAPI valida contra el perfil completo + binding ATC.
  </Step>
</Steps>

**Output (resumen + JSON):**

```text theme={null}
✅ MedicationRequest válido contra CL Core v1.9.4.
```

```json theme={null}
{
  "valid": true,
  "issues": [],
  "profile": "https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CoreMedicamentoCl",
  "resourceType": "MedicationRequest",
  "source": "local+server"
}
```

<Tip>
  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.
</Tip>

***

### `fhiron_lint`

**Cuándo:** estás iterando sobre un recurso y quieres feedback en milisegundos sin gastar cuota. Cubre las 35+ 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.
>
> ```json theme={null}
> {
>   "resourceType": "Encounter",
>   "status": "complete",
>   "subject": { "reference": "Patient/123" }
> }
> ```

**Lo que hace el modelo:**

<Steps>
  <Step title="fhiron_lint (offline, < 5 ms)">
    Corre las reglas locales sobre el JSON. No hay tráfico de red.
  </Step>

  <Step title="Devuelve issues con quickFix">
    Cada issue trae `code`, `path`, `why`, `suggestion` y, cuando aplica, un `quickFix` mecánico.
  </Step>
</Steps>

**Output:**

```text theme={null}
2 errores · 0 warnings detectados localmente.
```

```json theme={null}
{
  "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"
}
```

<Tip>
  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.
</Tip>

***

### `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:**

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Lee el archivo y delega">
    Si es un `Bundle`, delega a `fhiron_validate_bundle`. Si no, a `fhiron_validate`.
  </Step>
</Steps>

**Output:**

```text theme={null}
samples/encounter-ambulatorio.json (Encounter) — válido ✅
```

```json theme={null}
{
  "valid": true,
  "issues": [],
  "profile": "https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CoreEncuentroCl",
  "resourceType": "Encounter",
  "source": "local+server"
}
```

<Tip>
  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.
</Tip>

***

### `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:**

<Steps>
  <Step title="Linteo local de cada entry">
    Si una entry tiene errores locales, no llega al servidor (no consume crédito).
  </Step>

  <Step title="Validación servidor de las entries que pasan el lint">
    Hasta `max_server_calls` (default 50). El resto queda como `local-only`.
  </Step>

  <Step title="Agregación">
    Devuelve totales, agrupado por `resourceType`, y el detalle por entry.
  </Step>
</Steps>

**Output:**

```text theme={null}
12 entries · 9 OK · 3 fallaron · 9 créditos consumidos.
```

```json theme={null}
{
  "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" }]
    }
  ]
}
```

<Tip>
  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).
</Tip>

***

### `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:**

<Steps>
  <Step title="Validación SSRF">
    Bloquea loopback, redes privadas, link-local, metadata cloud y resuelve DNS para detectar rebind a IPs internas.
  </Step>

  <Step title="GET /metadata">
    Descarga el `CapabilityStatement` con cap de 10 MB.
  </Step>

  <Step title="Scoring sobre 5 dimensiones">
    `fhirVersion` · core resources · profiles declarados · interactions soportadas · sistemas terminológicos referenciados. 20 puntos cada una.
  </Step>
</Steps>

**Output:**

```text theme={null}
api.partner-salud.cl → 72 / 100 (B) · FHIR R4.0.1 · 8/10 core · 2 perfiles declarados.
```

```json theme={null}
{
  "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"
  ]
}
```

<Tip>
  La tool **no** llama al motor de Fhiron. El scoring corre localmente sobre el `CapabilityStatement`. No consume crédito.
</Tip>

***

## 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:**

<Steps>
  <Step title="fhiron_get_example('Encounter')">
    Devuelve un Encounter completo con `class.system = v3-ActCode`, `subject`, `period` ISO-8601 y narrative.
  </Step>
</Steps>

**Output:**

```text theme={null}
Ejemplo Encounter (CL Core v1.9.4) — pasa el linter local ✅
```

```json theme={null}
{
  "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" }
}
```

<Tip>
  Recursos disponibles: `Patient`, `Practitioner`, `Encounter`, `Observation`, `Condition`, `MedicationRequest`, `AllergyIntolerance`, `Procedure`, `Coverage`, `Organization`, `Immunization`, `DiagnosticReport`, `Bundle`.
</Tip>

***

### `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:**

<Steps>
  <Step title="fhiron_search_terminology({ system: 'deis-comuna', query: 'las condes' })">
    Búsqueda case-insensitive y sin tildes sobre el catálogo del decreto 817.
  </Step>

  <Step title="Construye el address">
    Inyecta `code` + `display` con el `system` canónico correcto.
  </Step>
</Steps>

**Output:**

```text theme={null}
1 coincidencia en Comunas DEIS (decreto 817 / MINSAL).
```

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

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

***

### `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:**

<Steps>
  <Step title="fhiron_explain_code({ code: 'cl-medreq-02' })">
    Busca en el catálogo `cl-*` / `hapi-*` / `mcp-*` y devuelve `why`, `suggestion`, `example` y links.
  </Step>
</Steps>

**Output:**

```text theme={null}
📘 cl-medreq-02 — explicación
```

```json theme={null}
{
  "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" }
}
```

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

***

### `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:**

<Steps>
  <Step title="Valida contra el StructureDefinition R4 base">
    `meta.profile = http://hl7.org/fhir/StructureDefinition/Patient`.
  </Step>

  <Step title="Valida en paralelo contra el CL Core">
    `meta.profile = https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/CorePacienteCl`.
  </Step>

  <Step title="Diff de errores">
    Devuelve las restricciones que sólo aparecen en CL Core, o sea, el costo de migración.
  </Step>
</Steps>

**Output:**

```text theme={null}
R4: 0 errores · CL Core: 2 errores · 2 son específicos de CL Core.
```

```json theme={null}
{
  "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 CodigoComunaDEIS (decreto 817)."
    ]
  },
  "clOnlyDiff": [
    "Patient.identifier requerido — al menos un identifier con system http://www.registrocivil.cl/run.",
    "Patient.address.city debe pertenecer al CodeSystem CodigoComunaDEIS (decreto 817)."
  ]
}
```

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

***

## 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:**

<Steps>
  <Step title="fhiron_apply_fix(resource, quickFix)">
    Aplica el RFC 6901 sobre el JSON. Si el path no existe, lo crea.
  </Step>
</Steps>

**Output:**

```json theme={null}
{
  "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" }
  }
}
```

<Tip>
  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.
</Tip>

***

## 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`.

## Siguiente

<CardGroup cols={2}>
  <Card title="Tools: Referencia técnica" icon="list" href="/mcp/tools">
    Mapa categórico, signatures, estructura del feedback y convenciones de naming.
  </Card>

  <Card title="Resources & Prompts" icon="folder-tree" href="/mcp/resources-prompts">
    Recursos consultables (`fhiron://...`) y slash-commands (`/validar-recurso`, `/crear-encounter-cl`, …).
  </Card>

  <Card title="Reglas locales cl-*" icon="ruler" href="/mcp/reglas-locales">
    Las 35+ reglas offline detrás de `fhiron_lint`.
  </Card>

  <Card title="Recetas por recurso" icon="book-open" href="/recetas/prescripcion-paracetamol-tfc-atc">
    Ejemplos verticales por caso clínico chileno (TFC + ATC, DEIS, v3-ActCode).
  </Card>
</CardGroup>