@fhiron/mcp-connector

v0.7.1

Published

3 days ago

Fhiron MCP connector — validación FHIR contra CL Core v1.9.4 con skill `fhiron-cl` embebida (operating contract + 17 recursos descubribles). 10 tools fhiron_*, prompts pre-armados, bilingüe es/en, wizard `init` 1-clic. Compatible con Claude Code, Cursor,

0High
0Medium
0Low

fhiron

fhir mcp model-context-protocol agent-skill chile cl-core hl7 deis minsal tfc cie10 validation spanish

@fhiron/mcp-connector

Built for FHIR® builders — Conecta tu agente de IA (Claude Desktop, Cursor, Antigravity, Windsurf) con Fhiron Bridge vía Model Context Protocol. Tu IDE valida recursos FHIR contra CL Core v1.9.4 en tiempo real — con errores en español, dígito verificador del RUN chequeado en el editor, ejemplos válidos a un comando, y catálogos chilenos (DEIS · TFC · CIE-10) consultables sin alucinar.

Demo

Lo que muestra: Claude crea un Patient CL Core, busca la comuna en DEIS (Las Condes → 13114), detecta puntos en el RUN (cl-run-01), aplica el quick-fix automáticamente y explica el código de error con referencia al perfil oficial.

Para reproducir el flow en tu terminal sin cliente MCP:
node node_modules/@fhiron/mcp-connector/assets/demo-flow.js

Instalación en 30 segundos

Wizard interactivo (recomendado)

npx -y @fhiron/mcp-connector init

Detecta tu IDE, escribe la config con merge no-destructivo y verifica el handshake. Soporta:

Claude Desktop · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor (global o por proyecto) · ~/.cursor/mcp.json o <repo>/.cursor/mcp.json
Antigravity · <repo>/.antigravity/mcp.json
Windsurf · ~/.codeium/windsurf/mcp_config.json
Claude Code (CLI) · ~/.claude.json

Manual

