Página de referencia. Para ver prompts naturales y outputs reales de cada tool en el chat de Cursor / Claude / Windsurf, ir directo a Ejemplos por tool. La estrategia de cuándo elegir lint vs validate (y por qué importa) vive en Skill CL Core: Routing por intent.
@fhiron/mcp-connector expone 10 herramientas con prefijo fhiron_. El prefijo evita colisión con la marca registrada FHIR® (HL7) y deja todo el namespace agrupado en cualquier cliente MCP.
Para que el modelo (y tú) las absorban rápido, están organizadas en tres categorías mentales según la intención:
- Validar: confirmar que un recurso cumple CL Core v1.9.4
- Explorar: entender el estándar, los perfiles y la terminología chilena
- Reparar: aplicar correcciones mecánicas
Regla práctica: empieza siempre por Explorar si no tienes un recurso aún (fhiron_get_example, fhiron_search_terminology), después Validar lo que armaste, y solo cuando un issue trae quickFix, llama a Reparar.
Mapa de herramientas
Validar
Confirman que un recurso, un Bundle o un endpoint completo cumple CL Core. Cinco tools, escaladas de barata a costosa.
| Tool | Costo | Cuándo usarla |
|---|
fhiron_lint | Gratis (offline) | Lint local determinístico antes de tocar la red. Atrapa los errores cl-* con quickFix mecánico. |
fhiron_validate | 1 crédito | Tool principal: corre el lint local y luego HAPI server-side para slicing y terminología profunda. |
fhiron_validate_file | 1 crédito | Igual que fhiron_validate pero leyendo un .json del filesystem. Evita pegar JSONs largos en el chat. |
fhiron_validate_bundle | 1 crédito por entry validada (cap 50) | Bundle entry-by-entry contra HAPI. Devuelve matriz pass/fail agrupada por resourceType. |
fhiron_score_endpoint | Gratis (no llama a Fhiron) | Escanea un endpoint FHIR público y devuelve un FHIR Score 0–100 con grade A–F y recomendaciones. |
fhiron_score_endpoint bloquea automáticamente URLs hacia redes privadas, loopback y metadata cloud (localhost, 10.x, 172.16-31.x, 192.168.x, 169.254.x, 100.64-127.x, ::1, fe8x..feb, fc/fd, metadata.google.internal). Usa únicamente endpoints FHIR públicos.
Explorar
Para entender el estándar, ver ejemplos válidos y consultar terminología chilena. Todas son gratis y offline. La IA debe llamarlas antes de inventar un código o un perfil.
| Tool | Costo | Cuándo usarla |
|---|
fhiron_get_example | Gratis (offline) | Devuelve un recurso CL Core válido listo para editar (Patient, Practitioner, Encounter, Condition, MedicationRequest, +9). |
fhiron_search_terminology | Gratis (offline) | Busca en catálogos chilenos: comunas DEIS, establecimientos DEIS, ATC/TFC, CIE-10, CSTipoIdentificador. |
fhiron_explain_code | Gratis (offline) | Explicación pedagógica de un código de error (cl-enc-04, cl-medreq-02, hapi-error-terminology, mcp-quota-01, etc.) con why, fix y ejemplo. |
fhiron_compare_profiles | 2 créditos | Valida el mismo recurso contra FHIR R4 base vs CL Core en paralelo y devuelve el diff de errores. |
Reparar
Aplica correcciones mecánicas obtenidas desde un issue.quickFix devuelto por fhiron_validate o fhiron_lint.
| Tool | Costo | Cuándo usarla |
|---|
fhiron_apply_fix | Gratis (offline) | Aplica un quickFix (RFC 6901 jsonPointer + replacement) sobre el JSON original. Idempotente: aplicar dos veces es seguro. |
Estructura del feedback
Cada issue que devuelven las tools de Validar responde las cuatro preguntas pedagógicas (qué / dónde / por qué / cómo arreglar):
{
"code": "cl-enc-04", // qué (estable, máquina-legible)
"severity": "error",
"path": "Encounter.status", // dónde (FHIRPath)
"message": "Encounter.status='complete' no pertenece al ValueSet EncounterStatus (binding required). Códigos válidos: planned · arrived · triaged · in-progress · onleave · finished · cancelled · entered-in-error · unknown.",
"why": "FHIR R4 — required binding al ValueSet http://hl7.org/fhir/ValueSet/encounter-status. 'complete' es un valor que devuelven varios HIS legacy, pero no es FHIR; el binding required no admite códigos custom.",
"profileUrl": "http://hl7.org/fhir/StructureDefinition/Encounter",
"docsUrl": "https://docs.fhiron.cl/inspect/errores#cl-enc-04",
"suggestion": "Mapear el estado interno del HIS a uno de los códigos del ValueSet (finished cuando la atención cerró, in-progress cuando está abierta, cancelled cuando se anuló).",
"example": { "status": "finished" },
"quickFix": {
"title": "Reemplazar por código FHIR válido",
"jsonPointer": "/status",
"replacement": "finished"
}
}
Convención de nombres
Los nombres canónicos usan el prefijo fhiron_ para diferenciarse de la marca registrada FHIR® (HL7) y para que cualquier cliente MCP agrupe visualmente las herramientas del connector. Los nombres no van a cambiar. Son parte del contrato público del paquete. 
