El servidor de KF expone su grafo de conocimiento a través del
Model Context Protocol en el endpoint /mcp.
Cualquier cliente LLM compatible con MCP —Claude Desktop, VS Code Copilot o un
agente propio— puede conectarse y obtener acceso de lectura completo a la base de
datos de KF: buscar en ella, recorrer las relaciones entre ítems y extraer análisis
de fallos y checklists de conformidad completos, todo en las palabras del propio
cliente.
El endpoint usa el transporte MCP Streamable HTTP. Todas las herramientas son síncronas y de solo lectura.
https://kf.example.com/mcp
Añádelo a la configuración de tu cliente MCP. Para Claude Desktop
(claude_desktop_config.json):
{
"mcpServers": {
"kf": {
"url": "https://kf.example.com/mcp",
"headers": { "Authorization": "Bearer f0e1d2…" }
}
}
}
El endpoint /mcp nunca se sirve de forma anónima —cada conexión necesita un
token de acceso personal (enviado como
Authorization: Bearer …) o una sesión activa. Un token lleva exactamente el acceso
del usuario que lo creó: el cliente MCP ve justo los ítems que ese usuario vería en
el navegador, ni uno más. Consulta autenticación y acceso
para crear un token.
KF almacena ítems. Cada ítem tiene un id estable, un title, una class
(m módulo, i contenedor/ítem, e evento, a acción, t tipo), un code
opcional (SKU / x0), tags separadas por espacios y un parent. Los ítems se
unen mediante aristas tipadas:
| Arista | Significado |
|---|---|
→ | causalidad — este ítem causa aquel evento |
∋ | contención — componente de |
⊃ | tipo / instancia — este ítem es una instancia de un tipo |
* | acción — una tarea vinculada a un ítem o evento |
⇒ | resultado — un resultado esperado |
≺ | precedencia |
Las acciones y los resultados llevan una etiqueta de estado: done,
not_applicable (na), missing (requerido por un tipo pero aún ausente) o ausente
(pendiente). Esto refleja el modelo de la API REST —las
herramientas MCP son el lado de lectura del mismo almacén, presentado para un LLM.
El servidor publica las siguientes herramientas de solo lectura. Toda herramienta
que actúa sobre un único ítem toma un parámetro id.
| Herramienta | Propósito |
|---|---|
search | búsqueda de texto completo (BM25) sobre todos los ítems |
get_item | obtiene los campos base de un ítem (y su cuerpo Markdown doc) |
get_item_path | ruta de migas —recorre la cadena de padres |
get_components | subcomponentes directos (∋ hacia abajo) |
get_events | eventos que este ítem causa (→ hacia abajo) |
get_events_up | eventos que causaron este ítem (→ hacia arriba) |
get_actions | acciones/tareas vinculadas a un ítem (*) |
get_outcomes | resultados esperados vinculados a un ítem (⇒) |
get_types | tipos de los que este ítem aprende (⊃ hacia arriba) |
get_instances | todas las instancias de un ítem tipo (⊃ hacia abajo) |
get_checklist | checklist de conformidad completo, fusionando requisitos heredados de los tipos |
get_checklist_summary | recuentos agregados done / na / missing / pending por ítem y tipo de origen |
get_inverted_checklist | vista de lecciones aprendidas —acciones en instancias aún no promovidas al tipo |
get_failure_analysis | árbol tipo FMEA: ítem + componentes + tipos, cada uno con sus eventos y acciones |
get_failure_tree | árbol de fallos como texto indentado —evento superior hasta causas raíz |
get_by_tag | todos los ítems que llevan una tag dada |
get_by_code | busca un ítem por su code (SKU / x0) |
search ejecuta una consulta de texto completo en orden de rango BM25. El query
admite sintaxis FTS5: palabras clave simples, "frase exacta", prefijo*, los
operadores booleanos AND / OR / NOT y cualificadores de campo como
title:pump. Cada acierto es una referencia compacta:
{ "id": "abc123", "title": "Fallo de bomba", "type": "e", "link": "/item/abc123" }
Estas son las herramientas que convierten a KF en algo más que una caja de búsqueda.
get_checklist devuelve cada acción y resultado requerido para un ítem —incluidos
los heredados de sus tipos pero aún no presentes en la instancia, que aparecen como
missing:
{
"item_id": "abc123", "item": "Bomba P-101",
"event": "Fallo de sello", "action": "Sustituir sello", "status": "done"
}
get_checklist_summary agrega los mismos datos en recuentos por ítem y tipo de
origen (done, na, missing, pending, total) —la forma ideal para un panel.
get_inverted_checklist invierte la pregunta: se ancla en las instancias de un
tipo y marca las acciones que existen en una instancia pero no en el tipo
—candidatas a lección aprendida que deberían promoverse para que toda instancia
futura las herede.
get_failure_analysis devuelve el árbol FMEA completo —el ítem con todos sus
componentes y tipos (plano, con una profundidad indent), cada uno con su árbol de
eventos y las acciones de cada evento:
[
{
"id": "abc123", "title": "Bomba P-101", "class": "i", "indent": 0,
"events": [
{ "id": "ev-01", "title": "Fallo de sello", "indent": 1,
"actions": [
{ "id": "ac-01", "title": "Inspeccionar sello", "status": "done" },
{ "id": "ac-02", "title": "Sustituir sello", "status": "pending" }
] }
]
}
]
Las herramientas están pensadas para que el LLM las componga en respuesta a una petición en lenguaje natural. Algunas cadenas comunes:
Informe de conformidad de un ítem —
search("bomba hidráulica") → get_item(id) para confirmar → get_item_path(id)
para el contexto → get_checklist(id) para el estado fila por fila →
get_checklist_summary(id) para los recuentos ejecutivos, y luego componer un
informe Markdown agrupado por estado.
*"Prepara un informe de conformidad para el sistema hidráulico. Muestra qué
acciones requeridas están completas, pendientes, no aplicables y ausentes. Incluye
una tabla resumen y un listado detallado fila por fila."*
Informe de análisis de fallos (FMEA) —
search("bomba") → get_failure_analysis(id) para el árbol de eventos/acciones →
get_failure_tree(event_id) para la cadena causal de un evento concreto, y luego
componer una tabla FMEA.
*"Genera una tabla FMEA completa para el ítem abc123. Para cada modo de fallo
lista las acciones correctivas asociadas y su estado actual. En formato Markdown."*
Encontrar lecciones aprendidas —
search("tipo bomba") → get_inverted_checklist(type_id) →
get_instances(type_id), y luego resumir qué lecciones deberían promoverse al tipo.
*"¿Qué acciones existen en instancias individuales de bomba pero aún no forman
parte del tipo estándar 'Bomba'? Preséntalas como adiciones propuestas al tipo."*
Explorar el grafo — las herramientas de navegación responden directamente:
"¿Qué componentes contiene el sistema de refrigeración?" (get_components),
"¿Qué puede desencadenar este conjunto de sello?" (get_events),
"¿Qué causó la pérdida de presión?" (get_events_up),
"Recorre la cadena causal desde la parada de planta hasta las causas raíz."
(get_events_up repetido).