Claude Desktop · `~/Library/Application Support/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "fhiron": {
      "command": "npx",
      "args": ["-y", "@fhiron/mcp-connector", "--key", "TU_API_KEY"]
    }
  }
}

Cursor / Antigravity · `.cursor/mcp.json` o `.antigravity/mcp.json`

{
  "mcpServers": {
    "fhiron": {
      "command": "npx",
      "args": ["-y", "@fhiron/mcp-connector", "--key", "TU_API_KEY"]
    }
  }
}

Obtén tu API key gratis en fhiron.cl/registro. Plan Free incluye 100 validaciones/mes y todas las tools offline.

Modo bilingüe

# Por defecto: español (CL Core es chileno)
npx -y @fhiron/mcp-connector --key K

# Inglés (jurados internacionales / equipos extranjeros)
npx -y @fhiron/mcp-connector --key K --lang en

# Vía variable de entorno
FHIRON_LANG=en npx -y @fhiron/mcp-connector --key K

El idioma afecta los mensajes "marco" del connector (descripciones de tools, summaries, errores de red). Los mensajes pedagógicos de las reglas CL Core (why, suggestion) se mantienen en español por diseño — son específicos del IG chileno.

Las 10 herramientas

Los nombres canónicos usan el prefijo fhiron_ para diferenciarse de la marca registrada FHIR® (HL7®). Están agrupadas por intención — Validar, Explorar, Reparar — para que un dev nuevo arme el mapa mental en 30 segundos.

flowchart TD
    ROOT([fhiron_*<br/>10 herramientas])

    ROOT --> V[Validar]
    ROOT --> E[Explorar]
    ROOT --> R[Reparar]

    V --> V1[fhiron_lint<br/>· offline · gratis]
    V --> V2[fhiron_validate<br/>· 1 crédito · principal]
    V --> V3[fhiron_validate_file<br/>· 1 crédito · lee .json]
    V --> V4[fhiron_validate_bundle<br/>· 1 crédito por entry]
    V --> V5[fhiron_score_endpoint<br/>· offline · escanea endpoint]

    E --> E1[fhiron_get_example<br/>· offline · scaffolding]
    E --> E2[fhiron_search_terminology<br/>· offline · DEIS·TFC·CIE-10]
    E --> E3[fhiron_explain_code<br/>· offline · pedagógico]
    E --> E4[fhiron_compare_profiles<br/>· 2 créditos · R4 vs CL Core]

    R --> R1[fhiron_apply_fix<br/>· offline · idempotente]

    classDef root fill:#1e1f24,stroke:#635BFF,stroke-width:2px,color:#fff
    classDef group fill:#1e1f24,stroke:#7C7BFF,stroke-width:1.5px,color:#fff
    classDef tool fill:#0f1115,stroke:#3a3a45,color:#cfcfd6

    class ROOT root
    class V,E,R group
    class V1,V2,V3,V4,V5,E1,E2,E3,E4,R1 tool

Regla práctica: si no tenés un recurso aún, empezá por Explorar (fhiron_get_example, fhiron_search_terminology). Si lo tenés, Validar (lint local → validate). Si el issue trae quickFix, Reparar y volvé a validar.

Validar

Confirman que un recurso, un Bundle o un endpoint cumple CL Core v1.9.4.

| Tool | Costo | Descripción | | -------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fhiron_lint | Gratis (offline) | Linter local offline (cl-* rules). No descuenta cuota. Ideal para auto-corregir antes de gastar un crédito en fhiron_validate. | | fhiron_validate | 1 crédito | Valida un recurso FHIR completo contra CL Core v1.9.4. Corre el linter local primero (gratis) y luego HAPI server-side. Esta es la tool principal de validación. | | fhiron_validate_file | igual que validate | Lee un archivo .json del filesystem local del usuario y lo valida. Read-only. Usá esta tool cuando el usuario menciona un archivo en vez de pegar el JSON inline. | | fhiron_validate_bundle | 1 crédito por entry | Valida un Bundle entry-by-entry contra HAPI. Devuelve matriz pass/fail por entry, agrupada por resourceType. Útil para datasets grandes (50–500 recursos). | | fhiron_score_endpoint | Gratis (no cuota) | Escanea un endpoint FHIR público (URL) y devuelve un FHIR Score 0-100 con grade A-F + recomendaciones por dimensión. Lectura del CapabilityStatement. |

Explorar

Para entender el estándar, ver ejemplos válidos y consultar terminología chilena. La IA debe llamarlas antes de inventar un código o un perfil.

| Tool | Costo | Descripción | | ----------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | fhiron_get_example | Gratis (offline) | Devuelve un recurso CL Core válido listo para editar. Cubre Patient, Practitioner, Encounter, Condition, MedicationRequest y 9 más. | | fhiron_search_terminology | Gratis (offline) | Busca en catálogos chilenos: comunas DEIS, establecimientos DEIS, TFC (medicamentos), CIE-10, CSTipoIdentificador. La IA debe consultar, no adivinar. | | fhiron_explain_code | Gratis (offline) | Explica un código de error (cl-run-01, hapi-error, mcp-quota-01) con why (porqué), profileUrl, suggestion y un example. | | fhiron_compare_profiles | 2 créditos | Valida el mismo recurso contra dos perfiles en paralelo (FHIR R4 base + CL Core) y devuelve el diff de errores. Útil para entender qué exige CL Core sobre R4 vanilla. |

Reparar

Aplica correcciones mecánicas obtenidas desde un issue.quickFix.

| Tool | Costo | Descripción | | ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | | fhiron_apply_fix | Gratis (offline) | Aplica un quickFix obtenido de issues[] directamente sobre el JSON del recurso (RFC 6901 jsonPointer). Idempotente. |

Migración desde v0.4.x

Los nombres anteriores siguen funcionando como aliases retrocompatibles (no aparecen en tools/list):

| Nombre v0.4.x | → Canónico v0.5.0 | | ------------------------------- | ----------------------- | | fhiron_validate_fhir_resource | fhiron_validate | | fhiron_fhir_lint_local | fhiron_lint | | fhiron_fhir_apply_quickfix | fhiron_apply_fix | | fhiron_fhir_lint_run | (deprecada — usar fhiron_validate con un Patient mínimo) | | validate_fhir_resource, fhir_validate, fhir_lint_local, fhir_lint_run, fhir_apply_quickfix | aliases legacy v0.3.x — siguen aceptados |

Estructura del feedback (las 4 preguntas)

Cada issue responde:

{
  "code": "cl-run-01",                                           // qué (estable, máquina-legible)
  "severity": "error",
  "path": "Patient.identifier[0].value",                          // dónde (FHIRPath)
  "message": "El RUN no debe incluir puntos. Formato esperado: 12345678-5 (perfil RUNcl · CL Core v1.9.4).",
  "why": "El perfil RUNcl de CL Core normaliza el RUN al cuerpo numérico sin separadores...",  // porqué
  "profileUrl": "https://hl7chile.cl/fhir/ig/clcore/StructureDefinition/RUNcl",  // dónde se indica
  "docsUrl": "https://docs.fhiron.cl/errores/cl-run-01",         // más info
  "suggestion": "Aplica el quickFix incluido o quita los puntos manualmente...",
  "example": { "identifier": [{ "system": "...CSIdentificadores", "value": "12345678-5" }] },
  "quickFix": {                                                  // solución mecánica
    "title": "Quitar puntos automáticamente",
    "jsonPointer": "/identifier/0/value",
    "replacement": "12345678-5"
  }
}

Resources MCP (`resources/list`)

El servidor expone contexto FHIR Chile que el agente IA puede leer sin pedirlo:

| URI | MIME | Contenido | | ------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------- | | fhiron://profiles/cl-core/v1.9.4 | application/json | Catálogo de StructureDefinitions y CodeSystems del IG. | | fhiron://examples/{ResourceType} | application/fhir+json | Ejemplo válido CL Core por cada uno de los 13 recursos cubiertos. | | fhiron://catalogs/{system} | application/json | DEIS comunas, DEIS establecimientos, TFC, CIE-10, CSIdentificadores. | | fhiron://docs/{topic} | text/markdown | Mini-docs: run-format, comunas-deis, tfc, identificadores, mcp-overview. | | fhiron://errors | application/json | Catálogo completo de códigos cl-*, hapi-* y mcp-* con metadatos. |

Prompts MCP (`prompts/list`)

Slash-commands listos para usar en Claude Desktop / Cursor:

| Nombre | Argumentos | Descripción | | ------------------- | -------------------------------- | ------------------------------------------------------------------------ | | validar-recurso | recurso | Valida + auto-aplica quickFix + reporta con why/suggestion. | | crear-paciente-cl | nombre, run, comuna | Genera un Patient CL Core válido con los datos provistos. | | auditar-bundle | bundle | Lint entry por entry, tabla de errores por recurso, resumen final. | | explicar-error | code | Pedagogía completa de un código de error. | | buscar-codigo | system, query | Busca un código en DEIS / TFC / CIE-10 / CSIdentificadores. |

Reglas locales (`cl-*`)

35+ reglas offline cubriendo los 13 recursos más comunes de CL Core v1.9.4.

Formato y estructura

| Código | Severidad | Descripción | | ------------ | --------- | ---------------------------------------------------------------------------- | | cl-json-01 | error | JSON inválido (string de entrada no parseable). | | cl-json-02 | error | El argumento no es un objeto FHIR. | | cl-json-03 | error | Falta resourceType. | | cl-json-04 | warning | resourceType no es un tipo oficial de FHIR R4 (el servidor lo rechazará). |

RUN chileno (perfil RUNcl)

| Código | Severidad | Descripción | | ------------ | --------- | ---------------------------------------------------------------------------- | | cl-run-01 | error | RUN con puntos — incluye quickFix que los elimina automáticamente. | | cl-run-02 | error | Identifier con system RUN pero sin value. | | cl-run-03 | error | Dígito verificador incorrecto. | | cl-run-04 | warning | System legacy hl7chile.cl/identificador/run obsoleto. |

Patient (CorePacienteCl)

| Código | Severidad | Descripción | | ---------------- | --------- | ------------------------------------------ | | cl-patient-01 | error | Falta identifier. | | cl-patient-02 | error | Falta name. | | cl-patient-03 | error | Elemento de name sin family ni given.| | cl-patient-04 | warning | gender recomendado. |

Practitioner (CorePrestadorCl)

| Código | Severidad | Descripción | | --------------------- | --------- | ----------------------- | | cl-practitioner-01 | error | Falta identifier. | | cl-practitioner-02 | error | Falta name. |

Observation

| Código | Severidad | Descripción | | ----------- | --------- | ---------------- | | cl-obs-01 | error | Falta status. | | cl-obs-02 | error | Falta code. | | cl-obs-03 | error | Falta subject. |

Medication (CoreMedicamentoCl)

| Código | Severidad | Descripción | | ----------- | --------- | -------------------------------------------------------- | | cl-med-01 | error | Falta code. | | cl-med-02 | warning | Sistema de codificación no reconocido (TFC/SNOMED/RxNorm recomendados). |

MedicationRequest

| Código | Severidad | Descripción | | ---------------- | --------- | -------------------------------------------- | | cl-medreq-01 | error | Falta status. | | cl-medreq-02 | error | Falta intent. | | cl-medreq-03 | error | Falta subject. | | cl-medreq-04 | error | Falta medication[x]. |

Encounter (CoreEncounterCl)

| Código | Severidad | Descripción | | ----------- | --------- | -------------------- | | cl-enc-01 | error | Falta status. | | cl-enc-02 | error | Falta class. | | cl-enc-03 | error | Falta subject. |

Condition / AllergyIntolerance / Procedure / Coverage / Organization / Immunization / DiagnosticReport / Bundle

Lista completa de códigos (cl-cond-*, cl-allergy-*, cl-proc-*, cl-cov-*, cl-org-*, cl-imm-*, cl-dr-*, cl-bundle-*) en docs.fhiron.cl y en Fhironstack/skills.

Compatibilidad MCP

Spec: soporta protocolVersion 2025-03-26 (con annotations) y negocia automáticamente con clientes en 2024-11-05.
Capabilities declaradas: tools, resources, prompts, logging.
Notifications: emite notifications/message (level=info) cuando el cliente declara logging capability — útil para mostrar progreso en Claude Desktop.

Verificar con el MCP Inspector oficial

cd packages/mcp-connector
FHIRON_API_KEY=tu_key npm run inspect

Seguridad

La API key se pasa por argumento o env var FHIRON_API_KEY. Nunca se persiste en disco (excepto cuando el wizard init la escribe en el config del IDE — ahí queda en plain text bajo tu control).
Todo el tráfico va por HTTPS a https://fhiron.cl/api/validate con header X-API-Key.
El conector no expone filesystem ni shell — solo las 7 tools declaradas.
Los errores de red, autenticación y cuota se devuelven como content[] en el idioma activo, nunca escapan como errores JSON-RPC crudos.
El subcomando init hace merge no-destructivo sobre la config existente — preserva otros mcpServers y otras keys top-level.

Stack

Node.js >= 20.9 (built-in fetch, node:test, AbortSignal.timeout).
Zero deps runtime salvo @fhiron/linter (también zero-deps).
CommonJS — el mismo módulo corre en el Web Worker del dashboard, en el MCP connector y en el servidor.

Tests

npm test    # 51 tests con stub HTTP local (node:test, sin dependencies)

Fhiron — Built for FHIR® builders. Hecho en Chile 🇨🇱 con MIT license.

FHIR® is the registered trademark of Health Level Seven International and the use does not constitute endorsement by HL7.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@fhiron/mcp-connector

Demo

Instalación en 30 segundos

Wizard interactivo (recomendado)

Manual

Claude Desktop · ~/Library/Application Support/Claude/claude_desktop_config.json

Cursor / Antigravity · .cursor/mcp.json o .antigravity/mcp.json

Modo bilingüe

Las 10 herramientas

Validar

Explorar

Reparar

Migración desde v0.4.x

Estructura del feedback (las 4 preguntas)

Resources MCP (resources/list)

Prompts MCP (prompts/list)

Reglas locales (cl-*)

Formato y estructura

RUN chileno (perfil RUNcl)

Patient (CorePacienteCl)

Practitioner (CorePrestadorCl)

Observation

Medication (CoreMedicamentoCl)

MedicationRequest

Encounter (CoreEncounterCl)

Condition / AllergyIntolerance / Procedure / Coverage / Organization / Immunization / DiagnosticReport / Bundle

Compatibilidad MCP

Verificar con el MCP Inspector oficial

Seguridad

Stack

Tests

Claude Desktop · `~/Library/Application Support/Claude/claude_desktop_config.json`

Cursor / Antigravity · `.cursor/mcp.json` o `.antigravity/mcp.json`

Resources MCP (`resources/list`)

Prompts MCP (`prompts/list`)

Reglas locales (`cl-*`)